Class

AUAudioUnit

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

Declaration

@interface AUAudioUnit : NSObject

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:

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 initWithComponentDescription:options:error: method ensures that the proper subclass is used.

Topics

Initialization

- initWithComponentDescription:error:

Synchronously initializes a new audio unit object.

- initWithComponentDescription:options:error:

Synchronously initializes a new audio unit object.

Instantiation

+ instantiateWithComponentDescription:options:completionHandler:

Asynchronously creates an audio unit instance.

Querying Descriptive Properties

componentDescription

The component description with which the audio unit was created.

component

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

componentName

The audio unit’s component’s name.

componentVersion

The audio unit’s component’s version.

audioUnitName

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

manufacturerName

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

Managing Render Resources

- allocateRenderResourcesAndReturnError:

Allocates resources required to render audio.

- deallocateRenderResources

Deallocates resources required to render audio.

- reset

Resets transitory rendering state to its initial state.

renderResourcesAllocated

Determines whether the audio unit has allocated render resources.

Querying Busses

inputBusses

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

outputBusses

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

Managing the Render Cycle

renderBlock

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

scheduleParameterBlock

The block that hosts use to schedule parameters.

maximumFramesToRender

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

- tokenByAddingRenderObserver:

Adds a block to be called on each render cycle.

- removeRenderObserver:

Removes an observer block previously added to the render cycle.

Querying Parameters

parameterTree

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

allParameterValues

Special read-only property for KVO.

- parametersForOverviewWithCount:

Returns the audio unit’s most important parameters.

Managing MIDI Events

musicDeviceOrEffect

Specifies whether an audio unit responds to MIDI events.

virtualMIDICableCount

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

scheduleMIDIEventBlock

A block used to schedule MIDI events.

Managing Presets

fullState

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

fullStateForDocument

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

factoryPresets

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

currentPreset

The audio unit’s last-selected preset.

Optimizing Performance

latency

The audio unit’s processing latency, in seconds.

tailTime

The audio unit’s tail time, in seconds.

renderQuality

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

shouldBypassEffect

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

canProcessInPlace

Determines whether an audio unit can process in place.

renderingOffline

Communicates to an audio unit that it is rendering offline.

Channel Capabilities

channelCapabilities

Expresses valid combinations of input and output channels.

Host Callbacks

musicalContextBlock

A callback to the host for musical context information.

transportStateBlock

A callback to the host for transport state information.

contextName

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

Input/Output Units

canPerformInput

Determines whether the I/O device can perform input.

canPerformOutput

Determines whether the I/O device can perform output.

inputEnabled

A flag enabling audio input from the unit.

outputEnabled

A flag enabling audio output from the unit.

inputHandler

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

outputProvider

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

deviceID

Gets the I/O hardware device.

- setDeviceID:error:

Sets the I/O hardware device.

- startHardwareAndReturnError:

Starts the audio hardware.

- stopHardware

Stops the audio hardware.

Audio Unit Implementations

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

internalRenderBlock

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

+ registerSubclass:asComponentDescription:name:version:

Registers an audio unit component implemented as an AUAudioUnit subclass.

- shouldChangeToFormat:forBus:

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

- setRenderResourcesAllocated:

Sets the Boolean value of the renderResourcesAllocated property.

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.

AURenderPullInputBlock

A block to supply audio input to a render block.

AURenderBlock

A block to render the audio unit.

AURenderObserver

A block called when an audio unit renders audio.

AUScheduleParameterBlock

A block to schedule parameter changes.

AUScheduleMIDIEventBlock

A block to schedule MIDI events.

AUHostMusicalContextBlock

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

AUHostTransportStateBlock

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

AUInputHandler

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

AUInternalRenderBlock

A block to render the audio unit.

Relationships

Inherits From

See Also

Audio Unit v3

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

An AUParameterGroup object represents a group of related audio unit parameters. A parameter group is KVC-compliant for its children.

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.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software