Functions


AUListenerCreate
Create an object for fielding notifications when AudioUnit parameter values change.
AUListenerDispose
Dispose a parameter listener object.
AUListenerAddParameter
Connect a parameter to a listener.
AUListenerRemoveParameter
Remove a parameter/listener connection.
AUParameterSet
Set an AudioUnit parameter value and notify listeners.
AUParameterListenerNotify
Notify listeners of a past parameter change.
AUEventListenerCreate
Creates an Audio Unit event listener.
AUEventListenerAddEventType
Begin delivering a particular type of events to a listener.
AUEventListenerRemoveEventType
Stop delivering a particular type of events to a listener.
AUEventListenerNotify
Deliver an AudioUnitEvent to all listeners registered to receive it.
AUParameterValueFromLinear
Converts a linear value to a parameter value according to the parameter's units.
AUParameterValueToLinear
Converts a parameter value to a linear value according to the parameter's units.
AUParameterFormatValue
Format a parameter value into a string.

AUListenerCreate


Create an object for fielding notifications when AudioUnit parameter values change.

extern OSStatus AUListenerCreate(
    AUParameterListenerProc inProc, 
    void *inRefCon, 
    CFRunLoopRef inRunLoop, 
    CFStringRef inRunLoopMode, 
    Float32 inNotificationInterval, 
    AUParameterListenerRef *outListener); 
Parameter Descriptions
inProc
Function called when the parameter's value changes.
inRefCon
A reference value for the use of the callback function.
inRunLoop
The run loop on which the callback is called. If NULL, CFRunLoopGetCurrent() is used.
inRunLoopMode
The run loop mode in which the callback's underlying run loop source will be attached. If NULL, kCFRunLoopDefaultMode is used.
inNotificationInterval
The minimum time interval, in seconds, at which the callback will be called. If multiple parameter value changes occur within this time interval, the listener will only receive a notification for the last value change that occurred before the callback. If inNotificationInterval is 0, the inRunLoop and inRunLoopMode arguments are ignored, and the callback will be issued immediately, on the thread on which the parameter was changed.
outListener
On succcessful return, an AUParameterListenerRef.
Discussion

Note that only parameter changes issued through AUParameterSet will generate notifications to listeners; thus, in most cases, AudioUnit clients should use AUParameterSet in preference to AudioUnitSetParameterValue.

Availability
Introduced in Mac OS X 10.2

AUListenerDispose


Dispose a parameter listener object.

extern OSStatus AUListenerDispose(
    AUParameterListenerRef inListener); 
Parameter Descriptions
inListener
The parameter listener to dispose.
Availability
Introduced in Mac OS X 10.2

AUListenerAddParameter


Connect a parameter to a listener.

extern OSStatus AUListenerAddParameter(
    AUParameterListenerRef inListener, 
    void *inObject, 
    const AudioUnitParameter *inParameter); 
Parameter Descriptions
inListener
The parameter listener which will receive the callback.
inObject
The object which is interested in the value of the parameter. This will be passed as the inObject parameter to the listener callback function when the parameter changes.
inParameter
The parameter whose value changes are to generate callbacks.
Discussion

Associates an arbitrary object (often a user interface widget) with an AudioUnitParameter, and delivers notifications to the specified listener, telling it that the object needs to be informed of the parameter's value change.

Availability
Introduced in Mac OS X 10.2

AUListenerRemoveParameter


Remove a parameter/listener connection.

extern OSStatus AUListenerRemoveParameter(
    AUParameterListenerRef inListener, 
    void *inObject, 
    const AudioUnitParameter *inParameter); 
Parameter Descriptions
inListener
The parameter listener to stop receiving callbacks.
inObject
The object which is no longer interested in the value of the parameter.
inParameter
The parameter whose value changes are to stop generating callbacks.
Availability
Introduced in Mac OS X 10.2

AUParameterSet


Set an AudioUnit parameter value and notify listeners.

extern OSStatus AUParameterSet(
    AUParameterListenerRef inSendingListener, 
    void *inSendingObject, 
    const AudioUnitParameter *inParameter, 
    Float32 inValue, 
    UInt32 inBufferOffsetInFrames) ; 
Parameter Descriptions
inListener
A parameter listener generating the change and which does not want to receive a callback as a result of it. May be NULL.
inObject
The object generating the change and which does not want to receive a callback as a result of it. NULL is treated specially when inListener is non-null; it signifies that none of the specified listener's objects will receive notifications.
inParameter
The parameter being changed.
inValue
The new value of the parameter.
Discussion

Calls AudioUnitSetParameter, and performs/schedules notification callbacks to all parameter listeners, for that parameter -- except that no callback will be generated to the inListener/inObject pair.

Availability
Introduced in Mac OS X 10.2

AUParameterListenerNotify


Notify listeners of a past parameter change.

extern OSStatus AUParameterListenerNotify(
    AUParameterListenerRef inSendingListener, 
    void *inSendingObject, 
    const AudioUnitParameter *inParameter); 
Parameter Descriptions
inListener
A parameter listener generating the change and which does not want to receive a callback as a result of it. May be NULL.
inObject
The object generating the change and which does not want to receive a callback as a result of it. NULL is treated specially when inListener is non-null; it signifies that none of the specified listener's objects will receive notifications.
inParameter
The parameter which was changed changed.
Discussion

Performs and schedules the notification callbacks of AUParameterSet, without actually setting an AudioUnit parameter value.

Clients scheduling ramped parameter changes to AudioUnits must make this call dynamically during playback in order for AudioUnitViews to be updated. When the view's listener receives a notification, it will be passed the current value of the parameter.

A special meaning is applied if the mParameterID value of inParameter is equal to kAUParameterListener_AnyParameter. In this case, ANY listener for ANY parameter value changes on the specified AudioUnit will be notified of the current value of that parameter.

Availability
Introduced in Mac OS X 10.2

AUEventListenerCreate


Creates an Audio Unit event listener.

extern OSStatus AUEventListenerCreate(
    AUEventListenerProc inProc, 
    void *inCallbackRefCon, 
    CFRunLoopRef inRunLoop, 
    CFStringRef inRunLoopMode, 
    Float32 inNotificationInterval, // seconds 
    Float32 inValueChangeGranularity, // seconds 
    AUEventListenerRef *outListener); 
Parameter Descriptions
inProc
Function called when an event occurs.
inCallbackRefCon
A reference value for the use of the callback function.
inRunLoop
The run loop on which the callback is called. If NULL, CFRunLoopGetCurrent() is used.
inRunLoopMode
The run loop mode in which the callback's underlying run loop source will be attached. If NULL, kCFRunLoopDefaultMode is used.
inNotificationInterval
The minimum time interval, in seconds, at which the callback will be called.
inValueChangeGranularity
Determines how parameter value changes occuring within this interval are queued; when an event follows a previous one by a smaller time interval than the granularity, then the listener will only be notified for the second parameter change.
outListener
On succcessful return, an AUEventListenerRef.

Discussion

AUEventListener is a specialization of AUParameterListener; use AUListenerDispose to dispose of an AUEventListener. You may use AUListenerAddParameter and AUListenerRemoveParameter with AUEventListerRef's, in addition to AUEventListenerAddEventType / AUEventListenerRemoveEventType.

Some examples illustrating inNotificationInterval and inValueChangeGranularity:

[1] a UI receiver: inNotificationInterval = 100 ms, inValueChangeGranularity = 100 ms. User interfaces almost never care about previous values, only the current one, and don't wish to perform redraws too often.

[2] An automation recorder: inNotificationInterval = 200 ms, inValueChangeGranularity = 10 ms. Automation systems typically wish to record events with a high degree of timing precision, but do not need to be woken up for each event.

In case [1], the listener will be called within 100 ms (the notification interval) of an event. It will only receive one notification for any number of value changes to the parameter concerned, occurring within a 100 ms window (the granularity).

In case [2], the listener will be received within 200 ms (the notification interval) of an event It can receive more than one notification per parameter, for the last of each group of value changes occurring within a 10 ms window (the granularity).

In both cases, thread scheduling latencies may result in more events being delivered to the listener callback than the theoretical maximum (notification interval / granularity).

Availability
Introduced in Mac OS X 10.3.

AUEventListenerAddEventType


Begin delivering a particular type of events to a listener.

extern OSStatus AUEventListenerAddEventType(
    AUEventListenerRef inListener, 
    void *inObject, 
    const AudioUnitEvent *inEvent); 
Parameter Descriptions
inListener
The parameter listener which will receive the events.
inObject
The object which is interested in the value of the parameter. This will be passed as the inObject parameter to the listener callback function when the parameter changes.
inEvent
The type of event to listen for.
function result
An OSStatus error code.
Availability
Introduced in Mac OS X 10.3.

AUEventListenerRemoveEventType


Stop delivering a particular type of events to a listener.

extern OSStatus AUEventListenerRemoveEventType(
    AUEventListenerRef inListener, 
    void *inObject, 
    const AudioUnitEvent *inEvent); 
Parameter Descriptions
inListener
The parameter listener to stop receiving events.
inObject
The object which is no longer interested in the value of the parameter.
inEvent
The type of event to stop listening for.
function result
An OSStatus error code.
Availability
Introduced in Mac OS X 10.3.

AUEventListenerNotify


Deliver an AudioUnitEvent to all listeners registered to receive it.

extern OSStatus AUEventListenerNotify(
    AUEventListenerRef inSendingListener, 
    void *inSendingObject, 
    const AudioUnitEvent *inEvent); 
Parameter Descriptions
inSendingListener
A parameter listener generating the change and which does not want to receive a callback as a result of it. May be NULL.
inSendingObject
The object generating the change and which does not want to receive a callback as a result of it. NULL is treated specially when inListener is non-null; it signifies that none of the specified listener's objects will receive notifications.
inEvent
The event to be delivered.
function result
An OSStatus error code.
Availability
Introduced in Mac OS X 10.3.

AUParameterValueFromLinear


Converts a linear value to a parameter value according to the parameter's units.

extern Float32 AUParameterValueFromLinear(
    Float32 inLinearValue, // 0-1 
    const AudioUnitParameter *inParameter); 
Parameter Descriptions
inLinearValue
The linear value (0.0-1.0) to convert.
inParameter
The parameter, including its Audio Unit, that will define the conversion of the supplied linear value to a value that is natural to that parameter.
function result
The converted parameter value, in the parameter's natural units.
Availability
Introduced in Mac OS X 10.2

AUParameterValueToLinear


Converts a parameter value to a linear value according to the parameter's units.

extern Float32 AUParameterValueToLinear(
    Float32 inParameterValue, 
    const AudioUnitParameter *inParameter); 
Parameter Descriptions
inParameterValue
The value in the natural units of the specified parameter.

inParameter
The parameter, including its Audio Unit, that will define the conversion of the supplied parameter value to a corresponding linear value.
function result
A number 0.0-1.0.
Availability
Introduced in Mac OS X 10.2

AUParameterFormatValue


Format a parameter value into a string.

extern char * AUParameterFormatValue(
    double inParameterValue, 
    const AudioUnitParameter *inParameter, 
    char *inTextBuffer, 
    UInt32 inDigits); 
Parameter Descriptions
inParameterValue
The parameter value to be formatted.
inParameter
The Audio Unit, scope, element, and parameter whose value this is.
inTextBuffer
The character array to receive the formatted text. Should be at least 32 characters.
inDigits
The resolution of the string (see example above).
function result
inTextBuffer
Discussion

Formats a floating point value into a string. Computes a power of 10 to which the value will be rounded and displayed as follows: if the the parameter is logarithmic (Hertz), the number of significant digits is inDigits - pow10(inParameterValue) + 1. Otherwise, it is inDigits - pow10(maxValue - minValue) + 1.

Example for inDigits=3:

	    pow10   range           digits after decimal place display
  1. .0100-.0999 4
  2. .100-.999 3
  3. 1.00-9.99 2
  4. 10.0-99.9 1
  5. 100-999 0
  6. 1000-9990 -1
  7. 10000-99900 -2
Availability
Introduced in Mac OS X 10.2

(Last Updated July 18, 2005)