<!--
{
  "availability" : [
    "iOS: 3.0.0 -",
    "iPadOS: 3.0.0 -",
    "macCatalyst: 13.1.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "AVFAudio",
  "identifier" : "/documentation/AVFAudio/AVAudioSession",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "AVFAudio"
    ],
    "preciseIdentifier" : "c:objc(cs)AVAudioSession"
  },
  "title" : "AVAudioSession"
}
-->

# AVAudioSession

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

```
class AVAudioSession
```

## 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`](/documentation/AVFAudio/AVAudioSession/Category-swift.struct/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`](/documentation/AVFAudio/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.

```swift
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:`](/documentation/AVFAudio/AVAudioSession/setActive:error:) or [`setActive(_:options:)`](/documentation/AVFAudio/AVAudioSession/setActive(_:options:)) method.

> Note:
> You can activate the audio session at any time after setting its category, but it’s generally preferable to defer this call until your app begins audio playback. Deferring the call ensures that you won’t prematurely interrupt any other background audio that may be in progress.

## Topics

### Accessing the shared audio session

[`sharedInstance()`](/documentation/AVFAudio/AVAudioSession/sharedInstance())

Returns the shared audio session instance.

### Configuring standard audio behaviors

[`setCategory(_:mode:policy:options:)`](/documentation/AVFAudio/AVAudioSession/setCategory(_:mode:policy:options:))

Sets the session category, mode, route-sharing policy, and options.

[`setCategory(_:mode:options:)`](/documentation/AVFAudio/AVAudioSession/setCategory(_:mode:options:))

Sets the audio session’s category, mode, and options.

[`setCategory(_:options:)`](/documentation/AVFAudio/AVAudioSession/setCategory(_:options:))

Sets the audio session’s category with the specified options.

[`setCategory(_:)`](/documentation/AVFAudio/AVAudioSession/setCategory(_:))

Sets the audio session’s category.

[`setMode(_:)`](/documentation/AVFAudio/AVAudioSession/setMode(_:))

Sets the audio session’s mode.

### Configuring the spatial experience in visionOS

[`intendedSpatialExperience`](/documentation/AVFAudio/AVAudioSession/intendedSpatialExperience-1bpnq)

The spatial audio experience your app intends to provide the user.   

[`intendedSpatialExperience`](/documentation/AVFAudio/AVAudioSession/intendedSpatialExperience-qlty)

The spatial audio experience your app intends to provide the user.

[`setIntendedSpatialExperience(_:)`](/documentation/AVFAudio/AVAudioSession/setIntendedSpatialExperience(_:))

Sets the spatial audio experience your app intends to provide the user.

[`setIntendedSpatialExperience:options:error:`](/documentation/AVFAudio/AVAudioSession/setIntendedSpatialExperience:options:error:)

Sets the spatial audio experience your app intends to provide the user.

[`AVAudioSessionSpatialExperience`](/documentation/AVFAudio/AVAudioSessionSpatialExperience-c.enum)

[`AVAudioSessionSpatialExperience`](/documentation/AVFAudio/AVAudioSessionSpatialExperience-swift.protocol)

[`intendedSpatialExperienceOptions`](/documentation/AVFAudio/AVAudioSession/intendedSpatialExperienceOptions)

A dictionary of options that customize the spatial experience.

[`AVAudioSessionSpatialExperienceOption`](/documentation/AVFAudio/AVAudioSessionSpatialExperienceOption)

A type definition for a spatial experience option.

[`isNowPlayingCandidate`](/documentation/AVFAudio/AVAudioSession/isNowPlayingCandidate)

A Boolean value that indicates whether the audio session is a candidate to be the Now Playing session.

[`setIsNowPlayingCandidate(_:)`](/documentation/AVFAudio/AVAudioSession/setIsNowPlayingCandidate(_:))

Sets a Boolean value that indicates whether the audio session is a candidate to be the Now Playing session.

### Activating the audio configuration

[`setActive:error:`](/documentation/AVFAudio/AVAudioSession/setActive:error:)

Activates or deactivates your app’s audio session.

[`setActive(_:options:)`](/documentation/AVFAudio/AVAudioSession/setActive(_:options:))

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

[`activate(options:completionHandler:)`](/documentation/AVFAudio/AVAudioSession/activate(options:completionHandler:))

Activates an audio session asynchronously.

[`deactivate(options:completionHandler:)`](/documentation/AVFAudio/AVAudioSession/deactivate(options:completionHandler:))

Deactivates the audio session asynchronously.

[`AVAudioSessionActivationOptions`](/documentation/AVFAudio/AVAudioSessionActivationOptions)

Constants that describe the options to pass when activating the audio session.

[`AVAudioSessionDeactivationOptions`](/documentation/AVFAudio/AVAudioSessionDeactivationOptions)

Options for deactivating an AVAudioSession

### Observing activation lifecycle

[`didBecomeActiveNotification`](/documentation/AVFAudio/AVAudioSession/didBecomeActiveNotification)

Notification sent when the audio session becomes active.

[`didBecomeInactiveNotification`](/documentation/AVFAudio/AVAudioSession/didBecomeInactiveNotification)

Notification sent when the audio session becomes inactive.

[`resumptionRecommendationNotification`](/documentation/AVFAudio/AVAudioSession/resumptionRecommendationNotification)

Notification sent when the system provides a resumption recommendation.

[`deactivationContextKey`](/documentation/AVFAudio/AVAudioSession/deactivationContextKey)

Keys for [`didBecomeInactiveNotification`](/documentation/AVFAudio/AVAudioSession/didBecomeInactiveNotification)
Value is an [`AVAudioSession.DeactivationContext`](/documentation/AVFAudio/AVAudioSession/DeactivationContext) object describing the deactivation.

[`resumptionContextKey`](/documentation/AVFAudio/AVAudioSession/resumptionContextKey)

Keys for [`resumptionRecommendationNotification`](/documentation/AVFAudio/AVAudioSession/resumptionRecommendationNotification)
Value is an [`AVAudioSession.ResumptionContext`](/documentation/AVFAudio/AVAudioSession/ResumptionContext) describing the resumption recommendation.

[`AVAudioSession.DidBecomeActiveMessage`](/documentation/AVFAudio/AVAudioSession/DidBecomeActiveMessage)

[`AVAudioSession.DidBecomeInactiveMessage`](/documentation/AVFAudio/AVAudioSession/DidBecomeInactiveMessage)

[`AVAudioSession.ResumptionRecommendationMessage`](/documentation/AVFAudio/AVAudioSession/ResumptionRecommendationMessage)

[`AVAudioSession.DeactivationResult`](/documentation/AVFAudio/AVAudioSession/DeactivationResult)

Type-safe representation of audio session deactivation results.

[`AVAudioSession.DeactivationContext`](/documentation/AVFAudio/AVAudioSession/DeactivationContext)

An object that describes why and how the audio session deactivated.

[`AVAudioSession.DeactivationSource`](/documentation/AVFAudio/AVAudioSession/DeactivationSource)

The source of the audio session deactivation.

[`AVAudioSession.InterruptionContext`](/documentation/AVFAudio/AVAudioSession/InterruptionContext)

An object that provides context about an audio session interruption.

[`AVAudioSession.ResumptionContext`](/documentation/AVFAudio/AVAudioSession/ResumptionContext)

An object that provides context when resumption becomes available.

[`AVAudioSession.ResumptionRecommendation`](/documentation/AVFAudio/AVAudioSession/ResumptionRecommendation)

The system’s recommendation on whether to resume playback.

### Inspecting the category configuration

[`category`](/documentation/AVFAudio/AVAudioSession/category-swift.property)

The current audio session category.

[`availableCategories`](/documentation/AVFAudio/AVAudioSession/availableCategories)

The audio session categories available on the current device.

[`AVAudioSession.Category`](/documentation/AVFAudio/AVAudioSession/Category-swift.struct)

Audio session category identifiers.

[`categoryOptions`](/documentation/AVFAudio/AVAudioSession/categoryOptions-swift.property)

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

[`AVAudioSession.CategoryOptions`](/documentation/AVFAudio/AVAudioSession/CategoryOptions-swift.struct)

Constants that specify optional audio behaviors.

[`farFieldInput`](/documentation/AVFAudio/AVAudioSession/CategoryOptions-swift.struct/farFieldInput)

This option should be used if a session prefers to use FarFieldInput when available.
This option is only valid with categories that support input -
[`playAndRecord`](/documentation/AVFAudio/AVAudioSession/Category-swift.struct/playAndRecord), [`record`](/documentation/AVFAudio/AVAudioSession/Category-swift.struct/record), and `AVAudioSessionMultiRoute` with [`dualRoute`](/documentation/AVFAudio/AVAudioSession/Mode-swift.struct/dualRoute).

### Inspecting mode configuration

[`mode`](/documentation/AVFAudio/AVAudioSession/mode-swift.property)

The current audio session’s mode.

[`availableModes`](/documentation/AVFAudio/AVAudioSession/availableModes)

The audio session modes available on the device.

[`AVAudioSession.Mode`](/documentation/AVFAudio/AVAudioSession/Mode-swift.struct)

Audio session mode identifiers.

### Inspecting rendering mode and capabilities

[`renderingMode`](/documentation/AVFAudio/AVAudioSession/renderingMode-swift.property)

The current audio session’s rendering mode.

[`AVAudioSession.RenderingMode`](/documentation/AVFAudio/AVAudioSession/RenderingMode-swift.enum)

Audio session rendering mode identifiers.

[`renderingModeChangeNotification`](/documentation/AVFAudio/AVAudioSession/renderingModeChangeNotification)

A notification the system posts when the rendering mode changes.

[`supportedOutputChannelLayouts`](/documentation/AVFAudio/AVAudioSession/supportedOutputChannelLayouts)

The array of channel layouts that the current route supports.

[`renderingCapabilitiesChangeNotification`](/documentation/AVFAudio/AVAudioSession/renderingCapabilitiesChangeNotification)

A notification the system posts when the rendering capabilities change.

### Inspecting the route sharing policy

[`routeSharingPolicy`](/documentation/AVFAudio/AVAudioSession/routeSharingPolicy-swift.property)

The active route-sharing policy.

[`AVAudioSession.RouteSharingPolicy`](/documentation/AVFAudio/AVAudioSession/RouteSharingPolicy-swift.enum)

Cases that indicate the possible route-sharing policies for an audio session.

### Mixing with other audio

[`isOtherAudioPlaying`](/documentation/AVFAudio/AVAudioSession/isOtherAudioPlaying)

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

[`secondaryAudioShouldBeSilencedHint`](/documentation/AVFAudio/AVAudioSession/secondaryAudioShouldBeSilencedHint)

A Boolean value that indicates whether another app, with a nonmixable audio session, is playing audio.

[`silenceSecondaryAudioHintNotification`](/documentation/AVFAudio/AVAudioSession/silenceSecondaryAudioHintNotification)

A notification the system posts when the primary audio from other apps starts and stops.

[`allowHapticsAndSystemSoundsDuringRecording`](/documentation/AVFAudio/AVAudioSession/allowHapticsAndSystemSoundsDuringRecording)

A Boolean value that indicates whether system sounds and haptics play while recording from audio input.

[`setAllowHapticsAndSystemSoundsDuringRecording(_:)`](/documentation/AVFAudio/AVAudioSession/setAllowHapticsAndSystemSoundsDuringRecording(_:))

Sets a Boolean value that indicates whether system sounds and haptics play while recording from audio input.

### Managing audio routing

[Audio routing](/documentation/AVFAudio/audio-routing)

Inspect and configure audio routes, ports, and data sources.

### Preparing for long-form video playback

[`prepareRouteSelectionForPlayback(completionHandler:)`](/documentation/AVFAudio/AVAudioSession/prepareRouteSelectionForPlayback(completionHandler:))

Prepares the route selection for long-form video playback.

[`AVAudioSession.RouteSelection`](/documentation/AVFAudio/AVAudioSession/RouteSelection)

Constants used to define the active route selection.

  <doc://com.apple.documentation/documentation/AVKit/AVAudioSessionRouteSelection>

### Handling interruptions

[`prefersNoInterruptionsFromSystemAlerts`](/documentation/AVFAudio/AVAudioSession/prefersNoInterruptionsFromSystemAlerts)

A Boolean value that indicates a preference for not interrupting the session with system alerts.

[`setPrefersNoInterruptionsFromSystemAlerts(_:)`](/documentation/AVFAudio/AVAudioSession/setPrefersNoInterruptionsFromSystemAlerts(_:))

Sets the preference for not interrupting the audio session with system alerts.

[`prefersInterruptionOnRouteDisconnect`](/documentation/AVFAudio/AVAudioSession/prefersInterruptionOnRouteDisconnect)

A Boolean value that indicates whether the system interrupts the audio session when the active route disconnects.

[`setPrefersInterruptionOnRouteDisconnect(_:)`](/documentation/AVFAudio/AVAudioSession/setPrefersInterruptionOnRouteDisconnect(_:))

Sets a preference to interrupt the audio session when the active route disconnects.

[`interruptionNotification`](/documentation/AVFAudio/AVAudioSession/interruptionNotification)

A notification the system posts when an audio interruption occurs.

### Monitoring spatial capabilities

[`spatialPlaybackCapabilitiesChangedNotification`](/documentation/AVFAudio/AVAudioSession/spatialPlaybackCapabilitiesChangedNotification)

A notification the system posts when its spatial playback capabilities change.

### Inspecting the audio prompt style

[`promptStyle`](/documentation/AVFAudio/AVAudioSession/promptStyle-swift.property)

A hint to audio sessions that use voice prompt mode to alter the type of prompts they issue in response to other system audio, such as Siri and phone calls.

[`AVAudioSession.PromptStyle`](/documentation/AVFAudio/AVAudioSession/PromptStyle-swift.enum)

Constants that indicate the prompt style to use.

### Enabling stereo recording

[`inputOrientation`](/documentation/AVFAudio/AVAudioSession/inputOrientation)

An orientation value that dictates which directions represent left and right when capturing audio from a built-in microphone configured for stereo recording.

[`preferredInputOrientation`](/documentation/AVFAudio/AVAudioSession/preferredInputOrientation)

The audio session’s preferred stereo input orientation.

[`setPreferredInputOrientation(_:)`](/documentation/AVFAudio/AVAudioSession/setPreferredInputOrientation(_:))

Sets the audio session’s preferred stereo input orientation.

[`AVAudioSession.StereoOrientation`](/documentation/AVFAudio/AVAudioSession/StereoOrientation)

Constants that define the supported stereo orientations.

### Enabling adding audio to calls

[`isMicrophoneInjectionAvailable`](/documentation/AVFAudio/AVAudioSession/isMicrophoneInjectionAvailable)

A Boolean value that indicates whether microphone injection is available.

[`preferredMicrophoneInjectionMode`](/documentation/AVFAudio/AVAudioSession/preferredMicrophoneInjectionMode)

The preferred mode of injecting audio into another app’s input stream.

[`setPreferredMicrophoneInjectionMode(_:)`](/documentation/AVFAudio/AVAudioSession/setPreferredMicrophoneInjectionMode(_:))

Sets the preferred mode of injecting audio into another app’s input stream.

[`AVAudioSession.MicrophoneInjectionMode`](/documentation/AVFAudio/AVAudioSession/MicrophoneInjectionMode)

The modes of injecting audio into another app’s input stream.

[`microphoneInjectionCapabilitiesChangeNotification`](/documentation/AVFAudio/AVAudioSession/microphoneInjectionCapabilitiesChangeNotification)

A notification the system posts when its capability to inject audio into an input stream changes.

### Configuring echo cancellation

[`isEchoCancelledInputAvailable`](/documentation/AVFAudio/AVAudioSession/isEchoCancelledInputAvailable)

A Boolean value that indicates whether the built-in microphone and speaker route supports echo cancellation.

[`isEchoCancelledInputEnabled`](/documentation/AVFAudio/AVAudioSession/isEchoCancelledInputEnabled)

A Boolean value that indicates whether an echo-canceled input is in an enabled state.

[`setPrefersEchoCancelledInput(_:)`](/documentation/AVFAudio/AVAudioSession/setPrefersEchoCancelledInput(_:))

Sets a preference to enable echo-canceled input on supported hardware.

[`prefersEchoCancelledInput`](/documentation/AVFAudio/AVAudioSession/prefersEchoCancelledInput)

A Boolean value that indicates the audio session’s preference for using an echo-canceled input.

### Configuring audio muting

[`isOutputMuted`](/documentation/AVFAudio/AVAudioSession/isOutputMuted)

A Boolean value that indicates whether audio output is in a muted state.

[`setOutputMuted(_:)`](/documentation/AVFAudio/AVAudioSession/setOutputMuted(_:))

Sets a Boolean value to inform the system to mute the session’s output audio. The default value is false (unmuted).

[`outputMuteStateChangeNotification`](/documentation/AVFAudio/AVAudioSession/outputMuteStateChangeNotification)

Notification sent to registered listeners when session’s output mute state changes.

[`muteStateKey`](/documentation/AVFAudio/AVAudioSession/muteStateKey)

Keys for [`outputMuteStateChangeNotification`](/documentation/AVFAudio/AVAudioSession/outputMuteStateChangeNotification)
Value is `NSNumber` type with boolean value 0 for unmuted or value 1 for muted (samples zeroed out)

[`userIntentToUnmuteOutputNotification`](/documentation/AVFAudio/AVAudioSession/userIntentToUnmuteOutputNotification)

Notification sent to registered listeners when the application’s output is muted and user hints to unmute.

[`userIntentToUnmuteOutputNotification`](/documentation/AVFAudio/AVAudioSession/userIntentToUnmuteOutputNotification)

Notification sent to registered listeners when the application’s output is muted and user hints to unmute.

[`muteStateKey`](/documentation/AVFAudio/AVAudioSession/muteStateKey)

Keys for [`outputMuteStateChangeNotification`](/documentation/AVFAudio/AVAudioSession/outputMuteStateChangeNotification)
Value is `NSNumber` type with boolean value 0 for unmuted or value 1 for muted (samples zeroed out)

### Configuring device settings

[Audio hardware](/documentation/AVFAudio/audio-hardware)

Inspect and configure audio device settings including input gain, sample rate, and channel counts.

### Setting the aggregated I/O preference

[`setAggregatedIOPreference(_:)`](/documentation/AVFAudio/AVAudioSession/setAggregatedIOPreference(_:))

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

[`AVAudioSession.IOType`](/documentation/AVFAudio/AVAudioSession/IOType)

Constant values used to specify the audio session’s aggregated I/O behavior.

### Handling a change of media services

[`mediaServicesWereResetNotification`](/documentation/AVFAudio/AVAudioSession/mediaServicesWereResetNotification)

A notification the system posts when the media server restarts.

[`mediaServicesWereLostNotification`](/documentation/AVFAudio/AVAudioSession/mediaServicesWereLostNotification)

A notification the system posts when it terminates the media server.

### Errors

  <doc://com.apple.documentation/documentation/CoreAudioTypes/AVAudioSession/ErrorCode>

### Deprecated

[Deprecated Symbols](/documentation/AVFAudio/deprecated-symbols)

Review unsupported symbols and their replacements.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)