Audio Session Services Reference

https://developer.apple.com/library/ios/documentation/AudioToolbox/Reference/AudioSessionServicesReference/Reference/reference.html

Overview

This document describes Audio Session Services, a C interface for managing an application’s audio behavior in the context of other applications.

Audio Session Services lets you specify the intended audio behavior for your iOS app. For example, you can specify whether you intend for your app’s audio to silence other apps or to mix with their audio. You also use this API to specify your app’s behavior when it is interrupted, such as by a phone call. When the system knows your intentions, it configures the audio hardware in the device to satisfy those intentions, as possible.

Starting in iOS 5.0, Audio Session Services offers the following three features:

• Audio session modes, each of which refines the configuration provided by your audio session category setting according to the specific purpose of your app. See “Audio Session Modes.”

• Input gain adjustment, providing you with the ability to improve the recorded signal level when the sound you are recording is unusually loud or soft. SeekAudioSessionProperty_InputGainScalar.

• Dictionary-based audio route information, providing specific information on the input and output audio route, on audio route changes, and on audio routes available in a USB-attached audio accessory. See kAudioSessionProperty_AudioRouteDescription,kAudioSessionProperty_AudioRouteChange, kAudioSessionProperty_InputSources, and kAudioSessionProperty_OutputDestinations.

Many of the features of this C interface are available through the Objective-C interface described in AVAudioSession Class Reference.

Functions by Task

These functions apply only to iOS. They do not apply to Mac OS X.

Initializing and Activating an Audio Session

• AudioSessionInitialize
• AudioSessionSetActive
• AudioSessionSetActiveWithFlags

Using Audio Session Properties

• AudioSessionGetProperty
• AudioSessionSetProperty
• AudioSessionGetPropertySize
• AudioSessionAddPropertyListener
• AudioSessionRemovePropertyListenerWithUserData
• AudioSessionRemovePropertyListener

Functions

AudioSessionAddPropertyListener

Adds a property listener callback function to your application’s audio session object.

OSStatus AudioSessionAddPropertyListener (
   AudioSessionPropertyID         inID,
   AudioSessionPropertyListener   inProc,
   void                           *inClientData
);

Parameters

inID

The identifier for the audio session property whose value changes you want to listen for.

inProc

The name of your property listener callback function.

inClientData

Data that you would like to be passed to your property listener callback.

Return Value

A result code. See “Result Codes.”

Discussion

When an audio session property value changes, and you have added a listener callback for that property, the audio session object invokes the callback.

You can add exactly one listener callback for a given inID-inClientData pair. In other words, you can add more than one property listener callback function for a given audio session property, provided you pass a unique inClientData parameter value each time you add a property listener.

Audio session properties are listed and described in “Audio Session Property Identifiers.”

Availability

• Available in iOS 2.0 and later.

See Also

• AudioSessionRemovePropertyListener

Related Sample Code

• AddMusic
• Audio Mixer (MixerHost)
• avTouch
• oalTouch
• SpeakHere

Declared In

AudioSession.h

AudioSessionGetProperty

Gets the value of a specified audio session property.

OSStatus AudioSessionGetProperty (
   AudioSessionPropertyID    inID,
   UInt32                    *ioDataSize,
   void                      *outData
);

Parameters

inID

The identifier for the audio session property that you want to get the value of.

ioDataSize

On input, the memory size for the outData parameter. On output, the actual size of the property value.

outData

On output, the value of the specified audio session property.

Return Value

A result code. See “Result Codes.”

Discussion

Audio session properties are listed and described in “Audio Session Property Identifiers.”

Special Considerations

Some Core Audio property values are C types and others are Core Foundation objects.

If you call this function to retrieve a value that is a Core Foundation object, then this function—despite the use of “Get” in its name—duplicates the object. You are responsible for releasing the object, as described in “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Availability

• Available in iOS 2.0 and later.

See Also

• AudioSessionGetPropertySize
• AudioSessionSetProperty

Related Sample Code

• aurioTouch2
• Breadcrumb
• oalTouch
• SpeakHere

Declared In

AudioSession.h

AudioSessionGetPropertySize

Gets the size of the value for a specified audio session property.

OSStatus AudioSessionGetPropertySize (
   AudioSessionPropertyID    inID,
   UInt32                    *outDataSize
);

Parameters

inID

The identifier for the audio session property whose value you want to get the size of.

outDataSize

On output, the size of the property value.

Return Value

A result code. See “Result Codes.”

Discussion

Audio session properties are listed and described in “Audio Session Property Identifiers.”

Availability

• Available in iOS 2.0 and later.

See Also

• AudioSessionGetProperty
• AudioSessionSetProperty

Declared In

AudioSession.h

AudioSessionInitialize

Initializes an iOS application’s audio session object.

OSStatus AudioSessionInitialize (
   CFRunLoopRef                      inRunLoop,
   CFStringRef                       inRunLoopMode,
   AudioSessionInterruptionListener  inInterruptionListener,
   void                              *inClientData
);

Parameters

inRunLoop

The run loop that the interruption listener callback should be run on. Pass NULL to use the main run loop.

inRunLoopMode

The mode for the run loop that the interruption listener function will run on. Passing NULL is equivalent to passing kCFRunLoopDefaultMode.

inInterruptionListener

The interruption listener callback function. The application’s audio session object invokes the callback when the session is interrupted and (if the application is still running) when the interruption ends. Can be NULL. See AudioSessionInterruptionListener.

inClientData

Data that you would like to be passed to your interruption listener callback.

Return Value

A result code. See “Result Codes.”

Discussion

Your application must call this function before making any other Audio Session Services calls. You may activate and deactivate your audio session as needed (see AudioSessionSetActive), but should initialize it only once.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• avTouch
• Breadcrumb
• MusicCube
• oalTouch
• SpeakHere

Declared In

AudioSession.h

AudioSessionRemovePropertyListener

Removes an audio session property listener callback function. (Deprecated. Use AudioSessionRemovePropertyListenerWithUserData instead.)

OSStatus AudioSessionRemovePropertyListener (
   AudioSessionPropertyID  inID
);

Parameters

inID

The identifier for the audio session property whose value changes you no longer want to listen for.

Return Value

A result code. See “Result Codes.”

Availability

• Available in iOS 2.0 and later.
• Deprecated in iOS 2.0.

Declared In

AudioSession.h

AudioSessionRemovePropertyListenerWithUserData

Removes a property listener callback function from your application’s audio session object.

OSStatus AudioSessionRemovePropertyListenerWithUserData (
   AudioSessionPropertyID         inID,
   AudioSessionPropertyListener   inProc,
   void                           *inClientData
);

Parameters

inID

The identifier for the audio session property whose value changes you no longer want to listen for.

inProc

The name of your property listener callback function.

inClientData

The same custom data for the property listener callback that you passed when calling the AudioSessionAddPropertyListener function.

Return Value

A result code. See “Result Codes.”

Discussion

Audio session properties are listed and described in “Audio Session Property Identifiers.”

Availability

• Available in iOS 2.1 and later.

Declared In

AudioSession.h

AudioSessionSetActive

Actives or deactivates your application’s audio session.

OSStatus AudioSessionSetActive (
   Boolean    active
);

Parameters

active

Pass true to activate your application’s audio session, or false to deactivate it.

Return Value

A result code. See “Result Codes.”

Discussion

Activating your audio session may interrupt audio sessions belonging to other applications running in the background, depending on categories and priorities. Deactivating your audio session allows other, interrupted audio sessions to resume.

When another active audio session does not allow mixing, attempting to activate your audio session may fail.

Availability

• Available in iOS 2.0 and later.

Related Sample Code

• aurioTouch2
• Breadcrumb
• MusicCube
• oalTouch
• SpeakHere

Declared In

AudioSession.h

AudioSessionSetActiveWithFlags

Activates or deactivates your application’s audio session; provides flags for use by other audio sessions.

OSStatus AudioSessionSetActiveWithFlags (
   Boolean    active,
   UInt32     inFlags
);

Parameters

active

Pass true to activate your application’s audio session, or false to deactivate it.

inFlags

A bitmapped value containing one or more flags from the “Audio Session Activation Flags” enumeration.

Return Value

A result code. See “Result Codes.”

Discussion

Activating your audio session may interrupt audio sessions belonging to other applications running in the background, depending on categories and priorities. Deactivating your audio session allows other, interrupted audio sessions to resume.

When another active audio session does not allow mixing, attempting to activate your audio session may fail.

Availability

• Available in iOS 4.0 and later.

Declared In

AudioSession.h

AudioSessionSetProperty

Sets the value of a specified audio session property.

OSStatus AudioSessionSetProperty (
   AudioSessionPropertyID    inID,
   UInt32                    inDataSize,
   const void                *inData
);

Parameters

inID

The identifier for the audio session property that you want to set the value of.

inDataSize

The size, in bytes, of the value in the inData parameter.

inData

The value that you are applying to the specified audio session property.

Return Value

A result code. See “Result Codes.”

Discussion

Audio session properties are listed and described in “Audio Session Property Identifiers.”

Availability

• Available in iOS 2.0 and later.

See Also

• AudioSessionGetProperty
• AudioSessionGetPropertySize

Related Sample Code

• aurioTouch2
• Breadcrumb
• MusicCube
• oalTouch
• SpeakHere

Declared In

AudioSession.h

Callbacks

AudioSessionInterruptionListener

Invoked when an audio interruption in iOS begins or ends.

typedef void    (*AudioSessionInterruptionListener)(
   void     *inClientData,
   UInt32   inInterruptionState
   );

If you named your function MyInterruptionListener, you would declare it like this:

void MyInterruptionListener (
   void     *inClientData,
   UInt32   inInterruptionState
);

Parameters

inClientData

Data that you specified in the inClientData parameter of the AudioSessionInitialize function. Can be NULL.

inInterruptionState

A constant that indicates whether the interruption has just started or just ended. See “Audio Session Interruption States.”

Discussion

To register your interruption listener callback with your application’s audio session object, specify it in the AudioSessionInitialize function.

Availability

• Available in iOS 2.0 and later.

Declared In

AudioSession.h

AudioSessionPropertyListener

Invoked when an audio session property changes in iOS.

typedef void    (*AudioSessionPropertyListener)(
   void                      *inClientData,
   AudioSessionPropertyID    inID,
   UInt32                    inDataSize,
   const void                *inData
   );

If you named your function MyPropertyListener, you would declare it like this:

void MyPropertyListener (
   void                      *inClientData,
   AudioSessionPropertyID    inID,
   UInt32                    inDataSize,
   const void                *inData
);

Parameters

inClientData

Data that you specified in the inClientData parameter of the AudioSessionAddPropertyListener function. Can be NULL.

inID

The identifier for the audio session property whose value just changed. See “Audio Session Property Identifiers.”

inDataSize

The size, in bytes, of the value of the changed property.

inData

The new value of the changed property.

Discussion

You can register one or more property listener callbacks with your application’s audio session object by calling the AudioSessionAddPropertyListenerfunction.

Availability

• Available in iOS 2.0 and later.

Declared In

AudioSession.h

Data Types

AudioSessionPropertyID

The data type for an audio session property identifier.

typedef UInt32 AudioSessionPropertyID;

Discussion

Each Audio Session property has a four-character identifier. The properties are listed in “Audio Session Property Identifiers.”

Availability

• Available in iOS 2.0 and later.

Declared In

AudioSession.h

Constants

Audio Session Property Identifiers

Property identifiers used with Audio Session Services in iOS.

enum {
   kAudioSessionProperty_PreferredHardwareSampleRate          = 'hwsr',
   // read/write
   kAudioSessionProperty_PreferredHardwareIOBufferDuration    = 'iobd',
   // read/write
   kAudioSessionProperty_AudioCategory                        = 'acat',
   // read/write
   kAudioSessionProperty_AudioRouteChange                     = 'roch',
   // callback function
   kAudioSessionProperty_CurrentHardwareSampleRate            = 'chsr',
   // read-only
   kAudioSessionProperty_CurrentHardwareInputNumberChannels   = 'chic',
   // read-only
   kAudioSessionProperty_CurrentHardwareOutputNumberChannels  = 'choc',
   // read-only
   kAudioSessionProperty_CurrentHardwareOutputVolume          = 'chov',
   // read-only + callback function
   kAudioSessionProperty_CurrentHardwareInputLatency          = 'cilt',
   // read-only
   kAudioSessionProperty_CurrentHardwareOutputLatency         = 'colt',
   // read-only
   kAudioSessionProperty_CurrentHardwareIOBufferDuration      = 'chbd',
   // read-only
   kAudioSessionProperty_OtherAudioIsPlaying                  = 'othr',
   // read-only
   kAudioSessionProperty_OverrideAudioRoute                   = 'ovrd',
   // write-only
   kAudioSessionProperty_AudioInputAvailable                  = 'aiav',
   // read-only + callback function
   kAudioSessionProperty_ServerDied                           = 'died',
   // callback function
   kAudioSessionProperty_OtherMixableAudioShouldDuck          = 'duck',
   // read/write
   kAudioSessionProperty_OverrideCategoryMixWithOthers        = 'cmix',
   // read/write
   kAudioSessionProperty_OverrideCategoryDefaultToSpeaker     = 'cspk',
   // read/write
   kAudioSessionProperty_OverrideCategoryEnableBluetoothInput = 'cblu'
   // read/write
   kAudioSessionProperty_InterruptionType                     = 'type'
   // read-only
   kAudioSessionProperty_Mode                                 = 'mode',
   // read/write
   kAudioSessionProperty_InputSources                         = 'srcs',
   // read-only + callback function
   kAudioSessionProperty_OutputDestinations                   = 'dsts',
   // read-only + callback function
   kAudioSessionProperty_InputSource                          = 'isrc',
   // read/write
   kAudioSessionProperty_OutputDestination                    = 'odst',
   // read/write
   kAudioSessionProperty_InputGainAvailable                   = 'igav',
   // read-only + callback function
   kAudioSessionProperty_InputGainScalar                      = 'igsc',
   // read/write + callback function
   kAudioSessionProperty_AudioRouteDescription                = 'crar',
   // read-only
};

Constants

kAudioSessionProperty_PreferredHardwareSampleRate

Your preferred hardware sample rate for the audio session. A read/write Float64 value. The actual sample rate may be different and can be obtained using the kAudioSessionProperty_CurrentHardwareSampleRate property.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_PreferredHardwareIOBufferDuration

Your preferred hardware I/O buffer duration in seconds. Do not set this property unless you require lower I/O latency than is provided by default.

A read/write Float32 value.

The actual I/O buffer duration may be different from the value that you request, and can be obtained from thekAudioSessionProperty_CurrentHardwareIOBufferDuration property.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_AudioCategory

The category for the audio session. A read/write UInt32 value. See “Audio Session Categories.”

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_AudioRouteChange

A CFDictionaryRef object containing the reason the audio route changed along with details on the previous and current audio route.

The dictionary contains the keys and corresponding values described in “Audio Route Change Dictionary Keys.”

The kAudioSessionProperty_AudioRouteChange dictionary is available to your app only by way of the AudioSessionPropertyListener callback function.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_CurrentHardwareSampleRate

Indicates the current hardware sample rate. A read-only Float64 value.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_CurrentHardwareInputNumberChannels

Indicates the current number of audio hardware input channels. A read-only UInt32 value.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_CurrentHardwareOutputNumberChannels

Indicates the current number of audio hardware output channels. A read-only UInt32 value.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_CurrentHardwareOutputVolume

Indicates the current audio output volume as Float32 value between 0.0 and 1.0. Read-only. This value is available to your app by way of a property listener callback function. See AudioSessionAddPropertyListener.

Available in iOS 2.1 and later.

Declared in AudioSession.h.

kAudioSessionProperty_CurrentHardwareInputLatency

Indicates the current hardware input latency, in seconds, as a read-only Float32 value.

Available in iOS 2.1 and later.

Declared in AudioSession.h.

kAudioSessionProperty_CurrentHardwareOutputLatency

Indicates the current hardware output latency, in seconds, as a read-only Float32 value.

Available in iOS 2.1 and later.

Declared in AudioSession.h.

kAudioSessionProperty_CurrentHardwareIOBufferDuration

Indicates the current hardware IO buffer duration, in seconds, as a read-only Float32 value.

Available in iOS 2.1 and later.

Declared in AudioSession.h.

kAudioSessionProperty_OtherAudioIsPlaying

Indicates whether or not another app (typically, the iPod app) is currently playing audio. Read-only. A non-zero UInt32 value indicates that other audio is playing.

Available in iOS 2.1 and later.

Declared in AudioSession.h.

kAudioSessionProperty_OverrideAudioRoute

Specifies whether or not to override the audio session category’s normal audio route.

A write-only UInt32 value. Can be set with one of two values: kAudioSessionOverrideAudioRoute_None, which specifies that you want to use the normal audio route; and kAudioSessionOverrideAudioRoute_Speaker, when sends output audio to the built-in speaker. This property can be used only with the kAudioSessionCategory_PlayAndRecord (or the equivalent AVAudioSessionCategoryPlayAndRecord) category.

If a headset is plugged in at the time you set this property’s value to kAudioSessionOverrideAudioRoute_Speaker, the system changes the audio routing for input as well as for output: input comes from the built-in microphone; output goes to the built-in speaker.

Upon an audio route change (such as by plugging in or unplugging a headset), or upon interruption, this property reverts to its default value.

See also kAudioSessionProperty_OverrideCategoryDefaultToSpeaker.

Available in iOS 2.1 and later.

Declared in AudioSession.h.

kAudioSessionProperty_AudioInputAvailable

Indicates if audio input is available (a nonzero value) or not (a value of 0).

A read-only UInt32 value, interpreted as a Boolean value. Use this property, rather than the device model, to determine if audio input is available.

You can listen for changes in the value of this property using a callback function. For instance, if a user plugs a headset into an iPod touch (2nd generation), audio input becomes available via the wired microphone and your callback is invoked. See AudioSessionAddPropertyListener.

Available in iOS 2.2 and later.

Declared in AudioSession.h.

kAudioSessionProperty_ServerDied

Indicates if the audio server has died (indicated by a nonzero UInt32 value) or is still running (a value of 0).

This value is available to your app only by way of a property listener callback function. See AudioSessionAddPropertyListener.

Available in iOS 3.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_OtherMixableAudioShouldDuck

For audio session categories that allow audio mixing with other apps, specifies whether other audio should be reduced in level when your app produces sound. This property has a value of FALSE (0) by default. Set it to a nonzero value to turn on ducking.

When your app is finished playing sound, be sure to set this property back to FALSE to remove ducking.

Available in iOS 3.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_OverrideCategoryMixWithOthers

Changes the mixing behavior of the kAudioSessionCategory_MediaPlayback and kAudioSessionCategory_PlayAndRecord audio session categories.

A read/write UInt32 value. By default, the value of this property is FALSE (0).

Setting this property to TRUE (any nonzero value) allows audio mixing with other apps. Other aspects of these categories, such as their Silent switch behavior, are not affected. (The switch is called the Ring/Silent switch on iPhone.)

When the audio session category changes, such as during an interruption, the value of this property reverts to FALSE. To regain mixing behavior you must then re-set this property.

Always check to see if setting this property succeeds or fails, and react appropriately; behavior may change in future releases of iOS.

Available in iOS 3.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_OverrideCategoryDefaultToSpeaker

Specifies whether or not to route audio to the speaker (instead of to the receiver) when no other audio route, such as a headset, is connected.

A read/write UInt32 value. By default, the value of this property is FALSE (0).

This property retains its value through an audio route change (such as when plugging in or unplugging a headset), and upon interruption; it reverts to its default value only upon an audio session category change. This property can be used only with the kAudioSessionCategory_PlayAndRecord (or the equivalent AVAudioSessionCategoryPlayAndRecord) category.

See also kAudioSessionProperty_OverrideAudioRoute.

Available in iOS 3.1 and later.

Declared in AudioSession.h.

kAudioSessionProperty_OverrideCategoryEnableBluetoothInput

Allows a paired Bluetooth device to appear as an available audio input route.

A read/write UInt32 value. By default, the value of this property is FALSE (0).

This property can be used to modify the kAudioSessionCategory_RecordAudio or kAudioSessionCategory_PlayAndRecord categories. Attempting to set this property to TRUE will fail for all other categories.

This property affects the kAudioSessionCategory_PlayAndRecord category as follows: If the audio input to the device is coming from a Bluetooth headset, setting this property to TRUE results in audio output also going to the Bluetooth headset.

Available in iOS 3.1 and later.

Declared in AudioSession.h.

kAudioSessionProperty_InterruptionType

Indicates the type of an end-interruption event.

A read-only UInt32 value that is one of the constants in the “Audio Session Interruption Types” enumeration.

Query this property within your interruption callback to find out whether or not it is appropriate to immediately resume the audio operation that was interrupted. Media playback apps (typically, those that have a “play” button) can use this property’s value as an indication for whether or not to resume playing after an interruption ends. Other app types (such as games) should normally resume audio playback whenever an interruption ends.

This property’s value is available within the scope of your app’s interruption listener callback function (see AudioSessionInterruptionListener), and valid only when your callback receives the kAudioSessionEndInterruption state identifier. At all other times, this property’s value is invalid.

Available in iOS 4.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_Mode

A read/write UIInt32 value that specifies the audio session mode.

An audio session mode is a key that identifies a set of device audio configuration details, such as whether or not the device performs automatic gain adjustment on incoming audio. A mode refines the configuration provided by a category (kAudioSessionProperty_AudioCategory).

The available modes are described in “Audio Session Modes.” The default mode is kAudioSessionMode_Default.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_InputSources

A CFArrayRef object containing details on the available audio input sources in a USB audio accessory attached through the iPad camera connection kit.

Each element of the array contains a CFDictionaryRef object with the keys and corresponding values described in “USB Accessory Audio Source Dictionary Keys.”

If there is no audio input source available from the attached accessory, this property’s value is an empty array.

This property is read-only. You can employ an AudioSessionPropertyListener callback function to listen for changes in this property’s value.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_OutputDestinations

A CFArrayRef object containing details on the available audio output destinations in a USB audio accessory attached through the iPad camera connection kit.

Each element of the array contains a CFDictionaryRef object with the keys and corresponding values described in “USB Accessory Audio Destination Dictionary Keys.”

If there is no audio output destination available from the attached accessory, this property’s value is an empty array.

This property is read-only. You can employ an AudioSessionPropertyListener callback function to listen for changes in this property’s value.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_InputSource

A read/write CFNumberRef object that indicates the audio input source, from a USB audio accessory attached through the iPad camera connection kit, that you want to use.

The value must be one of the identifiers provided as a kAudioSession_InputSourceKey_ID key as part of thekAudioSessionProperty_InputSources array.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_OutputDestination

A read/write CFNumberRef object that indicates the audio output destination, from a USB audio accessory attached through the iPad camera connection kit, that you want to use.

The value must be one of the identifiers provided as a kAudioSession_OutputDestinationKey_ID key as part of thekAudioSessionProperty_OutputDestinations array.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_InputGainAvailable

A read-only UInt32 value that indicates whether or not audio input gain adjustment is available, where a nonzero value means adjustment is available.

Note: Some audio inputs on some devices do not support gain adjustment. You must check this property’s value before attempting to set audio input gain.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_InputGainScalar

A read/write Float32 value that indicates the audio input gain setting for the active input source.

The range for this value is [0.0, 1.0], as follows:

• 0 indicates the lowest audio input gain setting

• 1 indicates the highest audio input gain setting

Attempting to set a value outside this range results in the value being clamped to this range. This property’s value is valid only if audio input gain is available (see kAudioSessionProperty_InputGainAvailable).

If no app with an active audio session is using this property for a given input source, the system restores the default input gain setting for the input source.

You can employ an AudioSessionPropertyListener callback function to listen for changes in this property’s value.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionProperty_AudioRouteDescription

A read-only CFDictionaryRef object containing information about an audio route.

The dictionary contains the keys and corresponding values described in “Audio Route Description Dictionary Keys.”

Available in iOS 5.0 and later.

Declared in AudioSession.h.

Discussion

Use these property identifiers in concert with the AudioSessionGetProperty, AudioSessionSetProperty, and AudioSessionAddPropertyListenerfunctions.

Audio Session Categories

Category identifiers for audio sessions, used as values for the kAudioSessionProperty_AudioCategory property.

enum {
   kAudioSessionCategory_AmbientSound              = 'ambi',
   kAudioSessionCategory_SoloAmbientSound          = 'solo',
   kAudioSessionCategory_MediaPlayback             = 'medi',
   kAudioSessionCategory_RecordAudio               = 'reca',
   kAudioSessionCategory_PlayAndRecord             = 'plar',
   kAudioSessionCategory_AudioProcessing           = 'proc'
};

Constants

kAudioSessionCategory_AmbientSound

For an app in which sound playback is nonprimary—that is, your app can be used successfully with the sound turned off.

This category is appropriate for “play along” style apps, such as a virtual piano that a user plays over iPod audio. When you use this category, audio from other apps mixes with your audio. Your audio is silenced by screen locking and by the Silent switch (called the Ring/Silent switch on iPhone).

This category is equivalent to the AVAudioSessionCategoryAmbient category provided in the AV Foundation framework.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionCategory_SoloAmbientSound

The default category, used unless you set a category with the AudioSessionSetProperty function.

When you use this category, audio from other apps is silenced. Your audio is silenced by screen locking and by the Silent switch (called the Ring/Silent switch on iPhone).

This category is equivalent to the AVAudioSessionCategorySoloAmbient category provided in the AV Foundation framework.

Available in iOS 2.2 and later.

Declared in AudioSession.h.

kAudioSessionCategory_MediaPlayback

For playing recorded music or other sounds that are central to the successful use of your app.

When using this category, your app audio continues with the Silent switch set to silent or when the screen locks. (The switch is called the Ring/Silent switch on iPhone.)

This category normally prevents audio from other apps from mixing with your app's audio. To allow mixing for this category, use thekAudioSessionProperty_OverrideCategoryMixWithOthers property.

This category is equivalent to the AVAudioSessionCategoryPlayback category provided in the AV Foundation framework.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionCategory_RecordAudio

For recording audio; this category silences playback audio. Recording continues with the screen locked.

This category is equivalent to the AVAudioSessionCategoryRecord category provided in the AV Foundation framework.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionCategory_PlayAndRecord

Allows recording (input) and playback (output) of audio, such as for a VOIP (voice over IP) app.

Your audio continues with the Silent switch set to silent and with the screen locked. (The switch is called the Ring/Silent switch on iPhone.)

This category is appropriate for simultaneous recording and playback, and also for apps that record and play back but not simultaneously. If you want to ensure that sounds such as Messages alerts do not play while your app is recording, use the kAudioSessionCategory_RecordAudio category instead.

This category normally prevents audio from other apps from mixing with your app's audio. To allow mixing when using this category, use thekAudioSessionProperty_OverrideCategoryMixWithOthers property.

This category is equivalent to the AVAudioSessionCategoryPlayAndRecord category provided in the AV Foundation framework.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionCategory_AudioProcessing

For using an audio hardware codec or signal processor while not playing or recording audio. Use this category, for example, when performing offline audio format conversion.

This category disables playback (audio output) and disables recording (audio input).

Audio processing does not normally continue when your app is in the background. However, when your app moves to the background, you can request additional time to complete processing. for more information, see “Understanding an Application’s States and Transitions” in iOS App Programming Guide.

This category is equivalent to the AVAudioSessionCategoryAudioProcessing category provided in the AV Foundation framework.

Available in iOS 3.1 and later.

Declared in AudioSession.h.

Discussion

Each app running in iOS has a single audio session, which in turn has a single category. You can change your audio session’s category while your app is running.

You can refine the configuration provided by the kAudioSessionCategory_RecordAudio and kAudioSessionCategory_PlayAndRecord categories by using an audio session mode, as described in “Audio Session Modes.”

Use the kAudioSessionCategory_AmbientSound category when you want your sounds to mix with other audio (such as from the iPod app). Use one of the other playback categories when you want audio from other apps to be silenced when your session is active. However, you can enable mixing for thekAudioSessionCategory_MediaPlayback and kAudioSessionCategory_PlayAndRecord categories by using thekAudioSessionProperty_OverrideCategoryMixWithOthers property. For more information on audio session categories, see Audio Session Programming Guide.

Audio Session Modes

Mode identifiers for audio sessions, used as values for the kAudioSessionProperty_Mode property.

enum {
   kAudioSessionMode_Default         = 'dflt',
   kAudioSessionMode_VoiceChat       = 'vcct',
   kAudioSessionMode_VideoRecording  = 'vrcd',
   kAudioSessionMode_Measurement     = 'msmt'
};

Constants

kAudioSessionMode_Default

The default mode; used unless you set a mode with the AudioSessionSetProperty function.

When this mode is in use, audio session behavior matches that of iOS versions prior to iOS 5.0. You can use this mode with every audio session category. On devices with more than one built-in microphone, the primary microphone is used.

This mode is equivalent to the AVAudioSessionModeDefault mode provided in the AV Foundation framework.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionMode_VoiceChat

Specify this mode if your app is performing two-way voice communication, such as using Voice over Internet Protocol (VoIP).

When this mode is in use, the device’s tonal equalization is optimized for voice. For use with the kAudioSessionCategory_PlayAndRecord audio session category. On devices with more than one built-in microphone, the primary microphone is used.

Using this mode has the side effect of setting the kAudioSessionProperty_OverrideCategoryEnableBluetoothInput category override to TRUE.

This mode is equivalent to the AVAudioSessionModeVoiceChat mode provided in the AV Foundation framework.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionMode_VideoRecording

Specify this mode if your app is recording a movie.

For use with the kAudioSessionCategory_RecordAudio audio session category. Also works with the kAudioSessionCategory_PlayAndRecordcategory. On devices with more than one built-in microphone, the microphone closest to the video camera is used.

Using this mode may result in the system providing appropriate audio signal processing.

This mode is equivalent to the AVAudioSessionModeVideoRecording mode provided in the AV Foundation framework.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionMode_Measurement

Specify this mode if your app is performing measurement of incoming audio.

When this mode is in use, the device does not perform automatic gain adjustment on incoming audio. For use with thekAudioSessionCategory_RecordAudio or kAudioSessionCategory_PlayAndRecord audio session categories. On devices with more than one built-in microphone, the primary microphone is used.

This mode is equivalent to the AVAudioSessionModeMeasurement mode provided in the AV Foundation framework.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

Discussion

Each app running in iOS has a single audio session, which in turn has a single mode. A mode refines the device’s audio configuration according to the purpose of the mode. You can change your audio session’s mode only when your audio session is inactive, and only if your audio session category is configured to disallow mixing with other apps.

Note: Misusing a mode by setting it for an inappropriate audio session category—such as setting the kAudioSessionMode_VoiceChat mode for thekAudioSessionCategory_AudioProcessing category—results in the behavior provided by the kAudioSessionMode_Default mode.

Audio Route Change Reasons

Identifiers for the various reasons that an audio route can change while your app is running.

enum {
   kAudioSessionRouteChangeReason_Unknown                    = 0,
   kAudioSessionRouteChangeReason_NewDeviceAvailable         = 1,
   kAudioSessionRouteChangeReason_OldDeviceUnavailable       = 2,
   kAudioSessionRouteChangeReason_CategoryChange             = 3,
   kAudioSessionRouteChangeReason_Override                   = 4,
   // this enum has no constant with a value of 5
   kAudioSessionRouteChangeReason_WakeFromSleep              = 6,
   kAudioSessionRouteChangeReason_NoSuitableRouteForCategory = 7
};

Constants

kAudioSessionRouteChangeReason_Unknown

The audio route changed but the reason is not known.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionRouteChangeReason_NewDeviceAvailable

A new audio hardware device became available; for example, a headset was plugged in.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionRouteChangeReason_OldDeviceUnavailable

The previously-used audio hardware device is now unavailable; for example, a headset was unplugged.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionRouteChangeReason_CategoryChange

The audio session category has changed.

Available in iOS 2.1 and later.

Declared in AudioSession.h.

kAudioSessionRouteChangeReason_Override

The audio route has been overridden. For example, while using the kAudioSessionCategory_PlayAndRecord category, output audio has been redirected to the speaker using the kAudioSessionProperty_OverrideAudioRoute property.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionRouteChangeReason_WakeFromSleep

The device woke from sleep.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionRouteChangeReason_NoSuitableRouteForCategory

There is no audio hardware route for the audio session category; for instance, the kAudioSessionCategory_RecordAudio is set but there is no audio input device.

Available in iOS 3.1 and later.

Declared in AudioSession.h.

Discussion

You encounter these identifiers as values in the CFDictionaryRef object passed to your property listener callback function when it is listening for audio route changes. See the description for kAudioSessionProperty_AudioRouteChange.

Audio Session Category Route Overrides

Specifies whether the default audio route for the PlayAndRecord category should be overridden.

enum {
   kAudioSessionOverrideAudioRoute_None    = 0,
   kAudioSessionOverrideAudioRoute_Speaker = 'spkr'
};

Constants

kAudioSessionOverrideAudioRoute_None

Specifies, for the kAudioSessionCategory_PlayAndRecord category, that output audio should go to the receiver. This is the default output audio route for this category.

Available in iOS 2.1 and later.

Declared in AudioSession.h.

kAudioSessionOverrideAudioRoute_Speaker

Specifies, for the kAudioSessionCategory_PlayAndRecord category, that output audio should go to the speaker, not the receiver.

Available in iOS 2.1 and later.

Declared in AudioSession.h.

Discussion

The kAudioSessionCategory_PlayAndRecord category supports simultaneous input and output. You could use this category, for example, to add an effect to audio coming into the device’s microphone. By default, output audio for this category goes to the receiver—the speaker you hold to your ear when on a phone call. The kAudioSessionOverrideAudioRoute_Speaker constant lets you direct the output audio to the speaker situated at the bottom of the phone.

Audio Session Activation Flags

Flags that provide additional information about your app’s audio intentions upon session activation or deactivation.

enum {
   kAudioSessionSetActiveFlag_NotifyOthersOnDeactivation = (1 << 0)  //  0x01
};

Constants

kAudioSessionSetActiveFlag_NotifyOthersOnDeactivation

Indicates that when your audio session deactivates, other audio sessions that had been interrupted by your session can return to their active state.

Used only when deactivating your audio session.

Available in iOS 4.0 and later.

Declared in AudioSession.h.

Audio Session Interruption Types

Identifiers that serve as values for the kAudioSessionProperty_InterruptionType property to indicate the nature of an interruption that has just ended.

enum {
   kAudioSessionInterruptionType_ShouldResume    = 'irsm',
   kAudioSessionInterruptionType_ShouldNotResume = '!rsm'
};
typedef UInt32 AudioSessionInterruptionType;

Constants

kAudioSessionInterruptionType_ShouldResume

Indicates that the interruption that has just ended was one for which it is appropriate to immediately resume playback; for example, an incoming phone call was rejected by the user.

Available in iOS 4.0 and later.

Declared in AudioSession.h.

kAudioSessionInterruptionType_ShouldNotResume

Indicates that the interruption that has just ended was one for which it is not appropriate to resume playback; for example, your app had been interrupted by iPod playback.

Available in iOS 4.0 and later.

Declared in AudioSession.h.

Audio Session Interruption States

Identifiers used with the AudioSessionInterruptionListener callback function in iOS to indicate that an audio interruption has started or stopped.

enum {
   kAudioSessionBeginInterruption  = 1,
   kAudioSessionEndInterruption    = 0
};

Constants

kAudioSessionBeginInterruption

Your app’s audio session has just been interrupted, such as by a phone call.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionEndInterruption

The interruption to your app’s audio session has just ended. In the case where a user confirms the interruption, such as answering a phone call, your app will not receive this constant.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

Audio Route Description Dictionary Keys

Keys for the kAudioSessionProperty_AudioRouteDescription dictionary.

const CFStringRef kAudioSession_AudioRouteKey_Inputs;
const CFStringRef kAudioSession_AudioRouteKey_Outputs;

Constants

kAudioSession_AudioRouteKey_Inputs

A CFArrayRef object containing details about audio input used in the current audio route.

If there is an audio input available, the array contains a CFDictionaryRef object with a single key, namely kAudioSession_AudioRouteKey_Type, whose value is one of the constants in “Audio Input Routes.”

If no audio input is available, the array is empty.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSession_AudioRouteKey_Outputs

A CFArrayRef object containing details about the audio output used in the current audio route.

If there is an audio output available, the array usually contains one CFDictionaryRef object with a single key, namelykAudioSession_AudioRouteKey_Type, whose value is one of the constants in “Audio Output Routes.”

In certain circumstances, such as when a ringtone is being sent to the device speaker and to a connected headset, the array contains more than one dictionary.

If no audio output is available, the array is empty.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

USB Accessory Audio Source Dictionary Keys

Keys for the dictionaries in the kAudioSessionProperty_InputSources array.

const CFStringRef kAudioSession_InputSourceKey_ID;
const CFStringRef kAudioSession_InputSourceKey_Description;

Constants

kAudioSession_InputSourceKey_ID

A CFNumberRef object, defined by a USB audio accessory attached to the device through the iPad camera connection kit, that identifies an audio input source. When setting a source on the accessory, use this identifier.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSession_InputSourceKey_Description

A CFStringRef object, defined by the accessory, that describes an audio input source and that is suitable for displaying in a user interface.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

USB Accessory Audio Destination Dictionary Keys

Keys for the dictionaries in the kAudioSessionProperty_OutputDestinations array.

const CFStringRef kAudioSession_OutputDestinationKey_ID;
const CFStringRef kAudioSession_OutputDestinationKey_Description;

Constants

kAudioSession_OutputDestinationKey_ID

A CFNumberRef object, defined by a USB audio accessory attached to the device through the iPad camera connection kit, that identifies the output destination. When setting an audio output destination on the accessory, use this identifier. For possible values, see “Audio Output Routes.”

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSession_OutputDestinationKey_Description

A CFStringRef object, defined by the accessory, that describes the audio output destination and that is suitable for displaying in a user interface.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

Audio Route Type Key

The one key for an audio route input or output dictionary.

const CFStringRef kAudioSession_AudioRouteKey_Type;

Constants

kAudioSession_AudioRouteKey_Type

A CFStringRef object that serves as the one key for an audio routes input or output dictionary, whose value specifies an input source or output destination.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

Discussion

This key is used with the dictionaries associated with the kAudioSession_AudioRouteKey_Inputs and kAudioSession_AudioRouteKey_Outputs arrays.

Audio Input Routes

Strings that identify the various audio input sources for a device.

const CFStringRef kAudioSessionInputRoute_LineIn;
const CFStringRef kAudioSessionInputRoute_BuiltInMic;
const CFStringRef kAudioSessionInputRoute_HeadsetMic;
const CFStringRef kAudioSessionInputRoute_BluetoothHFP;
const CFStringRef kAudioSessionInputRoute_USBAudio;

Constants

kAudioSessionInputRoute_LineIn

A line in input

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionInputRoute_BuiltInMic

A built-in microphone input.

Some early iOS devices do not have this input.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionInputRoute_HeadsetMic

A microphone that is part of a headset.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionInputRoute_BluetoothHFP

A microphone that is part of a Bluetooth Hands-Free Profile (HFP) device.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionInputRoute_USBAudio

A Universal Serial Bus (USB) input, accessed through the device 30-pin connector.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

Discussion

These strings are used as values for the kAudioSession_AudioRouteKey_Type key for the dictionary associated with thekAudioSession_AudioRouteKey_Inputs array.

Audio Output Routes

The various audio output destinations available for an iOS device.

const CFStringRef kAudioSessionOutputRoute_LineOut;
const CFStringRef kAudioSessionOutputRoute_Headphones;
const CFStringRef kAudioSessionOutputRoute_BluetoothHFP;
const CFStringRef kAudioSessionOutputRoute_BluetoothA2DP;
const CFStringRef kAudioSessionOutputRoute_BuiltInReceiver;
const CFStringRef kAudioSessionOutputRoute_BuiltInSpeaker;
const CFStringRef kAudioSessionOutputRoute_USBAudio;
const CFStringRef kAudioSessionOutputRoute_HDMI;
const CFStringRef kAudioSessionOutputRoute_AirPlay;

Constants

kAudioSessionOutputRoute_LineOut

Analog line-level output.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionOutputRoute_Headphones

Speakers in headphones or in a headset.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionOutputRoute_BluetoothHFP

Speakers that are part of a Bluetooth Hands-Free Profile (HFP) accessory.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionOutputRoute_BluetoothA2DP

Speakers in a Bluetooth A2DP device.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionOutputRoute_BuiltInReceiver

The built-in speaker you hold to your ear when on a phone call.

Some iOS devices do not have this output.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionOutputRoute_BuiltInSpeaker

The primary built-in speaker.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionOutputRoute_USBAudio

Speaker(s) in a Universal Serial Bus (USB) accessory, accessed through the device 30-pin connector.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionOutputRoute_HDMI

An output available through the HDMI interface.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSessionOutputRoute_AirPlay

An output on an AirPlay device.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

Discussion

These strings are used as values for the kAudioSession_AudioRouteKey_Type key for the dictionary associated with thekAudioSession_AudioRouteKey_Outputs array.

Audio Route Change Dictionary Keys

Keys for obtaining information about an audio hardware route change.

const CFStringRef kAudioSession_RouteChangeKey_Reason;
const CFStringRef kAudioSession_AudioRouteChangeKey_PreviousRouteDescription;
const CFStringRef kAudioSession_AudioRouteChangeKey_CurrentRouteDescription;

Constants

kAudioSession_RouteChangeKey_Reason

A CFNumberRef object that identifies the reason for the audio route change. See “Audio Route Change Reasons.”

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSession_AudioRouteChangeKey_PreviousRouteDescription

A CFDictionaryRef object that describes the previous audio route. For specifics on the contents of this dictionary, seekAudioSession_AudioRouteKey_Inputs and kAudioSession_AudioRouteKey_Outputs.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

kAudioSession_AudioRouteChangeKey_CurrentRouteDescription

A CFDictionaryRef object that describes the current audio route. For specifics on the contents of this dictionary, seekAudioSession_AudioRouteKey_Inputs and kAudioSession_AudioRouteKey_Outputs.

Available in iOS 5.0 and later.

Declared in AudioSession.h.

Alternative Audio Route Change Reason Dictionary Key

An alternate key for obtaining information about the reason for an audio route change.

#define kAudioSession_AudioRouteChangeKey_Reason "OutputDeviceDidChange_Reason"

Constants

kAudioSession_AudioRouteChangeKey_Reason

Value is a CFNumberRef object that identifies the reason for the audio route change. See “Audio Route Change Reasons.”

Note: It is typically more convenient to instead use the CFStringRef version of this constant, kAudioSession_RouteChangeKey_Reason.

Available in iOS 2.0 and later.

Declared in AudioSession.h.

Discussion

Use these dictionary keys to obtain information, from the kAudioSessionProperty_AudioRouteChange property, about an audio hardware route change event.

Deprecated Audio Session Categories

Deprecated category identifiers for audio sessions. Do not use for new development.

enum {
   kAudioSessionCategory_UserInterfaceSoundEffects = 'uifx',
   kAudioSessionCategory_LiveAudio                 = 'live'
};

Constants

kAudioSessionCategory_UserInterfaceSoundEffects

For sound effects such as touch feedback, explosions, and so on. (Deprecated. Equivalent to the kAudioSessionCategory_AmbientSound category, which you should use instead. The kAudioSessionCategory_UserInterfaceSoundEffects category was deprecated in iOS 3.0.)

Available in iOS 2.0 and later.

Declared in AudioSession.h.

kAudioSessionCategory_LiveAudio

For live performance of music, such as for an app that simulates a piano. (Deprecated. Equivalent to the kAudioSessionCategory_MediaPlaybackcategory, which you should use instead. The kAudioSessionCategory_LiveAudio category was deprecated in iOS 3.0.)

Available in iOS 2.0 and later.

Declared in AudioSession.h.

Deprecated Audio Route Change Dictionary Keys

Do not use these keys for new development.

#define kAudioSession_AudioRouteChangeKey_OldRoute  "OutputDeviceDidChange_OldRoute"

Constants

OutputDeviceDidChange_OldRoute

Used in versions of iOS prior to iOS 5.0 to indicate the previous audio route. The value for this key is a CFStringRef object that names the previous audio hardware route (such as “Headphone” or “Speaker”). (Deprecated. Instead, use thekAudioSession_AudioRouteChangeKey_PreviousRouteDescription dictionary key.)

Deprecated Audio Session Properties

Do not use these properties for new development

enum {
   kAudioSessionProperty_AudioRoute  = 'rout'
};

Constants

Constant

The name of the current audio route (such as “Headphone,” “Speaker,” and so on). A read-only CFStringRef value. (Deprecated. Instead, Use thekAudioSessionProperty_AudioRouteDescription property.)