Audio Unit Properties
This section will describe the different properties that apply to Audio Units.
These will be dealt with in functional groups as listed below. The propertyID is
listed with the struct or type that represents the property's value. These
values are declared in AudioUnit/AudioUnitProperties.h
.
Important - these property values are always passed by reference to
both the Get and Set property calls (i.e. you pass a pointer to the type
specified).
Connection Management
kAudioUnitProperty_MakeConnection -
(AudioUnitConnection)
Use this property with AudioUnitSetProperty to establish a connection
between the destination unit (which is the Audio Unit that you make the call on)
and the source unit that is specified in the provided AudioUnitConnection
struct. In AudioUnitSetProperty you specify kAudioUnitScope_Input for the
AudioUnitScope parameter. The elementID is the input number upon which the
connection will be made (this is also redundantly stored in the
AudioUnitConnection)
kAudioUnitProperty_BusCount - (UInt32)
The scope is either kAudioUnitScope_Input or kAudioUnitScope_Output to
both get and set the number of input or output busses. By default many
Audio Units will create a single input or output bus (elementID), so this call is
generally used to create additional busses. A typical example would be the
interleaver or deinterleaver units where their behaviour is determined by the
number of in or out busses respectively. Other units, such as Mixer units, may
have already allocated the necessary state to accept a number of inputs, so this
call can be used to determine that limit.
kAudioUnitProperty_SetRenderCallback -
(AURenderCallbackStruct)
This is used with a AudioUnitSetProperty call on a V2 Audio Unit (i.e.
where the Component's type is not kAudioUnitComponentType). This (and the
corresponding kAudioUnitProperty_SetInputCallback
for the V1
Audio Unit) are used to register a callback with an Audio Unit to provide audio
data on the specified elementID (bus) of the input scope. When the Audio Unit
calls the render callback (or input callback for V1), it will provide a buffer
that the input callback should fill with data. When this property is set the
caller should also set the stream format property for that elementID (bus) of
the input scope to tell the Audio Unit what format the data is in that it will be
providing (see kAudioUnitProperty_StreamFormat
).
kAudioUnitProperty_SetInputCallback -
(AudioUnitInputCallback)
This is used with a AudioUnitSetProperty call on a V1 Audio Unit (i.e.
where the Component's type is kAudioUnitComponentType).
Format Negotiation
kAudioUnitProperty_StreamFormat -
(AudioStreamBasicDescription)
Typically kAudioUnitScope_Input or kAudioUnitScope_Output are passed in for
the AudioUnitScope and the bus number (zero based) is specified in the
elementID. This completely specifies the format that exists on the specified
scope. Some units can take this property on the kAudioUnitScope_Global, which
will generally mean either (the common case) that the formats are the same on
both input and output, or that the audio unit can internally process data in a
different format than its in and out formats (less typical, but possible). See
kAudioUnitProperty_SpeakerConfiguration
for more complex rendering
processes involving audio spatialization.
kAudioUnitProperty_SampleRate - Float64
This is a convenience property of the complete
kAudioUnitProperty_StreamFormat
above. However, it is particularly
useful in those cases where an application wishes to track the sample rate of an
Audio Unit, for example, in the case of an AudioDeviceID unit where the user may
change its sample rate independently of the application. This can also be used
of course to set the sample rate of an input or output element.
kAudioUnitProperty_SupportedNumChannels -
(AUChannelInfo)
If not implemented, the Audio Unit is agnostic about the number of
channels and only a format setting can validate whether the channels are
accepted. Generally, this will mean (particularly with Effect Units) that any
number of channels are usable as long as there is the same number of channels on
both the input and output scopes. Other units can accept a mismatch in the
channelisation of their busses, thus this property is provide to allow those
units to publish the allowable channel configurations that can be accepted on
input and output.
Returns pairs of num channels (e.g. 1in, 1out, 1in2 out, 2in 2out,
etc...) If a value of -1 is seen, then this can be interpretted as "any" num
channels for that scope.
Parameters
kAudioUnitProperty_ParameterList -
(AudioUnitParameterID)
The caller specifies the AudioUnitScope to be queried for its
parameters. Most effect units will define parameters in the global scope (as the
unit itself applies the parameters to the work it does). A mixer unit will
typically define parameters in both the input (apply different volumes to each
input) and output scopes (the overall volume of the mix). The call will return a
list of AudioUnitParameterIDs, which can then be used with
kAudioUnitProperty_ParameterInfo
to obtain information about the
parameter.
Some parameters range may change depending on characteristics of
the formats the Audio Unit is operating in. For instance, a common case is a Hz
parameter in an effect, where the real limitation (max value) of this parameter
will vary based on the sample rate that the unit is operating at. In this case,
if the sample rate of an audio unit is changed, a notification can be sent for
this property change and the application can then re-present the new max value
of the Hz parameter at this new sample rate.
kAudioUnitProperty_ParameterInfo -
(AudioUnitParameterInfo)
The caller passes in the desired AudioUnitScope, AudioUnitElement for
the AudioUnitParameterID in the AudioUnitGetProperty call to obtain information
about a particular parameter.
kAudioUnitProperty_ParameterValueStrings -
(CFArrayRef)
The caller passes in the desired AudioUnitScope, AudioUnitElement for
the AudioUnitParameterID and receives an array of CFString's corresponding to
the discrete integral values of the parameter. Only valid for parameters which
have a unit of kAudioUnitParameterUnit_Indexed
. Caller is
responsible for releasing the array, which will in turn release the contained
CFStrings.
kAudioUnitProperty_MIDIControlMapping -
(AudioUnitMIDIControlMapping)
The caller passes in global scope, the elementID ignored. It returns an
array of AudioUnitMIDIControlMapping's, specifying a default mapping of MIDI
controls and/or NRPN's to Audio Unit scopes/elements/parameters.
For more detailed information on these properties see the section on Parameter Types and
Information.
Buffer Management
kAudioUnitProperty_MaximumFramesPerSlice -
(UInt32)
This call should be used if an Audio Unit is going to be asked a
particularly large buffer. This then allows the unit to pre-allocate enough
memory for any computations and output that it may have to have buffers for
(including the buffer that it can pass to a RenderCallback). This avoids
allocation in the render process, or a failure in the render process, because
the unit is asked to produce more data than it is able to at any given time.
kAudioUnitProperty_SetExternalBuffer -
(AudioUnitExternalBuffer)
A new property for the V2 Audio Unit, and should be set on a global
scope. Sophisticated hosting of audio units can use this property to better
manage the memory usage and performance of a graph of audio units, for instance
allowing for the reuse of buffers in a chain.
Basically, the behaviour of this is, if set, an Audio Unit can and
should use this buffer to pull its inputs (as a v2 AU MUST provide a buffer when
calling the RenderCallback on its inputs. It would use this instead of an
internally created buffer.
Rendering Properties
kAudioUnitProperty_Latency - (Float64)
The input to output latency in seconds. Audio Units which use delay or
reverb or similar should report zero latency since the delay is part of the
desired effect (presuming of course that they do not have any start up
latency!). Look-ahead compressors/limiters, pitch-shifters, phase-vocoders,
buffering Audio Units, etc. may have an in to out latency on the samples that
they process, and should report this. Applications can use this to account for
this latency.
kAudioUnitProperty_RampUpTime - (Float64)
Most Audio Units will report 0.0 for this value. The value represents
the amount of time (in seconds) for the internal DSP code to reach steady state
as soon as an input signal is applied - for example, the amount of time a
compressor takes to react to its input signal and scale its gain. This value
does not have to be exact - it could be a conservative estimate (greater than
the actual value).
kAudioUnitProperty_TailTime - (Float64)
Many Audio Units will report 0.0 for this value. This value represents
the amount of time for the output signal to die down to nothing (defined here as
less than -120dB of full scale). For example, a reverb effect having a tail
would take a certain amount of time (say 2 seconds) for its output to go to
silence after its input signal goes to silence. This value does not have to be
exact. It could be a conservative estimate (greater than the actual value).
kAudioUnitProperty_BypassEffect - (UInt32)
Can be used to have an effect unit not apply its processing on its
input, but just pass it through to the output without processing it.
kAudioUnitProperty_LastRenderError -
(OSStatus)
This is a read only property that returns the last error code returned
by RenderSlice, and clears it. Rather than polling this property, it's best that
interested clients install a property listener on it.
Performance Properties
kAudioUnitProperty_FastDispatch - (Function
Pointer)
The inElement value is the component selector that describes to the unit
what the function pointer corresponds to. Dispatching through the Component API
calls has some overhead that can and should be avoided in the rendering and
parameter setting calls where a real-time context is normally required.
kAudioUnitProperty_CPULoad - (Float32)
Is used to specify to the Audio Unit the desired load that it should
limit its rendering times to that limit. The property is specified with a range
of 0 to 1. A value of zero means no limitation - and represents a way to turn
this limitation off, desirable for instance when doing off-line rendering.
kAudioUnitProperty_RenderQuality -
(UInt32)
Provides a quality range (0->0x7F) that an audio unit can use to decide
how high a quality it uses when doing its rendering (which generally trades off
the amount of CPU that is consumed). Currently both the DLS Synth and the Reverb
use this to scale back the quality of their rendering. Generally the
kRenderQuality enum settings should be used, however some units may respond to
intermediate values. In those that don't, the quality is rounded to the nearest
value as represented by this enum.
Audio Unit View and Host Properties
kAudioUnitProperty_GetUIComponentList -
(ComponentDescription)
Returns an array of ComponentDescriptions specifying AudioUnitCarbonView
components designed to present user interfaces for editing this Audio Unit.
kAudioUnitProperty_ContextName -
(CFStringRef)
Allows an application to provide a name that can be presented to the
user that specifies the context of a specific unit. For instance, I can have 3
instances of the same reverb unit, 1 on channel 4, the second on channel 5. This
allows the host to present to the user "Channel 4:AUMatrixReverb".
The host can either specify any name for the Audio Unit and then
sets this property to tell the unit the name that is being used to display to
the unit. Thus, if unit is putting up some UI, it can use this name to be
consistent. No default name is expected to be provided - in that case the
ComponentInfo call could be used to provide the name to the user.
kAudioUnitProperty_HostCallbacks -
(HostCallbackInfo)
Used by the host to provide callbacks that an Audio Unit can use to
obtain runtime information from the host that it otherwise cannot find out
about.
Currently the struct passed in provides a single function pointer
that is used to determine both the current beat and tempo. This will generally
be defined to return that information for the particular buffer of audio the
unit has been asked to render. This is useful for those units that are able to
match their DSP to a beat based value.. (For instance, a delay time, that is one
delay per beat, where this changes based on the tempo).
If the property is supported and a host is using beats (e.g.
MusicSequence) to schedule events, then the scheduler should query any of its
units and be prepared to provide that information when asked. When this property
is set the host may pass in a value for hostUserData. The Audio Unit MUST provide
this in the inHostUserData argument when calling out to the host.
Audio Unit Presets and Persistence
kAudioUnitProperty_ClassInfo - (CFPropertyListRef,
dictionary)
CFPropertyListRef dictionary is a constrained subset of a CFDictionary
that uses CFStrings as keys, and whose values can only be CFPropertyListRefs
(which includes CFStrings, CFNumbers, CFData, or arrays/dictionaries whose
values and keys are constrained in this same way).
The dictionary contains several key/value pairs:
- name
- a CFString that is the name associated with the current
preset
- version
- a CFNumber that represents the version of the class
data
- type
- a CFNumber that represents the componentType of the
Audio Unit as defined by its ComponentDescription
- subtype
- a CFNumber that represents the componentSubType of the
Audio Unit as defined by its ComponentDescription
- manufacturer
- a CFNumber that represents the componentManufacturerID of
the Audio Unit as defined by its ComponentDescription
- data
- Audio Unit-specific internal state, contained in a CFDataRef
- currently this is the value of each of the parameters, on each element of each
scope.
On exit from GetProperty, the client owns a reference to the
CFPropertyListRef. SetProperty does not consume (release) a reference to the
CFPropertyListRef.
The name field is filled in by finding the last preset that was
currently set on the unit (whether factory or ClassInfo). The name will be
"Untitled" if the unit has no presets, and the ClassInfo has never been set.
The dictionary can be parsed using the appropriate CoreFoundation
calls. The class data contains enough information to establish a
ComponentDescription that can then be used to find and open the appropriate
Audio Unit, open it, and then re-establish the state as saved in the dictionary.
As this currently only contains the parameter values (for Apple's Audio Units as
shipped in 10.2) this may not be complete for some units. For example, the name of
the SoundBank for the DLSMusicDevice is not currently saved in the class data.
It is anticipated that properties that are needed to reestablish the complete
state of an Audio Unit will be saved in future release (and consequently, the
version number of the class data will be revised).
kAudioUnitProperty_CurrentPreset -
(AUPreset)
Read:
This can be used by the caller to identify the current preset of the
unit. This behaves differently for handling both Factory Presets and User states
(ClassInfo). If the last state set is a factory preset (i.e. no call to set
ClassInfo has been made), then the AUPreset contains both a valid number
(greater than or equal to zero) and name (the number and name of the appropriate
factory preset). If the unit has factory presets, then the first time this
property is queried, it returns the default preset.
If a set
ClassInfo property was the last call made, then the AUPreset will contain a
number of -1 (signifying User preset), and the name contained within the class
info. If the name has not been set, you get a default name, such as
"Untitled".
Write:
The number in AUPreset is used to select the preset.
If presetNumber is equal to or greater than zero (factory preset):
Set the state of the unit to one of the factory presets. The caller
provides an AUPreset (from kAudioUnitProperty_FactoryPresets), and this becomes
the current state of the unit. kAudioUnitErr_InvalidPropertyValue is returned if
the preset number is not recognised by the Audio Unit.
If presetNumber is less than zero: (signifying a user preset)
Sets the current preset for the unit (including the name supplied in
presetName). This name will then be saved into the unit's data when getting the
current state of the ClassInfo property. This allows the name of a state to be
saved along with the state so it can be shown to the user when that state is
re-established.
kAudioUnitProperty_FactoryPresets -
(CFArray)
Returns an array of AUPreset that contain a number and name for each of
the presets. The number of each preset must be greater (or equal to) zero, and
the numbers need not be ordered or contiguous. The name of each preset can be
presented to the user as a means of identifying each preset. The CFArray should
be released by the caller.
Internal Algorithm Configuration
kAudioUnitProperty_ReverbRoomType -
(UInt32)
The caller should pass in one of the kReverbRoomType enum values. This
property is supported by those units that implement the
kAudioUnitProperty_UsesInternalReverb
(DLSMusicDevice, 3DMixer) as
well as the MatrixReverb unit.
kAudioUnitProperty_UsesInternalReverb -
(UInt32)
Some audio units can use an internal reverb. The 3DMixer and the
DLSMusicDevice both have this property on by default (value==1). To turn this
off, set the value of this property to zero.
kAudioUnitProperty_SRCAlgorithm - (UInt32)
The value is an identifier for the sample rate converter algorithm to
use. This is currently supported by the AUConverter unit and the OutputDevice
units.
MusicDevice Properties
kMusicDeviceProperty_InstrumentCount -
(UInt32)
This returns the number of instruments that are able to be used by a
MusicDevice Audio Unit. In the DLSMusicDevice this returns the number of
instruments that are in the DLS or SoundFont collection that is currently set on
this unit.
kMusicDeviceProperty_InstrumentName -
(char)
The MusicDeviceInstrumentID is passed in for the inElement argument,
and the call returns the name for that instrumentID.
kMusicDeviceProperty_InstrumentNumber
The caller passes in the instrument "index" in the inElement argument.
This "index" is zero-based and must be less than the number of instruments
(determined using the kMusicDeviceProperty_InstrumentCount property).
The value passed back will be a MusicDeviceInstrumentID. This
MusicDeviceInstrumentID may then be used with the
kMusicDeviceProperty_InstrumentName property, or in any of the MusicDevice calls
which take a MusicDeviceInstrumentID argument.
This value is further expected to be formatted in a particular
manner relating to the bank and patch number values of MIDI. The number is
formatted as 0xMMLLPP, where the lowest byte is the patch number of the
instrument, the second byte the LSB of the instrument's bank select, and the 3rd
byte, the MSB of the instrument's bank select.
kMusicDeviceProperty_SoundBankFSSpec -
(FSSpec)
This property is used with a MusicDevice that requires sample data to
be used as a source for its rendering. The DLSMusicDevice will accept both
DownLoadable Sound files and Sound Fonts as the sample data for its
intruments.
kMusicDeviceProperty_BankName -
(CFStringRef)
Returns the name of the currently loaded sound bank of the
DLSMusicDevice. The CFStringRef should be released by the caller.
kMusicDeviceProperty_GroupOutputBus -
(UInt32)
The caller passes in MusicDeviceGroupID for the AudioUnitElement and
kAudioUnitScope_Group for the AudioUnitScope. The caller should pre-assign the
number of busses that are going to be assigned using this call. Then, when this
property is set, any notes that are produced on a particular group (which can be
considered as equivalent to a MIDI Channel for the moment) will be produced on
this assigned bus. This property is implemented by the DLSMusicDevice.
kMusicDeviceProperty_MIDIXMLNames -
(CFURLRef)
Returns a URL to a MIDINameDocument describing the MusicDevice's patch,
note and control names.
AudioDeviceID Properties
kAudioOutputUnitProperty_CurrentDevice -
(AudioDeviceID)
Will return the AudioDeviceID of any Audio Unit that is set (or will
track) and AudioDevice. The property can be set on some Audio Units, but not on
others.
OutputUnit Properties
kAudioOutputUnitProperty_IsRunning -
(UInt32)
This value is initially set to 0 (false). When AudioOutputUnitStart is
called the value of this property is 1 (true), and when AudioOutputUnitStop is
consequently called the value is again zero. Audio Units do not count the number
of times that their start or stop methods are called.
3D and Spatialization Properties
kAudioUnitProperty_SpeakerConfiguration -
(UInt32)
This is a property that is typically supported by Audio Units that
generate content that corresponds to common multi-channel formats. Currently the
following values are defined for this property. When this property is supported
it should be used over the kAudioUnitProperty_StreamFormat
as the
stream format doesn't describe sufficient information to the renderer when
applying spatialization techniques.
kSpeakerConfiguration_HeadPhones
- Used to signify that the rendering should be based on the user
listening with headphones
kSpeakerConfiguration_Stereo
- Used to signify that stereo speakers will be used. The channel
ordering is Left/Right. Stereo speakers are generally expected to be 30 degrees
to the left and right respectively of the listener
kSpeakerConfiguration_Quad
- Used to signify that quad speakers will be used. The channel
ordering is Left/Right/Rear Left/Rear Right. Generally these speakers are place
in a square around the listener, where the listener is located in the center of
the square.
kSpeakerConfiguration_5_1
- Used to signify a 5.1 speaker configuration. The channel
ordering is Left/Right/Rear Left/Rear Right/Center/Sub. Often, an Audio Unit
generating content for this configuration will olny generate 5 channels of data
(not 6). This channel ordering is expected to be observed for this value (even
though there are other channel orderings for 5.1 content that are also in common
usage.
kAudioUnitProperty_SpatializationAlgorithm -
(UInt32)
The caller passes in one of the kSpatializationAlgorithm enum values to
specify which particular algorithm should be applied on the specified scope
(input for the 3DMixer) and elementID (bus number). This allows different inputs
to the 3DMixer to have different spatialization algorithms applied to each
input.
kAudioUnitProperty_DopplerShift - (UInt32)
A value of 1 will enable the application of DopplerShift to a moving
source in the 3DMixer unit.