Android audio focus for workout cues: AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK

Android's answer to "duck the user's music for a cue" is audio focus, and the constant that does it is AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK. Since Android 8.0 the system does the ducking for you, which is good news with conditions attached. Request the wrong focus type and the music fades out and stays muted. Forget to abandon focus and it stays ducked. And the user's podcast is deliberately excluded from automatic ducking.

This page covers the request, the release, and what happens to the app you interrupt. The background restriction added for apps targeting Android 15 is its own page; the iOS counterpart is duckOthers.

Audio focus in one paragraph#

Google's Manage audio focus guide: "To avoid every music app playing at the same time, Android introduces the idea of audio focus. Only one app can hold audio focus at a time." And: "When your app needs to output audio, it should request audio focus." The AudioFocusRequest reference adds the rule cue code most often skips: "applications should not play anything until granted focus."

The four focus types, and the one a cue wants#

Google's AudioFocusRequest reference describes all four:

The AudioManager reference describes the third as "a temporary request of audio focus, anticipated to last a short amount of time, and where it is acceptable for other audio applications to keep playing after having lowered their output level (also referred to as "ducking")." Google's examples are driving directions; a coaching cue has the same shape: short, spoken, intermittent, over music.

Request, play, abandon#

private val cueAttributes = AudioAttributes.Builder()
    .setUsage(AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE)
    .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
    .build()

private val cueFocus = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK)
    .setAudioAttributes(cueAttributes)
    .build()

fun playCue() {
    if (audioManager.requestAudioFocus(cueFocus) != AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
        haptics.cue()          // no focus, no sound
        return
    }
    player.play(cue, cueAttributes) { audioManager.abandonAudioFocusRequest(cueFocus) }
}

Three documented rules sit in those lines. Google's guide says to "Use the same AudioFocusRequest instance both when you request and abandon focus." It says to use "the same attributes in the focus request that you use in your audio player," and if you set none, "AudioAttributes defaults to AudioAttributes.USAGE_MEDIA." And abandonAudioFocusRequest "Causes the previous focus owner, if any, to receive focus," which is what brings the music back up. Which usage to pick is a judgement with real consequences, set out on the AudioAttributes page.

Automatic ducking, and its conditions#

Google's guide: "Automatic ducking (temporarily reducing the audio level of one app so that another can be heard clearly) was introduced in Android 8.0 (API level 26). By having the system implement ducking, you don't have to implement ducking in your app."

It happens when the app already playing "successfully requested audio focus with any type of focus gain," "is not playing audio with content type AudioAttributes.CONTENT_TYPE_SPEECH," and "did not set AudioFocusRequest.Builder.setWillPauseWhenDucked(true)," and a second app "requests audio focus with AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK." Then "the audio system ducks all the active players of the first app while the second app has focus. When the second app abandons focus, it unducks them. The first app is not notified when it loses focus, so it doesn't have to do anything."

How far it ducks is not stated in that guide. The AudioFocusRequest reference gives the figure for apps that duck themselves: "A typical attenuation by the "ducked" application is a factor of 0.2f (or -14dB)." That is Google's number for self-ducking apps, not a measurement of the system's behaviour, and we have not measured either.

Why the podcast pauses instead#

The CONTENT_TYPE_SPEECH condition is deliberate. Google's guide: "automatic ducking is not performed when the user is listening to speech content, because the user might miss some of the program." The AudioFocusRequest reference describes what happens instead: since "the system will not automatically duck applications that play speech, it calls their focus listener instead to notify them of AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK, so they can pause instead."

So the same cue code produces different results depending on what the user is playing: music ducks, a well-behaved podcast app pauses, then resumes when you abandon focus. This matches what Apple achieves with interruptSpokenAudioAndMixWithOthers, reached from the other side. If your own app plays long guided audio, you are the podcast in this story; mark it CONTENT_TYPE_SPEECH and handle AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK by pausing.

Never request AUDIOFOCUS_GAIN for a cue#

On Android 12 (API level 31) and higher, Google documents a forced fade-out. It happens when the playing app has USAGE_MEDIA or USAGE_GAME, "successfully requested audio focus with AudioManager.AUDIOFOCUS_GAIN," and "is not playing audio with content type AudioAttributes.CONTENT_TYPE_SPEECH," and then "A second app requests audio focus with AudioManager.AUDIOFOCUS_GAIN." Then "the audio system fades out the first app. At the end of the fade out, the system notifies the first app of focus loss. The app's players remain muted until the app requests audio focus again."

That is the bug behind "my workout app killed my music." A cue that requests AUDIOFOCUS_GAIN tells the music app it has lost focus for good, and Google's guide says an app getting AUDIOFOCUS_LOSS "should pause playback immediately, as it won't ever receive an AUDIOFOCUS_GAIN callback. To restart playback, the user must take an explicit action."

When the request fails, or is delayed#

requestAudioFocus returns AUDIOFOCUS_REQUEST_GRANTED, AUDIOFOCUS_REQUEST_FAILED or AUDIOFOCUS_REQUEST_DELAYED. Google's guide: "Sometimes the system cannot grant a request for audio focus because the focus is "locked" by another app, such as during a phone call. In this case, requestAudioFocus() returns AUDIOFOCUS_REQUEST_FAILED. When this happens, your app should not proceed with audio playback because it did not gain focus."

setAcceptsDelayedFocusGain(true) turns that into AUDIOFOCUS_REQUEST_DELAYED, with a callback once the lock clears. Google says delayed gain "only works if you also specify an AudioManager.OnAudioFocusChangeListener." Our judgement: do not accept delayed gain for a time-critical cue. "Ten seconds left" delivered after the phone call ends is wrong; skip it, fire the haptic, and let the next cue land on time.

Older Android, briefly#

Before Android 8.0 there is no AudioFocusRequest: you call requestAudioFocus with a listener, a stream such as STREAM_MUSIC, and a duration hint, and release with abandonAudioFocus. Google's guide calls ducking "particularly suitable for apps that use the audio stream intermittently, such as for audible driving directions." On Android 11 and lower the guide warns that focus "is not managed by the system," so an app that keeps playing loudly after losing focus cannot be stopped by the system. In other words, on those versions ducking depends on other apps behaving well.

If your cues play through ExoPlayer, Google's guide suggests letting it manage focus "by calling setAudioAttributes with true for the handleAudioFocus parameter." Which focus gain ExoPlayer then requests for your attributes is not stated on the pages we read, so check it before relying on it for ducking.

Monday morning#

Grep for requestAudioFocus. Every cue path should request AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK with the same attributes the player uses, play only on AUDIOFOCUS_REQUEST_GRANTED, and abandon the same request instance when playback completes. Remove any AUDIOFOCUS_GAIN from cue code. Then test against a music app and a podcast app, and on a device running Android 12 or later.