Audio Session — what it is, categories and configuration in iOS

What is Audio Session?

Audio Session is a single AVAudioSession instance created by the system when an app launches and exists throughout its entire lifecycle. It acts as an intermediary between the app and the iOS audio system: the category configuration determines whether the app is allowed to play sound in the background, whether sound will be muted during a call, and which devices to output audio to.

Unlike Android Audio Focus, where each app independently requests and releases focus, iOS Audio Session is centrally managed through one session per app. When a session is activated, the system automatically deactivates the previous app’s session, sending it an interruption notification. This architectural difference defines the different approaches to audio handling on the two platforms.

According to WWDC 2024 Session 211, about 40% of audio problems in iOS apps are caused by incorrect Audio Session configuration. The most common mistake is choosing the ambient category instead of playback, which causes sound to disappear when the screen is locked.

How AVAudioSession Works

When launched, an app gets the sharedInstance of the session, sets the category via the setCategory(_:mode:options:) call, and activates the session through setActive(true). After activation, iOS considers the category policies for routing. If another app activates its session, the current one receives an AudioSessionInterruptionType.began notification through Notification.Name.AVAudioSessionInterruption.

Audio Session Categories

The category is the main parameter of Audio Session, defining six predefined behavior options. Choosing a category is the first and most important decision when setting up audio in iOS.

Playback Category — the Main Choice for Players

For music and video players, always use playback. This category allows: playing sound with the screen locked, with the mute switch turned off (physical button on the iPhone case), and when the app is in the background. Without the playback category, the session is deactivated when the screen locks or the app is minimized.

The ambient category is suitable for games and apps with background sounds — it allows other apps to continue playing. For example, if a user is listening to music and opens a game with an ambient session, the music continues to play over the game sounds. This is a fundamental difference from Android, where such a scenario requires explicit duck permission.

How to Set Up Audio Session

Audio Session configuration should be done before any playback begins. It is recommended to configure the session in the application(_:didFinishLaunchingWithOptions:) method or in the player’s initializer. After setting the category, the session must be activated.

Basic Audio Session Setup in Swift

import AVFAudio

let session = AVAudioSession.sharedInstance

do {
    try session.setCategory(
        playback,
        mode: default,
        options: [allowBluetooth, defaultToSpeaker]
    )
    try session.setActive(true)
} catch {
    print("Audio Session setup failed: \(error.localizedDescription)")
}

The options parameter includes allowBluetooth (output to Bluetooth headset) and defaultToSpeaker (playback through the speaker rather than the earpiece). The allowBluetooth option is required for apps that support Bluetooth headphones — without it, sound may be routed to the built-in speaker even when a headset is connected.

Configuration for Recording and Playback (VoIP)

let session = AVAudioSession.sharedInstance
try session.setCategory(
    playAndRecord,
    mode: voiceChat,
    options: [allowBluetooth, allowBluetoothA2DP]
)

try session.overrideOutputAudioPort(speaker)
try session.setActive(true)

The playAndRecord category with voiceChat mode optimizes the audio path for voice communication: enables echo cancellation, automatic gain control (AGC), and selects the optimal codec. OverrideOutputAudioPort(.speaker) forces output through the speaker even when a headset is connected — useful for speakerphone.

Session Activation and Deactivation

Calling setActive(true) activates the session and notifies the system that the app will use audio. When playback is paused, it is recommended to deactivate the session so that other apps can get the audio stream. The exception is apps with long-term background playback (music, podcasts), where the session remains active throughout the entire track.

It is important to handle errors when calling setActive. If another session with high priority is active (for example, Phone during a call), setActive may throw an error. In this case, you need to wait for the AudioSessionInterruptionType.ended notification and retry activation.

Audio Session Modes and Policies

Mode refines the category and optimizes the audio path for a specific use case. Each mode changes the behavior of AGC, echo cancellation, and codecs. Modes do not replace the category but complement it — one category can work with different modes.

• default — standard mode for music and video. AGC is off, echo cancellation is minimal.
• voiceChat — optimization for VoIP. Enables echo cancellation, AGC, noise suppression. Use with the playAndRecord category.
• videoRecording — for video recording. Prioritizes recording quality over playback. Use with the record or playAndRecord category.
• measurement — for audio measurements. Minimal signal processing, no AGC or echo cancellation.
• gameChat — for voice chat in games. Similar to voiceChat, but with priority for game audio.
• moviePlayback — for watching movies. Optimization for multichannel audio (5.1, 7.1) and Dolby Atmos.

Audio Session Category Options

Options provide fine-tuning of session behavior. Each option is a flag that can be combined with others in an array. For example, [.allowBluetooth, .defaultToSpeaker, .interruptSpokenAudioAndMix] allows sound output to a Bluetooth headset, uses the speaker by default, and mixes with audiobooks.

On iOS 17+, the spatialAudio option appeared, which enables personalized spatial audio for AirPods via AVAudioSessionSpatialPreferences. According to WWDC 2024, spatial audio increases user engagement in music apps by 25% in Apple’s tests.

Handling Interruptions and Calls

Interruptions are a key difference between Audio Session and Android Audio Focus. In iOS, interruptions are handled through NotificationCenter by subscribing to AVAudioSession.interruptionNotification. The notification contains a dictionary with the interruption type: began or ended.

Subscribing to Interruption Notifications

override func viewDidLoad() {
    super.viewDidLoad()
    let center = NotificationCenter.default
    center.addObserver(
        self,
        selector: #selector(handleInterruption),
        name: AVAudioSession.interruptionNotification,
        object: nil
    )
}

@objc func handleInterruption(_ notification: Notification) {
    guard let userInfo = notification.userInfo,
        let type = userInfo[AVAudioSession.interruptionTypeKey]
            as? AVAudioSessionInterruptionType
    else { return }

    switch type {
    case began:
        pausePlayback()
    case ended:
        guard let options = userInfo[AVAudioSession.interruptionOptionKey]
            as? AVAudioSessionInterruptionOptions
        else { return }

        if options.contains(shouldResume) {
            resumePlayback()
        }
    }

When interruptionType.began is received, the player should pause playback. When interruptionType.ended is received, the interruptionOptionKey property indicates whether the player can automatically resume (shouldResume). If the user declined the call, shouldResume = true. If the call ended by timeout — shouldResume = false, resumption is not allowed.

Handling Interruptions from Other Apps

When another app activates its Audio Session with the playback category, the current session receives an interruption notification. If another app uses ambient, no interruption occurs — sounds are mixed. This behavior is drastically different from Android, where any Audio Focus activation triggers a LOSS event.

For apps that need to continue playback when other sessions are activated (for example, navigation while music is playing), use the .mixWithOthers option. This option allows sound mixing with other apps, and no interruptions are sent. MixWithOthers is the iOS equivalent of the duck mode in Android.

Audio Routing and Bluetooth

Audio Session automatically manages audio routing between built-in speakers, headphones, Bluetooth headsets, and AirPlay devices. The app can monitor the current route through the currentRoute property and receive notifications about changes via AVAudioSession.routeChangeNotification.

When Bluetooth headphones are connected, iOS automatically switches the audio output to them if the session is configured with the allowBluetooth option. Without this option, sound continues through the built-in speaker. Starting with iOS 16, when AirPods Pro are connected, the system automatically enables ProMotion synchronization to reduce latency.

Monitoring Route Changes

Subscribing to routeChangeNotification allows reacting to headphone connection and disconnection. When a Bluetooth headset is disconnected, the player should pause playback — the user might not expect sound to start playing from the phone’s speaker. According to Apple HIG (2026), this is required behavior for music apps.

The availableInputs and availableOutputs properties return a list of available audio devices with their types (builtInSpeaker, headphones, bluetoothA2DP, hdmi). The developer can programmatically select a specific device through overrideOutputAudioPort for custom routing scenarios.