Audio Session Services

Overview

These functions apply only to iOS. They do not apply to macOS.

Overview

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.

Topics

Initializing and Activating an Audio Session

AudioSessionInitialize

Initializes an iOS application’s audio session object.

Deprecated
AudioSessionSetActive

Actives or deactivates your application’s audio session.

Deprecated
AudioSessionSetActiveWithFlags

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

Deprecated

Using Audio Session Properties

AudioSessionGetProperty

Gets the value of a specified audio session property.

Deprecated
AudioSessionSetProperty

Sets the value of a specified audio session property.

Deprecated
AudioSessionGetPropertySize

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

Deprecated
AudioSessionAddPropertyListener

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

Deprecated
AudioSessionRemovePropertyListenerWithUserData

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

Deprecated
AudioSessionRemovePropertyListener

Removes an audio session property listener callback function.

Deprecated

Callbacks

AudioSessionInterruptionListener

Invoked when an audio interruption in iOS begins or ends.

AudioSessionPropertyListener

Invoked when an audio session property changes in iOS.

Data Types

AudioSessionPropertyID

The data type for an audio session property identifier.

Constants

Audio Session Property Identifiers

Property identifiers used with Audio Session Services in iOS.

Audio Session Categories

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

Audio Session Modes

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

Audio Route Change Reasons

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

Audio Session Category Route Overrides

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

Audio Session Activation Flags

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

AudioSessionInterruptionType

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

Audio Session Interruption States

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

Audio Route Type Key

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

Audio Input Routes

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

Audio Output Routes

The various audio output destinations available for an iOS device.

Audio Route Change Dictionary Keys

Keys for obtaining information about an audio hardware route change.

Alternative Audio Route Change Reason Dictionary Key

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

Deprecated Audio Session Categories

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

Deprecated Audio Route Change Dictionary Keys

Do not use these keys for new development.

Deprecated Audio Session Properties

Do not use these properties for new development

Result Codes

This table lists the result codes defined for Audio Session Services.

kAudioSessionNoError

No error has occurred.

kAudioSessionNotInitialized

An Audio Session function was called without first initializing the session. To avoid this error, call the AudioSessionInitialize function before attempting to use the session.

kAudioSessionAlreadyInitialized

The AudioSessionInitialize function was called more than once during the lifetime of your application.

kAudioSessionInitializationError

There was an error during audio session initialization.

kAudioSessionUnsupportedPropertyError

The audio session property is not supported.

kAudioSessionBadPropertySizeError

The size of the audio session property data was not correct.

kAudioSessionNotActiveError

The audio operation failed because your application’s audio session was not active.

kAudioServicesNoHardwareError

The audio operation failed because the device has no audio input available.

kAudioSessionNoCategorySet

The audio operation failed because it requires the audio session to have an explicitly-set category, but none was set. To use a hardware codec you must explicitly initialize the audio session and explicitly set an audio session category.

kAudioSessionIncompatibleCategory

The specified audio session category cannot be used for the attempted audio operation. For example, you attempted to play or record audio with the audio session category set to kAudioSessionCategory_AudioProcessing.

kAudioSessionUnspecifiedError

An unspecified audio session error has occurred. This typically results from the audio system being in an inconsistent state.

See Also