IOS Audio -AudioUnit (official documentation)

4. Use specific Audio Units

Every iOS audio unit has some things in common and some things unique. The first few chapters of this document describe common areas, including the need to find an audio unit at run time, instantiate it, and ensure that its stream format is properly set. This chapter explains the differences between audio units and provides details on how to use them.

In a later section, Identifier Keys for Audio Units lists the code you need to find a dynamic link library for each Audio unit at runtime.

Using I/O Units

IOS provides three I/O (input/output) units. The vast majority of audio unit applications use the Remote I/O Unit, which connects to input and output audio hardware and provides low-latency access to individual incoming and outgoing audio sample values. For VoIP applications, the voice-processing I/O Unit extends the Remote I/O unit by adding echo cancellation and other features. To send audio back to the application rather than Output audio hardware, use the Generic Output Unit

Remote I/O Unit

The RemoteI /O unit (subtype kAudioUnitSubType_RemoteIO) is connected to the device hardware for input, output, or both. Use it for playback, recording, or low-latency synchronous input and output without the need for echo cancellation.

The device’s audio hardware forces its audio Stream Formats outside of the Reteme I/O unit, as described in Understanding Where and How to Set Stream Formats. The audio unit provides format conversion between hardware audio formats and application audio formats through the included format converter audio unit.

For sample code that demonstrates how to use this audio unit, see the sample code project aurioTouch

Table 3-1 describes the usage of the audio unit.

Table 3-1 Using the Remote I/O unit

Audio unit feature	Details
Elements	1. An output element: element 0. By default, input Element is disabled and Output Element is enabled. If you need to change this property, refer tokAudioOutputUnitProperty_EnableIOAttribute description.
Recommended stream format attributes	kAudioFormatLinearPCM AudioUnitSampleType kAudioFormatFlagsAudioUnitCanonical
Stream format notes	The external of the Remote I/O unit is obtained from the audio hardware in the following format: 1. The input scope of the input Element (Element 1) gets the stream format from the currently active audio input hardware. 2. The Output scope of the Output Element (Element 0) gets the stream format from the currently active output audio hardware. Format the application on the Output scope of the Input Element. Input elements perform formatting conversions between their input and output ranges as needed. Use hardware sampling rates for application flow formats. If an Output element’s input range is provided by an audio unit connection, it takes its stream format from that connection. However, if it is provided by the render callback function, then the application format is set on it.
Parameters	None in iOS.
Properties	referenceI/O Audio Unit Properties.
Property notes	You never need to set it up on this audio unitkAudioUnitProperty_MaximumFramesPerSliceattribute

Voice-Processing I/O Unit

The voice-processing I/O unit (subtype kAudioUnitSubType_VoiceProcessingIO) has the features of Remote I/O units and adds echo suppression for two-way duplex communication. It also adds automatic gain correction, voice processing quality adjustment and mute function. This is the correct I/O unit for Voice over Internet Protocol (VoIP) applications.

All of the considerations listed in Table 3-1 also apply to the Voice-Processing I/O unit. In addition, the specific Properties available for this Audio Unit are described in the Voice-Processing I/O Audio Unit Properties

Generic Output Unit

When sending the output of the Audio Processing graph to an application instead of the audio hardware, use an audio unit of subtype kAudioUnitSubType_GenericOutput. You typically use Generic Output units for offline audio processing. Like other I/O units, the generic output unit integrates a format converter unit. This allows the Generic Output unit to perform format conversions between the stream format used in the Audio Processing Graph and the format you want.

Using Mixer Units

IOS provides two Mixer units. In most cases, you should use a Multichannel Mixer unit, which provides mixing for any number of mono or stereo streams. If you need the functionality of a 3D Mixer unit, you’ll most likely use OpenAL instead. OpenAL is built on top of the 3D Mixer unit, providing the same performance through a simpler API ideal for game application development.

Multichannel Mixer Unit

The Multichannel Mixer Unit (subtype kAudioUnitSubType_MultiChannelMixer) accepts any number of mono or stereo streams and combines them into a single stereo output. It controls the audio gain for each input and output, and lets you turn each input on or off individually. Starting with iOS 4.0, The Multichannel Mixer supports stereo panning for every input.

For sample code that demonstrates how to use this audio unit, see the Sample code project Audio Mixer (MixerHost).

Table 3-2 describes the usage of the audio unit.

Table 3-2 Using the Multichannel Mixer unit

Audio unit feature	Details
Elements	One or more input elements, each of which can be mono or stereo. A stereo output element
Recommended stream format attributes	kAudioFormatLinearPCM AudioUnitSampleType kAudioFormatFlagsAudioUnitCanonical
Stream format notes	On Inout Scope, manage the stream format as follows: 1. If the input bus is provided by an audio unit connection, it gets the stream format from that connection. 2. If the input bus is provided by a callback function, set the full application flow format on the bus. Use the same flow format as the data provided by the callback. In the Output Scope, only the application sampling rate is set
Parameters	referenceMultichannel Mixer Unit Parameters.
Properties	kAudioUnitProperty_MeteringMode
Property notes	By default,kAudioUnitProperty_MaximumFramesPerSliceProperty is set to 1024, which is not sufficient for screen lock and display sleep. If your application plays audio with the screen locked, you must increase the value of this property unless audio input is enabled. Perform the following operations: 1. If the audio input is active, you do not need to set a value for the kAudioUnitProperty_MaximumFramesPerSlice property. If audio input is not active, set this property to 4096.

Using Effect Units

The iPodEQ unit (subtype kAudioUnitSubType_AUiPodEQ) is the only effect unit available in iOS 4. This is the same equalizer that uses the built-in iPod app. To see the iPod app’s user interface for this audio unit, go to Settings > iPod > EQ. This audio unit provides a set of preset equalization curves such as Bass Booster, Pop, and Spoken Word.

You must provide your own user interface iPod EQ unit, as you must do for any audio unit. The Mixer iPodEQ AUGraph Test sample code project demonstrates how to use the iPodEQ unit and shows a way to provide a user interface for it.

Table 3-4 describes the usage of the audio unit.

Table 3-4 Using the iPod EQ unit

Audio unit feature	Details
Elements	A mono or stereo input element. A mono or stereo output element
Recommended stream format attributes	1. kAudioFormatLinearPCM 2. AudioUnitSampleType 3. kAudioFormatFlagsAudioUnitCanonical
Stream format notes	On the Input Scope, manage the stream format as follows: 1. If the input is provided by an audio unit connection, it takes the stream format from that connection. 2. If the input is provided by a callback function, set the full application flow format on the bus. Use the same flow format as the data provided by the callback. On the Output scope, set the same full stream format as the input
Parameters	None.
Properties	kAudioUnitProperty_FactoryPresets 和 kAudioUnitProperty_PresentPreset
Property notes	The iPod EQ unit comes with a set of pre-set tonal equalization curves as factory presets. Get an array of available EQ Settings by accessing the audio unit’s ‘kAudioUnitProperty_FactoryPresets’ property. You can then apply a setting by using it as the value of the ‘kAudioUnitProperty_PresentPreset’ property. By default, the ‘kAudioUnitProperty_MaximumFramesPerSlice’ property is set to 1024, which is not sufficient for screen lock and display sleep. If your application plays audio with the screen locked, you must increase the value of this property unless audio input is enabled. Do the following: If the audio input is active, you do not need to set a value for the ‘kAudioUnitProperty_MaximumFramesPerSlice’ property. If audio input is not active, set this property to 4096.

Identifier Keys for Audio Units

This table provides the identification keys you need to access the dynamic link library for each iOS audio unit, along with a brief description of the audio unit.

Table 3-5 Identifier keys for accessing the dynamically-linkable libraries for each iOS audio unit

Name and description	Identifier keys	Corresponding four-char codes
Converter unitSupports audio format conversions to or from linear PCM.	kAudioUnitType_FormatConverter kAudioUnitSubType_AUConverter kAudioUnitManufacturer_Apple	aufc conv appl
iPod Equalizer unitProvides the features of the iPod equalizer.	kAudioUnitType_Effect kAudioUnitSubType_AUiPodEQ kAudioUnitManufacturer_Apple	aufx ipeq appl
3D Mixer unitSupports mixing multiple audio streams, output panning, sample rate conversion, and more.	kAudioUnitType_Mixer kAudioUnitSubType_AU3DMixerEmbedded kAudioUnitManufacturer_Apple	aumx 3dem appl
Multichannel Mixer unitSupports mixing multiple audio streams to a single stream.	kAudioUnitType_Mixer kAudioUnitSubType_MultiChannelMixer kAudioUnitManufacturer_Apple	aumx mcmx appl
Generic Output unitSupports converting to and from linear PCM format; can be used to start and stop a graph.	kAudioUnitType_Output kAudioUnitSubType_GenericOutput kAudioUnitManufacturer_Apple	auou genr appl
Remote I/O unitConnects to device hardware for input, output, or simultaneous input and output.	kAudioUnitType_Output kAudioUnitSubType_RemoteIO kAudioUnitManufacturer_Apple	auou rioc appl
Voice Processing I/O unitHas the characteristics of the I/O unit and adds echo suppression for two-way communication.	kAudioUnitType_Output kAudioUnitSubType_VoiceProcessingIO kAudioUnitManufacturer_Apple	auou vpio appl