Article

Hosting Audio Unit Extensions Using the AUv2 API

Update your existing Audio Unit v2 host app to load and use Audio Unit extensions.

Overview

The latest Audio Unit standard, AUv3, provides a robust plug-in model built on app extensions. This model provides several benefits to host apps, including greater security and stability, multiple view configurations, and support for shared user presets.

With only minor modifications to your existing AUv2 host app, you’re able to load and interact with Audio Unit extensions. The framework provides a bridging layer that automatically translates AUv2 calls into their AUv3 equivalents, and vice versa. This bridging is largely transparent to your app, and you’re only required to make minor changes to how you instantiate components and access their user interfaces.

A component diagram that shows the bridging support provided by the framework.

Asynchronously Instantiate Audio Units

AUv3 extensions that provide a user interface require that you instantiate them asynchronously. Attempting to instantiate them using the synchronous AudioComponentInstanceNew function fails. Instead, check for the existence of the kAudioComponentFlag_RequiresAsyncInstantiation component flag. If present, asynchronously instantiate the component using the new AudioComponentInstantiate function, as shown in the following code example.

AudioComponent component = ...
AudioComponentDescription componentDesc;

// Get the component description.
AudioComponentGetDescription(component, &componentDesc);

// Determine if async loading is required.
bool requiresAsync = (componentDesc.componentFlags &
                      kAudioComponentFlag_RequiresAsyncInstantiation) > 0;

if (requiresAsync) {
    // Asynchronous Path
    AudioComponentInstantiate(component,
                              kAudioComponentInstantiation_LoadOutOfProcess,
                              ^(AudioComponentInstance audioUnit, OSStatus error) {
        // Initialize AudioUnit instance.
    });
} else {
    // Synchronous Path
    AudioComponentInstance audioUnit;
    if (AudioComponentInstanceNew(component, &audioUnit) == noErr) {
        // Initialize AudioUnit instance.
    }
}

If the component requires asynchronous instantiation, call the AudioComponentInstantiate function, and pass it the component you want to instantiate, the desired instantiation option (in or out of process), and a completion block that’s called when the instantiation completes. This callback block provides the audio unit instance or any errors that might have occurred while instantiating the component.

Present the Audio Unit's User Interface

You access an AUv2 plug-in’s user interface by retrieving its kAudioUnitProperty_CocoaUI property. This property isn’t used with AUv3 plug-ins; you retrieve the user interface instead using the kAudioUnitProperty_RequestViewController property. You do so by setting a callback block that’s invoked when the framework loads the user interface. The callback provides a reference to the Audio Unit’s user interface, which you can present in your host’s interface.

AudioComponent component = ...

AudioComponentDescription componentDesc;
AudioComponentGetDescription(component, &componentDesc);

bool isAUv3 = (componentDesc.componentFlags &
               kAudioComponentFlag_IsV3AudioUnit) > 0;

if (isAUv3) {
    __block AUViewControllerBase *viewController = nil;
    
    auto callback = ^(AUViewControllerBase *vc) {
        viewController = vc;
        // Dispatch back to the main queue to embed the UI.
    };
    
    // AUv3: Retrieve the UI using the kAudioUnitProperty_RequestViewController property.
    AudioUnitSetProperty(audioUnit,
                         kAudioUnitProperty_RequestViewController,
                         kAudioUnitScope_Global,
                         0,
                         &callback,
                         sizeof(callback));
} else {
    // AUv2: Retrieve the UI using the kAudioUnitProperty_CocoaUI property.
}

See Also

Audio Unit v3

Migrating Your Audio Unit Host to the AUv3 API

Update your Audio Unit (AU) host app to take advantage of the new features and capabilities of AUv3.

AUAudioUnit

The AUAudioUnit class defines a host’s interface to an audio unit.

AUAudioUnitBus

The AUAudioUnitBus class defines an input or output connection point on an audio unit.

AUAudioUnitBusArray

The AUAudioUnitBusArray class defines a container for an audio unit’s input or output busses.

AUAudioUnitPreset

The AUAudioUnitPreset class describes an interface for custom parameter settings provided by the audio unit developer. These presets often produce a useful sound or starting point.

AUAudioUnitV2Bridge

The AUAudioUnitV2Bridge class wraps a version 2 audio unit in an AUAudioUnit subclass.

AUParameter

An AUParameter object represents a single audio unit parameter.

AUParameterGroup

A parameter group object represents a group of related audio unit parameters.

AUParameterNode

An AUParameterNode object represents a node in an audio unit’s parameter tree. Nodes are instances of either an AUParameter or AUParameterGroup class.

AUParameterTree

An AUParameterTree object is a top-level group node, representing all of an audio unit’s parameters. An audio unit’s parameters are organized into a tree containing groups and parameters (groups may be nested).

AUAudioUnitFactory

Implement this protocol to create a version 3 audio unit.