Audio Unit Properties Reference

Overview

Audio unit properties, part of the audio unit plug-in interface, are key-value pairs that declare attributes or behavior such as audio data stream format, latency, or connection from one audio unit to another. Properties are typically non-time-varying, not directly settable by the user, and changeable only before an audio unit is initialized. This document describes audio unit property identifiers and their accompanying values.

You access audio unit properties using the Audio Unit framework’s “Get” and “Set” functions, described in Audio Unit Component Services Reference. These functions are:

• AudioUnitGetPropertyInfo

• AudioUnitGetProperty

• AudioUnitSetProperty

So-called generic audio unit properties are those that can apply to any audio unit. There are also Apple-specific properties that apply only to Apple-supplied audio units. This document describes both. Apple reserves property IDs from 0 through 63999; you may use property IDs above this range.

In addition to its value, the attributes of an audio unit property are as follows:

• Scope—the programmatic context, within an audio unit, that the property applies to. A property applies to one or more scopes, as described in this document. The audio unit scopes in iOS are Input, Output, and Global. In OS X, audio units have additional, MIDI-related scopes: Group, Part, and Note.

• Data type—the programmatic data type for the property’s value.

• Access—read-only, write-only, or read/write.

Functions

This chapter describes the function-like macros declared in the AudioUnitProperties.h header file. You can use these macros to work with an audio unit parameter’s display types—one of the attributes specified by the flags field in the AudioUnitParameterInfo data structure.

AudioUnitDisplayTypeIsCubed

Determines if the display type is cubed.

#define AudioUnitDisplayTypeIsCubed (flags) (
   GetAudioUnitParameterDisplayType (flags) ==
   kAudioUnitParameterFlag_DisplayCubed
)

AudioUnitDisplayTypeIsCubeRoot

Determines if the display type is cube root.

#define AudioUnitDisplayTypeIsCubeRoot (flags) (
   GetAudioUnitParameterDisplayType (flags) ==
   kAudioUnitParameterFlag_DisplayCubeRoot
)

AudioUnitDisplayTypeIsExponential

Determines if the display type is exponential.

#define AudioUnitDisplayTypeIsExponential (flags) (
   GetAudioUnitParameterDisplayType (flags) ==
   kAudioUnitParameterFlag_DisplayExponential
)

AudioUnitDisplayTypeIsLogarithmic

Determines if the display type is logarithmic.

#define AudioUnitDisplayTypeIsLogarithmic (flags) (
   GetAudioUnitParameterDisplayType (flags) ==
   kAudioUnitParameterFlag_DisplayLogarithmic
)

AudioUnitDisplayTypeIsSquared

Determines if the display type is squared.

#define AudioUnitDisplayTypeIsSquared (flags) (
   GetAudioUnitParameterDisplayType (flags) ==
   kAudioUnitParameterFlag_DisplaySquared
)

AudioUnitDisplayTypeIsSquareRoot

Determines if the display type is square root.

#define AudioUnitDisplayTypeIsSquareRoot (flags) (
   GetAudioUnitParameterDisplayType (flags) ==
   kAudioUnitParameterFlag_DisplaySquareRoot
)

GetAudioUnitParameterDisplayType

Gets the display type for a parameter.

#define GetAudioUnitParameterDisplayType (flags) (
   (flags) & kAudioUnitParameterFlag_DisplayMask
)

SetAudioUnitParameterDisplayType

Sets the display type.

#define SetAudioUnitParameterDisplayType (flags, displayType) (
   ((flags) & ~kAudioUnitParameterFlag_DisplayMask) | (displayType)
)

Callbacks by Task

Timing and Transport Callback Functions

Audio unit host applications can implement these callback functions to provide information to audio units.

• HostCallback_GetBeatAndTempo
• HostCallback_GetMusicalTimeLocation
• HostCallback_GetTransportState

Callbacks

HostCallback_GetBeatAndTempo

When called by the system, provides beat and tempo information to an audio unit from a host application.

typedef OSStatus (*HostCallback_GetBeatAndTempo) (
   void      *inHostUserData,
   Float64   *outCurrentBeat,
   Float64   *outCurrentTempo
);

If you named your callback function MyHostCallback_GetBeatAndTempo, you would declare it like this:

OSStatus MyHostCallback_GetBeatAndTempo (
   void      *inHostUserData,
   Float64   *outCurrentBeat,
   Float64   *outCurrentTempo
);

HostCallback_GetMusicalTimeLocation

When called by the system, provides musical timing information to an audio unit from a host application.

typedef OSStatus (*HostCallback_GetMusicalTimeLocation) (
   void     *inHostUserData,
   UInt32   *outDeltaSampleOffsetToNextBeat,
   Float32  *outTimeSig_Numerator,
   UInt32   *outTimeSig_Denominator,
   Float64  *outCurrentMeasureDownBeat
);

If you named your callback function MyHostCallback_GetMusicalTimeLocation, you would declare it like this:

OSStatus MyHostCallback_GetMusicalTimeLocation (
   void     *inHostUserData,
   UInt32   *outDeltaSampleOffsetToNextBeat,
   Float32  *outTimeSig_Numerator,
   UInt32   *outTimeSig_Denominator,
   Float64  *outCurrentMeasureDownBeat
);

HostCallback_GetTransportState

When called by the system, provides audio transport state and timeline information to an audio unit from a host application.

typedef OSStatus (*HostCallback_GetTransportState) (
   void     *inHostUserData,
   Boolean  *outIsPlaying,
   Boolean  *outTransportStateChanged,
   Float64  *outCurrentSampleInTimeLine,
   Boolean  *outIsCycling,
   Float64  *outCycleStartBeat,
   Float64  *outCycleEndBeat
);

If you named your callback function MyHostCallback_GetTransportState, you would declare it like this:

OSStatus MyHostCallback_GetTransportState (
   void     *inHostUserData,
   Boolean  *outIsPlaying,
   Boolean  *outTransportStateChanged,
   Float64  *outCurrentSampleInTimeLine,
   Boolean  *outIsCycling,
   Float64  *outCycleStartBeat,
   Float64  *outCycleEndBeat
);

Data Types

AUChannelInfo

The audio input and output channel capabilities for an audio unit.

typedef struct AUChannelInfo {
   SInt16   inChannels;
   SInt16   outChannels;
} AUChannelInfo;

Fields

inChannels

The number of input channels.

outChannels

The number of output channels.

AUDependentParameter

An audio unit parameter whose value can change in response to a change in its parent metaparameter.

typedef struct AUDependentParameter {
   AudioUnitScope        mScope;
   AudioUnitParameterID  mParameterID;
} AUDependentParameter;

Fields

mScope

mParameterID

AudioOutputUnitStartAtTimeParams

A timestamp for scheduled starting of an I/O audio unit.

typedef struct AudioOutputUnitStartAtTimeParams {
   AudioTimeStamp  mTimestamp;
   UInt32          mFlags;
} AudioOutputUnitStartAtTimeParams;

Fields

mTimestamp

mFlags

AudioUnitConnection

An audio unit source-to-destination connection specification.

typedef struct AudioUnitConnection {
   AudioUnit    sourceAudioUnit;
   UInt32       sourceOutputNumber;
   UInt32       destInputNumber;
} AudioUnitConnection;

Fields

sourceAudioUnit

The audio unit that is serves as the source in the connection.

sourceOutputNumber

The source audio unit’s output element to be used in the connection.

destInputNumber

The destination audio unit’s input element to be used in the connection.

AudioUnitExternalBuffer

Allows an audio unit host application to tell an audio unit to use a specified buffer for its input callback.

typedef struct AudioUnitExternalBuffer {
   Byte     *buffer;
   UInt32   size;
} AudioUnitExternalBuffer;

Fields

buffer

size

AudioUnitFrequencyResponseBin

An audio unit’s audio level at a particular frequency.

typedef struct AudioUnitFrequencyResponseBin {
   Float64   mFrequency;
   Float64   mMagnitude;
} AudioUnitFrequencyResponseBin;

Fields

mFrequency

mMagnitude

AudioUnitMeterClipping

Audio clipping that has occurred in a mixer unit.

typedef struct AudioUnitMeterClipping {
   Float32    peakValueSinceLastCall;
   Boolean    sawInfinity;
   Boolean    sawNotANumber;
} AudioUnitMeterClipping;

Fields

peakValueSinceLastCall

The maximum value seen on the channel since the last time the property was retrieved.

sawInfinity

TRUE if there was an infinite value on this channel since the last time the property was retrieved.

sawNotANumber

TRUE if there was a floating point “not a number” value on this channel since the last time the property was retrieved.

AudioUnitParameterUnit

The unit-of-measure for an audio unit parameter.

typedef UInt32  AudioUnitParameterUnit;

AudioUnitParameterInfo

typedef struct AudioUnitParameterInfo {
   char                      name[52];
   CFStringRef               unitName;
   UInt32                    clumpID;
   CFStringRef               cfNameString;
   AudioUnitParameterUnit    unit;
   AudioUnitParameterValue   minValue;
   AudioUnitParameterValue   maxValue;
   AudioUnitParameterValue   defaultValue;
   UInt32                    flags;
} AudioUnitParameterInfo;

Fields

name

Must be set to 0.

unitName

If kAudioUnitParameterUnit_CustomUnit is set, this field must contain a valid CFString object. Only valid if kAudioUnitParameterUnit_CustomUnit is set.

clumpID

Only valid if kAudioUnitParameterFlag_HasClump is set.

cfNameString

Only valid if kAudioUnitParameterFlag_HasCFNameString is set.

unit

If the unit field contains a value not in the AudioUnitParameterUnit enumeration, then assume the unit type is kAudioUnitParameterUnit_Generic.

minValue

maxValue

defaultValue

flags

Due to some vagaries about the ways in which Parameter's CFNames have been described, it was necessary to add a flag: kAudioUnitParameterFlag_CFNameRelease. In normal usage a parameter name is essentially a static object, but sometimes an audio unit will generate parameter names dynamically. As these are expected to be CFString objects, in that case the host should release those names when it is finished with them, but there was no way to communicate this distinction in behavior. Thus, if an audio unit can generate a name dynamically, it should set this flag in the parameter's info. The host should check for this flag and, if present, release the parameter name when it is finished with it.

AudioUnitParameterHistoryInfo

The suggested update rate and history duration for parameters which have the kAudioUnitParameterFlag_PlotHistory flag set.

typedef struct AudioUnitParameterHistoryInfo {
   Float32  updatesPerSecond;
   Float32  historyDurationInSeconds;
} AudioUnitParameterHistoryInfo;

AUInputSamplesInOutputCallbackStruct

The callback function and custom data for providing input-to-output sample mapping for an audio unit.

typedef struct AUInputSamplesInOutputCallbackStruct {
   AUInputSamplesInOutputCallback  inputToOutputCallback;
   void                            *userData;
} AUInputSamplesInOutputCallbackStruct;

Fields

inputToOutputCallback

The callback function that provides input-to-output sample mapping for an audio unit.

userData

Custom data for input-to-output sample mapping for an audio unit.

AUPreset

Used to set factory presets for an audio unit.

typedef struct AUPreset {
   SInt32        presetNumber;
   CFStringRef   presetName;
} AUPreset;

Fields

presetNumber

If less than 0, then the preset is a user preset. If greater than or equal to 0, then this field is used to select a factory preset.

presetName

If a factory preset, the name of the specified factory preset.

AURenderCallbackStruct

Used for registering an input callback function with an audio unit.

typedef struct AURenderCallbackStruct {
   AURenderCallback  inputProc;
   void              *inputProcRefCon;
} AURenderCallbackStruct;

Fields

inputProc

inputProcRefCon

HostCallbackInfo

The time- and transport-related callback functions for an audio unit.

typedef struct HostCallbackInfo {
   void                                 *hostUserData;
   HostCallback_GetBeatAndTempo         beatAndTempoProc;
   HostCallback_GetMusicalTimeLocation  musicalTimeLocationProc;
   HostCallback_GetTransportState       transportStateProc;
} HostCallbackInfo;

Fields

hostUserData

Custom data specified by your application. May be NULL.

beatAndTempoProc

Your callback function that provides beat and tempo information to an audio unit. May be NULL.

musicalTimeLocationProc

Your callback function that provides musical timeline information to an audio unit. May be NULL.

transportStateProc

Your callback function that provides audio transport state information (play, rewind, and so on) to an audio unit. May be NULL.

MixerDistanceParams

typedef struct MixerDistanceParams {
   Float32    mReferenceDistance;
   Float32    mMaxDistance;
   Float32    mMaxAttenuation;    // in decibels
} MixerDistanceParams;

Fields

mReferenceDistance

mMaxDistance

mMaxAttenuation

ScheduledAudioFileRegion

struct ScheduledAudioFileRegion {
   AudioTimeStamp                          mTimeStamp;
   ScheduledAudioFileRegionCompletionProc  mCompletionProc;
   void                                    *mCompletionProcUserData;
   struct OpaqueAudioFileID                *mAudioFile;
   UInt32                                  mLoopCount;
   SInt64                                  mStartFrame;
   UInt32                                  mFramesToPlay;
};

Fields

mTimeStamp

mCompletionProc

may be NULL

mCompletionProcUserData

mAudioFile

Must be a valid and already-open audio file object (of type AudioFileID), as declared in AudioToolbox/AudioFile.h.

mLoopCount

0 = do not loop

mStartFrame

The frame offset into the file.

mFramesToPlay

The number of frames to play.

Constants

Audio Unit Scopes

Programmatic roles and contexts for audio unit properties.

enum {
   kAudioUnitScope_Global = 0,
   kAudioUnitScope_Input  = 1,
   kAudioUnitScope_Output = 2,
   kAudioUnitScope_Group  = 3,
   kAudioUnitScope_Part   = 4,
   kAudioUnitScope_Note   = 5
};

Constants

kAudioUnitScope_Global

The context for audio unit characteristics that apply to the audio unit as a whole.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitScope_Input

The context for audio data coming into an audio unit.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitScope_Output

The context for audio data leaving an audio unit.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitScope_Group

In OS X, a context specific to the control scope of audio unit parameters.

Available in iOS 5.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitScope_Part

In OS X, a distinct rendering context; for example, a single timbre in a multitimbral instrument or a single loop in a multi-looping-capable looper unit.

Available in iOS 5.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitScope_Note

In OS X, a scope for changes to an individual musical note. The element identifier used with this scope is the unique note identifier returned from a started note (see the MusicDeviceStartNote function in AudioUnit/MusicDevice.h).

Available in iOS 5.0 and later.

Declared in AudioUnitProperties.h.

Generic Audio Unit Properties

Properties that apply to any audio unit.

enum {
   kAudioUnitProperty_ClassInfo                  = 0,
   kAudioUnitProperty_MakeConnection             = 1,
   kAudioUnitProperty_SampleRate                 = 2,
   kAudioUnitProperty_ParameterList              = 3,
   kAudioUnitProperty_ParameterInfo              = 4,
   kAudioUnitProperty_StreamFormat               = 8,
   kAudioUnitProperty_ElementCount               = 11,
   kAudioUnitProperty_Latency                    = 12,
   kAudioUnitProperty_SupportedNumChannels       = 13,
   kAudioUnitProperty_MaximumFramesPerSlice      = 14,
   kAudioUnitProperty_AudioChannelLayout         = 19,
   kAudioUnitProperty_TailTime                   = 20,
   kAudioUnitProperty_BypassEffect               = 21,
   kAudioUnitProperty_LastRenderError            = 22,
   kAudioUnitProperty_SetRenderCallback          = 23,
   kAudioUnitProperty_FactoryPresets             = 24,
   kAudioUnitProperty_RenderQuality              = 26,
   kAudioUnitProperty_InPlaceProcessing          = 29,
   kAudioUnitProperty_ElementName                = 30,
   kAudioUnitProperty_SupportedChannelLayoutTags = 32,
   kAudioUnitProperty_PresentPreset              = 36,
   kAudioUnitProperty_ShouldAllocateBuffer       = 51,
   kAudioUnitProperty_ParameterHistoryInfo       = 53,
   
   kAudioUnitProperty_CPULoad                    = 6,
   kAudioUnitProperty_ParameterValueStrings      = 16,
   kAudioUnitProperty_HostCallbacks              = 27,
   kAudioUnitProperty_OfflineRender              = 37,
   kAudioUnitProperty_DependentParameters        = 45,
   kAudioUnitProperty_InputSamplesInOutput       = 49,
   kAudioUnitProperty_FrequencyResponse          = 52
};

Constants

kAudioUnitProperty_ClassInfo

Describes the state of an audio unit.

A read/write CFDictionaryRef object valid on the audio unit global scope. An OS X audio unit that supports the part scope may, in addition, support presets on that scope that apply to individual parts.

When assigning a class information dictionary to an audio unit with the AudioUnitSetProperty function, you own the reference to the dictionary and are responsible for later releasing it by calling the CFRelease function.

When obtaining a class information dictionary from an audio unit with the AudioUnitGetProperty function, you also own the reference to the dictionary and are responsible for later releasing it by calling the CFRelease function.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_MakeConnection

A write-only AudioUnitConnection data structure valid on the audio unit input scope.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_SampleRate

A read/write Float64 value valid on the audio unit input and output scopes.

The audio sample rate for a specified scope.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_ParameterList

A list of read-only AudioUnitParameterID values valid on any audio unit scope.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_ParameterInfo

A read-only AudioUnitParameterInfo data structure valid on any audio unit scope.

Characteristics for an audio unit parameter including minimum, maximum, and default values; full parameter name; and so on. For a shortened version of an audio unit parameter name suitable for compact display situations, see the kAudioUnitProperty_ParameterIDName property.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_StreamFormat

The audio data stream format for an audio unit input or output element (also called bus).

A read/write AudioStreamBasicDescription data structure valid on the audio unit input and output scopes.

An AudioStreamBasicDescription struct does not specify channel layout or purpose. To specify a channel layout, use the kAudioUnitProperty_AudioChannelLayout property.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_ElementCount

A read/write UInt32 value valid on any audio unit scope. The global audio unit scope always has an element count of 1.

Most audio units implement this property as read-only, indicating that they use a fixed number of input and output buses. An audio unit implemented to support adding and removing buses implements this property as read/write.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_Latency

A read-only Float64 value valid on the audio unit global scope.

The time, in seconds, that it takes an audio unit to move an audio sample from its input to its output.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_SupportedNumChannels

A read-only array of AUChannelInfo structures valid on the audio unit global scope.

The size of the array indicates the number of AUChannelInfo structures for an audio unit. Each structure describes the channel configuration for an audio input/output bus. For example, the values (2, 2) indicates a channel configuration of two input channels paired to two output channels on a bus.

A negative value for a field in an AUChannelInfo structure indicates that an input/output bus supports a variable number of channels, as follows:

• {–1, –1} indicates that a bus supports any number of input or output channels provided that the input and output channel counts match each other. This is the default configuration for effect units.

• {–1, –2} or {–2, –1} indicates that a bus supports any number of input and output channels; the channel counts on input and output can differ from each other.

• {–1, –3} indicates that a bus supports any number of input channels and up to three output channels.

A value of 0 for the inChannels field means that an audio unit does not have any audio input buses.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_MaximumFramesPerSlice

Specifies the maximum number of sample frames an audio unit is prepared to supply on one invocation of its AudioUnitRender function.

A read/write UInt32 value valid on the audio unit global scope.

The default value of this property is 1,024, corresponding to about 23 ms at a 44.1 kHz sample rate. This default value is sufficient when a host app is using the default hardware buffer size and the device screen is not sleeping. When the device screen sleeps, the system saves power by reducing the frequency at which it requests sample frames. There is a corresponding increase in the number of sample frames requested of an audio unit, per render call.

The following table provides some common slice sizes:

	Frame count	Milliseconds at 44.1 kHz (approximate)
Default	1024	23
Screen sleep	4096	93
Low latency	256	5

You never need to set this property for I/O units because they are preconfigured to handle any slice size requested by the system. For all other audio units, you must set this property to a value of 4096 to handle screen sleep—unless audio input is running on the device. When audio input is running, the system maintains a slice size of 1024.

Important: If audio input is not running and the device screen sleeps, and you have not set a value of 4096 on each non-I/O audio unit being used by your app, audio stops. Always set this property as described here.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_AudioChannelLayout

A read/write AudioChannelLayout data structure valid on the audio unit input and output scopes.

The channel order, within a given audio stream, for a specified audio unit element and scope. The number of channels in the layout must match the number of channels set for the scope-element. Each input and output bus in an audio unit can have one instance of this property.

Some audio units require this property. For example, the 3DMixer unit must implement this property on its output bus. If a host application attempts to clear the value of this property on a bus that requires a valid value, the audio unit will return a kAudioUnitErr_InvalidPropertyValue error.

Input and output buses can be in one of three states in regard to Audio channel layout:

1. Implemented and set

2. Implemented but not set

3. Unimplemented

Requesting the value of this property when it is implemented but not set results in a kAudioUnitErr_PropertyNotInUse error.

Use the kAudioUnitProperty_AudioChannelLayout property whenever channel layout is relevant.

For related information, refer to the descriptions for the ScheduledAudioFileRegion and AudioOutputUnitStartAtTimeParams data structures.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_TailTime

A read-only Float64 value valid on the audio unit global scope.

Indicates a time estimate, in seconds, between the last valid input being received by an audio unit and the audio unit’s output becoming silent. For example, a reverb unit’s tail time estimates the “decay” time. The tail time value is usually a conservative estimate that you can depend on.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_BypassEffect

A read/write UInt32 value, representing a Boolean value, valid on the audio unit global scope.

Indicates if an audio unit’s processing code is being bypassed (1) or not (0).

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_LastRenderError

A read-only OSStatus value valid on the audio unit global scope.

This property is set if a call to the AudioUnitRender function returns an error. To be notified of errors, register a callback function as a property listener using the AudioUnitAddPropertyListener function.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_SetRenderCallback

A write-only AURenderCallbackStruct data structure valid on the audio unit input scope.

Set this property to specify your callback function that provides audio samples to an audio unit. When you call the AudioUnitSetProperty function from your application to assign the callback, you specify the input bus that the callback applies to. See the AURenderCallback callback function.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_FactoryPresets

So-called factory presets (as opposed to user-configured presets) are ones supplied with an audio unit by the manufacturer. You choose the active preset by setting the kAudioUnitProperty_PresentPreset property.

A read-only CFArrayRef array of AUPreset structures.

When obtaining a factory preset array from an audio unit with the AudioUnitGetProperty function, you own the reference to the array and are responsible for later releasing it by calling the CFRelease function.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_RenderQuality

A read/write UInt32 value valid on the audio unit global scope.

A value in the range 0 through 127 that indicates an audio unit’s rendering quality. You should set this property to its maximum value unless doing so results in excessive CPU usage.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_InPlaceProcessing

A read/write UInt32 value, representing a Boolean value, valid on the audio unit global scope.

Indicates whether an audio unit can process input data directly within its input buffer (1) or not (0). You may want to disable in-place processing to allow your host application to manage the processing buffers.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_ElementName

The name of the specified element.

A read/write CFStringRef object valid on any audio unit scope.

When assigning an element name string to an audio unit with the AudioUnitSetProperty function, you own the reference to the name and are responsible for later releasing it by calling the CFRelease function.

When obtaining an element name string from an audio unit with the AudioUnitGetProperty function, you also own the reference to the name and are responsible for later releasing it by calling the CFRelease function.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_SupportedChannelLayoutTags

A read only array on AudioChannelLayoutTag structures, valid on the audio unit input and output scopes.

Used with GetProperty to ascertain what an audio unit understands about laying out of channel orders. This will normally return one or more of the specified layout tags.

When a specific set of layouts are returned, the client then uses the kAudioUnitProperty_AudioChannelLayout property (with one of those layout tags specified) to set the unit to use that layout. In this case the client (and the audio unit when reporting its AudioChannelLayout) is only expected to have set an AudioChannelLayout which only sets the layout tag as the valid field.

Some audio units may return the tag kAudioChannelLayoutTag_UseChannelDescriptions. This indicates a custom channel map.

In this case, the host then can look at supported number of channels on that scope (using the kAudioUnitProperty_SupportedNumChannels), and supply an AudioChannelLayout with the kAudioUnitProperty_AudioChannelLayout property to specify the layout, number of channels and location of each of those channels. This custom channel map MUST have a channel valence that is supported by the Audio Unit.

The UseChannelBitmap field is NOT used within the context of the AudioUnit.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_PresentPreset

The active factory preset for an audio unit.

A read/write AUPreset data structure valid on the audio unit global scope, The presetName field in the struct is of type CFStringRef and follows Core Foundation memory semantics.

When setting the active factory preset on an audio unit with the AudioUnitSetProperty function, you own the reference to the preset name and are responsible for later releasing it by calling the CFRelease function.

When obtaining the active factory preset from an audio unit with the AudioUnitGetProperty function, you also own the reference to the preset name and are responsible for later releasing it by calling the CFRelease function.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_ShouldAllocateBuffer

A read/write UInt32 value valid on the audio unit input and output scopes, settable individually on each element.

Default value is true, which means that the associated audio unit element creates a buffer for rendering into.

If true, the element will create a buffer for rendering into.

If false, the element will not create a buffer for rendering.

For example, if the audio unit is only ever going to have a connection as its input and never a callback, then it should not need to create a buffer (the API contract expects an audio unit to provide a buffer for callbacks, but no buffer for connections).

If the audio unit is always going to be pulled for audio with the client providing audio data buffers to the AudioUnitRender call, then it will never need to create an audio buffer on the output side.

So, this property can be used to control the default allocation strategy of an audio unit. If the audio unit needs a buffer, but one hasn't been allocated, then an error will be thrown from that call to AudioUnitRender.

This property cannot be set on initialized audio units as it may end up reallocating memory.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_ParameterHistoryInfo

For parameters that have the kAudioUnitParameterFlag_PlotHistory flag set, getting this property fills out the AudioUnitParameterHistoryInfo struct containing the recommended update rate and history duration.

Available in iOS 4.3 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_FrequencyResponse

Available in iOS 2.1 through iOS 2.2.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_CPULoad

A read-only Float64 value valid on the audio unit global scope.

The proportion of time that an audio unit is devoting to audio rendering. The value ranges from 0.0 (the audio unit is spending no time rendering) through 1.0 (the audio unit is spending all of its time rendering).

Available in iOS 5.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_ParameterValueStrings

An array of names for a named, indexed audio unit parameter. An indexed parameter is one whose unit type is kAudioUnitParameterUnit_Indexed. The array’s strings can be used to build a menu for the parameter.

A read-only CFArrayRef object whose elements are CFStringRef objects, valid on any audio unit scope.

When obtaining a parameter string array from an audio unit with the AudioUnitGetProperty function, you own the reference to the array and are responsible for later releasing it by calling the CFRelease function.

Indexed parameters use whole-number index values; the size of this property’s array should be the same as the range between the parameter’s minimum and maximum values.

Available in iOS 5.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_HostCallbacks

A write-only HostCallbackInfo data structure valid on the audio unit global scope.

A set of callback functions that allow an audio unit to get information, from the host, that may be relevant to rendering. You write the callbacks to provide an audio unit with music control information including beat, tempo, and audio transport state.

An audio unit should invoke host callbacks only from within its render function.

Any of the parameters of the callback function, when called by the audio unit, can be NULL. This indicates that the unit doesn't want to know that particular information. The exception is that the unit must always specify the HostUserData which was be supplied to the unit when the property was set.

If the host is unable to provide the requested information then it can return the kAudioUnitErr_CannotDoInCurrentContext error code.

Available in iOS 5.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_OfflineRender

Available in iOS 6.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_DependentParameters

A read-only array of AUDependentParameter structs, valid on the audio unit global scope.

This property is used for parameters with the kAudioUnitParameterFlag_IsGlobalMeta or kAudioUnitParameterFlag_IsElementMeta flags set. Hosts applications (and the AudioUnitParameterListener mechanism) can interrogate this property to determine which parameters are dependent on a meta-parameter.

For parameters marked with kAudioUnitParameterFlag_IsGlobalMeta, any non-global dependent parameters are assumed to be dependent in every element of their scope.

For parameters marked with kAudioUnitParameterFlag_IsElementMeta, then its dependent parameters must all be the same scope, and are assumed to apply only within a single element, not to other instances of the same parameter in other elements.

Available in iOS 6.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_InputSamplesInOutput

A read/write AUInputSamplesInOutputCallbackStruct struct, valid on the audio unit global scope.

An audio unit calls this callback at the end of its render call. The audio unit supplies the following information:

• outputTime - The timestamp passed in to the audio unit's render call. This timestamp represents the time of the first output sample.

• inputSample - The sample number of the first input sample that is present in the output audio.

• numInputSamples - The number of input samples that were used and are present in the output audio.

This property allows a host application to determine which input samples correspond to a sample in the output buffer. It is useful only for audio units that do time-stretching, such as the OS X AUVaripseed and AUTimePitch units, where the relationship between input and output samples is non-trivial. For these units, the range of input samples that correspond to an output buffer typically differs from the range of input samples that were pulled for that render call. This difference arises because of internal buffering, processing latency, and other factors.

Available in iOS 6.0 and later.

Declared in AudioUnitProperties.h.

I/O Audio Unit Properties

Properties for Apple I/O audio units (sometimes called output units).

enum {
   kAudioOutputUnitProperty_CurrentDevice         = 2000,
   kAudioOutputUnitProperty_IsRunning             = 2001,
   kAudioOutputUnitProperty_ChannelMap            = 2002,
   kAudioOutputUnitProperty_EnableIO              = 2003,
   kAudioOutputUnitProperty_StartTime             = 2004,
   kAudioOutputUnitProperty_SetInputCallback      = 2005,
   kAudioOutputUnitProperty_HasIO                 = 2006,
   kAudioOutputUnitProperty_StartTimestampsAtZero = 2007
};

Constants

kAudioOutputUnitProperty_CurrentDevice

A read/write audio device ID object, of type AudioDeviceID, valid on the audio unit global scope.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioOutputUnitProperty_IsRunning

Indicates whether an audio unit is running (TRUE) or not (FALSE).

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioOutputUnitProperty_ChannelMap

Maps input channels from an input (source) to an output (destination). The number of channels represented in the channel map is the number of channels of the destination. The channel map entries contain a channel number of the source that should be mapped to that destination channel. If -1 is specified, than that destination channel will not contain any channel from the source (so it will be silent). This will also work with the AUConverter unit.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioOutputUnitProperty_EnableIO

Specifies whether audio I/O is enabled for an I/O unit bus-scope combination.

An I/O unit’s bus 0 connects to output hardware, such as for playback through a speaker. Output is enabled by default. To disable output, the bus 0 output scope must be disabled, as follows:

UInt32 enableOutput = 0; // to disable output

AudioUnitElement outputBus = 0;

AudioUnitSetProperty (

io_unit_instance,

kAudioOutputUnitProperty_EnableIO,

kAudioUnitScope_Output,

outputBus,

&enableOutput,

sizeof (enableOutput)

);

An I/O unit’s bus 1 connects to input hardware, such as for recording from a microphone. Input is disabled by default. To enable input, the bus 1 input scope must be enabled, as follows:

UInt32 enableInput = 1; // to enable input

AudioUnitElement inputBus = 1;

AudioUnitSetProperty (

io_unit_instance,

kAudioOutputUnitProperty_EnableIO,

kAudioUnitScope_Input,

inputBus,

&enableInput,

sizeof (enableInput)

);

A read/write UInt32 value valid on the input and output scopes.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioOutputUnitProperty_StartTime

A write-only AudioOutputUnitStartAtTimeParams data structure valid on the audio unit global scope. When this property is set on an output unit, it will cause the next Start request (but no subsequent Starts) to use the AudioDeviceStartAtTime function, using the specified timestamp, passing false for inRequestedStartTimeIsInput.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioOutputUnitProperty_SetInputCallback

A read/write AURenderCallbackStruct data structure valid on the audio unit global scope. When an output unit has been enabled for input operation, this callback can be used to provide a single callback to the host application from the input I/O proc, in order to notify the host that input is available and may be obtained by calling the AudioUnitRender function.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioOutputUnitProperty_HasIO

A UInt32 value. Scope: { scope output, element 0 = output } { scope input, element 1 = input }. Value is 1 if input or output is enabled on the specified element. See kAudioOutputUnitProperty_EnableIO.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioOutputUnitProperty_StartTimestampsAtZero

A read/write UInt32 value valid on the audio unit global scope.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

Voice-Processing I/O Audio Unit Properties

Properties that apply to the Apple voice-processing I/O audio unit.

enum {
   kAUVoiceIOProperty_BypassVoiceProcessing     = 2100,
   kAUVoiceIOProperty_VoiceProcessingEnableAGC  = 2101,
   kAUVoiceIOProperty_MuteOutput                = 2104,
};

Constants

kAUVoiceIOProperty_BypassVoiceProcessing

Indicates whether voice processing is bypassed (any nonzero value) or active (a value of 0). Voice processing is active by default.

Value is a read/write UInt32 valid on the global audio unit scope.

Available in iOS 3.0 and later.

Declared in AudioUnitProperties.h.

kAUVoiceIOProperty_VoiceProcessingEnableAGC

Indicates whether automatic gain control is enabled (any nonzero value) or disabled (a value of 0). Automatic gain control is enabled by default.

Value is a read/write UInt32 valid on the global audio unit scope.

Available in iOS 3.0 and later.

Declared in AudioUnitProperties.h.

kAUVoiceIOProperty_MuteOutput

Mutes the output of the Voice-Processing I/O unit. Output muting is off (0) by default. To mute the output, set this property’s value to 1.

Value is a read/write UInt32 valid on the global audio unit scope.

Available in iOS 4.0 and later.

Declared in AudioUnitProperties.h.

Mixer Audio Unit Properties

Properties for Apple mixer audio units.

enum {
   // For general mixers
   kAudioUnitProperty_MeteringMode     = 3007,
   
   // For the matrix mixer
   kAudioUnitProperty_MatrixLevels     = 3006,
   kAudioUnitProperty_MatrixDimensions = 3009,
   kAudioUnitProperty_MeterClipping    = 3011
};

Constants

kAudioUnitProperty_MeteringMode

Specifies whether metering is enabled or disabled for a particular scope-element combination.

A read/write UInt32 value valid on the input and output scopes.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_MatrixLevels

Describes the internal state of a matrix mixer.

Calculate the size required for this property’s value as follows:

(input channel count + 1) * (output channel count + 1)

Obtain the channel counts using the kAudioUnitProperty_MatrixDimensions property.

For example, consider a matrix mixer that has 2 input channels and 2 output channels. The value of this property then requires a 3 x 3 array of Float32 values. You can retrieve specific pieces of information for this example matrix mixer’s state as follows:

• Global volume is stored at volumes[2][2]

• Input volumes are stored in the last column: first input channel at volumes[0][2]; second input channel at volumes[1][2]

• Output volumes are stored in the last row: first output channel at volumes [2][0]; second output channel at volumes[2][1]

• Cross-point volumes are stored at their expected locations(volumes[0][1], etc)

A read-only two-dimensional array of Float32 values valid on the audio unit global scope.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_MatrixDimensions

Indicates the total number of channels for input and output of a given matrix mixer.

A read-only 2 * UInt32 value valid on the audio unit global scope.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_MeterClipping

Indicates audio clipping that has occurred since this property was last accessed.

A read-only AudioUnitMeterClipping data structure valid on the audio unit global scope.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

3D Mixer Audio Unit Properties

Properties for the Apple 3D Mixer audio unit.

enum {
   kAudioUnitProperty_3DMixerDistanceParams   = 3010,
   kAudioUnitProperty_3DMixerAttenuationCurve = 3013,
   kAudioUnitProperty_SpatializationAlgorithm = 3000,
   kAudioUnitProperty_DopplerShift            = 3002,
   kAudioUnitProperty_3DMixerRenderingFlags   = 3003,
   kAudioUnitProperty_3DMixerDistanceAtten    = 3004,
   kAudioUnitProperty_ReverbPreset            = 3012
};

Constants

kAudioUnitProperty_3DMixerDistanceParams

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_3DMixerAttenuationCurve

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_SpatializationAlgorithm

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_DopplerShift

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_3DMixerRenderingFlags

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_3DMixerDistanceAtten

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitProperty_ReverbPreset

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

3D Mixer Attenuation Curves

Audio level attenuation curves to use with the Apple 3D Mixer audio unit.

enum {
   k3DMixerAttenuationCurve_Power       = 0,
   k3DMixerAttenuationCurve_Exponential = 1,
   k3DMixerAttenuationCurve_Inverse     = 2,
   k3DMixerAttenuationCurve_Linear      = 3
};

Constants

k3DMixerAttenuationCurve_Power

An equal-power-based attenuation curve.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

k3DMixerAttenuationCurve_Exponential

An exponential attenuation curve.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

k3DMixerAttenuationCurve_Inverse

An inverse attenuation curve.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

k3DMixerAttenuationCurve_Linear

A linear attenuation curve.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

3D Mixer Rendering Flags

Rendering options for the Apple 3D Mixer audio unit.

enum {
   k3DMixerRenderingFlags_InterAuralDelay            = (1L << 0),
   k3DMixerRenderingFlags_DopplerShift               = (1L << 1),
   k3DMixerRenderingFlags_DistanceAttenuation        = (1L << 2),
   k3DMixerRenderingFlags_DistanceFilter             = (1L << 3),
   k3DMixerRenderingFlags_DistanceDiffusion          = (1L << 4),
   k3DMixerRenderingFlags_LinearDistanceAttenuation  = (1L << 5),
   k3DMixerRenderingFlags_ConstantReverbBlend        = (1L << 6)
};

Constants

k3DMixerRenderingFlags_InterAuralDelay

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

k3DMixerRenderingFlags_DopplerShift

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

k3DMixerRenderingFlags_DistanceAttenuation

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

k3DMixerRenderingFlags_DistanceFilter

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

k3DMixerRenderingFlags_DistanceDiffusion

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

k3DMixerRenderingFlags_LinearDistanceAttenuation

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

k3DMixerRenderingFlags_ConstantReverbBlend

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

Converter Audio Unit Properties

Properties for the Apple AUConverter audio unit.

enum {
   kAudioUnitProperty_SampleRateConverterComplexity = 3014
};

Constants

kAudioUnitProperty_SampleRateConverterComplexity

The quality of sample-rate conversion for the audio unit to perform. A UInt32 value valid on the audio unit global scope.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

Audio Unit Sample Rate Converter Complexity

Quality levels for the audio sample-rate conversion algorithm.

enum {
   kAudioUnitSampleRateConverterComplexity_Linear     = 'line',
   kAudioUnitSampleRateConverterComplexity_Normal     = 'norm',
   kAudioUnitSampleRateConverterComplexity_Mastering  = 'bats'
};

Constants

kAudioUnitSampleRateConverterComplexity_Linear

Basic sample rate conversion using linear interpolation. Fast, but lower quality.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitSampleRateConverterComplexity_Normal

Normal quality sample rate conversion.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitSampleRateConverterComplexity_Mastering

Mastering quality sample rate conversion. More computationally expensive.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

RenderQuality

Render quality settings for audio units.

enum {
   kRenderQuality_Max     = 0x7F,
   kRenderQuality_High    = 0x60,
   kRenderQuality_Medium  = 0x40,
   kRenderQuality_Low     = 0x20,
   kRenderQuality_Min     = 0
};

Constants

kRenderQuality_Max

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kRenderQuality_High

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kRenderQuality_Medium

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kRenderQuality_Low

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kRenderQuality_Min

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

Spatialization Algorithms

Spatialization algorithms for panner audio units.

enum {
   kSpatializationAlgorithm_EqualPowerPanning  = 0,
   kSpatializationAlgorithm_SphericalHead      = 1,
   kSpatializationAlgorithm_HRTF               = 2,
   kSpatializationAlgorithm_SoundField         = 3,
   kSpatializationAlgorithm_VectorBasedPanning = 4,
   kSpatializationAlgorithm_StereoPassThrough  = 5
};

Constants

kSpatializationAlgorithm_EqualPowerPanning

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kSpatializationAlgorithm_SphericalHead

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kSpatializationAlgorithm_HRTF

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kSpatializationAlgorithm_SoundField

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kSpatializationAlgorithm_VectorBasedPanning

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kSpatializationAlgorithm_StereoPassThrough

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

Audio Unit Parameter Units of Measure

Keys that designate units of measure for audio unit parameters.

enum {
   kAudioUnitParameterUnit_Generic             = 0,
   kAudioUnitParameterUnit_Indexed             = 1,
   kAudioUnitParameterUnit_Boolean             = 2,
   kAudioUnitParameterUnit_Percent             = 3,
   kAudioUnitParameterUnit_Seconds             = 4,
   kAudioUnitParameterUnit_SampleFrames        = 5,
   kAudioUnitParameterUnit_Phase               = 6,
   kAudioUnitParameterUnit_Rate                = 7,
   kAudioUnitParameterUnit_Hertz               = 8,
   kAudioUnitParameterUnit_Cents               = 9,
   kAudioUnitParameterUnit_RelativeSemiTones   = 10,
   kAudioUnitParameterUnit_MIDINoteNumber      = 11,
   kAudioUnitParameterUnit_MIDIController      = 12,
   kAudioUnitParameterUnit_Decibels            = 13,
   kAudioUnitParameterUnit_LinearGain          = 14,
   kAudioUnitParameterUnit_Degrees             = 15,
   kAudioUnitParameterUnit_EqualPowerCrossfade = 16,
   kAudioUnitParameterUnit_MixerFaderCurve1    = 17,
   kAudioUnitParameterUnit_Pan                 = 18,
   kAudioUnitParameterUnit_Meters              = 19,
   kAudioUnitParameterUnit_AbsoluteCents       = 20,
   kAudioUnitParameterUnit_Octaves             = 21,
   kAudioUnitParameterUnit_BPM                 = 22,
   kAudioUnitParameterUnit_Beats               = 23,
   kAudioUnitParameterUnit_Milliseconds        = 24,
   kAudioUnitParameterUnit_Ratio               = 25,
   kAudioUnitParameterUnit_CustomUnit          = 26
};
typedef UInt32  AudioUnitParameterUnit;

Constants

kAudioUnitParameterUnit_Generic

A generic unit of measure.

Expected but not required to range between 0.0 and 1.0.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Indexed

An indexed unit of measure.

Indicates a particular menu item in a list of menu items, typically using whole-number values starting at 1.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Boolean

A Boolean-like unit of measure.

A value of 0.0 means FALSE and a nonzero value means TRUE.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Percent

A percentage unit of measure.

Most audio unit parameters of this type range from 0 (for 0%) through 100 (for 100%). Some range from from –50 to +50.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Seconds

A whole-seconds unit of measure, indicating either absolute or relative time.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_SampleFrames

A sample-frame-count unit of measure.

The duration of a sample frame, for fixed frame-rate audio formats, is equal to 1.0/kAudioUnitProperty_SampleRate seconds.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Phase

An angular degree unit of measure.

Typical range is –180 through +180 and is intended to represent the phase difference between two signals. See also the kAudioUnitParameterUnit_Degrees property.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Rate

A multiplication factor unit of measure.

A multiplication factor, most often used for playback speed. A value of 2.0, for example, means twice as fast. May also be used for other purposes where a multiplication factor is appropriate.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Hertz

A hertz unit of measure.

Absolute frequency or pitch in cycles per second.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Cents

A logarithmic unit of measure for a musical interval between two notes.

Relative musical pitch in cents, where 1,200 cents are equal to one octave. 100 cents are equal to one semitone. See also the kAudioUnitParameterUnit_AbsoluteCents property.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_RelativeSemiTones

A relative unit of measure for a musical interval between two notes.

One octave has 12 semitones equal in size. Each semitone is equivalent to 100 cents. This parameter unit is useful for coarse tuning or detuning.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_MIDINoteNumber

A whole-number unit of measure corresponding to audio frequency.

Absolute pitch as defined in the MIDI specification. A standard piano keyboard ranges from MIDI note number 21 (for the A0 note) to 108 (for the C8 note), with MIDI note 60 corresponding to middle C (C4). The frequency for a given MIDI note number may depend on a tuning table.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_MIDIController

A whole-number unit of measure corresponding to standard MIDI control numbers.

Range is from 0 through 127.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Decibels

A logarithmic unit of measure representing the ratio between two audio levels.

Typically used as a relative measure of audio gain.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_LinearGain

A linear unit of measure representing the difference between two audio levels.

Typically used as a relative measure of audio gain.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Degrees

An angular degree unit of measure.

Typical range is from –180° through +180° and is intended as a general representation of geometric position, such as for audio sources in a three-dimensional coordinate system. See also the kAudioUnitParameterUnit_Phase property.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_EqualPowerCrossfade

An audio power unit of measure.

Recommended range is from 0 through 100, representing a crossfade mix of two sources according to sqrt (x) and sqrt (1.0 - x).

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_MixerFaderCurve1

An audio power unit of measure.

Recommended range is from 0.0 through 1.0. Use pow (x, 3.0) to simulate a reasonable linear mixer channel fader response.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Pan

An audio position unit of measure.

For standard left-to-right audio panning.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Meters

A distance unit of measure, corresponding to meters.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_AbsoluteCents

An absolute unit of measure for the musical pitch of a note.

Absolute musical pitch in cents. 1,200 cents are equal to one octave. If f is a frequency in hertz, then absoluteCents = 1200 * log2 (f/440) + 6900. See also the kAudioUnitParameterUnit_Cents property.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Octaves

A relative unit of measure for the musical interval between two notes.

Octaves in relative pitch, where a value of 1 is equal to an interval of 1200 cents.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_BPM

A whole-number unit of measure for musical tempo, representing beats per minute.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Beats

A time unit of measure in musical beats.

1.0 beats at 120 BPM (beats per minute) equals a duration of 1/2 second.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Milliseconds

A time unit of measure representing milliseconds.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_Ratio

A unitless ratio unit of measure.

Useful for representing an amount of compression or expansion, for example.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterUnit_CustomUnit

A custom unit of measure.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

Audio Unit Parameter Flags

Value options for audio unit parameters.

enum {
   kAudioUnitParameterFlag_CFNameRelease        = (1L << 4),
   kAudioUnitParameterFlag_PlotHistory          = (1L << 14),
   kAudioUnitParameterFlag_MeterReadOnly        = (1L << 15),
   kAudioUnitParameterFlag_DisplayMask          = (7L << 16) | (1L << 22),
   kAudioUnitParameterFlag_DisplaySquareRoot    = (1L << 16),
   kAudioUnitParameterFlag_DisplaySquared       = (2L << 16),
   kAudioUnitParameterFlag_DisplayCubed         = (3L << 16),
   kAudioUnitParameterFlag_DisplayCubeRoot      = (4L << 16),
   kAudioUnitParameterFlag_DisplayExponential   = (5L << 16),
   kAudioUnitParameterFlag_HasClump             = (1L << 20),
   kAudioUnitParameterFlag_ValuesHaveStrings    = (1L << 21),
   kAudioUnitParameterFlag_DisplayLogarithmic   = (1L << 22),
   kAudioUnitParameterFlag_IsHighResolution     = (1L << 23),
   kAudioUnitParameterFlag_NonRealTime          = (1L << 24),
   kAudioUnitParameterFlag_CanRamp              = (1L << 25),
   kAudioUnitParameterFlag_ExpertMode           = (1L << 26),
   kAudioUnitParameterFlag_HasCFNameString      = (1L << 27),
   kAudioUnitParameterFlag_IsGlobalMeta         = (1L << 28),
   kAudioUnitParameterFlag_IsElementMeta        = (1L << 29),
   kAudioUnitParameterFlag_IsReadable           = (1L << 30),
   kAudioUnitParameterFlag_IsWritable           = (1L << 31)
};

Constants

kAudioUnitParameterFlag_CFNameRelease

If an audio unit can generate parameter names dynamically, it should set this flag.

Audio unit hosting applications should check for this flag being set. If it is, the host should release the audio unit parameter name when it is done using it.

If this flag is not set, the host application can assume that the audio unit will release its parameter names.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_PlotHistory

If set, getting the kAudioUnitProperty_ParameterHistoryInfo property fills out the AudioUnitParameterHistoryInfo struct containing the recommended update rate and history duration.

Available in iOS 4.3 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_MeterReadOnly

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_DisplayMask

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_DisplaySquareRoot

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_DisplaySquared

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_DisplayCubed

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_DisplayCubeRoot

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_DisplayExponential

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_HasClump

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_ValuesHaveStrings

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_DisplayLogarithmic

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_IsHighResolution

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_NonRealTime

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_CanRamp

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_ExpertMode

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_HasCFNameString

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_IsGlobalMeta

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_IsElementMeta

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_IsReadable

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAudioUnitParameterFlag_IsWritable

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

Frequency Response Constants

The maximum number of frequency response bin structures for the AudioUnitProperty_FrequencyResponse property.

enum {
   kNumberOfResponseFrequencies   = 1024
};

Constants

kNumberOfResponseFrequencies

The maximum number of frequency response bin structures for the AudioUnitProperty_FrequencyResponse property.

Available in iOS 2.1 and later.

Declared in AudioUnitProperties.h.

Audio Unit Preset Keys

Keys for audio unit kAudioUnitProperty_ClassInfo property dictionaries.

#define kAUPresetVersionKey       "version"
#define kAUPresetTypeKey          "type"
#define kAUPresetSubtypeKey       "subtype"
#define kAUPresetManufacturerKey  "manufacturer"
#define kAUPresetDataKey          "data"
#define kAUPresetNameKey          "name"
#define kAUPresetRenderQualityKey "render-quality"
#define kAUPresetCPULoadKey       "cpu-load"
#define kAUPresetElementNameKey   "element-name"
#define kAUPresetExternalFileRefs "file-references"
#define kAUPresetPartKey          "part"

Constants

kAUPresetVersionKey

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAUPresetTypeKey

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAUPresetSubtypeKey

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAUPresetManufacturerKey

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAUPresetDataKey

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAUPresetNameKey

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAUPresetRenderQualityKey

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAUPresetCPULoadKey

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAUPresetElementNameKey

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAUPresetExternalFileRefs

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

kAUPresetPartKey

If present, distinguishes a global preset that is set on the global scope from a part-based preset that is set on the part scope. The value of this key is defined by the audio unit it applies to.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

static const CFStringRef kMyVersionString = CFSTR (kAUPresetVersionKey);

Reserved Audio Unit Clump Identifier

Reserved for system use.

enum {
   kAudioUnitClumpID_System = 0
};

Constants

kAudioUnitClumpID_System

Reserved for system use. Use clump ID values other than 0.

Available in iOS 2.0 and later.

Declared in AudioUnitProperties.h.

Platform Considerations

In OS X, you should not use this constant. It is reserved for system use. This constant does not apply in iOS because iOS does not support audio unit views.