Audio Unit Utilities

Header file: AudioToolbox/AudioUnitUtilities.h

The AU Parameter Listener is designed to provide notifications of an Audio Unit's parameters. This API is designed to avoid the need for UI components to continually poll an Audio Unit to determine if a parameter value has been changed. In order for this notification to be used, the parameter value should be changed using the AUParameterSet call (discussed below), which allows the notification mechanism to be used. This also removes the need for an Audio Unit to provide and support a notification mechanism, particular as AudioUnitSetParameter may be received by an Audio Unit during the render process.

There are also some utilities for converting between non-linear and linear value ranges. These are very useful for displaying a non-linear parameter (such as Hz, or dB) 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.


Contents
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 parameter change without actually changing the value.
 AUParameterValueFromLinear Converts a linear value to the parameter's natural value range, according to its units.
 AUParameterValueToLinear Converts a parameter value to a linear value according to the parameter's units.
 AUParameterFormatValue Format a parameter value into a string.
Callbacks
 AUParameterListenerProc Called when a parameter's value has changed.
Defined Types
 AUParameterListenerRef
Constants
 kAUParameterListener_AnyParameter

AUListenerCreate

Create an object for fielding notifications when AudioUnit parameter values change.
OSStatus AUListenerCreate(
  AUParameterListenerProc   inProc,
  void *                    inRefCon,
  CFRunLoopRef              inRunLoop,
  CFStringRef               inRunLoopMode,
  Float32                   inNotificationInterval,
  AUParameterListenerRef *  outListener
);
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.

Parameters

inProc
The callback function which is called when the parameter's value changes.
inRefCon
A reference constant 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 maximum 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.

AUListenerDispose

Dispose a parameter listener object.
OSStatus AUListenerDispose(
  AUParameterListenerRef  inListener
);

Parameters

inListener
The parameter listener to dispose.

AUListenerAddParameter

Connect a parameter to a listener.
OSStatus AUListenerAddParameter(
  AUParameterListenerRef      inListener,
  void *                      inObject,
  const AudioUnitParameter *  inParameter
);
Associate an arbitrary object (often a user interface widget) with an AudioUnitParameter, and deliver notifications to the specified listener, telling it that the object needs to be informed of the parameter's value change.

Parameters

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.

AUListenerRemoveParameter

Remove a parameter/listener connection.
OSStatus AUListenerRemoveParameter(
  AUParameterListenerRef      inListener,
  void *                      inObject,
  const AudioUnitParameter *  inParameter
);

Parameters

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.

AUParameterSet

Set an AudioUnit parameter value and notify listeners.
OSStatus AUParameterSet(
  AUParameterListenerRef      inListener,
  void *                      inObject,
  const AudioUnitParameter *  inParameter,
  Float32                     inValue,
  UInt32                      inBufferOffsetInFrames
);
Calls AudioUnitSetParameter, and performs/schedules notification callbacks to all parameter listeners, for that parameter -- except that optionally, no callback will be generated to the inListener/inObject pair that invoked this call.

Parameters

inListener
A parameter listener generating the change and does not want to receive a callback as a result of it. May be NULL.
inObject
The object generating the change and 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.

AUParameterListenerNotify

Notify listeners of a parameter change without actually changing the value.
OSStatus AUParameterListenerNotify(
  AUParameterListenerRef      inListener,
  void *                      inObject,
  const AudioUnitParameter *  inParameter
);
Performs and schedules the listener notification functions 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.

Parameters

inListener
A parameter listener generating the change and does not want to receive a callback as a result of it. May be NULL.
inObject
The object generating the change and 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.

AUParameterValueFromLinear

Converts a linear value to the parameter's natural value range, according to its units.
Float32 AUParameterValueFromLinear(
  Float32                     inLinearValue,
  const AudioUnitParameter *  inParameter
);

Parameters

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.
Result: The converted parameter value.

AUParameterValueToLinear

Converts a parameter value to a linear value according to the parameter's units.
Float32 AUParameterValueToLinear(
  Float32                     inParameterValue,
  const AudioUnitParameter *  inParameter
);

Parameters

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.
Result: A number 0.0-1.0.

AUParameterFormatValue

Format a parameter value into a string.
char * AUParameterFormatValue(
  double                      inParameterValue,
  const AudioUnitParameter *  inParameter,
  char *                      inTextBuffer,
  UInt32                      inDigits
);
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
	    -2      .0100-.0999     4
	    -1      .100-.999       3
	    0       1.00-9.99       2
	    1       10.0-99.9       1
	    2       100-999         0
	    3       1000-9990       -1
	    4       10000-99900     -2

Parameters

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).
Result: outTextBuffer

AUParameterListenerProc

Called when a parameter's value has changed.
typedef void (*AUParameterListenerProc)(
  void *                      inRefCon,
  void *                      inObject,
  const AudioUnitParameter *  inParameter,
  Float32                     inValue
);

Parameters

inRefCon
The inRefCon argument which was passed to AUListenerCreate.
inObject
The inObject argument which was passed to AUListenerAddParameter for the parameter which has changed.
inParameter
The parameter which has changed.
inValue
The parameter's most recent value.

AUParameterListenerRef

typedef struct AUParameterListener *AUParameterListenerRef;

kAUParameterListener_AnyParameter

enum {
  kAUParameterListener_AnyParameter  = 0xFFFFFFFF
};