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

"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. The Android equivalent is AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK.

What Apple says duckOthers does#

Apple's 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.

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:

The second row comes from Apple's 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 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."

The middle-right cell depends on the podcast app having declared 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 "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 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 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.