Instrument

Description

Instrument items are created from Template items. They correspond to actual instances of DSP code running on the DSP. Several Instruments can be connected together to create a patch. Instruments can be played (by starting them), and controlled (by tweaking knobs). An Instrument is monophonic in the sense that it corresponds to a single voice. Multiple voices require creating an Instrument per voice.

Folio

audio

Item Type

AUDIO_INSTRUMENT_NODE

Create

AllocInstrument()

CreateInstrument() (new for V24)

CreateItem()

LoadInstrument()

Delete

DeleteInstrument() (new for V24)

DeleteItem()

FreeInstrument()

UnloadInstrument()

Query

GetAudioItemInfo()

Modify

None

Use

AbandonInstrument()

AttachEnvelope()

AttachSample()

BendInstrumentPitch()

ConnectInstruments()

CreateProbe() (new for V24)

DisconnectInstruments()

GetKnobName()

GetNumKnobs()

GrabKnob()

PauseInstrument()

ReleaseInstrument()

ResumeInstrument()

StartInstrument()

StopInstrument()

TuneInstrument()

Tags

AF_TAG_AMPLITUDE: (uint32) Start. Value to set instrument's Amplitude knob to before starting instrument (for instruments that have an Amplitude knob). Valid range is 0..0x7fff. Has no effect if Amplitude knob is connected to the output from another instrument. This tag is mutually exclusive with AF_TAG_VELOCITY.

AF_TAG_CALCRATE_DIVIDE: (uint32) (new tag for V24) Create. Specifies the the denominator of the fraction of the total DSP cycles on which this instrument is to run. The only valid settings at this time are 1 to run on all DSP cycles (i.e. e and 2 to run on only 1/2 of the DSP cycles (i.e. execute at 22,050 cycles/sec). Defaults to 1.

AF_TAG_FREQUENCY: (ufrac16) Start. Value to set Frequency knob to in 16.16 Hertz (for instruments that have a Frequency knob). Has no effect if Frequency knob is connected to the output from another instrument. This tag is mutually exclusive with AF_TAG_PITCH and AF_TAG_RATE.

AF_TAG_PITCH: (uint32) Start. Value to set Frequency knob (for instruments that have a Frequency knob) expressed as a MIDI note number. The range is 0 to 127; 60 is middle C. For multisample instruments, picks the sample associated with the MIDI pitch number. This tag is mutually exclusive with AF_TAG_FREQUENCY and AF_TAG_RATE.

AF_TAG_PRIORITY: (uint32) Create, Query. The priority of execution in DSP in the range of 0..255, where 255 is the highest priority. Defaults to 100 on creation.

AF_TAG_RATE: (uint32) Start. Value to set Frequency knob to in instrument-specific frequency units (e.g. phase increment, proportion of original sample rate) for instruments that have a Frequency knob. Has no effect if Frequency knob is connected to the output from another instrument. This tag is mutually exclusive with AF_TAG_FREQUENCY and AF_TAG_PITCH.

AF_TAG_SET_FLAGS: (uint32) Create. AF_INSF_ flags to set at creation time. Defaults to all cleared.

AF_TAG_START_TIME: (AudioTime) Query. Returns the AudioTime value of when the instrument was last started.

AF_TAG_STATUS: (uint32) Query. Returns the current instrument status: AF_STARTED, AF_RELEASED, AF_STOPPED, or AF_ABANDONED.

AF_TAG_TEMPLATE: (Item) Create. DSP Template Item used from which to create instrument. Note: this tag cannot be used with CreateInstrument().

AF_TAG_TIME_SCALE: (ufrac16) Start, Release. Scale times for all Envelopes attached to this Instrument. Original value is derived from the AF_TAG_TIME_SCALE; provided when the Envelope Attachment was made. This value remains in effect until another AF_TAG_TIME_SCALE is passed to StartInstrument() or ReleaseInstrument().

AF_TAG_VELOCITY: (uint32) Start. MIDI note velocity indicating the value to set instrument's Amplitude knob to before starting instrument (for instruments that have an Amplitude knob). Valid range is 0..127. Has no effect if Amplitude knob is connected to the output from another instrument. This tag is mutually exclusive with AF_TAG_AMPLITUDE.

Flags

AF_INSF_AUTOABANDON: When set, causes instrument to automatically go to the AF_ABANDONED state when stopped (either automatically because of an AF_ATTF_FATLADYSINGS flag, or manually because of a StopInstrument() call). Otherwise, the instrument goes to the AF_STOPPED state when stopped. Note that regardless of the state of this flag, instruments are created in the AF_STOPPED state.