# AudioFocusRequestCompat.Builder

Artifact: [androidx.media3:media3-common](https://developer.android.com/jetpack/androidx/releases/media3) [View Source](https://cs.android.com/search?q=file:androidx/media3/common/audio/AudioFocusRequestCompat.java+class:androidx.media3.common.audio.AudioFocusRequestCompat.Builder)

*** ** * ** ***


```
public final class AudioFocusRequestCompat.Builder
```

<br />

*** ** * ** ***

Builder class for `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat` objects.

The default values are:

- focus listener and handler: none
- audio attributes: `https://developer.android.com/reference/androidx/media3/common/AudioAttributes#DEFAULT()`
- pauses on duck: false
- supports delayed focus grant: false

In contrast to a `https://developer.android.com/reference/android/media/AudioFocusRequest.html`, attempting to `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder#build()` an `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat` without an `https://developer.android.com/reference/android/media/AudioManager.OnAudioFocusChangeListener.html` will throw an `https://developer.android.com/reference/java/lang/IllegalArgumentException.html`, because the listener is required for all API levels up to API 26.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder#Builder(int)(@https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat.AudioFocusGain int focusGain)` Constructs a new `Builder`, and specifies how audio focus will be requested. |

| ### Public methods |
|---|---|
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat` | `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder#build()()` Builds a new `AudioFocusRequestCompat` instance combining all the information gathered by this builder's configuration methods. |
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder#setAcceptsDelayedFocusGain(boolean)(boolean acceptsDelayedFocusGain)` Marks this focus request as compatible with delayed focus. |
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder#setAudioAttributes(androidx.media3.common.AudioAttributes)(https://developer.android.com/reference/androidx/media3/common/AudioAttributes attributes)` Sets the `https://developer.android.com/reference/androidx/media3/common/AudioAttributes` to be associated with the focus request, and which describe the use case for which focus is requested. |
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder#setFocusGain(int)(@https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat.AudioFocusGain int focusGain)` Sets the type of `https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat.AudioFocusGain` that will be requested. |
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder#setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener)( https://developer.android.com/reference/android/media/AudioManager.OnAudioFocusChangeListener.html listener )` Sets the listener called when audio focus changes after being requested with `https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat#requestAudioFocus(android.media.AudioManager,androidx.media3.common.audio.AudioFocusRequestCompat)`, and until being abandoned with `https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat#abandonAudioFocusRequest(android.media.AudioManager,androidx.media3.common.audio.AudioFocusRequestCompat)`. |
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder#setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener,android.os.Handler)( https://developer.android.com/reference/android/media/AudioManager.OnAudioFocusChangeListener.html listener, https://developer.android.com/reference/android/os/Handler.html handler )` Sets the listener called when audio focus changes after being requested with `https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat#requestAudioFocus(android.media.AudioManager,androidx.media3.common.audio.AudioFocusRequestCompat)`, and until being abandoned with `https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat#abandonAudioFocusRequest(android.media.AudioManager,androidx.media3.common.audio.AudioFocusRequestCompat)`. |
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder#setWillPauseWhenDucked(boolean)(boolean pauseOnDuck)` Declares the intended behavior of the application with regards to audio ducking. |

## Public constructors

### Builder

```
public Builder(@AudioManagerCompat.AudioFocusGain int focusGain)
```

Constructs a new `Builder`, and specifies how audio focus will be requested.

By default there is no focus change listener, delayed focus is not supported, ducking is suitable for the application, and the `https://developer.android.com/reference/androidx/media3/common/AudioAttributes` are set to `https://developer.android.com/reference/androidx/media3/common/AudioAttributes#DEFAULT()`.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat.AudioFocusGain int focusGain` | The type of `https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat.AudioFocusGain` that will be requested. |

## Public methods

### build

```
public AudioFocusRequestCompat build()
```

Builds a new `AudioFocusRequestCompat` instance combining all the information gathered by this builder's configuration methods.

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat` | The `AudioFocusRequestCompat`. |

### setAcceptsDelayedFocusGain

```
@CanIgnoreReturnValue
public AudioFocusRequestCompat.Builder setAcceptsDelayedFocusGain(boolean acceptsDelayedFocusGain)
```

Marks this focus request as compatible with delayed focus. See more details about delayed focus in the `https://developer.android.com/reference/android/media/AudioFocusRequest.html` class documentation.

Setting `acceptsDelayedFocusGain` to `true` will only have an effect on `https://developer.android.com/reference/android/os/Build.VERSION_CODES.html#O` and later.

| Parameters |
|---|---|
| `boolean acceptsDelayedFocusGain` | Use `true` if the application supports delayed focus. If `true`, note that you must also set a focus listener to be notified of delayed focus gain with `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder#setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener,android.os.Handler)`. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder` | This `Builder` instance. |

### setAudioAttributes

```
@CanIgnoreReturnValue
public AudioFocusRequestCompat.Builder setAudioAttributes(AudioAttributes attributes)
```

Sets the `https://developer.android.com/reference/androidx/media3/common/AudioAttributes` to be associated with the focus request, and which describe the use case for which focus is requested. As the focus requests typically precede audio playback, this information is used on certain platforms to declare the subsequent playback use case. It is therefore good practice to use in this method the same `
AudioAttributes` as used for playback, see for example `
ExoPlayer.Builder.setAudioAttributes()`.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/media3/common/AudioAttributes attributes` | The `https://developer.android.com/reference/androidx/media3/common/AudioAttributes` for the focus request. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder` | This `Builder` instance. |

### setFocusGain

```
@CanIgnoreReturnValue
public AudioFocusRequestCompat.Builder setFocusGain(@AudioManagerCompat.AudioFocusGain int focusGain)
```

Sets the type of `https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat.AudioFocusGain` that will be requested.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat.AudioFocusGain int focusGain` | The type of `https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat.AudioFocusGain` that will be requested. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder` | This `Builder` instance. |

### setOnAudioFocusChangeListener

```
@CanIgnoreReturnValue
public AudioFocusRequestCompat.Builder setOnAudioFocusChangeListener(
    AudioManager.OnAudioFocusChangeListener listener
)
```

Sets the listener called when audio focus changes after being requested with `https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat#requestAudioFocus(android.media.AudioManager,androidx.media3.common.audio.AudioFocusRequestCompat)`, and until being abandoned with `https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat#abandonAudioFocusRequest(android.media.AudioManager,androidx.media3.common.audio.AudioFocusRequestCompat)`. Note that only focus changes (gains and losses) affecting the focus owner are reported, not gains and losses of other focus requesters in the system. Notifications are delivered on the main thread.

| Parameters |
|---|---|
| `https://developer.android.com/reference/android/media/AudioManager.OnAudioFocusChangeListener.html listener` | The `https://developer.android.com/reference/android/media/AudioManager.OnAudioFocusChangeListener.html` receiving the focus change notifications. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder` | This `Builder` instance. |

### setOnAudioFocusChangeListener

```
@CanIgnoreReturnValue
public AudioFocusRequestCompat.Builder setOnAudioFocusChangeListener(
    AudioManager.OnAudioFocusChangeListener listener,
    Handler handler
)
```

Sets the listener called when audio focus changes after being requested with `https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat#requestAudioFocus(android.media.AudioManager,androidx.media3.common.audio.AudioFocusRequestCompat)`, and until being abandoned with `https://developer.android.com/reference/androidx/media3/common/audio/AudioManagerCompat#abandonAudioFocusRequest(android.media.AudioManager,androidx.media3.common.audio.AudioFocusRequestCompat)`. Note that only focus changes (gains and losses) affecting the focus owner are reported, not gains and losses of other focus requesters in the system.

| Parameters |
|---|---|
| `https://developer.android.com/reference/android/media/AudioManager.OnAudioFocusChangeListener.html listener` | The `https://developer.android.com/reference/android/media/AudioManager.OnAudioFocusChangeListener.html` receiving the focus change notifications. |
| `https://developer.android.com/reference/android/os/Handler.html handler` | The `https://developer.android.com/reference/android/os/Handler.html` for the thread on which to execute the notifications. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder` | This `Builder` instance. |

### setWillPauseWhenDucked

```
@CanIgnoreReturnValue
public AudioFocusRequestCompat.Builder setWillPauseWhenDucked(boolean pauseOnDuck)
```

Declares the intended behavior of the application with regards to audio ducking. See more details in the `https://developer.android.com/reference/android/media/AudioFocusRequest.html` class documentation. Setting `pauseOnDuck` to true will only have an effect on `https://developer.android.com/reference/android/os/Build.VERSION_CODES.html#O` and later.

| Parameters |
|---|---|
| `boolean pauseOnDuck` | Use `true` if the application intends to pause audio playback when losing focus with `https://developer.android.com/reference/android/media/AudioManager.html#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK`. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media3/common/audio/AudioFocusRequestCompat.Builder` | This `Builder` instance. |