# AudioFocusRequestCompat.Builder

Artifact: [androidx.media:media](https://developer.android.com/jetpack/androidx/releases/media) [View Source](https://cs.android.com/search?q=file:androidx/media/AudioFocusRequestCompat.java+class:androidx.media.AudioFocusRequestCompat.Builder) Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

*** ** * ** ***


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

<br />

*** ** * ** ***

> [!CAUTION]
> **This class is deprecated.**   
>
> androidx.media is deprecated. Please migrate to [androidx.media3](https://developer.android.com/media/media3).

Builder class for `https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat` objects.

See `https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat` for an example of building an instance with this builder. The default values for the instance to be built are:

|---|---|
| focus listener and handler | none |
| `https://developer.android.com/reference/androidx/media/AudioAttributesCompat` | attributes with usage set to `https://developer.android.com/reference/androidx/media/AudioAttributesCompat#USAGE_MEDIA()` |
| 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/media/AudioFocusRequestCompat.Builder#build()` an `https://developer.android.com/reference/androidx/media/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 |
|---|
| `[Builder](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#Builder(int))(int focusGain)` **This method is deprecated.** Deprecated in Java |
| `[Builder](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#Builder(androidx.media.AudioFocusRequestCompat))(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat requestToCopy)` **This method is deprecated.** Deprecated in Java |

| ### Public methods |
|---|---|
| `https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat` | `[build](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#build())()` **This method is deprecated.** Deprecated in Java |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder` | `[setAudioAttributes](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#setAudioAttributes(androidx.media.AudioAttributesCompat))(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioAttributesCompat attributes)` **This method is deprecated.** Deprecated in Java |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder` | `[setFocusGain](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#setFocusGain(int))(int focusGain)` **This method is deprecated.** Deprecated in Java |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder` | `[setOnAudioFocusChangeListener](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener))( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/media/AudioManager.OnAudioFocusChangeListener.html listener )` **This method is deprecated.** Deprecated in Java |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder` | `[setOnAudioFocusChangeListener](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener,android.os.Handler))( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/media/AudioManager.OnAudioFocusChangeListener.html listener, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/os/Handler.html handler )` **This method is deprecated.** Deprecated in Java |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder` | `[setWillPauseWhenDucked](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#setWillPauseWhenDucked(boolean))(boolean pauseOnDuck)` **This method is deprecated.** Deprecated in Java |

## Public constructors

### Builder

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

```
public [Builder](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#Builder(int))(int focusGain)
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

Constructs a new `Builder`, and specifies how audio focus will be requested. Valid values for focus requests are `https://developer.android.com/reference/androidx/media/AudioManagerCompat#AUDIOFOCUS_GAIN()`, `https://developer.android.com/reference/androidx/media/AudioManagerCompat#AUDIOFOCUS_GAIN_TRANSIENT()`, and `https://developer.android.com/reference/androidx/media/AudioManagerCompat#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK()`, and `https://developer.android.com/reference/androidx/media/AudioManagerCompat#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE()`. `https://developer.android.com/reference/androidx/media/AudioManagerCompat#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE()` is converted to `https://developer.android.com/reference/androidx/media/AudioManagerCompat#AUDIOFOCUS_GAIN_TRANSIENT()` on API levels previous to API 19.

By default there is no focus change listener, delayed focus is not supported, ducking is suitable for the application, and the `AudioAttributesCompat` have a usage of `https://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_MEDIA`.

| Parameters |
|---|---|
| `int focusGain` | the type of audio focus gain that will be requested Value is one of the following: - `AudioManagerCompat.AUDIOFOCUS_GAIN` - `AudioManagerCompat.AUDIOFOCUS_GAIN_TRANSIENT` - `AudioManagerCompat.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK` - `AudioManagerCompat.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE` <br /> |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | thrown when an invalid focus gain type is used |

### Builder

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

```
public [Builder](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#Builder(androidx.media.AudioFocusRequestCompat))(@NonNull AudioFocusRequestCompat requestToCopy)
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

Constructs a new `Builder` with all the properties of the `
AudioFocusRequestCompat` passed as parameter. Use this method when you want a new request to differ only by some properties.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat requestToCopy` | the non-null `AudioFocusRequestCompat` to duplicate. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | thrown when a null `AudioFocusRequestCompat` is used. |

## Public methods

### build

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

```
public AudioFocusRequestCompat [build](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#build())()
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

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

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat` | the `AudioFocusRequestCompat` instance qualified by all the properties set on this `Builder`. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | thrown when attempting to build a focus request without a focus change listener set. |

### setAudioAttributes

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

```
public @NonNull AudioFocusRequestCompat.Builder [setAudioAttributes](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#setAudioAttributes(androidx.media.AudioAttributesCompat))(@NonNull AudioAttributesCompat attributes)
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

Sets the `https://developer.android.com/reference/androidx/media/AudioAttributesCompat` 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 `AudioAttributesCompat` as used for playback, see for example `https://developer.android.com/reference/android/media/MediaPlayer.html#setAudioAttributes(android.media.AudioAttributes)` in `MediaPlayer` or `https://developer.android.com/reference/android/media/AudioTrack.Builder.html#setAudioAttributes(android.media.AudioAttributes)` in `AudioTrack`.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioAttributesCompat attributes` | the `https://developer.android.com/reference/androidx/media/AudioAttributesCompat` for the focus request. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder` | this `Builder` instance. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | thrown when using null for the attributes. |

### setFocusGain

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

```
public @NonNull AudioFocusRequestCompat.Builder [setFocusGain](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#setFocusGain(int))(int focusGain)
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

Sets the type of focus gain that will be requested. Use this method to replace the focus gain when building a request by modifying an existing `AudioFocusRequestCompat` instance.

| Parameters |
|---|---|
| `int focusGain` | the type of audio focus gain that will be requested. Value is one of the following: - `AudioManagerCompat.AUDIOFOCUS_GAIN` - `AudioManagerCompat.AUDIOFOCUS_GAIN_TRANSIENT` - `AudioManagerCompat.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK` - `AudioManagerCompat.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE` <br /> |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder` | this `Builder` instance |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | thrown when an invalid focus gain type is used |

### setOnAudioFocusChangeListener

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

```
public @NonNull AudioFocusRequestCompat.Builder [setOnAudioFocusChangeListener](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener))(
    @NonNull AudioManager.OnAudioFocusChangeListener listener
)
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

Sets the listener called when audio focus changes after being requested with `https://developer.android.com/reference/androidx/media/AudioManagerCompat#requestAudioFocus(android.media.AudioManager,androidx.media.AudioFocusRequestCompat)`, and until being abandoned with `https://developer.android.com/reference/androidx/media/AudioManagerCompat#abandonAudioFocusRequest(android.media.AudioManager,androidx.media.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://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/media/AudioManager.OnAudioFocusChangeListener.html listener` | the listener receiving the focus change notifications. |

| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder` | this `Builder` instance. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | thrown when a null focus listener is used. |

### setOnAudioFocusChangeListener

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

```
public @NonNull AudioFocusRequestCompat.Builder [setOnAudioFocusChangeListener](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener,android.os.Handler))(
    @NonNull AudioManager.OnAudioFocusChangeListener listener,
    @NonNull Handler handler
)
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

Sets the listener called when audio focus changes after being requested with `https://developer.android.com/reference/androidx/media/AudioManagerCompat#requestAudioFocus(android.media.AudioManager,androidx.media.AudioFocusRequestCompat)`, and until being abandoned with `https://developer.android.com/reference/androidx/media/AudioManagerCompat#abandonAudioFocusRequest(android.media.AudioManager,androidx.media.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://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/media/AudioManager.OnAudioFocusChangeListener.html listener` | the listener receiving the focus change notifications. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html 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://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder` | this `Builder` instance. |

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | thrown when a null focus listener or handler is used. |

### setWillPauseWhenDucked

Added in [1.1.0](https://developer.android.com/jetpack/androidx/releases/media#1.1.0) Deprecated in [1.8.0](https://developer.android.com/jetpack/androidx/releases/media#1.8.0)

```
public @NonNull AudioFocusRequestCompat.Builder [setWillPauseWhenDucked](https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder#setWillPauseWhenDucked(boolean))(boolean pauseOnDuck)
```

> [!CAUTION]
> **This method is deprecated.**   
> Deprecated in Java

Declare 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://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/media/AudioFocusRequestCompat.Builder` | this `Builder` instance. |