StartInstrument
Begins playing an instrument (Note On).
Synopsis
Err StartInstrument (Item Instrument, TagArg *tagList)
Err StartInstrumentVA (Item Instrument, uint32 tag1, ...)
Description
This function begins execution of an instrument. This typically starts a sound but may have other results, depending on the nature of the instrument. This call links the DSP code into the list of active instruments. If the instrument has Samples or Envelopes attached, they will also be started (unless the Attachments specify otherwise). This is equivalent to a MIDI "Note On" event.
The Amplitude and Frequency knobs, of instruments that have such, can be tweaked by some of the tags listed below before the instrument is started. When none of the tags for a particular know are specified, that knob is left set to its previous value. At most one tag for each knob can be specified. Tags are ignored for Instruments without the corresponding knob. Knobs connected to the output of another Instrument (ConnectInstruments()), cannot be set in this manner. A Knob that has been grabbed, can however be set in this manner.
This function puts the instrument in the AF_STARTED state. If the instrument was previous running, it is first stopped and then restarted. If the instrument has a sustain or release loop, it stays in the AF_STARTED state until the state is explicitly changed (e.g. ReleaseInstrument(), StopInstrument()).
This function supersedes a call to PauseInstrument().
Arguments
- Instrument
- The item number for the instrument.
Tags
- Amplitude:
-
- AF_TAG_AMPLITUDE
- (uint32) Value to set instrument's Amplitude knob. Valid range is 0..0x7fff.
- AF_TAG_VELOCITY
- (uint32) MIDI note velocity indicating the value to set instrument's Amplitude knob. Valid range is 0..127.
Frequency:
- AF_TAG_FREQUENCY
- (ufrac16) Value to set Frequency knob to in 16.16 Hz.
- AF_TAG_PITCH
- (uint32) Value to set 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.
- AF_TAG_RATE
- (uint32) Value to set Frequency knob to in instrument-specific frequency units (e.g. phase increment, proportion of original sample rate).
Other:
- AF_TAG_TIME_SCALE
- (ufrac16) 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().
Return Value
The function returns a non-negative value if successful or an error code (a negative value) if an error occurs.
Implementation
SWI implemented in Audio folio V20.
Associated Files
audio.h
Caveats
Ideally this function should also use the MIDI note velocity specified by AF_TAG_VELOCITY to pick samples in a multisample (e.g. a pp piano sample versus a ff piano sound) based on AF_TAG_HIGHVELOCITY and AF_TAG_LOWVELOCITY sample settings. At present multisample selection ignores AF_TAG_HIGHVELOCITY and AF_TAG_LOWVELOCITY sample settings. This features cannot be added such that it would affect existing applications. If it were added, there would be some mechanism to enable it, for example a new tag for either Samples or StartInstrument().
See Also
ResumeInstrument(), StopInstrument(), PauseInstrument(), ReleaseInstrument(), Instrument