AudioFocusRequestCompat.Builder

public final class AudioFocusRequestCompat.Builder

Builder class for AudioFocusRequestCompat objects.

The default values are:

  • focus listener and handler: none
  • audio attributes: DEFAULT
  • pauses on duck: false
  • supports delayed focus grant: false

In contrast to a AudioFocusRequest, attempting to build an without an AudioManager.OnAudioFocusChangeListener will throw an IllegalArgumentException, because the listener is required for all API levels up to API 26.

Summary

Public constructors

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

Public methods
AudioFocusRequestCompat

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

Sets the AudioAttributes to be associated with the focus request, and which describe the use case for which focus is requested.
AudioFocusRequestCompat.Builder

Sets the type of AudioManagerCompat.AudioFocusGain that will be requested.
AudioFocusRequestCompat.Builder

Sets the listener called when audio focus changes after being requested with requestAudioFocus, and until being abandoned with abandonAudioFocusRequest.
AudioFocusRequestCompat.Builder

Sets the listener called when audio focus changes after being requested with requestAudioFocus, and until being abandoned with abandonAudioFocusRequest.
AudioFocusRequestCompat.Builder

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 AudioAttributes are set to DEFAULT.

Parameters
@AudioManagerCompat.AudioFocusGain int focusGain

The type of 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
AudioFocusRequestCompat

The AudioFocusRequestCompat.

setAudioAttributes

@CanIgnoreReturnValue
public AudioFocusRequestCompat.Builder setAudioAttributes(AudioAttributes attributes)

Sets the 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
AudioAttributes attributes

The AudioAttributes for the focus request.
Returns
AudioFocusRequestCompat.Builder

This Builder instance.

setFocusGain

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

Sets the type of AudioManagerCompat.AudioFocusGain that will be requested.

Parameters
@AudioManagerCompat.AudioFocusGain int focusGain

The type of AudioManagerCompat.AudioFocusGain that will be requested.
Returns
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 requestAudioFocus, and until being abandoned with abandonAudioFocusRequest. 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
AudioManager.OnAudioFocusChangeListener listener

The AudioManager.OnAudioFocusChangeListener receiving the focus change notifications.
Returns
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 requestAudioFocus, and until being abandoned with abandonAudioFocusRequest. 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
AudioManager.OnAudioFocusChangeListener listener

The AudioManager.OnAudioFocusChangeListener receiving the focus change notifications.
Handler handler

The Handler for the thread on which to execute the notifications.
Returns
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 AudioFocusRequest class documentation. Setting pauseOnDuck to true will only have an effect on O and later.

Parameters
boolean pauseOnDuck

Use true if the application intends to pause audio playback when losing focus with AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK.
Returns
AudioFocusRequestCompat.Builder

This Builder instance.