# Envelope

Audio envelope.

### Description

An envelope is a time-variant control signal which can be used to control parameters of sounds that are to change over time (e.g. amplitude, frequency, filter characteristics, modulation amount, etc.).

Envelope Items use a function defined by a set of points in time-level space described by an array of DataTimePairs (defined in audio.h). The function is a continuous set of line segments drawn between the points in the DataTimePair array.

Envelopes are used in conjunction with Instruments that accept the Envelope Item's data and output the control signal (e.g. envelope.dsp).

### Folio

audio

### Item Type

AUDIO_ENVELOPE_NODE

### Create

`CreateEnvelope()`

`CreateItem()`

### Delete

`DeleteEnvelope()`

`DeleteItem()`

### Query

None

### Modify

`SetAudioItemInfo()`

### Use

`AttachEnvelope()`

### Tags

AF_TAG_ADDRESS
  (const DataTimePair *) Create, Modify. Pointer to array of DataTimePairs used to define the envelope. All of the points in this array must be sorted in increasing order by time. The length of the array is specified with AF_TAG_FRAMES.

AF_TAG_CLEAR_FLAGS
  (uint32) Create, Modify. Set of AF_ENVF_ flags to clear. Clears every flag for which a 1 is set in ta_Arg.

AF_TAG_FRAMES
  (int32) Create, Modify. Number of DataTimePairs in array pointed to by AF_TAG_ADDRESS.

AF_TAG_MICROSPERUNIT
  (int32) Create, Modify. Number of microseconds for each time unit specified in DataTimePairs and time related envelope tags. Defaults to 1000 on creation, which sets each time unit equal to one millisecond.

AF_TAG_RELEASEBEGIN
  (int32) Create, Modify. Index in DataTimePair array for beginning of release loop. -1 indicates no loop, which is the default on creation. If not -1, must <= the value set by AF_TAG_RELEASEEND.

AF_TAG_RELEASEEND
  (int32) Create, Modify. Index in DataTimePair array for end of release loop. -1 indicates no loop, which is the default on creation. If not -1, must >= the value set by AF_TAG_RELEASEBEGIN.

AF_TAG_RELEASEJUMP
  (int32) Create, Modify. Index in DataTimePair array to jump to on release. When set, release causes escape from normal envelope processing to the specified index without disturbing the current output envelope value. From there, the envelope proceeds to the next DataTimePair from the current value. -1 to disable, which is the default on creation.

AF_TAG_RELEASETIME
  (int32) Create, Modify. The time in units used when looping from the end of the release loop back to the beginning. Defaults to 0 on creation.

AF_TAG_SET_FLAGS
  (uint32) Create, Modify. Set of AF_ENVF_ flags to set. Sets every flag for which a 1 is set in ta_Arg.

AF_TAG_SUSTAINBEGIN
  (int32) Create, Modify. Index in DataTimePair array for beginning of sustain loop. -1 indicates no loop, which is the default on creation. If not -1, <= the value set by AF_TAG_SUSTAINEND.

AF_TAG_SUSTAINEND
  (int32) Create, Modify. Index in DataTimePair array for end of sustain loop. -1 indicates no loop, which is the default on creation. If not -1, >= the value set by AF_TAG_SUSTAINBEGIN.

AF_TAG_SUSTAINTIME
  (int32) Create, Modify. The time in units used when looping from the end of the sustain loop back to the beginning. Defaults to 0 on creation.

### Flags

AF_ENVF_FATLADYSINGS
  The state of this flag indicates the default setting for the AF_ATTF_FATLADYSINGS flag whenever this envelope is attached to an instrument.

### See Also

``Attachment`, Instrument, envelope.dsp`