AudioUnitUtilities.h


Abstract

Contains higher-level utility functions for the use of AudioUnit clients.

Discussion

The AU Parameter Listener is designed to provide notifications when an Audio Unit's parameters or other state changes. It makes it unnecessary for UI components to continually poll an Audio Unit to determine if a parameter value has been changed. In order for this notification mechanism to work properly, parameter values should be changed using the AUParameterSet call (discussed below). This also makes it unnecessary for an Audio Unit to provide and support a notification mechanism, particularly as AudioUnitSetParameter may be received by an Audio Unit during the render process.

The AUEventListener API's extend the AUParameterListener API's by supporting event types other than parameter changes. Events, including parameter changes are delivered serially to the listener, preserving the time order of the events and parameter changes.

There are also some utilities for converting between non-linear and linear value ranges. These are useful for displaying a non-linear parameter (such as one whose units are in Hertz or decibels) using a linear control mechanism, such as a slider, to ensure that the user has a wider perceived range of control over the parameter value.



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

Typedefs


AUParameterListenerRef


An object which receives notifications of Audio Unit parameter value changes.

typedef struct AUListenerBase *AUParameterListenerRef; 

AUEventListenerRef


An object which receives Audio Unit events.

typedef AUParameterListenerRef AUEventListenerRef; 
Discussion

An AUEventListenerRef may be passed to API's taking an AUEventListenerRef as an argument.


AudioUnitEvent


Describes a change to an Audio Unit's state.

See Also:
AudioUnitEvent
typedef struct AudioUnitEvent { 
    AudioUnitEventType mEventType; 
    union { 
        AudioUnitParameter mParameter; // for parameter value change, begin and end gesture 
        AudioUnitProperty mProperty; // for kAudioUnitEvent_PropertyChange 
        } mArgument; 
} AudioUnitEvent; 
Field Descriptions
mEventType
The type of event.
mArgument
Specifies the parameter or property which has changed.

AUParameterListenerProc


A function called when a parameter value changes.

typedef void (*AUParameterListenerProc)(
    void *inRefCon, 
    void *inObject, 
    const AudioUnitParameter *inParameter, 
    Float32 inValue); 
Parameter Descriptions
inRefCon
The value passed to AUListenerCreate when the callback function was installed.
inObject
The object which generated the parameter change.
inParameter
Signifies the parameter whose value changed.
inValue
The parameter's new value.

AUParameterListenerProc


A function called when an Audio Unit event occurs.

See Also:
AUEventListenerProc
typedef void (*AUEventListenerProc)(
    void *inCallbackRefCon, 
    void *inObject, 
    const AudioUnitEvent *inEvent, 
    UInt64 inEventHostTime, 
    Float32 inParameterValue); 
Parameter Descriptions
inCallbackRefCon
The value passed to AUListenerCreate when the callback function was installed.
inObject
The object which generated the parameter change.
inEvent
The event which occurred.
inEventHostTime
The host time at which the event occurred.
inParameterValue
If the event is parameter change, the parameter's new value (otherwise, undefined).

AUEventListenerProc


A function called when an Audio Unit event occurs.

See Also:
AUParameterListenerProc
typedef void (*AUEventListenerProc)(
    void *inCallbackRefCon, 
    void *inObject, 
    const AudioUnitEvent *inEvent, 
    UInt64 inEventHostTime, 
    Float32 inParameterValue); 
Field Descriptions
inCallbackRefCon
The value passed to AUListenerCreate when the callback function was installed.
inObject
The object which generated the parameter change.
inEvent
The event which occurred.
inEventHostTime
The host time at which the event occurred.
inParameterValue
If the event is parameter change, the parameter's new value (otherwise, undefined).

Enumerations


kAUParameterListener_AnyParameter


enum { 
    kAUParameterListener_AnyParameter = 0xFFFFFFFF 
}; 
Constants
kAUParameterListener_AnyParameter
A wildcard value for an AudioUnitParameterID.
Discussion




AudioUnitEventType


Types of Audio Unit Events.

enum { // typedef UInt32 AudioUnitEventType 
    kAudioUnitEvent_ParameterValueChange = 0, 
    kAudioUnitEvent_BeginParameterChangeGesture = 1, 
    kAudioUnitEvent_EndParameterChangeGesture = 2, 
    kAudioUnitEvent_PropertyChange = 3 
}; 
Constants
kAudioUnitEvent_ParameterValueChange
The event is a change to a parameter value
kAudioUnitEvent_BeginParameterChangeGesture
The event signifies a gesture (e.g. mouse-down) beginning a potential series of related parameter value change events.
kAudioUnitEvent_EndParameterChangeGesture
The event signifies a gesture (e.g. mouse-up) ending a series of related parameter value change events.
kAudioUnitEvent_PropertyChange
The event is a change to a property value.
Discussion



(Last Updated July 18, 2005)