AudioFocusRequestCompat.Builder

public final class AudioFocusRequestCompat.Builder


Builder class for AudioFocusRequestCompat objects.

See 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
AudioAttributesCompat attributes with usage set to USAGE_MEDIA
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.

Constructs a new Builder with all the properties of the AudioFocusRequestCompat passed as parameter.

Public methods

AudioFocusRequestCompat

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

@NonNull AudioFocusRequestCompat.Builder

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

@NonNull AudioFocusRequestCompat.Builder

Sets the type of focus gain that will be requested.

@NonNull AudioFocusRequestCompat.Builder

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

@NonNull AudioFocusRequestCompat.Builder

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

@NonNull AudioFocusRequestCompat.Builder
setWillPauseWhenDucked(boolean pauseOnDuck)

Declare the intended behavior of the application with regards to audio ducking.

Public constructors

Builder

Added in 1.1.0
public Builder(@AudioFocusRequestCompat.FocusGainType int focusGain)

Constructs a new Builder, and specifies how audio focus will be requested. Valid values for focus requests are AUDIOFOCUS_GAIN, AUDIOFOCUS_GAIN_TRANSIENT, and AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK, and AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE. AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE is converted to 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 USAGE_MEDIA.

Parameters
@AudioFocusRequestCompat.FocusGainType int focusGain

the type of audio focus gain that will be requested

Throws
java.lang.IllegalArgumentException

thrown when an invalid focus gain type is used

Builder

Added in 1.1.0
public Builder(@NonNull AudioFocusRequestCompat requestToCopy)

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
@NonNull AudioFocusRequestCompat requestToCopy

the non-null AudioFocusRequestCompat to duplicate.

Throws
java.lang.IllegalArgumentException

thrown when a null AudioFocusRequestCompat is used.

Public methods

build

Added in 1.1.0
public AudioFocusRequestCompat build()

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

Returns
AudioFocusRequestCompat

the AudioFocusRequestCompat instance qualified by all the properties set on this Builder.

Throws
java.lang.IllegalStateException

thrown when attempting to build a focus request without a focus change listener set.

setAudioAttributes

Added in 1.1.0
public @NonNull AudioFocusRequestCompat.Builder setAudioAttributes(@NonNull AudioAttributesCompat attributes)

Sets the 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 setAudioAttributes in MediaPlayer or setAudioAttributes in AudioTrack.

Parameters
@NonNull AudioAttributesCompat attributes

the AudioAttributesCompat for the focus request.

Returns
@NonNull AudioFocusRequestCompat.Builder

this Builder instance.

Throws
java.lang.NullPointerException

thrown when using null for the attributes.

setFocusGain

Added in 1.1.0
public @NonNull AudioFocusRequestCompat.Builder setFocusGain(@AudioFocusRequestCompat.FocusGainType int focusGain)

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
@AudioFocusRequestCompat.FocusGainType int focusGain

the type of audio focus gain that will be requested.

Returns
@NonNull AudioFocusRequestCompat.Builder

this Builder instance

Throws
java.lang.IllegalArgumentException

thrown when an invalid focus gain type is used

setOnAudioFocusChangeListener

Added in 1.1.0
public @NonNull AudioFocusRequestCompat.Builder setOnAudioFocusChangeListener(
    @NonNull 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
@NonNull AudioManager.OnAudioFocusChangeListener listener

the listener receiving the focus change notifications.

Returns
@NonNull AudioFocusRequestCompat.Builder

this Builder instance.

Throws
java.lang.NullPointerException

thrown when a null focus listener is used.

setOnAudioFocusChangeListener

Added in 1.1.0
public @NonNull AudioFocusRequestCompat.Builder setOnAudioFocusChangeListener(
    @NonNull AudioManager.OnAudioFocusChangeListener listener,
    @NonNull 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
@NonNull AudioManager.OnAudioFocusChangeListener listener

the listener receiving the focus change notifications.

@NonNull Handler handler

the Handler for the thread on which to execute the notifications.

Returns
@NonNull AudioFocusRequestCompat.Builder

this Builder instance.

Throws
java.lang.NullPointerException

thrown when a null focus listener or handler is used.

setWillPauseWhenDucked

Added in 1.1.0
public @NonNull AudioFocusRequestCompat.Builder setWillPauseWhenDucked(boolean pauseOnDuck)

Declare 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
@NonNull AudioFocusRequestCompat.Builder

this Builder instance.