Contents

AVAudioSession

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

Declaration

class AVAudioSession

Mentioned in

Overview

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

All iOS, tvOS, and watchOS apps have a default audio session that comes preconfigured with the following behavior:

  • It supports audio playback, but disallows audio recording.

  • When the app plays audio, it silences any other background audio.

  • In iOS, setting the Ring/Silent switch to silent mode silences any audio the app is playing.

  • In iOS, locking a device silences the app’s audio.

Although the default audio session provides useful behavior, it generally doesn’t provide the audio behavior a media app needs. To change the default behavior, you configure your app’s audio session category.

There are six possible categories you can use, but playback is the one that playback apps most commonly use. This category indicates that audio playback is a central feature of your app. When you specify this category, your app’s audio continues with the Ring/Silent switch set to silent mode (iOS only). Using this category, you can also play background audio if you’re using the Audio, AirPlay, and Picture in Picture background mode. For more information, see Enabling Background Audio.

You use an AVAudioSession object to configure your app’s audio session. This class is a singleton object used to set the audio session’s category, mode, and other configurations. You can interact with the audio session throughout your app’s life cycle, but it’s often useful to perform this configuration at app launch, as shown in the following example.

func configureAudioSession() {
    // Retrieve the shared audio session.
    let audioSession = AVAudioSession.sharedInstance()
    do {
        // Set the audio session category and mode.
        try audioSession.setCategory(.playback, mode: .moviePlayback)
    } catch {
        print("Failed to set the audio session configuration")
    }
}

The audio session uses this configuration when you activate the session using the setActive:error: or setActive(_:options:) method.

Topics

Accessing the shared audio session

Configuring standard audio behaviors

Configuring the spatial experience in visionOS

Activating the audio configuration

Inspecting the category configuration

Inspecting mode configuration

Inspecting rendering mode and capabilities

Inspecting the route sharing policy

Mixing with other audio

Managing audio routing

Preparing for long-form video playback

Handling interruptions

Monitoring spatial capabilities

Inspecting the audio prompt style

Enabling stereo recording

Enabling adding audio to calls

Configuring echo cancellation

Configuring audio muting

Configuring device settings

Setting the aggregated I/O preference

Handling a change of media services

Errors

Deprecated

Structures

Enumerations

See Also

System audio