---
title: "playback or ambient: choosing the AVAudioSession category for workout cues"
canonical: "https://aifitnessapi.com/audio-coaching/avaudiosession-category-workout-app"
cluster: "Audio Coaching"
primary_query: "avaudiosession category for workout app"
last_reviewed: "2026-10-03"
description: "Apple's default session silences the user's music and goes quiet on lock. Which category and mode let a workout cue play over music with the screen off."
publisher: "AIFitnessAPI — independent, not sponsored"
cite_as: "\"playback or ambient: choosing the AVAudioSession category for workout cues\", AIFitnessAPI, https://aifitnessapi.com/audio-coaching/avaudiosession-category-workout-app"
---

# playback or ambient: choosing the AVAudioSession category for workout cues

> The audio session category decides whether a workout cue survives the screen locking and whether it stops the user's music. Apple documents that the default category, soloAmbient, silences other background audio when your app plays and is itself silenced by screen locking and the Silent switch, and that ambient mixes with other apps but is silenced the same way. The playback category keeps playing through the Silent switch and the lock, and needs the audio value in UIBackgroundModes to continue in the background, but Apple says it is nonmixable by default, so on its own it interrupts the user's music. For cues that must be heard mid-workout, that points to playback with a mixing option such as duckOthers, plus the voicePrompt mode when the cue is synthesized speech.

- Canonical: https://aifitnessapi.com/audio-coaching/avaudiosession-category-workout-app
- Last reviewed: 2026-10-03
- Publisher: AIFitnessAPI (https://aifitnessapi.com) — independent, not sponsored
- Cite as: "playback or ambient: choosing the AVAudioSession category for workout cues", AIFitnessAPI, https://aifitnessapi.com/audio-coaching/avaudiosession-category-workout-app

---

The first audio bug most workout apps ship is not in their own code. It is in the session they never configured. The cue works on a desk with the screen on, then goes silent on the first run with the phone in an armband, or it plays and the user's music stops dead. Both are the documented behaviour of the category the app is using, usually the one it got by default.

This page is about choosing that category and mode. Lowering the user's music while a cue plays is the next page, [duckOthers and notifyOthersOnDeactivation](/audio-coaching/avaudiosession-duckothers-workout-cues); keeping the app allowed to play after the screen locks is [UIBackgroundModes audio](/audio-coaching/background-audio-workout-app-ios).

## The default you are already shipping

Apple's [AVAudioSession overview](https://developer.apple.com/documentation/avfaudio/avaudiosession) lists what every iOS app gets before it touches the session. 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," and "locking a device silences the app's audio."

Read that list as a workout app. The user starts their music, starts your workout, locks the phone and puts it away. Under the default session, your first cue silences their music, and every cue after the lock is silenced. Apple's verdict on the default is polite: it "generally doesn't provide the audio behavior a media app needs."

The default has a name. Apple documents [`soloAmbient`](https://developer.apple.com/documentation/avfaudio/avaudiosession/category-swift.struct/soloambient) as "The default audio session category," whose audio "is silenced by screen locking and by the Silent switch," and which "implies that your app's audio is nonmixable—activating your session will interrupt any other audio sessions which are also nonmixable."

## The four categories a workout app considers

| Category | Apple's one-line description | Mixes with the user's music | Silent switch | Screen lock |
| --- | --- | --- | --- | --- |
| `soloAmbient` (default) | The default audio session category | No, nonmixable by default | Silences it | Silences it |
| `ambient` | Sound playback is nonprimary; the app also works with the sound turned off | Yes, other apps' audio mixes with yours | Silences it | Silences it |
| `playback` | Recorded music or other sounds that are central to the successful use of your app | No by default; add `mixWithOthers` | Keeps playing | Keeps playing, with the background mode |
| `playAndRecord` | Recording and playback, such as a VoIP app | No by default; add `mixWithOthers` | Keeps playing | Keeps playing, with the background mode |

Each cell is from Apple's category pages. [`ambient`](https://developer.apple.com/documentation/avfaudio/avaudiosession/category-swift.struct/ambient): "audio from other apps mixes with your audio. Screen locking and the Silent switch (on iPhone, the Ring/Silent switch) silence your audio." [`playback`](https://developer.apple.com/documentation/avfaudio/avaudiosession/category-swift.struct/playback): "your app audio continues with the Silent switch set to silent or when the screen locks," and "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." [`playAndRecord`](https://developer.apple.com/documentation/avfaudio/avaudiosession/category-swift.struct/playandrecord) adds that "The user must grant permission for audio recording," which is a permission prompt no cue-only app should trigger.

Apple's [Playing audio guidelines](https://developer.apple.com/design/human-interface-guidelines/playing-audio) give the same split in design terms: ambient is for when sound "isn't essential, and it doesn't silence other audio"; playback is for when sound "is essential and might mix with other audio," and it "Can play in the background."

## Why ambient is tempting and usually wrong

`ambient` looks like exactly what a polite workout app wants. It mixes with the user's music without being asked, so there is no ducking to configure and no option to get wrong. For a cue that is genuinely optional, that is a fine choice: a metronome tick while the app is open, a celebratory sound on the summary screen.

The problem is the moment the cue exists for. A rest-over cue matters most when the phone is locked in a pocket, and Apple documents that screen locking silences an `ambient` session. That is not a bug you can work around inside the category; it is the category's definition. Our judgement: if a cue has to be heard with the screen off, it cannot live in `ambient`.

## Why playback is right and has one trap

`playback` keeps going through the Silent switch and the lock, which is what a coaching cue needs. The trap is the sentence that follows on Apple's page: "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 mixWithOthers option."

So a workout app that sets `.playback` and nothing else has traded one bug for another: instead of going silent when the phone locks, it now stops the user's music every time it speaks. The fix is a category option. Apple documents three that matter here, and two of them imply the third:

- [`mixWithOthers`](https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions-swift.struct/mixwithothers): "If you set this option, your app mixes its audio with audio playing in background apps, such as the Music app." Apple notes that setting `duckOthers` or `interruptSpokenAudioAndMixWithOthers` "also enables this option."
- `duckOthers` lowers the other audio while yours plays.
- `interruptSpokenAudioAndMixWithOthers` pauses spoken audio, such as a podcast, instead of talking over it.

The last two are the subject of the [duckOthers page](/audio-coaching/avaudiosession-duckothers-workout-cues). Apple's guidelines put the principle plainly: "don't make people stop listening to music from another app if you don't need to."

## The mode: voicePrompt, not spokenAudio

The mode refines the category. Apple documents [`default`](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode-swift.struct/default) as usable "with every audio session category," and two spoken-audio modes that are easy to confuse:

- [`voicePrompt`](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode-swift.struct/voiceprompt): "A mode that indicates that your app plays audio using text-to-speech." Apple says setting it "allows for different routing behaviors when your app connects to certain audio devices, such as CarPlay," and that apps of this type "also configure their sessions to use the duckOthers and interruptSpokenAudioAndMixWithOthers options."
- [`spokenAudio`](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode-swift.struct/spokenaudio): "A mode used for continuous spoken audio to pause the audio when another app plays a short audio prompt," appropriate for "podcasts or audio books."

`spokenAudio` is the mode of the app you are interrupting, not yours. A coaching app that speaks short cues over the user's music is the "short audio prompt" in that sentence. If your app also plays long guided sessions, those are the continuous spoken audio, and the mode can differ between the two activities.

Apple scopes `voicePrompt` to text-to-speech. For cues recorded as audio files, Apple's page does not say whether the mode applies; our judgement is to use `default` for recorded clips and tones, and `voicePrompt` when the cue is synthesized speech, as on the [AVSpeechSynthesizer page](/audio-coaching/avspeechsynthesizer-workout-cues).

```swift
let session = AVAudioSession.sharedInstance()
try session.setCategory(.playback,
                        mode: .voicePrompt,
                        options: [.duckOthers, .interruptSpokenAudioAndMixWithOthers])
```

Apple's [`setCategory(_:mode:options:)`](https://developer.apple.com/documentation/avfaudio/avaudiosession/setcategory(_:mode:options:)) page says you "Typically" set the category and mode "before activating the session," and that setting them while active "results in an immediate change." Configure once, at workout start, and do not activate yet: Apple's overview notes it is "generally preferable to defer this call until your app begins audio playback," which "ensures that you won't prematurely interrupt any other background audio that may be in progress."

## Knowing whether the user already has music on

Many workout apps ship their own music bed under the coaching. When the user starts their own music, the bed should get out of the way and the cues should stay. Apple documents exactly this split for games.

[`secondaryAudioShouldBeSilencedHint`](https://developer.apple.com/documentation/avfaudio/avaudiosession/secondaryaudioshouldbesilencedhint) is "A Boolean value that indicates whether another app, with a nonmixable audio session, is playing audio," to be used "as a hint to silence audio that's secondary to the functionality of the app." Apple's example: a game "can use this property to mute the soundtrack while leaving sound effects unmuted." Swap soundtrack for music bed and sound effects for cues.

Apple steers you to it over [`isOtherAudioPlaying`](https://developer.apple.com/documentation/avfaudio/avaudiosession/isotheraudioplaying), which "returns true if any other audio is playing, including audio from an app using the ambient category." For change events, [`silenceSecondaryAudioHintNotification`](https://developer.apple.com/documentation/avfaudio/avaudiosession/silencesecondaryaudiohintnotification) is posted "when the primary audio from other apps starts and stops," but only "to registered listeners who are currently in the foreground and have an active audio session," so re-read the hint when the app returns to the foreground rather than relying on the notification alone.

## The Silent switch question

Apple's guidelines describe what silent mode means to the person who flips it: "When a device is in silent mode, it plays only the audio that people explicitly initiate, like media playback, alarms, and audio/video messaging." A `playback` session plays through the switch. Whether a workout cue counts as audio the person explicitly initiated is a product decision Apple's text does not make for you. Our judgement: starting a workout with voice cues switched on is an explicit request, and a setting that turns cues off, paired with [haptics as the fallback channel](/accessibility/haptics-when-audio-is-busy), respects the person who wants silence.

## Monday morning

Find where your app first touches `AVAudioSession`. If the answer is nowhere, you are on `soloAmbient` and every symptom above is expected. Set `.playback` with a mixing option at workout start, choose `voicePrompt` for synthesized speech and `default` for clips, defer activation until the first cue, and add the `audio` background mode. Then lock the phone with music playing and listen to one full interval.

## Sources

- [developer.apple.com/documentation/avfaudio/avaudiosession](https://developer.apple.com/documentation/avfaudio/avaudiosession) — default session behaviour; deferring activation (checked 2026-10-03)
- [developer.apple.com/documentation/avfaudio/avaudiosession/category-swift.struct/playback](https://developer.apple.com/documentation/avfaudio/avaudiosession/category-swift.struct/playback) — playback category, Silent switch, lock, UIBackgroundModes, nonmixable default (checked 2026-10-03)
- [developer.apple.com/documentation/avfaudio/avaudiosession/category-swift.struct/ambient](https://developer.apple.com/documentation/avfaudio/avaudiosession/category-swift.struct/ambient) — ambient mixes; silenced by lock and Silent switch (checked 2026-10-03)
- [developer.apple.com/documentation/avfaudio/avaudiosession/mode-swift.struct/voiceprompt](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode-swift.struct/voiceprompt) — voicePrompt mode for text-to-speech (checked 2026-10-03)
- [developer.apple.com/documentation/avfaudio/avaudiosession/secondaryaudioshouldbesilencedhint](https://developer.apple.com/documentation/avfaudio/avaudiosession/secondaryaudioshouldbesilencedhint) — hint to silence secondary audio (checked 2026-10-03)
- [developer.apple.com/design/human-interface-guidelines/playing-audio](https://developer.apple.com/design/human-interface-guidelines/playing-audio) — category table; silent mode; don't stop other music (checked 2026-10-03)

## FAQ

### Why does my workout cue go silent when the iPhone screen locks?

Because the category your app is using is silenced by the lock. Apple documents that the default category, soloAmbient, is silenced by screen locking and by the Silent switch, and the ambient category is silenced the same way. The playback category is the one Apple documents as continuing when the screen locks, and Apple's playback page adds that continuing in the background also requires the audio value in the UIBackgroundModes key of your Info.plist. Without both, a cue that works on your desk with the screen on will stop as soon as the phone goes into a pocket.

[Permalink](https://aifitnessapi.com/audio-coaching/avaudiosession-category-workout-app#faq-1)

### Does the AVAudioSession playback category stop the user's music?

It does by default. Apple's playback page says the category implies your audio is nonmixable, so activating your session interrupts any other nonmixable session, which is how most music playback is configured. To keep the music playing, add a mixing option: mixWithOthers mixes your audio with theirs, and duckOthers lowers their volume while yours plays and, per Apple, implicitly sets mixWithOthers. Apple's design guidance says not to make people stop listening to music from another app if you don't need to, and a workout cue never needs to.

[Permalink](https://aifitnessapi.com/audio-coaching/avaudiosession-category-workout-app#faq-2)

### Should a workout app use the spokenAudio mode or voicePrompt?

voicePrompt, for synthesized cues. Apple documents spokenAudio for continuous spoken audio such as podcasts or audio books, where your app should pause rather than duck when another app plays a short prompt. A coaching cue is that short prompt, not the podcast. Apple describes voicePrompt as indicating that your app plays audio using text-to-speech, and says apps of that type typically also set duckOthers and interruptSpokenAudioAndMixWithOthers. Apple scopes voicePrompt to text-to-speech, so for recorded clips and tones our choice is the default mode.

[Permalink](https://aifitnessapi.com/audio-coaching/avaudiosession-category-workout-app#faq-3)

### How can an iOS workout app tell whether the user is already playing their own music?

Read secondaryAudioShouldBeSilencedHint. Apple describes it as indicating whether another app with a nonmixable audio session is playing audio, and recommends it over isOtherAudioPlaying, which also counts audio from ambient-category apps. Apple's example is a game muting its soundtrack while keeping sound effects; for a workout app that is muting your own music bed while keeping the coaching cues. Apple's change notification for this hint is only delivered to apps in the foreground with an active session, so re-read the property when the app returns to the foreground.

[Permalink](https://aifitnessapi.com/audio-coaching/avaudiosession-category-workout-app#faq-4)