iOS Developer Library

Developer

AVFoundation Framework Reference AVAudioSession Class Reference

Options
Deployment Target:

On This Page
Language:

AVAudioSession

An instance of the AVAudioSession class, called an audio session, is a singleton object that you employ to set the audio context for your app.

Use this class to:

  • Activate or deactivate your app’s audio session

  • Set the audio session category and mode in order to communicate to the system how you intend to use audio in your app

  • Configure audio settings such as sample rate, I/O buffer duration, and number of channels

  • Handle audio route changes

  • React to important audio events, such as changes to the availability of the underlying Media Services daemon

Configuring the Audio Session

The shared audio session object acts as an intermediary between your app and the system’s media services daemon (and in turn, the underlying audio hardware). The media service is subject to requests from other apps—some of which may have a higher priority than your app’s audio needs, such as handling a phone call. Because of the intermediary role that the media services daemon plays, your app does not directly control certain audio settings; instead, you request preferred values for these settings and observe properties on the AVAudioSession object (or related port and data source objects) to see whether, when, and to what extent your requests take effect.

For example, to set the number of output channels do the following:

  1. Call setPreferredOutputNumberOfChannels:error: with a proposed number of channels.

  2. If that method returns YEStrue, your request was accepted. Otherwise, examine the NSError parameter to find the cause of the error.

    Even if your request was accepted, the number of channels you proposed may not be available, or the change might not take effect immediately.

  3. Examine the value of the outputNumberOfChannels property to see what the current number of channels is, or use key-value observing to see when it changes.

If an audio route change occurs (due to such events as a phone call or audio in use by another app while yours is in the background), you may need to reapply your preferred audio settings. Subscribe to the AVAudioSessionRouteChangeNotification notification to respond to these events.

Preferred settings may not take effect immediately. For example, you can use the setPreferredDataSource:error: method on the built-in microphone port to select the front microphone while a headset is plugged in—this preference does not take effect until the headset is unplugged and the audio route changes.

Routing and Mixing

Your session’s category helps to determine audio input and output behaviors when multiple sessions are active. Other active sessions may be associated with system services (such as the Music app, turn-by-turn navigation, or a phone call) or background apps that support audio (see App States and Multitasking).

To control how your audio session interacts with others, use the setCategory:error: or setCategory:withOptions:error: method. If you choose a category or option that supports mixing (see “Audio Session Categories” and “AVAudioSessionCategoryOptions”), audio from other apps continues when you make your session active.

The system allows only one session to control audio routing. If multiple sessions are active, the system chooses which one controls routing based on priority (system sessions such as a phone call may supersede your app’s session) and whether the session is mixable.

Recording Requires User Permission

Recording audio requires explicit permission from the user. The first time your app’s audio session attempts to use an audio input route while using a category that enables recording, the system automatically prompts the user for permission. In iOS 7.0 and earlier, call requestRecordPermission: to prompt the user at a time of your choosing (see “Audio Session Categories”).

In iOS 8.0 and later, the user will not be asked to grant permission until the application attempt to use audio input.

After the user grants or denies permission, the system remembers the choice for future use in the same app. If the user has denied your app recoding permission or has not yet responded to the permission prompt, any audio recording sessions record only silence.

Media Services Availability

In iOS, the system provides audio and other multimedia functionality through a shared server process. Under certain circumstances, the system may terminate and restart this process. Your app should be prepared to respond to these events by reinitializing any audio objects in use (such as players, recorders, converters, or audio queues) in use and reapplying preferred audio session settings.

To respond to a media server restart, subscribe to the AVAudioSessionMediaServicesWereResetNotification notification.

Inheritance


Conforms To


Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in iOS 3.0 and later.
  • Returns the singleton audio session.

    Declaration

    Swift

    class func sharedInstance() -> AVAudioSession!

    Objective-C

    + (AVAudioSession *)sharedInstance

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 3.0 and later.

  • Request the user’s permission for audio recording.

    Declaration

    Swift

    func requestRecordPermission(_ response: PermissionBlock!)

    Objective-C

    - (void)requestRecordPermission:(PermissionBlock)response

    Parameters

    response

    A block to be called when recording permission has been granted or denied.

    Discussion

    Recording audio requires explicit permission from the user. The system automatically prompts the user for permission if you use any session categories that enable recording. Or you can call this method to prompt for permission at a time of your choosing. After the user grants or denies permission, the system remembers the choice for future use in the same app. If permission is not granted, or if the user has not yet responded to the permission prompt, any audio recording sessions record only silence.

    The response parameter is a block of the PermissionBlock type, whose sole parameter indicates whether the user granted or denied permission to record. This method always returns immediately. If the user has previously granted or denied recording permission, it executes the block when called; otherwise, it displays an alert and executes the block only after the user has responded to the alert.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • The current recording permission status.

    Declaration

    Swift

    func recordPermission() -> AVAudioSessionRecordPermission

    Objective-C

    - (AVAudioSessionRecordPermission)recordPermission

    Return Value

    Returns one of three statuses:

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 8.0 and later.

  • category category Property

    The audio session category. (read-only)

    Declaration

    Swift

    var category: String! { get }

    Objective-C

    @property(readonly) NSString *category

    Discussion

    An audio session category identifies a set of audio behaviors for your app.

    The possible values are described in Audio Session Categories). The default category is AVAudioSessionCategorySoloAmbient.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 3.0 and later.

  • The options associated with the current category. (read-only)

    Declaration

    Swift

    var categoryOptions: AVAudioSessionCategoryOptions { get }

    Objective-C

    @property(readonly) AVAudioSessionCategoryOptions categoryOptions

    Discussion

    Use category options to tweak your app’s audio behavior. For a list of options that may be specified in this property, see “AVAudioSessionCategoryOptions”.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • Sets the audio session category.

    Declaration

    Swift

    func setCategory(_ theCategory: String!, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)setCategory:(NSString *)theCategory error:(NSError **)outError

    Parameters

    theCategory

    The audio session category to apply to the audio session. See Audio Session Categories.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    YEStrue if the category and options were set successfully, or NOfalse otherwise.

    Discussion

    The session's category and mode together define how the application intends to use audio. Typically, you set the category and mode before activating the session. You can also set the category or mode while the session is active, but this results in an immediate route change.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 3.0 and later.

    See Also

    category

  • Sets the audio session category with the specified options.

    Declaration

    Swift

    func setCategory(_ category: String!, withOptions options: AVAudioSessionCategoryOptions, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)setCategory:(NSString *)category withOptions:(AVAudioSessionCategoryOptions)options error:(NSError **)outError

    Parameters

    category

    The audio session category to apply to the audio session. For a list of values, see Audio Session Categories.

    options

    A mask of additional options for handling audio. For a list of constants, see AVAudioSessionCategoryOptions

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    YEStrue if the category and options were set successfully, or NOfalse otherwise.

    Discussion

    The session's category and mode together define how the application intends to use audio. Typically, you set the category and mode before activating the session. You can also set the category or mode while the session is active, but this results in an immediate route change.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • mode mode Property

    The audio session mode. (read-only)

    Declaration

    Swift

    var mode: String! { get }

    Objective-C

    @property(readonly) NSString *mode

    Discussion

    One of the constants listed in Audio Session Modes, which together with the audio session’s category indicates to the system how you intend to use audio in your app. You can use a mode to configure the audio system for specific use cases such as video recording, voice or video chat, or taking measurements. The default mode is AVAudioSessionModeDefault.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 5.0 and later.

  • Sets the audio session mode.

    Declaration

    Swift

    func setMode(_ theMode: String!, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)setMode:(NSString *)theMode error:(NSError **)outError

    Parameters

    theMode

    The audio session mode to apply to the audio session.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    Returns YEStrue on success or NOfalse on failure.

    Discussion

    The session's category and mode together define how the application intends to use audio. Typically, you set the category and mode before activating the session. You can also set the category or mode while the session is active, but this results in an immediate route change.

    See Audio Session Modes for discussion of modes and their effects.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 5.0 and later.

  • Activates or deactivates your app’s audio session.

    Declaration

    Swift

    func setActive(_ beActive: Bool, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)setActive:(BOOL)beActive error:(NSError **)outError

    Parameters

    beActive

    Use YEStrue to activate your app’s audio session, or NOfalse to deactivate it.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    YEStrue if the session’s active state was changed successfully, or NOfalse if it was not.

    Discussion

    If another active audio session has higher priority than yours (for example, a phone call), and neither audio session allows mixing, attempting to activate your audio session fails. Deactivating your session will fail if any associated audio objects (such as queues, converters, players, or recorders) are currently running.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 3.0 and later.

  • Activates or deactivates your app’s audio session using the specified options.

    Declaration

    Swift

    func setActive(_ active: Bool, withOptions options: AVAudioSessionSetActiveOptions, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)setActive:(BOOL)active withOptions:(AVAudioSessionSetActiveOptions)options error:(NSError **)outError

    Parameters

    active

    Specify YEStrue to activate your app’s audio session, or NOfalse to deactivate it.

    options

    An integer bit mask containing one or more constants from the AVAudioSessionSetActiveOptions enumeration.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    YEStrue if the session’s active state was changed successfully, or NOfalse if it was not.

    Discussion

    If another active audio session has higher priority than yours (for example, a phone call), and neither audio session allows mixing, attempting to activate your audio session fails. Deactivating your session will fail if any associated audio objects (such as queues, converters, players, or recorders) are currently running.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • The system wide output volume set by the user. (read-only)

    Declaration

    Swift

    var outputVolume: Float { get }

    Objective-C

    @property(readonly) float outputVolume

    Discussion

    A value in the range 0.0 to 1.0, with 0.0 representing the minimum volume and 1.0 representing the maximum volume.

    The system wide output volume can be set directly only by the user; to provide volume control in your app, use the MPVolumeView class.

    You can observe changes to the value of this property by using key-value observing.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • inputGain inputGain Property

    The gain applied to inputs associated with the session. (read-only)

    Declaration

    Swift

    var inputGain: Float { get }

    Objective-C

    @property(readonly) float inputGain

    Discussion

    A floating point value ranging from 0.0 to 1.0, where 0.0 represents the lowest gain setting and 1.0 represents the highest gain setting.

    You can observe changes to the value of this property using key-value observing.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • A Boolean value that indicates whether the input gain can be set. (read-only)

    Declaration

    Swift

    var inputGainSettable: Bool { get }

    Objective-C

    @property(readonly, getter=isInputGainSettable) BOOL inputGainSettable

    Discussion

    Returns YEStrue if the device allows input gain to be changed, or NOfalse otherwise. Not all devices support variable gain, check this property before attempting to set the input gain.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • Changes the input gain to the specified value.

    Declaration

    Swift

    func setInputGain(_ gain: Float, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)setInputGain:(float)gain error:(NSError **)outError

    Parameters

    gain

    The new gain value, which must be in the range 0.0 to 1.0, where 0.0 represents the lowest gain setting and 1.0 represents the highest gain setting.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    YEStrue if the new gain value was set successfully, NOfalse if it was not.

    Discussion

    Before calling this method, check the value in the inputGainSettable property to make sure the input gain level is settable for the current inputs.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • The latency for audio input, in seconds. (read-only)

    Declaration

    Swift

    var inputLatency: NSTimeInterval { get }

    Objective-C

    @property(readonly) NSTimeInterval inputLatency

    Discussion

    If the audio session category for your app does not support input recording, this property generates an AVAudioSessionErrorCodeIncompatibleCategory error.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • The latency for audio output, measured in seconds. (read-only)

    Declaration

    Swift

    var outputLatency: NSTimeInterval { get }

    Objective-C

    @property(readonly) NSTimeInterval outputLatency

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • The audio sample rate, in hertz, that is currently in effect. (read-only)

    Declaration

    Swift

    var sampleRate: Double { get }

    Objective-C

    @property(readonly) double sampleRate

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • The preferred sample rate, in hertz. (read-only)

    Declaration

    Swift

    var preferredSampleRate: Double { get }

    Objective-C

    @property(readonly) double preferredSampleRate

    Discussion

    The value of this property indicates the preferred sample rate set using the setPreferredSampleRate:error: method. To see the actual sample rate, use the sampleRate property.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • Sets the preferred sample rate for input and output.

    Declaration

    Swift

    func setPreferredSampleRate(_ sampleRate: Double, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)setPreferredSampleRate:(double)sampleRate error:(NSError **)outError

    Parameters

    sampleRate

    The hardware sample rate to use. The available range for hardware sample rate is device dependent. It typically ranges from 8000 through 48000 hertz.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    YEStrue if a request was successfully made, or NOfalse otherwise.

    Discussion

    This method requests a change to the input and output audio sample rate. To see the effect of this change, use the sampleRate property. For details see “Configuring the Audio Session”.

    You can set a preferred sample rate before or after activating the audio session.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • The I/O buffer duration, in seconds, that is currently in effect. (read-only)

    Declaration

    Swift

    var IOBufferDuration: NSTimeInterval { get }

    Objective-C

    @property(readonly) NSTimeInterval IOBufferDuration

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • The preferred I/O buffer duration, in seconds. (read-only)

    Declaration

    Swift

    var preferredIOBufferDuration: NSTimeInterval { get }

    Objective-C

    @property(readonly) NSTimeInterval preferredIOBufferDuration

    Discussion

    The value of this property indicates the buffer duration selected using the setPreferredIOBufferDuration:error: method. To see the actual buffer duration, use the IOBufferDuration property.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 3.0 and later.

  • Sets the preferred audio I/O buffer duration, in seconds.

    Declaration

    Swift

    func setPreferredIOBufferDuration(_ duration: NSTimeInterval, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)setPreferredIOBufferDuration:(NSTimeInterval)duration error:(NSError **)outError

    Parameters

    duration

    The audio I/O buffer duration, in seconds, that you want to use.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    YEStrue if a request was successfully made, or NOfalse otherwise.

    Discussion

    This method requests a change to the I/O buffer duration. To determine whether the change takes effect, use the IOBufferDuration property. For details see “Configuring the Audio Session”.

    The audio I/O buffer duration is the number of seconds for a single audio input/output cycle. For example, with an I/O buffer duration of 0.005 s, on each audio I/O cycle:

    • You receive 0.005 s of audio if obtaining input.

    • You must provide 0.005 s of audio if providing output.

    The typical maximum I/O buffer duration is 0.93 s (corresponding to 4096 sample frames at a sample rate of 44.1 kHz). The minimum I/O buffer duration is at least 0.005 s (256 frames) but may be lower depending on the hardware in use.

    You can set a preferred I/O buffer duration before or after activating the audio session.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 3.0 and later.

  • A Boolean value that indicates whether another application is playing audio. (read-only)

    Declaration

    Swift

    var secondaryAudioShouldBeSilencedHint: Bool { get }

    Objective-C

    @property(readonly) BOOL secondaryAudioShouldBeSilencedHint

    Discussion

    The value is YEStrue when another application with a non-mixable audio session is playing audio.

    Applications should use this property as a hint to silence audio that is secondary to the functionality of the application. For example, a game using AVAudioSessionCategoryAmbient may use this property to decide to mute its soundtrack while leaving its sound effects unmuted.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 8.0 and later.

  • The number of audio input channels for the current route. (read-only)

    Declaration

    Swift

    var inputNumberOfChannels: Int { get }

    Objective-C

    @property(readonly) NSInteger inputNumberOfChannels

    Discussion

    You can observe changes to the value of this property by using key-value observing. If the audio session category for your app does not support input recording, this property generates an AVAudioSessionErrorCodeIncompatibleCategory error.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • The largest number of input channels available for the current route. (read-only)

    Declaration

    Swift

    var maximumInputNumberOfChannels: Int { get }

    Objective-C

    @property(readonly) NSInteger maximumInputNumberOfChannels

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • The preferred number of input channels for the current route. (read-only)

    Declaration

    Swift

    var preferredInputNumberOfChannels: Int { get }

    Objective-C

    @property(readonly) NSInteger preferredInputNumberOfChannels

    Discussion

    The value of this property indicates the number of channels selected using the setPreferredInputNumberOfChannels:error: method. To see the actual number of channels, use the inputNumberOfChannels property.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • Sets the preferred number of input channels for the current route.

    Declaration

    Swift

    func setPreferredInputNumberOfChannels(_ count: Int, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)setPreferredInputNumberOfChannels:(NSInteger)count error:(NSError **)outError

    Parameters

    count

    The number of input channels you want to use.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    YEStrue if a request was successfully made, or NOfalse otherwise.

    Discussion

    This method requests a change to the number of input channels. To determine whether the change takes effect, use the inputNumberOfChannels property. For details see “Configuring the Audio Session”. Requesting a number of input channels less than one or greater than that returned by the maximumInputNumberOfChannels results in an error.

    You must set a preferred number of input channels only after setting the audio session’s category and mode and activating the session.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • The number of audio output channels. (read-only)

    Declaration

    Swift

    var outputNumberOfChannels: Int { get }

    Objective-C

    @property(readonly) NSInteger outputNumberOfChannels

    Discussion

    You can observe changes to the value of this property by using key-value observing.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • The largest number of output channels available for the current route. (read-only)

    Declaration

    Swift

    var maximumOutputNumberOfChannels: Int { get }

    Objective-C

    @property(readonly) NSInteger maximumOutputNumberOfChannels

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • The preferred number of output channels for the current route. (read-only)

    Declaration

    Swift

    var preferredOutputNumberOfChannels: Int { get }

    Objective-C

    @property(readonly) NSInteger preferredOutputNumberOfChannels

    Discussion

    The value of this property indicates preferred number of output channels selected using the setPreferredOutputNumberOfChannels:error: method. To see the actual number of channels, use the outputNumberOfChannels property.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • Sets the preferred number of output channels for the current route.

    Declaration

    Swift

    func setPreferredOutputNumberOfChannels(_ count: Int, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)setPreferredOutputNumberOfChannels:(NSInteger)count error:(NSError **)outError

    Parameters

    count

    The number of output channels you want to use.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    YEStrue if a request was successfully made, or NOfalse otherwise.

    Discussion

    This method requests a change to the number of output channels. To determine whether the change takes effect, use the outputNumberOfChannels property. For details see “Configuring the Audio Session”. Requesting a number of output channels less than one or greater than that returned by the maximumOutputNumberOfChannels results in an error. This feature is supported only on certain devices and peripherals.

    You set a preferred number of output channels only after setting the audio session’s category and mode and activating the session.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • An object describing the current audio input and output route. (read-only)

    Declaration

    Swift

    var currentRoute: AVAudioSessionRouteDescription! { get }

    Objective-C

    @property(readonly) AVAudioSessionRouteDescription *currentRoute

    Discussion

    This object describes the input and output ports associated with the current audio route.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • A Boolean value indicating whether an audio input path is available. (read-only)

    Declaration

    Swift

    var inputAvailable: Bool { get }

    Objective-C

    @property(readonly, getter=isInputAvailable) BOOL inputAvailable

    Discussion

    YEStrue if an input route is available, or NOfalse otherwise.

    Use this property to determine whether the device currently supports audio input.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • A Boolean value indicating whether another app is currently playing audio. (read-only)

    Declaration

    Swift

    var otherAudioPlaying: Bool { get }

    Objective-C

    @property(readonly, getter=isOtherAudioPlaying) BOOL otherAudioPlaying

    Discussion

    In iOS 8.0 and later applications should use secondaryAudioShouldBeSilencedHint instead of this property.

    The otherAudioPlaying property will be true if any other audio (including audio from an app using AVAudioSessionCategoryAmbient is playing, whereas the secondaryAudioShouldBeSilencedHint property is more restrictive in its consideration of whether primary audio from another application is playing.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • Temporarily changes the current audio route.

    Declaration

    Swift

    func overrideOutputAudioPort(_ portOverride: AVAudioSessionPortOverride, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)overrideOutputAudioPort:(AVAudioSessionPortOverride)portOverride error:(NSError **)outError

    Parameters

    portOverride

    The override option for output. For a list of constants, see “AVAudioSessionPortOverride”.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    YEStrue if the new routing option was set successfully, or NOfalse if it was not.

    Discussion

    Calling this method with the AVAudioSessionPortOverrideSpeaker option and the audio session’s category AVAudioSessionCategoryPlayAndRecord causes audio to use the built-in speaker and microphone regardless of other settings. This change remains in effect only until the current route changes or you call this method again with the AVAudioSessionPortOverrideNone option.

    Apple recommends using the MPVolumeView class to provide user control for audio input and output selection.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • An array of input ports available for routing. (read-only)

    Declaration

    Swift

    var availableInputs: [AnyObject]! { get }

    Objective-C

    @property(readonly) NSArray *availableInputs

    Discussion

    An array of AVAudioSessionPortDescription objects representing audio input devices currently attached to the system and relevant to the audio session’s current category and mode. For example, if the session’s category is AVAudioSessionCategoryPlayAndRecord, the array may contain a built-in microphone and (if plugged in) a headset microphone port.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • The preferred input port for audio routing. (read-only)

    Declaration

    Swift

    var preferredInput: AVAudioSessionPortDescription! { get }

    Objective-C

    @property(readonly) AVAudioSessionPortDescription *preferredInput

    Discussion

    The value of this property indicates the input port selected using the setPreferredInput:error: method. To see the actual current input port, use the currentRoute property. Returns nil if no preference has been set or if the previously set preferred input is no longer available.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

    See Also

    availableInputs

  • Sets the preferred input port for audio routing.

    Declaration

    Swift

    func setPreferredInput(_ inPort: AVAudioSessionPortDescription!, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)setPreferredInput:(AVAudioSessionPortDescription *)inPort error:(NSError **)outError

    Parameters

    inPort

    An AVAudioSessionPortDescription object describing the port to use for input.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    YEStrue if a request was successfully made, or NOfalse otherwise.

    Discussion

    Setting the preferred input port requests a change to the input audio route. To determine whether the change takes effect, use the currentRoute property. For details see “Configuring the Audio Session”.

    The value of the inPort parameter must be one of the AVAudioSessionPortDescription objects in the availableInputs array. If this parameter specifies a port that is not already part of the current audio route and the app’s session controls audio routing, this method initiates a route change to use the preferred port.

    You must set a preferred input port only after setting the audio session’s category and mode and activating the session.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • An array of available data sources for the audio session’s current input port. (read-only)

    Declaration

    Swift

    var inputDataSources: [AnyObject]! { get }

    Objective-C

    @property(readonly) NSArray *inputDataSources

    Discussion

    An array of AVAudioSessionDataSourceDescription objects representing available input sources, or nil if switching between multiple input sources is not currently possible. This feature is supported only on certain devices and peripherals–for example, on an iPhone equipped with both front- and rear-facing microphones.

    You can observe changes to the value of this property by using key-value observing.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • The currently selected input data source. (read-only)

    Declaration

    Swift

    var inputDataSource: AVAudioSessionDataSourceDescription! { get }

    Objective-C

    @property(readonly) AVAudioSessionDataSourceDescription *inputDataSource

    Discussion

    The value of this property is nil if switching between multiple input sources is not currently possible. This feature is supported only on certain devices and peripherals–for example, on an iPhone equipped with both front- and rear-facing microphones.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

    See Also

    inputDataSources

  • Selects a data source for the audio session’s current input port.

    Declaration

    Swift

    func setInputDataSource(_ dataSource: AVAudioSessionDataSourceDescription!, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)setInputDataSource:(AVAudioSessionDataSourceDescription *)dataSource error:(NSError **)outError

    Parameters

    dataSource

    The data source for the audio session’s input.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    YEStrue if the input data source for the audio session was successfully assigned; otherwise, NOfalse.

    Discussion

    You may change the input source to just one of the AVAudioSessionDataSourceDescription objects in the inputDataSources array. Switching between multiple input sources is supported only on certain devices and peripherals; for example, this method can be used to choose between front- and rear-facing microphones on an iPhone equipped with them.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

    See Also

    inputDataSources

  • An array of available output data sources for the current audio route. (read-only)

    Declaration

    Swift

    var outputDataSources: [AnyObject]! { get }

    Objective-C

    @property(readonly) NSArray *outputDataSources

    Discussion

    An array of AVAudioSessionDataSourceDescription objects representing available output sources, or nil if switching between multiple output sources is not currently possible. This feature is supported only on certain USB accessories.

    You can observe changes to the value of this property by using key-value observing.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • The currently selected output data source. (read-only)

    Declaration

    Swift

    var outputDataSource: AVAudioSessionDataSourceDescription! { get }

    Objective-C

    @property(readonly) AVAudioSessionDataSourceDescription *outputDataSource

    Discussion

    The value of this property is nil if switching between multiple output sources is not currently possible. Switching output sources is supported only on certain USB accessories.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • Sets the output data source for an audio session.

    Declaration

    Swift

    func setOutputDataSource(_ dataSource: AVAudioSessionDataSourceDescription!, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)setOutputDataSource:(AVAudioSessionDataSourceDescription *)dataSource error:(NSError **)outError

    Parameters

    dataSource

    The data source for the audio session’s output.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    YEStrue if the output data source for the audio session was successfully assigned; otherwise, NOfalse.

    Discussion

    You can change the output source to one of the AVAudioSessionDataSourceDescription objects in the outputDataSources array. This feature is supported only on certain USB accessories.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • delegate delegate (iOS 6.0) Property

    The delegate object for the audio session.

    Deprecation Statement

    Use the notifications described in the Notifications section of this class instead.

    Declaration

    Objective-C

    @property(assign) id< AVAudioSessionDelegate > delegate

    Discussion

    The delegate object must implement the protocol described in AVAudioSessionDelegate Protocol Reference.

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 6.0.

  • The number of audio hardware input channels. (read-only)

    Deprecation Statement

    Use inputNumberOfChannels instead.

    Declaration

    Objective-C

    @property(readonly) NSInteger currentHardwareInputNumberOfChannels

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 6.0.

  • The number of audio hardware output channels. (read-only)

    Deprecation Statement

    Use outputNumberOfChannels instead.

    Declaration

    Objective-C

    @property(readonly) NSInteger currentHardwareOutputNumberOfChannels

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 6.0.

  • The audio hardware sample rate, in hertz. (read-only)

    Deprecation Statement

    Use sampleRate instead

    Declaration

    Objective-C

    @property(readonly) double currentHardwareSampleRate

    Discussion

    Obtain the value of this property after activating your audio session. After successful activation, the value of this property does not change while your session remains active.

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 6.0.

  • The preferred hardware sample rate, in hertz. (read-only)

    Deprecation Statement

    Use preferredSampleRate instead.

    Declaration

    Objective-C

    @property(readonly) double preferredHardwareSampleRate

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 6.0.

  • Sets the preferred hardware sample rate for input and output.

    Deprecation Statement

    Use setPreferredSampleRate:error: instead.

    Declaration

    Objective-C

    - (BOOL)setPreferredHardwareSampleRate:(double)sampleRate error:(NSError **)outError

    Parameters

    sampleRate

    The hardware sample rate you want to use. The available range for hardware sample rate is device dependent.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    Returns YEStrue on success or NOfalse on failure.

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 6.0.

  • inputIsAvailable inputIsAvailable (iOS 6.0) Property

    A Boolean value that indicates whether a hardware audio input path is available (YEStrue), or not (NOfalse). (read-only)

    Deprecation Statement

    Use inputAvailable instead.

    Declaration

    Objective-C

    @property(readonly) BOOL inputIsAvailable

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 3.0 and later.

    Deprecated in iOS 6.0.

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

    Deprecation Statement

    Use setActive:withOptions:error: instead.

    Declaration

    Objective-C

    - (BOOL)setActive:(BOOL)beActive withFlags:(NSInteger)flags error:(NSError **)outError

    Parameters

    beActive

    Use YEStrue to activate your app’s audio session or NOfalse to deactivate it.

    flags

    A bitmapped value containing one or more flags from the Activation Flags enumeration.

    outError

    On input, a pointer to an error object. If an error occurs, the pointer is set to an NSError object that describes the error. If you do not want error information, pass in nil.

    Return Value

    Returns YEStrue on success or NOfalse on failure.

    Discussion

    If another app’s active audio session has higher priority than your app, and that other audio session does not allow mixing with other apps, attempting to activate your audio session may fail.

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 6.0.

Data Types

  • The signature for the block executed when the user responds to a prompt for recording permission.

    Declaration

    Swift

    typealias PermissionBlock = (Bool) -> Void

    Objective-C

    typedef void (^PermissionBlock)(BOOL granted)

    Discussion

    The block takes a single parameter:

    granted

    YEStrue if the user has explicitly granted the app permission for audio recording; NOfalse if the user denied permission.

    This block type is used by the requestRecordPermission: method.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • Category identifiers for audio sessions, used as values for the setCategory:error: method.

    Declaration

    Swift

    let AVAudioSessionCategoryAmbient: NSString! let AVAudioSessionCategorySoloAmbient: NSString! let AVAudioSessionCategoryPlayback: NSString! let AVAudioSessionCategoryRecord: NSString! let AVAudioSessionCategoryPlayAndRecord: NSString! let AVAudioSessionCategoryAudioProcessing: NSString! let AVAudioSessionCategoryMultiRoute: NSString!

    Objective-C

    NSString *const AVAudioSessionCategoryAmbient; NSString *const AVAudioSessionCategorySoloAmbient; NSString *const AVAudioSessionCategoryPlayback; NSString *const AVAudioSessionCategoryRecord; NSString *const AVAudioSessionCategoryPlayAndRecord; NSString *const AVAudioSessionCategoryAudioProcessing; NSString *const AVAudioSessionCategoryMultiRoute;

    Constants

    • AVAudioSessionCategoryAmbient

      AVAudioSessionCategoryAmbient

      The category 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 also appropriate for “play along” style apps, such as a virtual piano that a user plays while the Music app is playing. 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).

      Available in iOS 3.0 and later.

    • AVAudioSessionCategorySoloAmbient

      AVAudioSessionCategorySoloAmbient

      The category for default category, used unless you set a category with the setCategory:error: or setCategory:withOptions:error: method.

      Your audio is silenced by screen locking and by the Silent switch (called the Ring/Silent switch on iPhone).

      By default, using this category implies that your app’s audio is nonmixable—activating your session will interrupt any other audio sessions which are also nonmixable. To allow mixing, use the AVAudioSessionCategoryAmbient category instead.

      Available in iOS 3.0 and later.

    • AVAudioSessionCategoryPlayback

      AVAudioSessionCategoryPlayback

      The category 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.) To continue playing audio when your app transitions to the background (for example, when the screen locks), add the audio value to the UIBackgroundModes key in your information property list file.

      By default, using this category implies that your app’s audio is nonmixable—activating your session will interrupt any other audio sessions which are also nonmixable. To allow mixing for this category, use the AVAudioSessionCategoryOptionMixWithOthers option.

      Available in iOS 3.0 and later.

    • AVAudioSessionCategoryRecord

      AVAudioSessionCategoryRecord

      The category for recording audio; this category silences playback audio.

      To continue recording audio when your app transitions to the background (for example, when the screen locks), add the audio value to the UIBackgroundModes key in your information property list file.

      The user must grant permission for audio recording (see “Recording Requires User Permission”).

      Available in iOS 3.0 and later.

    • AVAudioSessionCategoryPlayAndRecord

      AVAudioSessionCategoryPlayAndRecord

      The category for recording (input) and playback (output) of audio, such as for a VoIP (Voice over Internet Protocol) 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.) To continue playing audio when your app transitions to the background (for example, when the screen locks), add the audio value to the UIBackgroundModes key in your information property list file.

      This category is appropriate for simultaneous recording and playback, and also for apps that record and play back but not simultaneously.

      By default, using this category implies that your app’s audio is nonmixable—activating your session will interrupt any other audio sessions which are also nonmixable. To allow mixing for this category, use the AVAudioSessionCategoryOptionMixWithOthers option.

      The user must grant permission for audio recording (see “Recording Requires User Permission”).

      Available in iOS 3.0 and later.

    • AVAudioSessionCategoryAudioProcessing

      AVAudioSessionCategoryAudioProcessing

      The category 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 App Programming Guide for iOS.

      Available in iOS 3.1 and later.

    • AVAudioSessionCategoryMultiRoute

      AVAudioSessionCategoryMultiRoute

      The category for routing distinct streams of audio data to different output devices at the same time. For example, use this category to route audio to both a USB device and a set of headphones. Use of this category requires a more detailed knowledge of, and interaction with, the capabilities of the available audio routes.

      This category may be used for input, output, or both.

      The user must grant permission for audio recording (see “Recording Requires User Permission”).

      Available in iOS 6.0 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 AVAudioSessionCategoryPlayback, AVAudioSessionCategoryRecord, and AVAudioSessionCategoryPlayAndRecord categories by using an audio session mode, as described in Audio Session Modes.

  • Constants that specify optional audio behaviors.

    Declaration

    Swift

    struct AVAudioSessionCategoryOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var MixWithOthers: AVAudioSessionCategoryOptions { get } static var DuckOthers: AVAudioSessionCategoryOptions { get } static var AllowBluetooth: AVAudioSessionCategoryOptions { get } static var DefaultToSpeaker: AVAudioSessionCategoryOptions { get } }

    Objective-C

    enum { AVAudioSessionCategoryOptionMixWithOthers = 1, AVAudioSessionCategoryOptionDuckOthers = 2, AVAudioSessionCategoryOptionAllowBluetooth = 4, AVAudioSessionCategoryOptionDefaultToSpeaker = 8 }; typedef NSUInteger AVAudioSessionCategoryOptions;

    Constants

    • MixWithOthers

      AVAudioSessionCategoryOptionMixWithOthers

      Mixes audio from this session with audio from other active sessions.

      Valid only if the session category is AVAudioSessionCategoryPlayAndRecord or AVAudioSessionCategoryPlayback. (Implicit if the session category is AVAudioSessionCategoryAmbient.)

      If you activate your session while using this option, your app’s audio will not interrupt audio from other apps (such as the Music app). If not using this option (or a category that is implicitly mixable), activating your session will interrupt other nonmixable sessions.

      Available in iOS 6.0 and later.

    • DuckOthers

      AVAudioSessionCategoryOptionDuckOthers

      Causes audio from other sessions to be ducked (reduced in volume) while audio from this session plays.

      Valid only if the session category is AVAudioSessionCategoryPlayAndRecord or AVAudioSessionCategoryPlayback.

      Use this option if you want audio from your app (for example, voice prompts in a navigation app) to be heard over music or other currently playing audio. Note that ducking begins when you activate your app’s audio session and ends when you deactivate the session.

      Available in iOS 6.0 and later.

    • AllowBluetooth

      AVAudioSessionCategoryOptionAllowBluetooth

      Allows Bluetooth handsfree devices to appear as available input routes.

      Valid only if the session category is AVAudioSessionCategoryPlayAndRecord or AVAudioSessionCategoryRecord.

      Available in iOS 6.0 and later.

    • DefaultToSpeaker

      AVAudioSessionCategoryOptionDefaultToSpeaker

      Routes audio from the session to the built-in speaker by default.

      Valid only if the session category is AVAudioSessionCategoryPlayAndRecord.

      When using this option and no other audio route (such as a headset) is available, session audio will play through the device’s built-in speaker. When not using this option, and no other audio output is available or selected, audio will play through the receiver (a speaker intended to be held to the ear). Note that only iPhone devices are equipped with a receiver; on iPad and iPod touch devices, this option has no effect.

      Available in iOS 6.0 and later.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • Mode identifiers for audio sessions, used as values for the setMode:error: method.

    Declaration

    Swift

    let AVAudioSessionModeDefault: NSString! let AVAudioSessionModeVoiceChat: NSString! let AVAudioSessionModeGameChat: NSString! let AVAudioSessionModeVideoRecording: NSString! let AVAudioSessionModeMeasurement: NSString! let AVAudioSessionModeMoviePlayback: NSString! let AVAudioSessionModeVideoChat: NSString!

    Objective-C

    NSString *const AVAudioSessionModeDefault; NSString *const AVAudioSessionModeVoiceChat; NSString *const AVAudioSessionModeGameChat NSString *const AVAudioSessionModeVideoRecording; NSString *const AVAudioSessionModeMeasurement; NSString *const AVAudioSessionModeMoviePlayback; NSString *const AVAudioSessionModeVideoChat;

    Constants

    • AVAudioSessionModeDefault

      AVAudioSessionModeDefault

      The default mode; used unless you set a mode with the setMode:error: method.

      You can use this mode with every audio session category.

      Available in iOS 5.0 and later.

    • AVAudioSessionModeVoiceChat

      AVAudioSessionModeVoiceChat

      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 and the set of allowable audio routes is reduced to only those appropriate for voice chat. For use with the AVAudioSessionCategoryPlayAndRecord audio session category. Apple recommends using the Voice Processing Audio Unit with this mode (see Audio Unit Hosting Guide for iOS).

      Using this mode has the side effect of enabling the AVAudioSessionCategoryOptionAllowBluetooth category option.

      Available in iOS 5.0 and later.

    • AVAudioSessionModeGameChat

      AVAudioSessionModeGameChat

      Do not set this mode directly. This mode is set by Game Kit on behalf of an application that uses a GKVoiceChat object. This mode is valid only with the AVAudioSessionCategoryPlayAndRecord category.

      If you need similar behavior and are not using a GKVoiceChat object, use AVAudioSessionModeVoiceChat or AVAudioSessionModeVideoChat instead.

      Available in iOS 5.0 and later.

    • AVAudioSessionModeVideoRecording

      AVAudioSessionModeVideoRecording

      Specify this mode if your app is recording a movie.

      For use with the AVAudioSessionCategoryRecord audio session category. Also works with the AVAudioSessionCategoryPlayAndRecord 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.

      If your app records video, you can use the AVCaptureSession class to control your audio session instead of setting this mode directly.

      Available in iOS 5.0 and later.

    • AVAudioSessionModeMeasurement

      AVAudioSessionModeMeasurement

      Specify this mode if your app is performing measurement of audio input or output.

      When this mode is in use, the device does minimal signal processing on input and output audio. For use with the AVAudioSessionCategoryPlayback, AVAudioSessionCategoryRecord, or AVAudioSessionCategoryPlayAndRecord audio session categories. If recording on devices with more than one built-in microphone, the primary microphone is used.

      Available in iOS 5.0 and later.

    • AVAudioSessionModeMoviePlayback

      AVAudioSessionModeMoviePlayback

      Specify this mode if your app is playing back movie content.

      When this mode is in use, signal processing is employed to enhance movie playback for certain audio routes such as built-in speaker or headphones.

      Available in iOS 6.0 and later.

    • AVAudioSessionModeVideoChat

      AVAudioSessionModeVideoChat

      Specify this mode if your app is engaging in online video conferencing.

      When this mode is in use, the device’s tonal equalization is optimized for voice and the set of allowable audio routes is reduced to only those appropriate for video chat. For use with the AVAudioSessionCategoryPlayAndRecord or AVAudioSessionCategoryRecord audio session category. Apple recommends using the Voice Processing Audio Unit with this mode (see Audio Unit Hosting Guide for iOS).

      Using this mode has the side effect of enabling the AVAudioSessionCategoryOptionAllowBluetooth category option.

      Available in iOS 7.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. Change your audio session’s mode only if your audio session category is configured to disallow mixing with other apps (see AVAudioSessionCategoryOptionMixWithOthers); mode applies to the system as a whole, so an app whose session is active and nonmixable will typically typically control the mode for the system.

  • A constant that indicates the state of the audio session following an interruption.

    Declaration

    Swift

    struct AVAudioSessionInterruptionOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var OptionShouldResume: AVAudioSessionInterruptionOptions { get } }

    Objective-C

    enum { AVAudioSessionInterruptionOptionShouldResume = 1 }; typedef NSUInteger AVAudioSessionInterruptionOptions;

    Constants

    • OptionShouldResume

      AVAudioSessionInterruptionOptionShouldResume

      Interruption by another audio session has ended and the app may resume its audio session.

      This value may be present for the AVAudioSessionInterruptionOptionKey key in the userInfo dictionary of the AVAudioSessionInterruptionNotification notification if the interruption type is AVAudioSessionInterruptionTypeEnded. It serves as a hint that it is appropriate for your app to resume audio playback without waiting for user input. Apps that do not normally require user input to begin audio playback (such as games) may ignore this flag and always resume playback upon ending an interruption.

      Available in iOS 6.0 and later.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • A flag that provides additional information about your app’s audio intentions upon session activation or deactivation.

    Declaration

    Swift

    struct AVAudioSessionSetActiveOptions : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var OptionNotifyOthersOnDeactivation: AVAudioSessionSetActiveOptions { get } }

    Objective-C

    enum { AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation = 1 }; typedef NSUInteger AVAudioSessionSetActiveOptions;

    Constants

    • OptionNotifyOthersOnDeactivation

      AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation

      When passed in the flags parameter of the setActive:withOptions:error: instance method, indicates that when your audio session deactivates, other audio sessions that had been interrupted by your session can return to their active state.

      This flag is used only when deactivating your audio session; that is, when you pass a value of NOfalse in the beActive parameter of the setActive:withOptions:error: instance method.

      Available in iOS 6.0 and later.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • Constants for use with the overrideOutputAudioPort:error: method.

    Declaration

    Swift

    enum AVAudioSessionPortOverride : UInt { case None case Speaker }

    Objective-C

    enum { AVAudioSessionPortOverrideNone = 0, AVAudioSessionPortOverrideSpeaker = 'spkr' }; typedef NSUInteger AVAudioSessionPortOverride;

    Constants

    • None

      AVAudioSessionPortOverrideNone

      Do not override the output audio port. Use this option to route audio to the system default outputs for the current category and mode.

      Available in iOS 6.0 and later.

    • Speaker

      AVAudioSessionPortOverrideSpeaker

      Override the current inputs and outputs and route audio to the built-in speaker and microphone. Only valid with the AVAudioSessionCategoryPlayAndRecord category.

      Available in iOS 6.0 and later.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • Constants indicating the reason for an audio route change.

    Declaration

    Swift

    enum AVAudioSessionRouteChangeReason : UInt { case Unknown case NewDeviceAvailable case OldDeviceUnavailable case CategoryChange case Override case WakeFromSleep case NoSuitableRouteForCategory case RouteConfigurationChange }

    Objective-C

    enum { AVAudioSessionRouteChangeReasonUnknown = 0, AVAudioSessionRouteChangeReasonNewDeviceAvailable = 1, AVAudioSessionRouteChangeReasonOldDeviceUnavailable = 2, AVAudioSessionRouteChangeReasonCategoryChange = 3, AVAudioSessionRouteChangeReasonOverride = 4, AVAudioSessionRouteChangeReasonWakeFromSleep = 6, AVAudioSessionRouteChangeReasonNoSuitableRouteForCategory = 7, AVAudioSessionRouteChangeReasonRouteConfigurationChange = 8, }; typedef NSUInteger AVAudioSessionRouteChangeReason;

    Constants

    • Unknown

      AVAudioSessionRouteChangeReasonUnknown

      The reason for the change is unknown.

      Available in iOS 6.0 and later.

    • NewDeviceAvailable

      AVAudioSessionRouteChangeReasonNewDeviceAvailable

      A user action (such as plugging in a headset) has made a preferred audio route available.

      Available in iOS 6.0 and later.

    • OldDeviceUnavailable

      AVAudioSessionRouteChangeReasonOldDeviceUnavailable

      The previous audio output path is no longer available.

      Available in iOS 6.0 and later.

    • CategoryChange

      AVAudioSessionRouteChangeReasonCategoryChange

      The category of the session object changed. Also used when the session is first activated.

      Available in iOS 6.0 and later.

    • Override

      AVAudioSessionRouteChangeReasonOverride

      The output route was overridden by the app.

      Available in iOS 6.0 and later.

    • WakeFromSleep

      AVAudioSessionRouteChangeReasonWakeFromSleep

      The route changed when the device woke up from sleep.

      Available in iOS 6.0 and later.

    • NoSuitableRouteForCategory

      AVAudioSessionRouteChangeReasonNoSuitableRouteForCategory

      The route changed because no suitable route is now available for the specified category.

      Available in iOS 6.0 and later.

    • RouteConfigurationChange

      AVAudioSessionRouteChangeReasonRouteConfigurationChange

      The set of input and output ports has not changed, but their configuration has—for example, a port’s selected data source has changed.

      Available in iOS 7.0 and later.

    Discussion

    These constants appear as possible values for the AVAudioSessionRouteChangeReasonKey key in the userInfo dictionary in a AVAudioSessionRouteChangeNotification notification.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • Constants that describe the state of the audio interruption.

    Declaration

    Swift

    enum AVAudioSessionInterruptionType : UInt { case Began case Ended }

    Objective-C

    enum { AVAudioSessionInterruptionTypeBegan = 1, AVAudioSessionInterruptionTypeEnded = 0, }; typedef NSUInteger AVAudioSessionInterruptionType;

    Constants

    • Began

      AVAudioSessionInterruptionTypeBegan

      The system interrupted the audio session.

      Available in iOS 6.0 and later.

    • Ended

      AVAudioSessionInterruptionTypeEnded

      The interruption ended.

      Available in iOS 6.0 and later.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • Keys available in the user info dictionary of an interruption notification.

    Declaration

    Swift

    let AVAudioSessionInterruptionTypeKey: NSString! let AVAudioSessionInterruptionOptionKey: NSString! let AVAudioSessionRouteChangeReasonKey: NSString! let AVAudioSessionRouteChangePreviousRouteKey: NSString! let AVAudioSessionSilenceSecondaryAudioHintTypeKey: NSString!

    Objective-C

    NSString *const AVAudioSessionInterruptionTypeKey; NSString *const AVAudioSessionInterruptionOptionKey; NSString *const AVAudioSessionRouteChangeReasonKey; NSString *const AVAudioSessionRouteChangePreviousRouteKey; NSString *const AVAudioSessionSilenceSecondaryAudioHintTypeKey;

    Constants

    • AVAudioSessionInterruptionTypeKey

      AVAudioSessionInterruptionTypeKey

      An NSNumber object containing an unsigned integer that identifies the type of interruption. For a list of possible values, see “AVAudioSessionInterruptionType”.

      Available in iOS 6.0 and later.

    • AVAudioSessionInterruptionOptionKey

      AVAudioSessionInterruptionOptionKey

      An NSNumber object containing an unsigned integer that identifies any options associated with the interruption. For a list of possible flags, see “AVAudioSessionInterruptionOptions”.

      Available in iOS 6.0 and later.

    • AVAudioSessionRouteChangeReasonKey

      AVAudioSessionRouteChangeReasonKey

      An NSNumber object containing an unsigned integer that identifies the reason why the route changed. For a list of possible values, see “AVAudioSessionRouteChangeReason”.

      Available in iOS 6.0 and later.

    • AVAudioSessionRouteChangePreviousRouteKey

      AVAudioSessionRouteChangePreviousRouteKey

      An AVAudioSessionRouteDescription object describing audio route settings from before the route change.

      Available in iOS 6.0 and later.

    • AVAudioSessionSilenceSecondaryAudioHintTypeKey

      AVAudioSessionSilenceSecondaryAudioHintTypeKey

      An AVAudioSessionRouteDescription object describing secondary audio hints. See AVAudioSessionSilenceSecondaryAudioHintType for supported values.

      Available in iOS 8.0 and later.

  • Constants that indicate the state of the audio session following an interruption.

    Use the constants in “AVAudioSessionInterruptionOptions” instead.

    Declaration

    Swift

    var AVAudioSessionInterruptionFlags_ShouldResume: Int { get }

    Objective-C

    enum { AVAudioSessionInterruptionFlags_ShouldResume = 1 };

    Constants

    • AVAudioSessionInterruptionFlags_ShouldResume

      AVAudioSessionInterruptionFlags_ShouldResume

      Indicates that your audio session is active and immediately ready to be used. Your app can resume the audio operation that was interrupted.

      Use AVAudioSessionInterruptionOptionShouldResume instead.

      Look for this flag in the flags parameter when your audio session delegate’s endInterruptionWithFlags: method is invoked.

      Available in iOS 4.0 and later.

      Deprecated in iOS 6.0.

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

    Use the constants in “AVAudioSessionSetActiveOptions” instead.

    Declaration

    Swift

    var AVAudioSessionSetActiveFlags_NotifyOthersOnDeactivation: Int { get }

    Objective-C

    enum { AVAudioSessionSetActiveFlags_NotifyOthersOnDeactivation = 1 };

    Constants

    • AVAudioSessionSetActiveFlags_NotifyOthersOnDeactivation

      AVAudioSessionSetActiveFlags_NotifyOthersOnDeactivation

      When passed in the flags parameter of the setActive:withFlags:error: instance method, indicates that when your audio session deactivates, other audio sessions that had been interrupted by your session can return to their active state.

      Use AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation instead.

      This flag is used only when deactivating your audio session; that is, when you pass a value of NOfalse in the beActive parameter of the setActive:withFlags:error: instance method.

      Available in iOS 4.0 and later.

      Deprecated in iOS 6.0.

  • Error codes used in NSError objects returned by AVAudioSession methods.

    Declaration

    Swift

    enum AVAudioSessionErrorCode : Int { case CodeNone case CodeMediaServicesFailed case CodeIsBusy case CodeIncompatibleCategory case CodeCannotInterruptOthers case CodeMissingEntitlement case CodeSiriIsRecording case CodeCannotStartPlaying case CodeCannotStartRecording case CodeBadParam case InsufficientPriority case CodeUnspecified }

    Objective-C

    enum { AVAudioSessionErrorCodeNone = 0, AVAudioSessionErrorCodeMediaServicesFailed = 'msrv', AVAudioSessionErrorCodeIsBusy = '!act', AVAudioSessionErrorCodeIncompatibleCategory = '!cat', AVAudioSessionErrorCodeCannotInterruptOthers = '!int', AVAudioSessionErrorCodeMissingEntitlement = 'ent?', AVAudioSessionErrorCodeSiriIsRecording = 'siri', AVAudioSessionErrorCodeCannotStartPlaying = '!pla', AVAudioSessionErrorCodeCannotStartRecording = '!rec', AVAudioSessionErrorCodeBadParam = -50, AVAudioSessionErrorInsufficientPriority = '!pri', AVAudioSessionErrorCodeUnspecified = 'what' }; typedef NSInteger AVAudioSessionErrorCode;

    Constants

    • CodeNone

      AVAudioSessionErrorCodeNone

      The operation succeeded.

      Available in iOS 7.0 and later.

    • CodeMediaServicesFailed

      AVAudioSessionErrorCodeMediaServicesFailed

      An attempt was made to use the audio session during or after a Media Services failure.

      See “Media Services Availability” for more information.

      Available in iOS 7.0 and later.

    • CodeIsBusy

      AVAudioSessionErrorCodeIsBusy

      An attempt was made to set its audio session inactive, but it is still actively playing and/or recording.

      Available in iOS 7.0 and later.

    • CodeIncompatibleCategory

      AVAudioSessionErrorCodeIncompatibleCategory

      An attempt was made to perform an operation not permitted in its current category.

      For example, this error type can occur if you call setPreferredInputNumberOfChannels:error: while the session’s category is set to AVAudioSessionCategoryPlayback.

      Available in iOS 7.0 and later.

    • CodeCannotInterruptOthers

      AVAudioSessionErrorCodeCannotInterruptOthers

      An attempt was made to make a nonmixable audio session active while the app was in the background.

      Available in iOS 7.0 and later.

    • CodeMissingEntitlement

      AVAudioSessionErrorCodeMissingEntitlement

      An attempt was made to perform an operation for which the app does not have the required entitlements.

      Available in iOS 7.0 and later.

    • CodeSiriIsRecording

      AVAudioSessionErrorCodeSiriIsRecording

      An attempt was made to perform an operation that is not allowed while Siri is recording.

      Available in iOS 7.0 and later.

    • CodeCannotStartPlaying

      AVAudioSessionErrorCodeCannotStartPlaying

      An attempt was made to start audio playback, but playback is not allowed.

      This error type can occur if the app’s Information property list does not permit audio use, or if the app is in the background and using a category which does not allow background audio.

      Available in iOS 7.0 and later.

    • CodeCannotStartRecording

      AVAudioSessionErrorCodeCannotStartRecording

      An attempt was made to start audio recording, but failed.

      This error type usually because it is starting a mixable recording from the background and is not an Inter-App Audio app.

      Available in iOS 7.0 and later.

    • CodeBadParam

      AVAudioSessionErrorCodeBadParam

      An attempt was made to set a property to an illegal value.

      Available in iOS 7.0 and later.

    • InsufficientPriority

      AVAudioSessionErrorInsufficientPriority

      The application was not allowed to set the audio category because it is in use by another application.

      Available in iOS 7.0 and later.

    • CodeUnspecified

      AVAudioSessionErrorCodeUnspecified

      No further error information is available. This error type typically results when the audio system is in an inconsistent state.

      Available in iOS 7.0 and later.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

  • The values that define port types that refer to either input or output.

    Declaration

    Swift

    let AVAudioSessionPortBluetoothHFP: NSString! let AVAudioSessionPortUSBAudio: NSString! let AVAudioSessionPortCarAudio: NSString!

    Objective-C

    NSString *const AVAudioSessionPortBluetoothHFP; NSString *const AVAudioSessionPortUSBAudio; NSString *const AVAudioSessionPortCarAudio;

    Constants

    • AVAudioSessionPortBluetoothHFP

      AVAudioSessionPortBluetoothHFP

      Input or output on a Bluetooth Hands-Free Profile device.

      Available in iOS 6.0 and later.

    • AVAudioSessionPortUSBAudio

      AVAudioSessionPortUSBAudio

      Input or output on a Universal Serial Bus device.

      Available in iOS 6.0 and later.

    • AVAudioSessionPortCarAudio

      AVAudioSessionPortCarAudio

      Input or output via Car Audio.

      Available in iOS 7.0 and later.

  • The values that define the current state of the record permission request.

    Declaration

    Swift

    struct AVAudioSessionRecordPermission : RawOptionSetType { init(_ rawValue: UInt) init(rawValue rawValue: UInt) static var Undetermined: AVAudioSessionRecordPermission { get } static var Denied: AVAudioSessionRecordPermission { get } static var Granted: AVAudioSessionRecordPermission { get } }

    Objective-C

    enum { AVAudioSessionRecordPermissionUndetermined = 'undt', AVAudioSessionRecordPermissionDenied = 'deny', AVAudioSessionRecordPermissionGranted = 'grnt' }; typedef NSUInteger AVAudioSessionRecordPermission;

    Constants

    • Undetermined

      AVAudioSessionRecordPermissionUndetermined

      Recording permission has not been granted or denied. This typically means that permission has yet to be requested, or is in the process of being requested.

      Available in iOS 8.0 and later.

    • Denied

      AVAudioSessionRecordPermissionDenied

      Recording permission has been denied.

      Available in iOS 8.0 and later.

    • Granted

      AVAudioSessionRecordPermissionGranted

      Recording permission has been granted.

      Available in iOS 8.0 and later.

    Discussion

    These values are returned by the recordPermission method.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 8.0 and later.

  • These constants are returned by AVAudioSessionSilenceSecondaryAudioHintType to indicate whether optional secondary audio muting should begin or end

    Declaration

    Swift

    enum AVAudioSessionSilenceSecondaryAudioHintType : UInt { case Begin case End }

    Objective-C

    enum { AVAudioSessionSilenceSecondaryAudioHintTypeBegin = 1, AVAudioSessionSilenceSecondaryAudioHintTypeEnd = 0 }; typedef NSUInteger AVAudioSessionSilenceSecondaryAudioHintType;

    Constants

    • Begin

      AVAudioSessionSilenceSecondaryAudioHintTypeBegin

      The system is indicating that another application's primary audio has started.

      Available in iOS 8.0 and later.

    • End

      AVAudioSessionSilenceSecondaryAudioHintTypeEnd

      The system is indicating that another application's primary audio has stopped.

      Available in iOS 8.0 and later.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 8.0 and later.