Every question the Audio Coaching pages answer
The 12 audio coaching pages answer 42 named questions between them. Every one is listed below, and every link lands on the paragraph that answers it rather than the top of the page.
playback or ambient: choosing the AVAudioSession category for workout cues
- 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…
- 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…
- 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…
- 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…
duckOthers: lowering the user's music for a workout cue, then giving it back
- 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…
- 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…
- 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…
- 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…
Spoken workout cues with AVSpeechSynthesizer, and when to stay quiet
- Why does my AVSpeechSynthesizer cue never play, or stop after the first word?The usual cause is that nothing is holding on to the synthesizer. Apple's AVSpeechSynthesizer documentation notes that the system doesn't…
- Should usesApplicationAudioSession be true or false for workout cues?It depends on whether speech is your only audio. Apple documents that when the property is false the system creates a separate audio…
- How do I stop a late spoken cue from playing after its moment has passed?Cancel it before speaking the new one. AVSpeechSynthesizer queues utterances and speaks them in the order received, so a long cue still…
- What should a workout app do when AVAudioSession promptStyle is none?Not prompt at all, by voice or by tone. Apple documents the none style as meaning your app shouldn't issue prompts at this time, because…
Audio interruptions during a workout on iOS: calls, Siri and the cue that never comes back
- Why does my app never get an interruption ended notification after a call?Because the end signal is not guaranteed. Apple's Handling audio interruptions article says the iOS 27 lifecycle notifications exist…
- Should a workout app automatically resume voice cues after a phone call ends?Resume the schedule, not the interrupted cue. Apple documents shouldResume as a hint that it's appropriate to resume audio playback without…
- What does AVAudioSessionInterruptionWasSuspendedKey mean in a workout app?That your process was suspended and the session was deactivated while it was asleep. Apple documents that starting in iOS 10 the system…
- Can I stop incoming calls from interrupting my app's workout audio?Partly, and only for one call style. Apple documents setPrefersNoInterruptionsFromSystemAlerts: if the user has chosen the banner style for…
Background audio for an iPhone workout app: UIBackgroundModes audio, and what it does not promise
- Do I need UIBackgroundModes audio for workout cues on iPhone?Yes, if cues must play after the app leaves the foreground. Apple's playback category page says that to continue playing audio when your…
- Will App Review accept background audio in a workout app?We cannot predict any review outcome, and this is not legal or store-policy advice. What we can quote is App Store Review Guideline 2.5.4,…
- Why does my workout cue play in testing but not when the iPhone is locked?Usually one of two switches is missing. The default and ambient categories are, per Apple, silenced by screen locking, so the session needs…
Headphones out mid-run: route changes on iOS and AUDIO_BECOMING_NOISY on Android
- Should a workout app keep speaking cues through the phone speaker after headphones disconnect?Not unless the user opted in. Apple's route-change guide frames a headphone disconnect as an implicit privacy request and says apps should…
- Which thread does AVAudioSession routeChangeNotification arrive on?A secondary thread. Apple's routeChangeNotification page states that the system posts this notification on a secondary thread, unlike the…
- What is ACTION_AUDIO_BECOMING_NOISY and when is it sent?A broadcast intent Android sends just before audio moves to the speaker. Google's AudioManager reference describes it as a hint that audio…
Android audio focus for workout cues: AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK
- Which audio focus type should a workout cue request on Android?AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK. Google's AudioManager reference describes it as a temporary request of audio focus, anticipated to last…
- Why does the user's podcast pause instead of ducking when my app speaks?Because Android deliberately does not duck speech. Google's audio focus guide says automatic ducking is not performed when the user is…
- Does my app have to lower the other app's volume itself on Android?Not on Android 8.0 and higher. Google documents automatic ducking from Android 8.0: when you request AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK,…
- Should a workout cue accept delayed audio focus gain?Our judgement is no. Google documents setAcceptsDelayedFocusGain(true) as turning a request made while focus is locked, for instance during…
AUDIOFOCUS_REQUEST_FAILED in the background on Android 15: your cue needs a foreground service
- Why does requestAudioFocus return AUDIOFOCUS_REQUEST_FAILED when my app is in the background?If your app targets Android 15 or higher, that is the documented behaviour. Google's requestAudioFocus reference says such an app cannot…
- Which foreground service type should a workout app use so its audio cues keep working?Our recommendation is health, with mediaPlayback only for apps whose product is audio playback. Google's foreground service types page…
- When should a workout app start its foreground service so background cues get audio focus?When the user starts the workout, while the app is in front, not when the screen turns off. The focus request in the background only…
TextToSpeech workout cues on Android: initialization, focus, queue and completion
- Does Android TextToSpeech duck the user's music automatically?Not as far as Google's reference says. The TextToSpeech and UtteranceProgressListener references describe initialization, queuing,…
- Should workout cues use QUEUE_FLUSH or QUEUE_ADD in TextToSpeech?QUEUE_FLUSH for anything time-critical. Google documents QUEUE_FLUSH as dropping all entries in the playback queue and replacing them with…
- Why does TextToSpeech setLanguage return LANG_MISSING_DATA?Because the voice data for that language is not on the device. Google's reference documents LANG_MISSING_DATA as the language data being…
- Why does my TextToSpeech onInit callback run before the instance is assigned?Because Google documents that it can. The TextToSpeech constructor's listener documentation says that in a case of a failure the listener…
Which AudioAttributes usage a workout coaching cue should declare
- Which AudioAttributes usage should a spoken workout cue use?There is no documented answer, so this is our judgement: USAGE_ASSISTANCE_NAVIGATION_GUIDANCE with CONTENT_TYPE_SPEECH. Google describes…
- Does CONTENT_TYPE_SPEECH stop my guided run audio from being ducked by other apps?Yes, by design. Google's audio focus guide says automatic ducking only applies when the playing app is not playing CONTENT_TYPE_SPEECH…
- What usage does an Android AudioFocusRequest use if I do not set attributes?USAGE_MEDIA. Google's audio focus guide and the AudioFocusRequest reference both say that if no attributes are set, the request uses…
Audio cues on the wrist: Wear OS speakers, Bluetooth, and Apple Watch workout sessions
- Can a Wear OS fitness app speak exercise cues through the watch's built-in speaker?Yes, Google's guide encourages it for non-media sound. The Play audio on wearables guide says that if your app offers a non-media use case…
- Can an Apple Watch workout app play audio cues in the background?Yes, while a workout session is running. Apple's Running workout sessions article says workout apps can use AVFoundation to play short…
- Why does my watchOS long-form audio session fail to activate?Most likely there is no Bluetooth route. Apple's Playing Background Audio article says watchOS requires a Bluetooth audio route for…
Testing workout audio cues: calls, Siri, Bluetooth and the podcast that never resumes
- How do I test my iOS app's response to a media services reset?Use the switch Apple documents for it. Apple's mediaServicesWereResetNotification page says you can trigger a media server reset by…
- What should I test before shipping workout audio cues on an app targeting Android 15?A cue with the screen off. Google documents that an app targeting Android 15 or higher cannot request audio focus unless it's the top app…
- Which audio events should a workout app test on a real device before release?Our list, built from what the platforms document: a full workout with the screen locked and music playing; a podcast app playing, which…
Back to the Audio Coaching hub, or see every question this site answers.