Class

AUAudioUnit

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

Overview

Hosts can instantiate either version 3 or version 2 audio units with this class, and to some extent control whether an audio unit is instantiated in-process or in a separate extension process.

Version 3 audio units should subclass the AUAudioUnit class. Version 3 audio unit components can be registered in the following ways:

  • Package the component into an app extension containing an AudioComponents Info.plist entry. The principal class must conform to the AUAudioUnitFactory protocol, which will typically instantiate an AUAudioUnit subclass.

  • Call the registerSubclass(_:as:name:version:) method to associate a component description with an AUAudioUnit subclass.

Version 2 audio units should subclass the AUAudioUnitV2Bridge class instead. Version 2 audio unit components can be registered in the following ways:

  • Package the component into a component bundle containing an AudioComponents Info.plist entry, referring to an AudioComponentFactoryFunction function.

  • Call the AudioComponentRegister function to associate a component description with an AudioComponentFactoryFunction function.

A host does not need to be aware of the concrete AUAudioUnit subclass that is being instantiated. The init(componentDescription:options:) method ensures that the proper subclass is used.

Topics

Initialization

Querying Descriptive Properties

var componentDescription: AudioComponentDescription

The component description with which the audio unit was created.

var component: AudioComponent

The component found in the component description with which the audio unit was created.

var componentName: String?

The audio unit’s component’s name.

var componentVersion: UInt32

The audio unit’s component’s version.

var audioUnitName: String?

The audio unit’s name, derived from the component’s name.

var manufacturerName: String?

The manufacturer’s name, derived from the component’s name.

Managing Render Resources

func allocateRenderResources()

Allocates resources required to render audio.

func deallocateRenderResources()

Deallocates resources required to render audio.

func reset()

Resets transitory rendering state to its initial state.

var renderResourcesAllocated: Bool

Determines whether the audio unit has allocated render resources.

Querying Busses

var inputBusses: AUAudioUnitBusArray

An array containing the audio unit’s input connection points.

var outputBusses: AUAudioUnitBusArray

An array containing the audio unit’s output connection points.

Managing the Render Cycle

var renderBlock: AURenderBlock

The block that hosts use to ask the audio unit to render audio.

var scheduleParameterBlock: AUScheduleParameterBlock

The block that hosts use to schedule parameters.

var maximumFramesToRender: AUAudioFrameCount

The maximum number of frames that the audio unit can render at once.

func token(byAddingRenderObserver: AURenderObserver) -> Int

Adds a block to be called on each render cycle.

func removeRenderObserver(Int)

Removes an observer block previously added to the render cycle.

Querying Parameters

var parameterTree: AUParameterTree?

An audio unit’s parameters, organized in a tree hierarchy.

var allParameterValues: Bool

Special read-only property for KVO.

func parametersForOverview(withCount: Int) -> [NSNumber]

Returns the audio unit’s most important parameters.

Managing MIDI Events

var isMusicDeviceOrEffect: Bool

Specifies whether an audio unit responds to MIDI events.

var virtualMIDICableCount: Int

The number of virtual MIDI cables implemented by a music device or effect.

var scheduleMIDIEventBlock: AUScheduleMIDIEventBlock?

A block used to schedule MIDI events.

Managing Presets

var fullState: [String : Any]?

A persistable snapshot of the audio unit’s properties and parameters, suitable for saving as a user preset.

var fullStateForDocument: [String : Any]?

A persistable snapshot of the audio unit’s properties and parameters, suitable for saving in a user’s document.

var factoryPresets: [AUAudioUnitPreset]?

A collection of presets provided by the audio unit’s developer.

var currentPreset: AUAudioUnitPreset?

The audio unit’s last-selected preset.

Optimizing Performance

var latency: TimeInterval

The audio unit’s processing latency, in seconds.

var tailTime: TimeInterval

The audio unit’s tail time, in seconds.

var renderQuality: Int

Provides a trade-off between rendering quality and CPU load.

var shouldBypassEffect: Bool

Determines whether an effect should route input directly to output, without any processing.

var canProcessInPlace: Bool

Determines whether an audio unit can process in place.

var isRenderingOffline: Bool

Communicates to an audio unit that it is rendering offline.

Channel Capabilities

var channelCapabilities: [NSNumber]?

Expresses valid combinations of input and output channels.

Host Callbacks

var musicalContextBlock: AUHostMusicalContextBlock?

A callback to the host for musical context information.

var transportStateBlock: AUHostTransportStateBlock?

A callback to the host for transport state information.

var contextName: String?

Information about the host context in which the audio unit is connected, for display in the audio unit’s view.

Input/Output Units

var canPerformInput: Bool

Determines whether the I/O device can perform input.

var canPerformOutput: Bool

Determines whether the I/O device can perform output.

var isInputEnabled: Bool

A flag enabling audio input from the unit.

var isOutputEnabled: Bool

A flag enabling audio output from the unit.

var inputHandler: AUInputHandler?

The block that the output unit will call to notify when input is available.

var outputProvider: AURenderPullInputBlock?

The block that the output unit will call to get audio to send to the output.

var deviceID: AudioObjectID

Gets the I/O hardware device.

func setDeviceID(AudioObjectID)

Sets the I/O hardware device.

func startHardware()

Starts the audio hardware.

func stopHardware()

Stops the audio hardware.

Audio Unit Implementations

These methods and properties are only of interest to audio unit subclasses.

var internalRenderBlock: AUInternalRenderBlock

The block which you must provide, via a getter, in order to implement rendering.

class func registerSubclass(AnyClass, as: AudioComponentDescription, name: String, version: UInt32)

Registers an audio unit component implemented as an AUAudioUnit subclass.

func shouldChange(to: AVAudioFormat, for: AUAudioUnitBus) -> Bool

This is called when you set the format on a bus.

Constants

AUEventSampleTime

Expresses time as a sample count.

AUAudioUnitBusType

Describes whether a bus array is for input or output.

AUHostTransportStateFlags

Flags describing the host’s transport state.

AURenderEventType

Describes the type of a render event.

typealias AURenderPullInputBlock

A block to supply audio input to a render block.

typealias AURenderBlock

A block to render the audio unit.

typealias AURenderObserver

A block called when an audio unit renders audio.

typealias AUScheduleParameterBlock

A block to schedule parameter changes.

typealias AUScheduleMIDIEventBlock

A block to schedule MIDI events.

typealias AUHostMusicalContextBlock

A block through which hosts provide musical tempo, time signature, and beat position.

typealias AUHostTransportStateBlock

A block through which hosts provide information about their transport state.

typealias AUInputHandler

A block to notify the host of an I/O unit that an input is available.

typealias AUInternalRenderBlock

A block to render the audio unit.

Relationships

Inherits From

Conforms To