Audio Unit
An Audio Unit app extension gives users a convenient way to create or modify audio in any iOS or macOS app that uses sound, including music production apps such as GarageBand or Logic Pro X.
An Audio Unit app extension has two main elements: an audio unit proper and a user interface (UI) to control the audio unit. The audio unit itself is a custom plug-in in which you implement an audio creation or an audio processing algorithm. You build the audio unit using the Audio Unit framework, whose APIs are described in Audio Unit Framework Reference. (Designing and building audio units is not covered in the current document, which instead explains how to incorporate an audio unit into an Audio Unit app extension target.) When creating an Audio Unit app extension, you design and create its UI in the storyboard file that is included in the extension’s Xcode template.
Figure 6-1 shows the architectural relationships between an audio unit proper and its user interface, which are both contained in the Audio Unit app extension, and between the extension and the host app that is using it.
If you have need to provide an Audio Unit app extension without a UI, you can do so by excluding the audio unit user interface, as suggested by the dashed outline in the figure.
Figure 6-2 shows an example UI for a custom filter Audio Unit app extension. The “draggable point” in the figure is a control that lets the user modify audio unit parameters for resonance and cutoff frequency.
For a video introduction to Audio Unit app extensions, watch the WWDC 2015 presentation Audio Unit Extensions. For a code example that shows how to create an Audio Unit app extension, see AudioUnitV3Example: A Basic AudioUnit Extension and Host Implementation. For more information on the audio unit API, see Audio Unit Framework Reference.
Audio Unit app extensions are supported in iOS 9.0 and later, and in macOS v10.11 and later. The Audio Unit app extension template is available starting in Xcode 7.
How Audio Unit App Extensions Work
In a host app that supports audio units in its audio processing pipeline, a user can choose to use an Audio Unit app extension to add the app extension’s features to the host app.
Each Audio Unit app extension contains exactly one audio unit. There are four audio unit types you can choose from, according to the role for your app extension:
For audio creation: A generator unit creates audio according to a digital signal processing (DSP) algorithm that you provide. An instrument unit creates audio, typically using a voice bank, in response to MIDI events.
For audio modification: An effect unit modifies audio according to a DSP algorithm. A music effect unit modifies audio, using DSP, in response to MIDI events.
Table 6-1 summarizes the four variants of Audio Unit app extension you can create, according to the contained audio unit type:
Category |
Employs DSP |
Employs DSP and responds to MIDI events |
---|---|---|
Audio creation |
|
|
Audio modification |
|
|
.
For the principal class in an Audio Unit app extension, subclass the AUViewController
class. (If you need to provide an Audio Unit app extension with no UI, subclass the NSObject
class instead.) The principal class for your extension must conform to the AUAudioUnitFactory
protocol.
Using the Xcode Audio Unit App Extension Template
The Xcode Audio Unit app extension template includes default source files for an AUAudioUnit
subclass for the audio unit itself, an Info.plist
file, an AUViewController
subclass, and a MainInterface.storyboard
file.
Listing 6-1 shows the Info.plist
keys and values for an iOS Audio Unit app extension for the Effect variant. The type
key in this property list specifies the audio unit type that determines the variant, in this case with a value of aufx
. For explanations of all the available keys and values, see Table 6-2.
<key>NSExtension</key>
<dict>
<key>NSExtensionAttributes</key>
<dict>
<key>AudioComponents</key>
<array>
<dict>
<key>description</key>
<string>TremoloUnit</string>
<key>manufacturer</key>
<string>Aaud</string>
<key>name</key>
<string>Aaud: TremoloUnit</string>
<key>sandboxSafe</key>
<true/>
<key>subtype</key>
<string>tmlo</string>
<key>tags</key>
<array>
<string>Effects</string>
</array>
<key>type</key>
<string>aufx</string>
<key>version</key>
<integer>0001</integer>
</dict>
</array>
</dict>
<key>NSExtensionMainStoryboard</key>
<string>MainInterface</string>
<key>NSExtensionPointIdentifier</key>
<string>com.apple.AudioUnit-UI</string>
</dict>
The Audio Unit app extension template includes an Audio Unit Type option that lets you pick among four variants: Instrument, Generator, Effect, and Music Effect. Each of these variants includes a storyboard file for a user interface. If you need to create an app extension without a UI, with any of these variants, perform the following steps after you have created the app extension target:
Replace the
AUViewController
subclass with anNSObject
subclass.Replace the
NSExtensionMainStoryboard
key with theNSExtensionPrincipalClass
key.
An Audio Unit app extension has several customizable values in its Info.plist
file, described in Table 6-2.
Key |
Value description |
---|---|
|
A product name for the audio unit, such as |
|
A manufacturer code for the audio unit, such as |
|
The full name of the audio unit. This is derived from the |
|
(macOS only) A Boolean value indicating whether the audio unit can be loaded directly into a sandboxed process. For more information on sandboxing, see App Sandboxing. |
|
A subtype code for the audio unit, such as |
|
An array of tags that describe the audio unit. The following predefined tags are already localized for your convenience: |
|
The specific variant of the Audio Unit app extension, as you choose it when setting up the Xcode template. The four possible types and their values are: Effect ( |
|
A version number for the Audio Unit app extension, such as |
|
The name of the main storyboard file for the Audio Unit app extension. This key is required unless you are specifically creating an Audio Unit app extension without a user interface. In that unusual case, use the |
|
The extension point identifier for the Audio Unit app extension. This value is |
Designing the User Interface
In iOS, a host app defines the size and position of a container view that embeds the remote view controller from the Audio Unit app extension.
For more information on designing app extension user interfaces for iOS, see iOS Human Interface Guidelines.
For macOS, consider the size and position of the selected content in the host app when specifying the size and position of the Audio Unit app extension’s main view.
For macOS, use the preferredContentSize
property of the NSViewController
class to specify the Audio Unit app extension main view’s preferred size, based on the size of the selected content. (You can also specify minimum and maximum sizes for the extension’s view, to ensure that a host app doesn’t make unreasonable adjustments to the view.) To specify a preferred position for the app extension main view, set the preferredScreenOrigin
property to the lower-left corner of the extension’s view.
For more information on designing app extensions for macOS, see macOS Human Interface Guidelines.
Connecting the App Extension UI to the Audio Unit
You must connect your App Extension UI—specifically, the audio unit user interface code—to the audio unit proper. Critically, you cannot assume the order in which the extension UI and its associated audio unit are loaded when a host app requests the app extension. The AUViewController
subclass must attempt to connect its UI controls to its audio unit parameters when either the UI has been loaded or when the audio unit has been loaded, whichever happens first. Listing 6-2 shows code that attempts to connect the extension UI to its audio unit for both cases.
@implementation AudioUnitViewController {
AUAudioUnit *audioUnit;
}
- (AUAudioUnit *)createAudioUnitWithComponentDescription:(AudioComponentDescription)desc error:(NSError **)error {
audioUnit = [[MyAudioUnit alloc] initWithComponentDescription:desc error:error];
// Check if the UI has been loaded
if(self.isViewLoaded) {
[self connectUIToAudioUnit];
}
return audioUnit;
}
- (void) viewDidLoad {
[super viewDidLoad];
// Check if the Audio Unit has been loaded
if(audioUnit) {
[self connectUIToAudioUnit];
}
}
- (void)connectUIToAudioUnit {
// Get the parameter tree and add observers for any parameters that the UI needs to keep in sync with the Audio Unit
}
@end
Overriding AUAudioUnit Properties and Methods
You must override the following properties in your AUAudioUnit
subclass:
Override the
inputBusses
getter method to return the app extension’s audio input connection points.Override the
outputBusses
getter method to return the app extension’s audio output connection points.Override the
internalRenderBlock
getter method to return the block that implements the app extension’s audio rendering loop.
Also override the allocateRenderResourcesAndReturnError:
method, which the host app calls before it starts to render audio, and override the deallocateRenderResources
method, which the host app calls after it has finished rendering audio. Within each override, call the AUAudioUnit
superclass implementation.
Copyright © 2018 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2017-10-19