Class

AVAudioSession

An audio session communicates to the system how you intend to use audio in your app.

Overview

An audio session acts as an intermediary between your app and the operating system—and in turn, the underlying audio hardware. You use it to communicate to the operating system the nature of your app’s audio without detailing the specific behavior or required interactions with the audio hardware. This delegates the management of those details to the audio session, which ensures that the operating system can best manage the user’s audio experience.

Use this class to:

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

  • Activate your app’s audio session to put your category and mode configuration into action

  • Request user permission to record audio

  • Subscribe and respond to important audio session notifications, such as audio interruptions and route changes

  • Perform advanced audio device configuration such as setting sample rate, I/O buffer duration, and number of channels

Topics

Accessing the Audio Session

Access your app's singleton audio session instance to configure its category, mode, and preferred device settings.

class func sharedInstance()

Returns the shared audio session instance.

Configuring the Audio Session

Configure your app’s audio session by setting its category, options, and mode. Setting an audio session category lets you semantically indicate the general behavior needed by your app, such as playback or recording, but delegates the management of those behaviors to the audio session. Some categories can be further customized with the use of category options and modes, which provide more fine-grained control over the general audio behaviors provided by a particular category.

var category: String

The current audio session category.

func setCategory(String)

Sets the current audio session category.

func setCategory(String, with: AVAudioSessionCategoryOptions = [])

Sets the audio session category with the specified options.

func setCategory(String, mode: String, options: AVAudioSessionCategoryOptions = [])

Sets the audio session category, mode, and desired options.

var availableCategories: [String]

The audio session categories available on the current device.

var categoryOptions: AVAudioSessionCategoryOptions

The mask of options associated with the current audio session category.

var mode: String

The current audio session mode.

func setMode(String)

Sets the audio session mode.

var availableModes: [String]

The audio session modes available on the device.

Activating the Audio Session

Activate your audio session to puts its category and mode configuration into action. To ensure the best user experience, activate your audio session only as needed and deactivate it when you are not using audio. This is essential if you use a nonmixing audio session category.

func setActive(Bool)

Activates or deactivates your app’s audio session.

func setActive(Bool, with: AVAudioSessionSetActiveOptions = [])

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

Requesting Permission to Record

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. You can explicitly ask earlier by calling the requestRecordPermission(_:) method. Until the user grants your app permission to record, your app can record only silence.

func recordPermission()

The current recording permission status.

func requestRecordPermission(PermissionBlock)

Requests the user’s permission for audio recording.

Responding to Other Audio

Determine if other apps are playing background audio so you can decide how, or if, to play audio in your app.

var isOtherAudioPlaying: Bool

A Boolean value indicating whether another app is currently playing audio.

var secondaryAudioShouldBeSilencedHint: Bool

A Boolean value that indicates whether another application is playing audio.

Responding to Audio Session Notifications

AVAudioSession posts notifications indicating important state changes such as interruptions, route changes, and media services resets. Register to listen for these notifications prior to activating your audio session.

static let AVAudioSessionInterruption: NSNotification.Name

Posted when an audio interruption occurs.

static let AVAudioSessionRouteChange: NSNotification.Name

Posted when the system’s audio route changes.

static let AVAudioSessionSilenceSecondaryAudioHint: NSNotification.Name

Posted when the primary audio from other applications starts and stops.

Working with Audio Routes

An audio route is an electronic pathway for audio signals. Inspect the state of device audio routes and configure your preferred input and output route settings.

var currentRoute: AVAudioSessionRouteDescription

An object describing the current audio input and output route.

var isInputAvailable: Bool

A Boolean value indicating whether an audio input path is available.

var availableInputs: [AVAudioSessionPortDescription]?

An array of input ports available for routing.

var preferredInput: AVAudioSessionPortDescription?

The preferred input port for audio routing.

func setPreferredInput(AVAudioSessionPortDescription?)

Sets the preferred input port for audio routing.

var inputDataSources: [AVAudioSessionDataSourceDescription]?

An array of available data sources for the audio session’s current input port.

var inputDataSource: AVAudioSessionDataSourceDescription?

The currently selected input data source.

func setInputDataSource(AVAudioSessionDataSourceDescription?)

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

var outputDataSources: [AVAudioSessionDataSourceDescription]?

An array of available output data sources for the current audio route.

var outputDataSource: AVAudioSessionDataSourceDescription?

The currently selected output data source.

func setOutputDataSource(AVAudioSessionDataSourceDescription?)

Sets the output data source for an audio session.

func overrideOutputAudioPort(AVAudioSessionPortOverride)

Temporarily changes the current audio route.

Working with Audio Channels

Inspect and configure the number of audio input and output channels available on the current audio device.

var inputNumberOfChannels: Int

The number of audio input channels for the current route.

var maximumInputNumberOfChannels: Int

The maximum number of input channels available for the current audio route.

var preferredInputNumberOfChannels: Int

The preferred number of input channels for the current route.

func setPreferredInputNumberOfChannels(Int)

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

var outputNumberOfChannels: Int

The number of audio output channels.

var maximumOutputNumberOfChannels: Int

The maximum number of output channels available for the current audio route.

var preferredOutputNumberOfChannels: Int

The preferred number of output channels for the current route.

func setPreferredOutputNumberOfChannels(Int)

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

Working with Audio Device Settings

Inspect and configure audio device settings such as input gain, sample rate, and I/O buffer duration.

var inputGain: Float

The gain applied to inputs associated with the session.

var isInputGainSettable: Bool

A Boolean value that indicates whether the input gain can be set.

func setInputGain(Float)

Changes the input gain to the specified value.

var outputVolume: Float

The system wide output volume set by the user.

var inputLatency: TimeInterval

The latency for audio input, measured in seconds.

var outputLatency: TimeInterval

The latency for audio output, measured in seconds.

var sampleRate: Double

The current audio sample rate, in hertz.

var preferredSampleRate: Double

The preferred sample rate, in hertz.

func setPreferredSampleRate(Double)

Sets the preferred sample rate for input and output.

var ioBufferDuration: TimeInterval

The current I/O buffer duration, in seconds.

var preferredIOBufferDuration: TimeInterval

The preferred I/O buffer duration, in seconds.

func setPreferredIOBufferDuration(TimeInterval)

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

Setting the Aggregated I/O Preference

Starting with iOS 10, AVCaptureSession has changed its default audio input configuration on iPhones and iPads that support the Live Photos feature. This change allows taking a Live Photo without interrupting background audio playback. Configure your preferred audio input behavior by setting your aggregated I/O preference.

func setAggregatedIOPreference(AVAudioSessionIOType)

Sets the audio session's aggregated I/O configuration preference.

Constants

Audio Session Categories

Category identifiers for audio sessions, used to set the session's category property.

Audio Session Modes

Mode identifiers for audio sessions, used to set the session's mode property.

Audio Session Error Codes

Error codes used in NSError objects returned by AVAudioSession methods.

Interruption Flags

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

Activation Flags

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

Supporting Types

protocol AVAudioSessionDelegate

The use of this protocol is deprecated in iOS 6 and later. Instead, you should use the notifications declared in AVAudioSession.

class AVAudioSessionChannelDescription

A channel description provides descriptive information about a hardware channel on the current device.

class AVAudioSessionDataSourceDescription

A data source description defines a data source for an audio input or output, providing information such as the source’s name, location and orientation.

class AVAudioSessionPortDescription

A port description object describes a single input or output port associated with an audio route. You can use the information in this class to obtain information about the capabilities of the port and the hardware channels it supports.

class AVAudioSessionRouteDescription

A route description manages the input and output ports associated with the current audio route for a session.

Relationships

Inherits From

Conforms To