iOS Developer Library

Developer

AudioToolbox Framework Reference Audio Session Services Reference

Options
Deployment Target:

On This Page
Language:

Audio Session Services Reference

Inherits From


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import AudioToolbox

Objective-C

@import AudioToolbox;

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.

Functions

  • Initializes an iOS application’s audio session object.

    Deprecation Statement

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Availability

    Available in iOS 2.0 and later

    Deprecated in iOS 7.0

  • Actives or deactivates your application’s audio session.

    Deprecation Statement

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Availability

    Available in iOS 2.0 and later

    Deprecated in iOS 7.0

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

    Deprecation Statement

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Availability

    Available in iOS 4.0 and later

    Deprecated in iOS 7.0

  • Gets the value of a specified audio session property.

    Deprecation Statement

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Availability

    Available in iOS 2.0 and later

    Deprecated in iOS 7.0

  • Sets the value of a specified audio session property.

    Deprecation Statement

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Availability

    Available in iOS 2.0 and later

    Deprecated in iOS 7.0

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

    Deprecation Statement

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Availability

    Available in iOS 2.0 and later

    Deprecated in iOS 7.0

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

    Deprecation Statement

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Availability

    Available in iOS 2.0 and later

    Deprecated in iOS 7.0

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

    Deprecation Statement

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Availability

    Available in iOS 2.1 and later

    Deprecated in iOS 7.0

  • Removes an audio session property listener callback function.

    Deprecation Statement

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Availability

    Available in iOS 2.0 and later

    Deprecated in iOS 2.0

Callbacks

  • Invoked when an audio interruption in iOS begins or ends.

    Deprecated in iOS 7.0.

    Declaration

    Swift

    typealias AudioSessionInterruptionListener = CFunctionPointer<((UnsafeMutablePointer<Void>, UInt32) -> Void)>

    Objective-C

    typedef void (*AudioSessionInterruptionListener)( 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.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later

  • Invoked when an audio session property changes in iOS.

    Deprecated in iOS 7.0.

    Declaration

    Swift

    typealias AudioSessionPropertyListener = CFunctionPointer<((UnsafeMutablePointer<Void>, AudioSessionPropertyID, UInt32, UnsafePointer<Void>) -> Void)>

    Objective-C

    typedef void (*AudioSessionPropertyListener)( 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 AudioSessionAddPropertyListener function.

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later

Data Types

  • The data type for an audio session property identifier.

    Deprecated in iOS 7.0.

    Declaration

    Swift

    typealias AudioSessionPropertyID = UInt32

    Objective-C

    typedef UInt32 AudioSessionPropertyID;

    Discussion

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

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 2.0 and later

Constants

  • Property identifiers used with Audio Session Services in iOS.

    Deprecated in iOS 7.0.

    Declaration

    Swift

    var kAudioSessionProperty_PreferredHardwareSampleRate: Int { get } var kAudioSessionProperty_PreferredHardwareIOBufferDuration: Int { get } var kAudioSessionProperty_AudioCategory: Int { get } var kAudioSessionProperty_AudioRouteChange: Int { get } var kAudioSessionProperty_CurrentHardwareSampleRate: Int { get } var kAudioSessionProperty_CurrentHardwareInputNumberChannels: Int { get } var kAudioSessionProperty_CurrentHardwareOutputNumberChannels: Int { get } var kAudioSessionProperty_CurrentHardwareOutputVolume: Int { get } var kAudioSessionProperty_CurrentHardwareInputLatency: Int { get } var kAudioSessionProperty_CurrentHardwareOutputLatency: Int { get } var kAudioSessionProperty_CurrentHardwareIOBufferDuration: Int { get } var kAudioSessionProperty_OtherAudioIsPlaying: Int { get } var kAudioSessionProperty_OverrideAudioRoute: Int { get } var kAudioSessionProperty_AudioInputAvailable: Int { get } var kAudioSessionProperty_ServerDied: Int { get } var kAudioSessionProperty_OtherMixableAudioShouldDuck: Int { get } var kAudioSessionProperty_OverrideCategoryMixWithOthers: Int { get } var kAudioSessionProperty_OverrideCategoryDefaultToSpeaker: Int { get } var kAudioSessionProperty_OverrideCategoryEnableBluetoothInput: Int { get } var kAudioSessionProperty_InterruptionType: Int { get } var kAudioSessionProperty_Mode: Int { get } var kAudioSessionProperty_InputSources: Int { get } var kAudioSessionProperty_OutputDestinations: Int { get } var kAudioSessionProperty_InputSource: Int { get } var kAudioSessionProperty_OutputDestination: Int { get } var kAudioSessionProperty_InputGainAvailable: Int { get } var kAudioSessionProperty_InputGainScalar: Int { get } var kAudioSessionProperty_AudioRouteDescription: Int { get }

    Objective-C

    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

      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

    • kAudioSessionProperty_PreferredHardwareIOBufferDuration

      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 the kAudioSessionProperty_CurrentHardwareIOBufferDuration property.

      Available in iOS 2.0 and later

    • kAudioSessionProperty_AudioCategory

      kAudioSessionProperty_AudioCategory

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

      Available in iOS 2.0 and later

    • kAudioSessionProperty_AudioRouteChange

      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

    • kAudioSessionProperty_CurrentHardwareSampleRate

      kAudioSessionProperty_CurrentHardwareSampleRate

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

      Available in iOS 2.0 and later

    • kAudioSessionProperty_CurrentHardwareInputNumberChannels

      kAudioSessionProperty_CurrentHardwareInputNumberChannels

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

      Available in iOS 2.0 and later

    • kAudioSessionProperty_CurrentHardwareOutputNumberChannels

      kAudioSessionProperty_CurrentHardwareOutputNumberChannels

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

      Available in iOS 2.0 and later

    • kAudioSessionProperty_CurrentHardwareOutputVolume

      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

    • kAudioSessionProperty_CurrentHardwareInputLatency

      kAudioSessionProperty_CurrentHardwareInputLatency

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

      Available in iOS 2.1 and later

    • kAudioSessionProperty_CurrentHardwareOutputLatency

      kAudioSessionProperty_CurrentHardwareOutputLatency

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

      Available in iOS 2.1 and later

    • kAudioSessionProperty_CurrentHardwareIOBufferDuration

      kAudioSessionProperty_CurrentHardwareIOBufferDuration

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

      Available in iOS 2.1 and later

    • kAudioSessionProperty_OtherAudioIsPlaying

      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

    • kAudioSessionProperty_OverrideAudioRoute

      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

    • kAudioSessionProperty_AudioInputAvailable

      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

    • kAudioSessionProperty_ServerDied

      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

    • kAudioSessionProperty_OtherMixableAudioShouldDuck

      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

    • kAudioSessionProperty_OverrideCategoryMixWithOthers

      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

    • kAudioSessionProperty_OverrideCategoryDefaultToSpeaker

      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

    • kAudioSessionProperty_OverrideCategoryEnableBluetoothInput

      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

    • kAudioSessionProperty_InterruptionType

      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

    • kAudioSessionProperty_Mode

      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

    • kAudioSessionProperty_InputSources

      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

    • kAudioSessionProperty_OutputDestinations

      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

    • kAudioSessionProperty_InputSource

      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 the kAudioSessionProperty_InputSources array.

      Available in iOS 5.0 and later

    • kAudioSessionProperty_OutputDestination

      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 the kAudioSessionProperty_OutputDestinations array.

      Available in iOS 5.0 and later

    • kAudioSessionProperty_InputGainAvailable

      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.

      Available in iOS 5.0 and later

    • kAudioSessionProperty_InputGainScalar

      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

    • kAudioSessionProperty_AudioRouteDescription

      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

    Discussion

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

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

    Deprecated in iOS 7.0.

    Declaration

    Swift

    var kAudioSessionCategory_AmbientSound: Int { get } var kAudioSessionCategory_SoloAmbientSound: Int { get } var kAudioSessionCategory_MediaPlayback: Int { get } var kAudioSessionCategory_RecordAudio: Int { get } var kAudioSessionCategory_PlayAndRecord: Int { get } var kAudioSessionCategory_AudioProcessing: Int { get }

    Objective-C

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

    Constants

    • kAudioSessionCategory_AmbientSound

      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

    • kAudioSessionCategory_SoloAmbientSound

      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

    • kAudioSessionCategory_MediaPlayback

      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 the kAudioSessionProperty_OverrideCategoryMixWithOthers property.

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

      Available in iOS 2.0 and later

    • kAudioSessionCategory_RecordAudio

      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

    • kAudioSessionCategory_PlayAndRecord

      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 the kAudioSessionProperty_OverrideCategoryMixWithOthers property.

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

      Available in iOS 2.0 and later

    • kAudioSessionCategory_AudioProcessing

      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 Defining a Document-Based Data Model in App Programming Guide for iOS.

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

      Available in iOS 3.1 and later

    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 the kAudioSessionCategory_MediaPlayback and kAudioSessionCategory_PlayAndRecord categories by using the kAudioSessionProperty_OverrideCategoryMixWithOthers property. For more information on audio session categories, see Audio Session Programming Guide.

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

    Deprecated in iOS 7.0.

    Declaration

    Swift

    var kAudioSessionMode_Default: Int { get } var kAudioSessionMode_VoiceChat: Int { get } var kAudioSessionMode_VideoRecording: Int { get } var kAudioSessionMode_Measurement: Int { get }

    Objective-C

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

    Constants

    • kAudioSessionMode_Default

      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

    • kAudioSessionMode_VoiceChat

      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

    • kAudioSessionMode_VideoRecording

      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_PlayAndRecord category. 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

    • kAudioSessionMode_Measurement

      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 the kAudioSessionCategory_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

    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.

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

    Deprecated in iOS 7.0.

    Declaration

    Swift

    var kAudioSessionRouteChangeReason_Unknown: Int { get } var kAudioSessionRouteChangeReason_NewDeviceAvailable: Int { get } var kAudioSessionRouteChangeReason_OldDeviceUnavailable: Int { get } var kAudioSessionRouteChangeReason_CategoryChange: Int { get } var kAudioSessionRouteChangeReason_Override: Int { get } var kAudioSessionRouteChangeReason_WakeFromSleep: Int { get } var kAudioSessionRouteChangeReason_NoSuitableRouteForCategory: Int { get }

    Objective-C

    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

      kAudioSessionRouteChangeReason_Unknown

      The audio route changed but the reason is not known.

      Available in iOS 2.0 and later

    • kAudioSessionRouteChangeReason_NewDeviceAvailable

      kAudioSessionRouteChangeReason_NewDeviceAvailable

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

      Available in iOS 2.0 and later

    • kAudioSessionRouteChangeReason_OldDeviceUnavailable

      kAudioSessionRouteChangeReason_OldDeviceUnavailable

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

      Available in iOS 2.0 and later

    • kAudioSessionRouteChangeReason_CategoryChange

      kAudioSessionRouteChangeReason_CategoryChange

      The audio session category has changed.

      Available in iOS 2.1 and later

    • kAudioSessionRouteChangeReason_Override

      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

    • kAudioSessionRouteChangeReason_WakeFromSleep

      kAudioSessionRouteChangeReason_WakeFromSleep

      The device woke from sleep.

      Available in iOS 2.0 and later

    • kAudioSessionRouteChangeReason_NoSuitableRouteForCategory

      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

    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.

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

    Deprecated in iOS 7.0.

    Declaration

    Swift

    var kAudioSessionOverrideAudioRoute_None: Int { get } var kAudioSessionOverrideAudioRoute_Speaker: Int { get }

    Objective-C

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

    Constants

    • kAudioSessionOverrideAudioRoute_None

      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

    • kAudioSessionOverrideAudioRoute_Speaker

      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

    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.

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

    Deprecated in iOS 7.0.

    Declaration

    Swift

    var kAudioSessionSetActiveFlag_NotifyOthersOnDeactivation: Int { get }

    Objective-C

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

    Constants

    • kAudioSessionSetActiveFlag_NotifyOthersOnDeactivation

      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

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

    Deprecated in iOS 7.0.

    Declaration

    Swift

    typealias AudioSessionInterruptionType = UInt32

    Objective-C

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

    Constants

    • kAudioSessionInterruptionType_ShouldResume

      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

    • kAudioSessionInterruptionType_ShouldNotResume

      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

    Import Statement

    Objective-C

    @import AudioToolbox;

    Swift

    import AudioToolbox

    Availability

    Available in iOS 4.0 and later

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

    Deprecated in iOS 7.0.

    Declaration

    Swift

    var kAudioSessionBeginInterruption: Int { get } var kAudioSessionEndInterruption: Int { get }

    Objective-C

    enum { kAudioSessionBeginInterruption = 1, kAudioSessionEndInterruption = 0 };

    Constants

    • kAudioSessionBeginInterruption

      kAudioSessionBeginInterruption

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

      Available in iOS 2.0 and later

    • kAudioSessionEndInterruption

      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

  • Keys for the kAudioSessionProperty_AudioRouteDescription dictionary.

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    const CFStringRef kAudioSession_AudioRouteKey_Inputs; const CFStringRef kAudioSession_AudioRouteKey_Outputs;

    Constants

    • kAudioSession_AudioRouteKey_Inputs

      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

      Deprecated in iOS 7.0

    • kAudioSession_AudioRouteKey_Outputs

      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, namely kAudioSession_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

      Deprecated in iOS 7.0

  • Keys for the dictionaries in the kAudioSessionProperty_InputSources array.

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    const CFStringRef kAudioSession_InputSourceKey_ID; const CFStringRef kAudioSession_InputSourceKey_Description;

    Constants

    • kAudioSession_InputSourceKey_ID

      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

      Deprecated in iOS 7.0

    • kAudioSession_InputSourceKey_Description

      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

      Deprecated in iOS 7.0

  • Keys for the dictionaries in the kAudioSessionProperty_OutputDestinations array.

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    const CFStringRef kAudioSession_OutputDestinationKey_ID; const CFStringRef kAudioSession_OutputDestinationKey_Description;

    Constants

    • kAudioSession_OutputDestinationKey_ID

      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

      Deprecated in iOS 7.0

    • kAudioSession_OutputDestinationKey_Description

      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

      Deprecated in iOS 7.0

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

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    const CFStringRef kAudioSession_AudioRouteKey_Type;

    Constants

    • kAudioSession_AudioRouteKey_Type

      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

      Deprecated in iOS 7.0

    Discussion

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

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

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

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

    Constants

    • kAudioSessionInputRoute_LineIn

      kAudioSessionInputRoute_LineIn

      A line in input

      Available in iOS 5.0 and later

      Deprecated in iOS 7.0

    • kAudioSessionInputRoute_BuiltInMic

      kAudioSessionInputRoute_BuiltInMic

      A built-in microphone input.

      Some early iOS devices do not have this input.

      Available in iOS 5.0 and later

      Deprecated in iOS 7.0

    • kAudioSessionInputRoute_HeadsetMic

      kAudioSessionInputRoute_HeadsetMic

      A microphone that is part of a headset.

      Available in iOS 5.0 and later

      Deprecated in iOS 7.0

    • kAudioSessionInputRoute_BluetoothHFP

      kAudioSessionInputRoute_BluetoothHFP

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

      Available in iOS 5.0 and later

      Deprecated in iOS 7.0

    • kAudioSessionInputRoute_USBAudio

      kAudioSessionInputRoute_USBAudio

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

      Available in iOS 5.0 and later

      Deprecated in iOS 7.0

    Discussion

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

  • The various audio output destinations available for an iOS device.

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    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

      kAudioSessionOutputRoute_LineOut

      Analog line-level output.

      Available in iOS 5.0 and later

      Deprecated in iOS 7.0

    • kAudioSessionOutputRoute_Headphones

      kAudioSessionOutputRoute_Headphones

      Speakers in headphones or in a headset.

      Available in iOS 5.0 and later

      Deprecated in iOS 7.0

    • kAudioSessionOutputRoute_BluetoothHFP

      kAudioSessionOutputRoute_BluetoothHFP

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

      Available in iOS 5.0 and later

      Deprecated in iOS 7.0

    • kAudioSessionOutputRoute_BluetoothA2DP

      kAudioSessionOutputRoute_BluetoothA2DP

      Speakers in a Bluetooth A2DP device.

      Available in iOS 5.0 and later

      Deprecated in iOS 7.0

    • kAudioSessionOutputRoute_BuiltInReceiver

      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

      Deprecated in iOS 7.0

    • kAudioSessionOutputRoute_BuiltInSpeaker

      kAudioSessionOutputRoute_BuiltInSpeaker

      The primary built-in speaker.

      Available in iOS 5.0 and later

      Deprecated in iOS 7.0

    • kAudioSessionOutputRoute_USBAudio

      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

      Deprecated in iOS 7.0

    • kAudioSessionOutputRoute_HDMI

      kAudioSessionOutputRoute_HDMI

      An output available through the HDMI interface.

      Available in iOS 5.0 and later

      Deprecated in iOS 7.0

    • kAudioSessionOutputRoute_AirPlay

      kAudioSessionOutputRoute_AirPlay

      An output on an AirPlay device.

      Available in iOS 5.0 and later

      Deprecated in iOS 7.0

    Discussion

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

  • Keys for obtaining information about an audio hardware route change.

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

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

    Constants

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

    Deprecated in iOS 7.0.

    Declaration

    Swift

    var kAudioSession_AudioRouteChangeKey_Reason: String { get }

    Objective-C

    #define kAudioSession_AudioRouteChangeKey_Reason "OutputDeviceDidChange_Reason"

    Constants

    • kAudioSession_AudioRouteChangeKey_Reason

      kAudioSession_AudioRouteChangeKey_Reason

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

      Available in iOS 2.0 and later

    Discussion

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

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

    Deprecated in iOS 7.0.

    Declaration

    Swift

    var kAudioSessionCategory_UserInterfaceSoundEffects: Int { get } var kAudioSessionCategory_LiveAudio: Int { get }

    Objective-C

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

    Constants

    • kAudioSessionCategory_UserInterfaceSoundEffects

      kAudioSessionCategory_UserInterfaceSoundEffects

      For sound effects such as touch feedback, explosions, and so on.

      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

    • kAudioSessionCategory_LiveAudio

      kAudioSessionCategory_LiveAudio

      For live performance of music, such as for an app that simulates a piano.

      Equivalent to the kAudioSessionCategory_MediaPlayback category, which you should use instead. The kAudioSessionCategory_LiveAudio category was deprecated in iOS 3.0.

      Available in iOS 2.0 and later

  • Do not use these keys for new development.

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    #define kAudioSession_AudioRouteChangeKey_OldRoute "OutputDeviceDidChange_OldRoute"

    Constants

    • OutputDeviceDidChange_OldRoute

      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”).

      Instead, use the kAudioSession_AudioRouteChangeKey_PreviousRouteDescription dictionary key.

  • Do not use these properties for new development

    Deprecated in iOS 7.0.

    Declaration

    Objective-C

    enum { kAudioSessionProperty_AudioRoute = 'rout' };

    Constants

Result Codes

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

  • No error has occurred.

    Value

    0

    Description

    No error has occurred.

    Available in iOS 2.0 and later.

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

    Value

    '!ini'

    Description

    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.

    Available in iOS 2.0 and later.

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

    Value

    'init'

    Description

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

    Available in iOS 2.0 and later.

  • There was an error during audio session initialization.

    Value

    ''ini?'

    Description

    There was an error during audio session initialization.

    Available in iOS 2.0 and later.

  • The audio session property is not supported.

    Value

    'pty?'

    Description

    The audio session property is not supported.

    Available in iOS 2.0 and later.

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

    Value

    '!siz'

    Description

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

    Available in iOS 2.0 and later.

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

    Value

    '!act'

    Description

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

    Available in iOS 2.0 and later.

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

    Value

    'nohw'

    Description

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

    Available in iOS 3.0 and later.

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

    Value

    '?cat'

    Description

    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.

    Available in iOS 3.1 and later.

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

    Value

    '!cat'

    Description

    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.

    Available in iOS 3.1 and later.

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

    Value

    'what'

    Description

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

    Available in iOS 4.0 and later.