- iOS 13.0+
- macOS 10.15+
- Xcode 11.1+
This sample app shows you how to use AU plug-ins in your iOS and macOS apps. You find and instantiate plug-ins, incorporate their user interfaces into your app’s interface, and work with their presets.
The sample app has targets for iOS and macOS. Both versions have three primary classes.
Hostand its associated Storyboard provide the user interface.
Audiomanages the interactions with the effect and instrument plug-ins.
AVAudioto play back audio samples and MIDI data.
Find Audio Units
You find Audio Units that are registered with the host system by creating an
Audio defining your search criteria. The sample app searches for component types, either audio effects (
k) or MIDI instruments (
k). You can also pass values for the other fields of
Audio or pass
0 as a wildcard matching all values. Get the shared instance of
AVAudio and call its
components(matching:) method to find the components matching your search criteria.
This method returns an array of
AVAudio objects matching the component description, or an empty array if it found no matches. You can access a component’s properties to determine its capabilities and find identifying values, such as its name and manufacturer, for display in your user interface.
Instantiate Audio Units
When the user selects an Audio Unit in the user interface, your app needs to find the component and instantiate it.
iOS supports third-party plug-ins built using the latest Audio Unit standard (AUv3), which is based on the App Extensions model. Like all App Extensions in iOS, AUv3 plug-ins run out-of-process, which means they run in a dedicated process outside your app, and communication with the extension is done over interprocess communication (IPC).
You instantiate an AU by calling the
instantiate(with: method, passing it the component description. This method asynchronously returns the instantiated
AVAudio or an
Error if the process failed. You must avoid blocking your application’s main thread when instantiating an Audio Unit.
In macOS, AUv3 plug-ins also default to running out-of-process. Running an Audio Unit this way is safer and more secure, because a misbehaving plug-in can’t corrupt or crash your app. However, the interprocess communication required of this model adds some small but potentially significant overhead. This can be problematic in professional audio environments where multiple Audio Units are used, especially when rendering at small audio I/O buffer sizes. To resolve this problem, AU authors can package their plug-ins to be run in-process. In macOS only, you can load an appropriately packaged plug-in in-process by passing that instantiation option to the
instantiate method, as shown below.
Present an Audio Unit’s Custom View
A plug-in can provide a custom user interface to control its parameters. You get the custom view by asking the plug-in for its view controller, which returns an instance of
nil if it doesn’t provide a custom view. You add the view controller’s view to your user interface using the appropriate approach for your platform.
Select Alternative View Configurations
All AU plug-ins can provide a custom user interface, but AUv3 plug-ins may also provide alternative views. A host app can support multiple view configurations. For example, an iOS app may provide compact and expanded views and switch between them depending on the device size or orientation. You define one or more supported view configurations using the
The host can ask the plug-in which, if any, custom view configurations it supports.
When the host switches between its supported configurations, it can ask the Audio Unit to do the same. The sample app defines two configurations and attempts to toggle between them.
Load Factory Presets
A plug-in author can optionally provide one or more presets that define specific configurations of the plug-in’s parameter values. You access an
AUAudio object’s presets through its
factory property, which returns an array of
AUAudio instances, or an empty array if it defines none.
The sample app uses a simple wrapper type called
Preset to pass to the user interface tier. The view controller uses these objects to build the app’s preset selection interface.
Manage User Presets
A plug-in may also support user presets, which are user-configured parameter settings. You query the Audio Unit’s
supports property to determine if it supports saving user presets.
If a plug-in supports user presets, you can get the currently saved presets by querying its
To be notified of changes to the Audio Unit’s user presets, you add a key-value observer to the
user property. By observing changes to this property, you’ll get callbacks as presets are added or deleted.
To create a new user preset, first create an instance of
AUAudio and give it a user-defined name and a negative
number value (user presets require a negative value for this property). Then call the
save method, which persists the parameter state so the Audio Unit can recall it later.
If the user decides to delete this or another user preset, you call
delete to remove it.
Select Factory and User Presets
To select a factory or user preset, set it as the Audio Unit’s
current property. This restores the plug-in’s parameter state to the values stored with the specified preset.