---
title: "duckOthers: lowering the user's music for a workout cue, then giving it back"
canonical: "https://aifitnessapi.com/audio-coaching/avaudiosession-duckothers-workout-cues"
cluster: "Audio Coaching"
primary_query: "avaudiosession duckothers"
last_reviewed: "2026-10-03"
description: "duckOthers works only with playback, playAndRecord or multiRoute, lasts while your session is active, and Apple says use it for a few seconds at most."
publisher: "AIFitnessAPI — independent, not sponsored"
cite_as: "\"duckOthers: lowering the user's music for a workout cue, then giving it back\", AIFitnessAPI, https://aifitnessapi.com/audio-coaching/avaudiosession-duckothers-workout-cues"
---

# duckOthers: lowering the user's music for a workout cue, then giving it back

> duckOthers is the AVAudioSession category option that, in Apple's words, reduces the volume of other audio sessions while audio from your session plays. Apple documents that it can be set only with the playAndRecord, playback or multiRoute category, that ducking begins when you activate your session and ends when you deactivate it, and that it should be used on a temporary basis only, never to duck other apps for more than a few seconds. For an exercise app Apple says to also set interruptSpokenAudioAndMixWithOthers, which pauses podcast-style spoken audio instead of talking over it. So activate the session immediately before each cue and deactivate it with notifyOthersOnDeactivation once the cue has finished, which lets the music return to full volume and a paused podcast resume.

- Canonical: https://aifitnessapi.com/audio-coaching/avaudiosession-duckothers-workout-cues
- Last reviewed: 2026-10-03
- Publisher: AIFitnessAPI (https://aifitnessapi.com) — independent, not sponsored
- Cite as: "duckOthers: lowering the user's music for a workout cue, then giving it back", AIFitnessAPI, https://aifitnessapi.com/audio-coaching/avaudiosession-duckothers-workout-cues

---

"Duck, don't stop" is the requirement every workout app writes down. On iOS it is one option, `duckOthers`, plus a rule about timing that the option's name does not mention and most first implementations break: the ducking lasts exactly as long as your audio session is active. Activate at workout start and the user's music sits at reduced volume for forty minutes.

This page assumes the session is already in the `playback` category; choosing it is [the category page](/audio-coaching/avaudiosession-category-workout-app). The Android equivalent is [AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK](/audio-coaching/android-audio-focus-may-duck).

## What Apple says duckOthers does

Apple's [`duckOthers`](https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions-swift.struct/duckothers) page, in full on the parts that matter:

- "An option that reduces the volume of other audio sessions while audio from this session plays."
- "You can set this option only if the audio session category is playAndRecord, playback, or multiRoute. Setting it implicitly sets the mixWithOthers option."
- "If your app provides occasional spoken audio, such as in a turn-by-turn navigation app or an exercise app, you should also set the interruptSpokenAudioAndMixWithOthers option."
- "Ducking begins when you activate your app's audio session and ends when you deactivate the session. If you clear this option, activating your session interrupts other audio sessions."
- Marked important: "Set this option on a temporary basis only. Don't use it to duck the audio of other apps for more than a few seconds."

Apple names exercise apps by type. That makes this one of the few places where a platform vendor tells a fitness developer exactly which options to set.

## The rule that shapes your architecture

The fourth bullet is the one that matters. Ducking is not tied to your sound playing; it is tied to your session being active. So the unit you manage is the activation window, and the window should wrap the cue and nothing else.

```swift
let session = AVAudioSession.sharedInstance()

// Once, at workout start. Do not activate yet.
try session.setCategory(.playback,
                        mode: .voicePrompt,
                        options: [.duckOthers, .interruptSpokenAudioAndMixWithOthers])

// Immediately before each cue.
try session.setActive(true)
// ... play the cue ...

// After the cue has finished playing.
try session.setActive(false, options: .notifyOthersOnDeactivation)
```

Three timing mistakes produce three different symptoms:

| What the code does | What the user hears | Why |
| --- | --- | --- |
| Activates once at workout start | Music quiet for the whole workout | Ducking begins at activation and ends at deactivation |
| Deactivates before the cue finishes | The end of the cue cut off | Apple: deactivating with running audio objects stops the objects |
| Never deactivates | Music stays quiet after the last cue | Nothing ended the ducking |

The second row comes from Apple's [`setActive(_:options:)`](https://developer.apple.com/documentation/avfaudio/avaudiosession/setactive(_:options:)) page: "Deactivating an audio session with running audio objects stops the objects, makes the session inactive, and returns an AVAudioSession.ErrorCode.isBusy error." The session does go inactive, so the music comes back, but your cue is truncated and you get an error that looks like a failure to deactivate. Deactivate from the player's or synthesizer's completion callback, not from a timer you hope is long enough.

## Music is ducked; podcasts are paused

`duckOthers` alone talks over whatever is playing. That works for music. Over a podcast or an audiobook it produces two voices at once, which is why Apple pairs it with a second option.

Apple's [`interruptSpokenAudioAndMixWithOthers`](https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions-swift.struct/interruptspokenaudioandmixwithothers) page: "the system mixes your audio with other audio sessions, but interrupts (and stops) audio sessions that use the spokenAudio audio session mode. It pauses the audio from other apps as long as your session is active. After your audio session deactivates, the system resumes the interrupted app's audio." And: "Set this option if your app's audio is occasional and spoken, such as in a turn-by-turn navigation app or an exercise app. This avoids intelligibility problems when two spoken audio apps mix. If you set this option, also set the duckOthers option unless you have a specific reason not to."

| What the user is playing | `duckOthers` only | `duckOthers` + `interruptSpokenAudioAndMixWithOthers` |
| --- | --- | --- |
| Music | Lowered while your session is active | Lowered while your session is active |
| A podcast app using the spokenAudio mode | Lowered; two voices at once | Paused while your session is active, resumed after you deactivate with notification |
| Nothing | Your cue plays | Your cue plays |

The middle-right cell depends on the podcast app having declared [`spokenAudio`](https://developer.apple.com/documentation/avfaudio/avaudiosession/mode-swift.struct/spokenaudio), which Apple describes as indicating the app "should pause, rather than duck, its audio if another app plays a spoken audio prompt." You cannot control what other apps declare, so test against the podcast apps your users actually run.

## notifyOthersOnDeactivation: the podcast that never comes back

The paused podcast resumes only if you tell the system you are done. Apple's option page says so directly: "When you configure your audio session category using this option, notify other apps on the system when you deactivate your session so that they can resume audio playback. To do so, deactivate your session using the notifyOthersOnDeactivation option."

[`notifyOthersOnDeactivation`](https://developer.apple.com/documentation/avfaudio/avaudiosession/setactiveoptions/notifyothersondeactivation) "indicates that when your audio session deactivates, other audio sessions that had been interrupted by your session can return to their active state," and Apple adds: "Only use this option when deactivating your audio session." Apple's [Playing audio guidelines](https://developer.apple.com/design/human-interface-guidelines/playing-audio) make it a design rule: "If your app can temporarily interrupt the audio of other apps, be sure to flag your audio session in a way that lets other apps know when they can resume."

If users report that their podcast stops at the first cue and stays stopped, look for a `setActive(false)` without this option.

## How long is a few seconds

Apple writes "more than a few seconds" and gives no number, so neither do we. What follows is our judgement about applying it to coaching:

- A single cue ("rest, thirty seconds", "last rep") is one window.
- A countdown ("three, two, one, go") is one window, not four. Re-activating for every word ducks and un-ducks the music in a stutter, and each activation is another chance to fail.
- A long explanation of the next exercise is not a cue. If it runs for more than a sentence or two, it belongs in a guided-session flow where pausing the user's music, with their consent, is the honest behaviour, rather than holding a duck past what Apple calls temporary.

## When activation fails

Activation can fail, and a cue path that assumes it cannot will hang. Apple's `setActive(_:options:)` page: "The session fails to activate if another audio session has higher priority than yours (such as a phone call) and neither audio session allows mixing." A ducking session is mixable, because `duckOthers` sets `mixWithOthers`, but the call can still throw, and during a call or Siri you probably should not speak anyway; [promptStyle](/audio-coaching/avspeechsynthesizer-workout-cues) is the documented signal for that. Our judgement: when activation throws, skip the spoken cue, fire the haptic, keep the workout clock running, and log it.

## Monday morning

Search the codebase for `setActive(true)`. Every call should sit immediately before a cue, and every cue should end in `setActive(false, options: .notifyOthersOnDeactivation)` called from a completion callback. Add `interruptSpokenAudioAndMixWithOthers` next to `duckOthers`. Then run one interval with music playing and one with a podcast playing, and listen for whether each comes back.

## Sources

- [developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions-swift.struct/duckothers](https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions-swift.struct/duckothers) — categories allowed, implicit mixWithOthers, activation window, few seconds (checked 2026-10-03)
- [developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions-swift.struct/interruptspokenaudioandmixwithothers](https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions-swift.struct/interruptspokenaudioandmixwithothers) — pausing spokenAudio sessions; exercise apps; notify on deactivation (checked 2026-10-03)
- [developer.apple.com/documentation/avfaudio/avaudiosession/setactiveoptions/notifyothersondeactivation](https://developer.apple.com/documentation/avfaudio/avaudiosession/setactiveoptions/notifyothersondeactivation) — letting interrupted sessions return (checked 2026-10-03)
- [developer.apple.com/documentation/avfaudio/avaudiosession/setactive(_:options:)](https://developer.apple.com/documentation/avfaudio/avaudiosession/setactive%28_:options:%29) — isBusy on deactivation with running audio objects; activation failure (checked 2026-10-03)
- [developer.apple.com/design/human-interface-guidelines/playing-audio](https://developer.apple.com/design/human-interface-guidelines/playing-audio) — let other apps know when temporary audio finishes (checked 2026-10-03)

## FAQ

### Why does the user's music stay quiet after my workout cue finishes?

Because your audio session is still active. Apple documents that duckOthers ducking begins when you activate your session and ends when you deactivate it, so the volume comes back only when you call setActive with false. Apps that activate the session once at workout start keep the music ducked for the whole workout. Apps that never deactivate keep it ducked after the last cue. Deactivate from the cue's completion callback, using the notifyOthersOnDeactivation option so that any other app you interrupted is told it can resume.

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

### Can I keep duckOthers active for a whole workout?

Apple says not to. The duckOthers documentation marks it as important to set the option on a temporary basis only and not to use it to duck the audio of other apps for more than a few seconds. Because ducking lasts exactly as long as your session is active, the practical pattern is to activate right before a cue and deactivate right after it. Apple gives no number for a few seconds, and neither do we. Our rule is that one cue, or one countdown, is one activation window.

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

### What does interruptSpokenAudioAndMixWithOthers do to a podcast the user is playing?

It pauses it while your cue plays, then lets it resume. Apple documents that with this option the system mixes your audio with other sessions but interrupts and stops sessions that use the spokenAudio mode, pausing them as long as your session is active, and resuming the interrupted app's audio after your session deactivates. Apple tells apps using it to deactivate with notifyOthersOnDeactivation so other apps can resume, and recommends setting duckOthers alongside it, since ducking is appropriate when the other audio is not spoken.

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

### Why does deactivating my audio session return an isBusy error?

Because audio was still playing when you deactivated. Apple's setActive(_:options:) documentation says deactivating a session with running audio objects stops the objects, makes the session inactive, and returns AVAudioSession.ErrorCode.isBusy. The session does deactivate, so the other app's music comes back, but your cue is cut off. Deactivate from the player's or speech synthesizer's completion callback instead of from a timer that guesses how long the cue lasts.

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