Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels) Summary: [Nested Classes](https://developer.android.com/reference/android/media/AudioFocusRequest#nestedclasses) \| [Methods](https://developer.android.com/reference/android/media/AudioFocusRequest#pubmethods) \| [Inherited Methods](https://developer.android.com/reference/android/media/AudioFocusRequest#inhmethods)

# AudioFocusRequest

*** ** * ** ***


`
public

final

class
AudioFocusRequest
`


`

extends https://developer.android.com/reference/java/lang/Object


`

`


`

|---|---|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.media.AudioFocusRequest |

<br />

*** ** * ** ***

A class to encapsulate information about an audio focus request.
An `AudioFocusRequest` instance is built by `https://developer.android.com/reference/android/media/AudioFocusRequest.Builder`, and is used to
request and abandon audio focus, respectively
with `https://developer.android.com/reference/android/media/AudioManager#requestAudioFocus(android.media.AudioFocusRequest)` and
`https://developer.android.com/reference/android/media/AudioManager#abandonAudioFocusRequest(android.media.AudioFocusRequest)`.

### What is audio focus?

Audio focus is a concept introduced in API 8. It is used to convey the fact that a user can
only focus on a single audio stream at a time, e.g. listening to music or a podcast, but not
both at the same time. In some cases, multiple audio streams can be playing at the same time,
but there is only one the user would really listen to (focus on), while the other plays in
the background. An example of this is driving directions being spoken while music plays at
a reduced volume (a.k.a. ducking).

When an application requests audio focus, it expresses its intention to "own" audio focus to
play audio. Let's review the different types of focus requests, the return value after a request,
and the responses to a loss.

Note: applications should not play anything until granted focus.

### The different types of focus requests

There are four focus request types. A successful focus request with each will yield different
behaviors by the system and the other application that previously held audio focus.

- `https://developer.android.com/reference/android/media/AudioManager#AUDIOFOCUS_GAIN` expresses the fact that your application is now the sole source of audio that the user is listening to. The duration of the audio playback is unknown, and is possibly very long: after the user finishes interacting with your application, (s)he doesn't expect another audio stream to resume. Examples of uses of this focus gain are for music playback, for a game or a video player.
- `https://developer.android.com/reference/android/media/AudioManager#AUDIOFOCUS_GAIN_TRANSIENT` is for a situation when you know your application is temporarily grabbing focus from the current owner, but the user expects playback to go back to where it was once your application no longer requires audio focus. An example is for playing an alarm, or during a VoIP call. The playback is known to be finite: the alarm will time-out or be dismissed, the VoIP call has a beginning and an end. When any of those events ends, and if the user was listening to music when it started, the user expects music to resume, but didn't wish to listen to both at the same time.
- `https://developer.android.com/reference/android/media/AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK`: this focus request type is similar to `AUDIOFOCUS_GAIN_TRANSIENT` for the temporary aspect of the focus request, but it also expresses the fact during the time you own focus, you allow another application to keep playing at a reduced volume, "ducked". Examples are when playing driving directions or notifications, it's ok for music to keep playing, but not loud enough that it would prevent the directions to be hard to understand. A typical attenuation by the "ducked" application is a factor of 0.2f (or -14dB), that can for instance be applied with `MediaPlayer.setVolume(0.2f)` when using this class for playback.
- `https://developer.android.com/reference/android/media/AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE` is also for a temporary request, but also expresses that your application expects the device to not play anything else. This is typically used if you are doing audio recording or speech recognition, and don't want for examples notifications to be played by the system during that time.

An `AudioFocusRequest` instance always contains one of the four types of requests
explained above. It is passed when building an `AudioFocusRequest` instance with its
builder in the `https://developer.android.com/reference/android/media/AudioFocusRequest.Builder` constructor
`https://developer.android.com/reference/android/media/AudioFocusRequest.Builder#Builder(int)`, or
with `https://developer.android.com/reference/android/media/AudioFocusRequest.Builder#setFocusGain(int)` after copying an existing instance with
`https://developer.android.com/reference/android/media/AudioFocusRequest.Builder#Builder(android.media.AudioFocusRequest)`.

> [!NOTE]
> **Note:** If an app targets Android 15 (API level 35) or higher, it cannot request audio focus unless it's the top app or running a foreground service. This requirement is similar to the [requirements
> for audio playback](https://developer.android.com/media/media3/session/background-playback#service-declaration). If an app requests audio focus when it does not meet these requirements, the method returns `https://developer.android.com/reference/android/media/AudioManager#AUDIOFOCUS_REQUEST_FAILED`.

### Qualifying your focus request

#### Use case requiring a focus request

Any focus request is qualified by the `https://developer.android.com/reference/android/media/AudioAttributes`
(see `https://developer.android.com/reference/android/media/AudioFocusRequest.Builder#setAudioAttributes(android.media.AudioAttributes)`) that describe the audio use case that
will follow the request (once it's successful or granted). It is recommended to use the
same `AudioAttributes` for the request as the attributes you are using for audio/media
playback.

If no attributes are set, default attributes of `https://developer.android.com/reference/android/media/AudioAttributes#USAGE_MEDIA` are used.

#### Delayed focus

Audio focus can be "locked" by the system for a number of reasons: during a phone call, when
the car to which the device is connected plays an emergency message... To support these
situations, the application can request to be notified when its request is fulfilled, by flagging
its request as accepting delayed focus, with `https://developer.android.com/reference/android/media/AudioFocusRequest.Builder#setAcceptsDelayedFocusGain(boolean)`.

If focus is requested while being locked by the system,
`https://developer.android.com/reference/android/media/AudioManager#requestAudioFocus(android.media.AudioFocusRequest)` will return
`https://developer.android.com/reference/android/media/AudioManager#AUDIOFOCUS_REQUEST_DELAYED`. When focus isn't locked anymore, the focus
listener set with `https://developer.android.com/reference/android/media/AudioFocusRequest.Builder#setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener)`
or with `https://developer.android.com/reference/android/media/AudioFocusRequest.Builder#setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener,%20android.os.Handler)` will
be called to notify the application it now owns audio focus.

#### Pausing vs ducking

When an application requested audio focus with
`https://developer.android.com/reference/android/media/AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK`, the system will duck the current focus
owner.

Note: this behavior is **new for Android O** , whereas applications targeting
SDK level up to API 25 had to implement the ducking themselves when they received a focus
loss of `https://developer.android.com/reference/android/media/AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK`.

But ducking is not always the behavior expected by the user. A typical example is when the
device plays driving directions while the user is listening to an audio book or podcast, and
expects the audio playback to pause, instead of duck, as it is hard to understand a navigation
prompt and spoken content at the same time. Therefore the system will not automatically duck
when it detects it would be ducking spoken content: such content is detected when the
`AudioAttributes` of the player are qualified by
`https://developer.android.com/reference/android/media/AudioAttributes#CONTENT_TYPE_SPEECH`. Refer for instance to
`https://developer.android.com/reference/android/media/AudioAttributes.Builder#setContentType(int)` and
`https://developer.android.com/reference/android/media/MediaPlayer#setAudioAttributes(android.media.AudioAttributes)` if you are writing a media playback
application for audio book, podcasts... Since the system will not automatically duck applications
that play speech, it calls their focus listener instead to notify them of
`https://developer.android.com/reference/android/media/AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK`, so they can pause instead. Note that
this behavior is independent of the use of `AudioFocusRequest`, but tied to the use
of `AudioAttributes`.

If your application requires pausing instead of ducking for any other reason than playing
speech, you can also declare so with `https://developer.android.com/reference/android/media/AudioFocusRequest.Builder#setWillPauseWhenDucked(boolean)`, which will
cause the system to call your focus listener instead of automatically ducking.

#### Example

The example below covers the following steps to be found in any application that would play
audio, and use audio focus. Here we play an audio book, and our application is intended to pause
rather than duck when it loses focus. These steps consist in:

- Creating `AudioAttributes` to be used for the playback and the focus request.
- Configuring and creating the `AudioFocusRequest` instance that defines the intended focus behaviors.
- Requesting audio focus and checking the return code to see if playback can happen right away, or is delayed.
- Implementing a focus change listener to respond to focus gains and losses.


```
 // initialization of the audio attributes and focus request
 mAudioManager = (AudioManager) Context.getSystemService(Context.AUDIO_SERVICE);
 mPlaybackAttributes = new AudioAttributes.Builder()
         .setUsage(AudioAttributes.USAGE_MEDIA)
         .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
         .build();
 mFocusRequest = new AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
         .setAudioAttributes(mPlaybackAttributes)
         .setAcceptsDelayedFocusGain(true)
         .setWillPauseWhenDucked(true)
         .setOnAudioFocusChangeListener(this, mMyHandler)
         .build();
 mMediaPlayer = new MediaPlayer();
 mMediaPlayer.setAudioAttributes(mPlaybackAttributes);
 final Object mFocusLock = new Object();

 boolean mPlaybackDelayed = false;

 // requesting audio focus
 int res = mAudioManager.requestAudioFocus(mFocusRequest);
 synchronized (mFocusLock) {
     if (res == AudioManager.AUDIOFOCUS_REQUEST_FAILED) {
         mPlaybackDelayed = false;
     } else if (res == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
         mPlaybackDelayed = false;
         playbackNow();
     } else if (res == AudioManager.AUDIOFOCUS_REQUEST_DELAYED) {
        mPlaybackDelayed = true;
     }
 }

 // implementation of the OnAudioFocusChangeListener
 @Override
 public void onAudioFocusChange(int focusChange) {
     switch (focusChange) {
         case AudioManager.AUDIOFOCUS_GAIN:
             if (mPlaybackDelayed || mResumeOnFocusGain) {
                 synchronized (mFocusLock) {
                     mPlaybackDelayed = false;
                     mResumeOnFocusGain = false;
                 }
                 playbackNow();
             }
             break;
         case AudioManager.AUDIOFOCUS_LOSS:
             synchronized (mFocusLock) {
                 // this is not a transient loss, we shouldn't automatically resume for now
                 mResumeOnFocusGain = false;
                 mPlaybackDelayed = false;
             }
             pausePlayback();
             break;
         case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT:
         case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK:
             // we handle all transient losses the same way because we never duck audio books
             synchronized (mFocusLock) {
                 // we should only resume if playback was interrupted
                 mResumeOnFocusGain = mMediaPlayer.isPlaying();
                 mPlaybackDelayed = false;
             }
             pausePlayback();
             break;
     }
 }

 // Important:
 // Also set "mResumeOnFocusGain" to false when the user pauses or stops playback: this way your
 // application doesn't automatically restart when it gains focus, even though the user had
 // stopped it.
 
```

<br />

## Summary

| ### Nested classes ||
|---|---|
| ` class` | `https://developer.android.com/reference/android/media/AudioFocusRequest.Builder` Builder class for `https://developer.android.com/reference/android/media/AudioFocusRequest` objects. |

| ### Public methods ||
|---|---|
| ` boolean` | ` https://developer.android.com/reference/android/media/AudioFocusRequest#acceptsDelayedFocusGain()() ` Returns whether the application that would use this `AudioFocusRequest` supports a focus gain granted after a temporary request failure. |
| ` https://developer.android.com/reference/android/media/AudioAttributes` | ` https://developer.android.com/reference/android/media/AudioFocusRequest#getAudioAttributes()() ` Returns the `https://developer.android.com/reference/android/media/AudioAttributes` set for this `AudioFocusRequest`, or the default attributes if none were set. |
| ` int` | ` https://developer.android.com/reference/android/media/AudioFocusRequest#getFocusGain()() ` Returns the type of audio focus request configured for this `AudioFocusRequest`. |
| ` boolean` | ` https://developer.android.com/reference/android/media/AudioFocusRequest#willPauseWhenDucked()() ` Returns whether the application that would use this `AudioFocusRequest` would pause when it is requested to duck. |

| ### Inherited methods |
|---|---|
| From class ` https://developer.android.com/reference/java/lang/Object ` |---|---| | ` https://developer.android.com/reference/java/lang/Object` | ` https://developer.android.com/reference/java/lang/Object#clone()() ` Creates and returns a copy of this object. | | ` boolean` | ` https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object)(https://developer.android.com/reference/java/lang/Object obj) ` Indicates whether some other object is "equal to" this one. | | ` void` | ` https://developer.android.com/reference/java/lang/Object#finalize()() ` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. | | ` final https://developer.android.com/reference/java/lang/Class<?>` | ` https://developer.android.com/reference/java/lang/Object#getClass()() ` Returns the runtime class of this `Object`. | | ` int` | ` https://developer.android.com/reference/java/lang/Object#hashCode()() ` Returns a hash code value for the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notify()() ` Wakes up a single thread that is waiting on this object's monitor. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#notifyAll()() ` Wakes up all threads that are waiting on this object's monitor. | | ` https://developer.android.com/reference/java/lang/String` | ` https://developer.android.com/reference/java/lang/Object#toString()() ` Returns a string representation of the object. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long,%20int)(long timeoutMillis, int nanos) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait(long)(long timeoutMillis) ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` https://developer.android.com/reference/java/lang/Object#wait()() ` Causes the current thread to wait until it is awakened, typically by being *notified* or *interrupted*. | ||

## Public methods

### acceptsDelayedFocusGain

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public boolean acceptsDelayedFocusGain ()
```

Returns whether the application that would use this `AudioFocusRequest` supports
a focus gain granted after a temporary request failure.

<br />

| Returns ||
|---|---|
| `boolean` | whether delayed focus gain is supported. <br /> |

### getAudioAttributes

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public AudioAttributes getAudioAttributes ()
```

Returns the `https://developer.android.com/reference/android/media/AudioAttributes` set for this `AudioFocusRequest`, or the default
attributes if none were set.

<br />

| Returns ||
|---|---|
| `https://developer.android.com/reference/android/media/AudioAttributes` | non-null `https://developer.android.com/reference/android/media/AudioAttributes`. <br /> |

### getFocusGain

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public int getFocusGain ()
```

Returns the type of audio focus request configured for this `AudioFocusRequest`.

<br />

| Returns ||
|---|---|
| `int` | one of `https://developer.android.com/reference/android/media/AudioManager#AUDIOFOCUS_GAIN`, `https://developer.android.com/reference/android/media/AudioManager#AUDIOFOCUS_GAIN_TRANSIENT`, `https://developer.android.com/reference/android/media/AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK`, and `https://developer.android.com/reference/android/media/AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE`. <br /> |

### willPauseWhenDucked

Added in [API level 26](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)

```
public boolean willPauseWhenDucked ()
```

Returns whether the application that would use this `AudioFocusRequest` would pause
when it is requested to duck.

<br />

| Returns ||
|---|---|
| `boolean` | the duck/pause behavior. <br /> |