Advanced Search

Log In | Not a Member?

Contact ADC

< Previous PageNext Page > Hide TOC

Parameter and Property Events

Audio unit automation (as described back in “Supporting Parameter Automation”) is a feature implemented by host applications and custom views. It relies on parameter and property events—which in turn rely on the Audio Unit Event API, described next.

In this section:

The Audio Unit Event API
Parameter Gestures
Basic Parameter Adjustments
Parameter Adjustments with Notification
Tutorial: Demonstrating Parameter Gestures and Audio Unit Events

The Audio Unit Event API

Hosts, views, and audio units can take advantage of Core Audio notifications to ensure that all three of these entities stay in sync in terms of parameter adjustments. The notifications, accessed through the Audio Unit Event API, work no matter which of the three entities invokes a parameter change. The API is declared in the AudioUnitUtilities.h header file in the Audio Toolbox framework.

The Audio Unit Event API defines an AudioUnitEvent data type, shown in Listing 3-2:

Listing 3-2  The AudioUnitEvent structure

typedef struct AudioUnitEvent {

    AudioUnitEventType mEventType;          // 1

        union {

            AudioUnitParameter mParameter;  // 2

            AudioUnitProperty mProperty;    // 3

        } mArgument;

} AudioUnitEvent;

Here’s how this structure works:

1. Identifies the type of the notification, as defined in the AudioUnitEventType enumeration.

2. Identifies the parameter involved in the notification, for notifications that are begin or end gestures or changes to parameters. (See “Parameter Gestures.”) The AudioUnitParameter data type is used by the Audio Unit Event API and not by the Audio Unit framework, even though it is defined in the Audio Unit framework.

3. Identifies the property involved in the notification, for notifications that are property change notifications.

A corresponding AudioUnitEventType enumeration lists the various defined AudioUnitEvent event types, shown in Listing 3-3:

Listing 3-3  The AudioUnitEventType enumeration

typedef UInt32 AudioUnitEventType;

enum {

    kAudioUnitEvent_ParameterValueChange        = 0,

    kAudioUnitEvent_BeginParameterChangeGesture = 1,

    kAudioUnitEvent_EndParameterChangeGesture   = 2,

    kAudioUnitEvent_PropertyChange              = 3

};

kAudioUnitEvent_ParameterValueChange

Indicates that the notification describes a change in the value of a parameter

kAudioUnitEvent_BeginParameterChangeGesture

Indicates that the notification describes a parameter “begin” gesture; a parameter value is about to change

kAudioUnitEvent_EndParameterChangeGesture

Indicates that the notification describes a parameter “end” gesture; a parameter value has finished changing

kAudioUnitEvent_PropertyChange

Indicates that the notification describes a change in the value of an audio unit property

Parameter Gestures

User-interface events that signal the start or end of a parameter change are called gestures. These events can serve to pass notifications among a host, a view, and an audio unit that a parameter is about to be changed, or has just finished being changed. Like parameter and property changes, gestures are communicated using the Audio Unit Event API. Specifically, gestures use the kAudioUnitEvent_BeginParameterChangeGesture and kAudioUnitEvent_EndParameterChangeGesture event types, as shown in Listing 3-3, above.

Basic Parameter Adjustments

For basic parameter adjustment, Core Audio provides the AudioUnitSetParameter function, declared in the AUComponent.h header file in the Audio Unit framework. When a host or a view calls this function, it sets the specified parameter in the audio unit by invoking the SetParameter method in the audio unit. It does not provide notification to support automation or updating of views.

Parameter Adjustments with Notification

To add notification that a parameter has changed, a host or custom view follows a call to the AudioUnitSetParameter function with a call to the AUParameterListenerNotify function from the Audio Unit Event API in the AudioUnitUtilities.h header file.

To set a parameter and notify listeners in one step, a host or a custom view calls the AUParameterSet function, also from the Audio Unit Event API.

Sometimes an audio unit itself changes the value of one of its parameters. In such a case, it should issue a notification about the value change. For a discussion on this, refer back to “Defining and Using Parameters” in “The Audio Unit.”

Tutorial: Demonstrating Parameter Gestures and Audio Unit Events

This mini-tutorial illustrates how gestures and audio unit events work by:

• Instantiating two views for an audio unit

• Performing adjustments in one of the views while observing the effect in the other view

Along the way, this tutorial:

• Introduces you to compiling an audio unit project with Xcode

• Shows how AU Lab can display a generic view and a custom view for the same audio unit

• Shows how a custom property supports communication between an audio unit and a custom view

Before you start, make sure that you’ve installed Xcode and the Core Audio SDK, both of which are part of Apple’s Xcode Tools installation.

1. Open the FilterDemo.xcodeproj Xcode project file in the Developer/Examples/CoreAudio/AudioUnits/FilterDemo folder.

2. Click Build to build the audio unit project. (You may see some warnings about “non-virtual destructors.“ Ignore these warnings.)

Xcode creates a new build folder inside the FilterDemo project folder.

3. Open the build folder and look inside the Development target folder.

The newly built audio unit bundle is named FilterDemo.component, as shown in the figure.

4. Copy the FilterDemo.component bundle to the ~/Library/Audio/Plug-Ins/Components folder. In this location, the newly built audio unit is available to host applications.

5. Launch the AU Lab audio unit host application (in /Developer/Applications/Audio/) and create a new AU Lab document. Unless you've configured AU Lab to use a default document style, the Create New Document window opens. If AU Lab was already running, choose File > New to get this window.

Ensure that the configuration matches the settings shown in the figure: Built-In Audio for the Audio Device, Line In for the Input Source, and Stereo for Output Channels. Leave the window's Inputs tab unconfigured; you will specify the input later. Click OK.

A new AU Lab window opens, showing the output channel you specified.

6. Click the triangular menu button in the one row of the Effects section in the Master Out track in AU Lab, as shown in the figure.

In the menu that opens, choose the Filter audio unit from the Apple Demo group:

The custom view for the Filter audio unit opens.

The custom view’s frequency response curve is drawn in real time based on the audio unit’s actual frequency response. The audio unit makes its frequency response data available to the custom view by declaring a custom property. The audio unit keeps the value of its custom property up to date. The custom view queries the audio unit’s custom property to draw the frequency response curve.

7. Option-click the audio unit name in the Effects row.

A second instance of a view for the Filter audio unit opens.

8. Click the view type pop-up menu in one instance of the audio unit’s view, as shown in the figure:

In the menu that opens, choose the Generic View item:

The view changes to the generic view, as shown in the next figure. You are now set up to demonstrate gestures and audio unit events.

9. Click and hold one of the sliders in the generic view, as shown in the figure. When you click, observe that the crosshairs in the custom view become highlighted in bright blue. They remain highlighted as long as you hold down the mouse button.

As you move the slider in the generic view, frequency response curve in the custom view keeps pace with the new setting.

• The highlighting and un-highlighting of the crosshairs in the custom view, when you click and release on a slider in the generic view, result from gesture events.

• The changes in the frequency response curve in the custom view, as you move a slider in the generic view, result from parameter change events

10. Finally, click and hold at the intersection of the crosshairs in the custom view. When you click, observe that the sliders in the generic view become highlighted. As you move the crosshairs in the custom view, the sliders in the generic view keep pace with the new settings.

This demonstrates that both views, and the audio unit itself, remain in sync by way of audio unit events.

< Previous PageNext Page > Hide TOC

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice