Manage audio focus

Two or more Android apps can play audio to the same output stream simultaneously, and the system mixes everything together. While this is technically impressive, it can be very aggravating to a user. 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.

When your app needs to output audio, it should request audio focus. When it has focus, it can play sound. However, after you acquire audio focus you may not be able to keep it until you’re done playing. Another app can request focus, which preempts your hold on audio focus. If that happens, your app should pause playing or lower its volume to let users hear the new audio source more easily.

Before Android 12 (API level 31), audio focus is not managed by the system. So, while app developers are encouraged to comply with the audio focus guidelines, if an app continues to play loudly even after losing audio focus on a device running Android 11 (API level 30) or lower, the system can't prevent it. However, this app behavior leads to a bad user experience and can often lead users to uninstall the misbehaving app.

A well-designed audio app should manage audio focus according to these general guidelines:

  • Call requestAudioFocus() immediately before starting to play and verify that the call returns AUDIOFOCUS_REQUEST_GRANTED. Make the call to requestAudioFocus() in the onPlay() callback of your media session.

  • When another app gains audio focus, stop or pause playing, or duck (that is, reduce) the volume.

  • When playback stops (for example, when the app has nothing left to play), abandon audio focus. Your app doesn't have to abandon audio focus if the user pauses playback but might resume playback later.

  • Use AudioAttributes to describe the type of audio your app is playing. For example, for apps that play speech, specify CONTENT_TYPE_SPEECH.

Audio focus is handled differently depending on the version of Android that is running:

Android 12 (API level 31) or later
Audio focus is managed by the system. The system forces audio playback from an app to fade out when another app requests audio focus. The system also mutes audio playback when an incoming call is received.
Android 8.0 (API level 26) through Android 11 (API level 30)
Audio focus is not managed by the system, but includes some changes that were introduced starting in Android 8.0 (API level 26).
Android 7.1 (API level 25) and lower
Audio focus is not managed by the system, and apps manage audio focus using the requestAudioFocus() and abandonAudioFocus().

Audio focus in Android 12 and higher

A media or game app that uses audio focus shouldn't play audio after it loses focus. In Android 12 (API level 31) and higher, the system enforces this behavior. When an app requests audio focus while another app has the focus and is playing, the system forces the playing app to fade out. The addition of the fade-out provides a smoother transition when going from one app to another.

This fade out behavior happens when the following conditions are met:

  1. The first, currently playing app meets all of these criteria:

  2. A second app requests audio focus with AudioManager.AUDIOFOCUS_GAIN.

When these conditions are met, 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.

Existing audio focus behaviors

You should also be aware of these other cases that involve a switch in audio focus.

Automatic ducking

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.

Automatic ducking also occurs when an audio notification grabs the focus from a playing app. The start of the notification playback is synchronized with the end of the ducking ramp.

Automatic ducking happens when the following conditions are met:

  1. The first, currently-playing app meets all of these criteria:

  2. A second app requests audio focus with AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK.

When these conditions are met, 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.

Note that automatic ducking is not performed when the user is listening to speech content, because the user might miss some of the program. For example, voice guidance for driving directions are not ducked.

Mute current audio playback for incoming phone calls

Some apps don't behave properly and continue playing audio during phone calls. This situation forces the user to find and mute or quit the offending app in order to hear their call. To prevent this, the system can mute audio from other apps while there is an incoming call. The system invokes this feature when an a incoming phone call is received and an app meets these conditions:

  • The app has either the AudioAttributes.USAGE_MEDIA or AudioAttributes.USAGE_GAME usage attribute.
  • The app successfully requested audio focus (any focus gain) and is playing audio.

If an app continues playing during the call, its playback is muted until the call ends. However, if an app starts playing during the call, that player is not muted on the assumption that the user started playback intentionally.

Audio focus in Android 8.0 through Android 11

Beginning with Android 8.0 (API level 26), when you call requestAudioFocus() you must supply an AudioFocusRequest parameter. The AudioFocusRequest contains information about the audio context and capabilities of your app. The system uses this information to manage the gain and loss of audio focus automatically. To release audio focus, call the method abandonAudioFocusRequest() which also takes an AudioFocusRequest as its argument. Use the same AudioFocusRequest instance both when you request and abandon focus.

To create an AudioFocusRequest, use an AudioFocusRequest.Builder. Since a focus request must always specify the type of the request, the type is included in the constructor for the builder. Use the builder's methods to set the other fields of the request.

The FocusGain field is required; all the other fields are optional.

MethodNotes
setFocusGain() This field is required in every request. It takes the same values as the durationHint used in the pre-Android 8.0 call to requestAudioFocus(): AUDIOFOCUS_GAIN, AUDIOFOCUS_GAIN_TRANSIENT, AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK, or AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE.