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.

Topics

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.

typealias HostCallback_GetBeatAndTempo

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

typealias HostCallback_GetMusicalTimeLocation

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

typealias HostCallback_GetTransportState

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

typealias AUMIDIOutputCallback

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

Data Types

struct AUChannelInfo

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

struct AUDependentParameter

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

struct AudioOutputUnitStartAtTimeParams

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

struct AudioUnitCocoaViewInfo

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

struct AudioUnitConnection

An audio unit source-to-destination connection specification.

struct AudioUnitExternalBuffer

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

struct AudioUnitFrequencyResponseBin

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

struct AudioUnitMeterClipping

Audio clipping that has occurred in a mixer unit.

enum AudioUnitParameterUnit

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

typealias AudioUnitParameterIDName

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

struct AudioUnitParameterStringFromValue

A string representation of a parameter’s value.

struct AudioUnitParameterValueFromString

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

struct AudioUnitParameterHistoryInfo

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

struct AUHostVersionIdentifier

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

struct AUInputSamplesInOutputCallbackStruct

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

struct AUMIDIOutputCallbackStruct

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

struct AUPreset

Used to set factory presets for an audio unit.

struct AURenderCallbackStruct

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

struct 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.

struct AudioUnitParameterOptions

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.