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 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.

class AUAudioUnit

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

class AUAudioUnitBus

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

class AUAudioUnitBusArray

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

class 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.

class AUAudioUnitV2Bridge

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

class AUParameter

An AUParameter object represents a single audio unit parameter.

class AUParameterGroup

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

class AUParameterNode

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

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).

protocol AUAudioUnitFactory

Implement this protocol to create a version 3 audio unit.