Audio Unit Properties

Overview

This chapter describes the function-like macros declared in the AudioUnitProperties.h header file. You can use these macros to work with an audio unit parameter’s display types—one of the attributes specified by the flags field in the AudioUnitParameterInfo data structure.

Overview

Audio unit properties, part of the audio unit plug-in interface, are key-value pairs that declare attributes or behavior such as audio data stream format, latency, or connection from one audio unit to another. Properties are typically non-time-varying, not directly settable by the user, and changeable only before an audio unit is initialized. This document describes audio unit property identifiers and their accompanying values.

You access audio unit properties using the Audio Unit framework’s “Get” and “Set” functions, described in Audio Unit Component Services. These functions are:

So-called generic audio unit properties are those that can apply to any audio unit. There are also Apple-specific properties that apply only to Apple-supplied audio units. This document describes both. Apple reserves property IDs from 0 through 63999; you may use property IDs above this range.

In addition to its value, the attributes of an audio unit property are as follows:

  • Scope—the programmatic context, within an audio unit, that the property applies to. A property applies to one or more scopes, as described in this document. The audio unit scopes in iOS are Input, Output, and Global. In macOS, audio units have additional, MIDI-related scopes: Group, Part, and Note.

  • Data type—the programmatic data type for the property’s value.

  • Access—read-only, write-only, or read/write.

Symbols

Callbacks

Audio unit host applications can implement these callback functions to provide information to audio units.

On the desktop, MIDI audio units can implement these callbacks to provide MIDI data to audio unit host applications.

HostCallback_GetBeatAndTempo

When called by the system, provides beat and tempo information to an audio unit from a host application.

HostCallback_GetMusicalTimeLocation

When called by the system, provides musical timing information to an audio unit from a host application.

HostCallback_GetTransportState

When called by the system, provides audio transport state and timeline information to an audio unit from a host application.

AUMIDIOutputCallback

When called by a host application, gets MIDI data from an audio unit.

Data Types

AUChannelInfo

The audio input and output channel capabilities for an audio unit.

AUDependentParameter

An audio unit parameter whose value can change in response to a change in its parent metaparameter.

AudioOutputUnitStartAtTimeParams

A timestamp for scheduled starting of an I/O audio unit.

AudioUnitCocoaViewInfo

The name and number of custom Cocoa views for an audio unit.

AudioUnitConnection

An audio unit source-to-destination connection specification.

AudioUnitExternalBuffer

Allows an audio unit host application to tell an audio unit to use a specified buffer for its input callback.

AudioUnitFrequencyResponseBin

An audio unit’s audio level at a particular frequency.

AudioUnitMeterClipping

Audio clipping that has occurred in a mixer unit.

AudioUnitParameterUnit

The unit-of-measure for an audio unit parameter.

AudioUnitParameterNameInfo

A short version of the name for an audio unit parameter.

AudioUnitParameterStringFromValue

A string representation of a parameter’s value.

AudioUnitParameterValueFromString

A parameter's value based on a string representation of the value.

AudioUnitParameterHistoryInfo

The suggested update rate and history duration for parameters which have the flag_PlotHistory flag set.

AUHostVersionIdentifier

The name and version of an audio unit’s host application.

AUInputSamplesInOutputCallbackStruct

The callback function and custom data for providing input-to-output sample mapping for an audio unit.

AUMIDIOutputCallbackStruct

The callback function and custom data for an audio unit that provides MIDI output.

AUPreset

Used to set factory presets for an audio unit.

AURenderCallbackStruct

Used for registering an input callback function with an audio unit.

HostCallbackInfo

The time- and transport-related callback functions for an audio unit.

Constants

Audio Unit Scopes

Programmatic roles and contexts for audio unit properties.

Generic Audio Unit Properties

Properties that apply to any audio unit.

I/O Audio Unit Properties

Properties for Apple I/O audio units (sometimes called output units).

Voice-Processing I/O Audio Unit Properties

Properties that apply to the Apple voice-processing I/O audio unit.

Mixer Audio Unit Properties

Properties for Apple mixer audio units.

3D Mixer Audio Unit Properties

Properties for the Apple 3D Mixer audio unit.

3D Mixer Attenuation Curves

Audio level attenuation curves to use with the Apple 3D Mixer audio unit.

3D Mixer Rendering Flags

Rendering options for the Apple 3D Mixer audio unit.

Converter Audio Unit Properties

Properties for the Apple AUConverter audio unit.

Offline Audio Unit Properties

Properties for audio units that perform offline processing—that is, processing in a nonplayback, nonrealtime mode.

Audio Unit Sample Rate Converter Complexity

Quality levels for the audio sample-rate conversion algorithm.

RenderQuality

Render quality settings for audio units.

Spatialization Algorithms

Spatialization algorithms for panner audio units.

Audio Unit Parameter Units of Measure

Keys that designate units of measure for audio unit parameters.

Audio Unit Parameter Flags

Value options for audio unit parameters.

Frequency Response Constants

The maximum number of frequency response bin structures for the AudioUnitProperty_FrequencyResponse property.

Audio Unit Preset Keys

Keys for audio unit kAudioUnitProperty_ClassInfo property dictionaries.

Reserved Audio Unit Clump Identifier

Reserved for system use.