Save the date! Android Dev Summit is coming to Sunnyvale, CA on Oct 23-24, 2019.

Builder

class Builder
kotlin.Any
   ↳ androidx.media.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 handlernone AudioAttributesCompatattributes with usage set to AudioAttributesCompat#USAGE_MEDIA pauses on duckfalse supports delayed focus grantfalse

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
<init>(focusGain: Int)

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

<init>(@NonNull requestToCopy: AudioFocusRequestCompat)

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

Public methods
AudioFocusRequestCompat.Builder

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

AudioFocusRequestCompat.Builder

Sets the listener called when audio focus changes after being requested with , and until being abandoned with AudioManagerCompat#abandonAudioFocusRequest(AudioManager, * AudioFocusRequestCompat).

AudioFocusRequestCompat.Builder
setOnAudioFocusChangeListener(@NonNull listener: OnAudioFocusChangeListener, @NonNull handler: Handler)

Sets the listener called when audio focus changes after being requested with , and until being abandoned with AudioManagerCompat#abandonAudioFocusRequest(AudioManager, * AudioFocusRequestCompat).

AudioFocusRequestCompat.Builder

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

AudioFocusRequestCompat.Builder
setFocusGain(focusGain: Int)

Sets the type of focus gain that will be requested.

AudioFocusRequestCompat!

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

Public constructors

<init>

Builder(focusGain: Int)

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

Parameters
focusGain Int: the type of audio focus gain that will be requested
Exceptions
IllegalArgumentException thrown when an invalid focus gain type is used

<init>

Builder(@NonNull requestToCopy: AudioFocusRequestCompat)

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
requestToCopy AudioFocusRequestCompat: the non-null AudioFocusRequestCompat to duplicate.
Exceptions
IllegalArgumentException thrown when a null AudioFocusRequestCompat is used.

Public methods

setWillPauseWhenDucked

@NonNull fun setWillPauseWhenDucked(pauseOnDuck: Boolean): AudioFocusRequestCompat.Builder

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 android.os.Build.VERSION_CODES#O and later.

Parameters
pauseOnDuck Boolean: use true if the application intends to pause audio playback when losing focus with AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK.
Return
AudioFocusRequestCompat.Builder: this Builder instance.

setOnAudioFocusChangeListener

@NonNull fun setOnAudioFocusChangeListener(@NonNull listener: OnAudioFocusChangeListener): AudioFocusRequestCompat.Builder

Sets the listener called when audio focus changes after being requested with , and until being abandoned with AudioManagerCompat#abandonAudioFocusRequest(AudioManager, * 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
listener OnAudioFocusChangeListener: the listener receiving the focus change notifications.
Return
AudioFocusRequestCompat.Builder: this Builder instance.
Exceptions
NullPointerException thrown when a null focus listener is used.

setOnAudioFocusChangeListener

@NonNull fun setOnAudioFocusChangeListener(@NonNull listener: OnAudioFocusChangeListener, @NonNull handler: Handler): AudioFocusRequestCompat.Builder

Sets the listener called when audio focus changes after being requested with , and until being abandoned with AudioManagerCompat#abandonAudioFocusRequest(AudioManager, * 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
listener OnAudioFocusChangeListener: the listener receiving the focus change notifications.
handler OnAudioFocusChangeListener: the Handler for the thread on which to execute the notifications.
Return
AudioFocusRequestCompat.Builder: this Builder instance.
Exceptions
NullPointerException thrown when a null focus listener or handler is used.

setAudioAttributes

@NonNull fun setAudioAttributes(@NonNull attributes: AudioAttributesCompat): AudioFocusRequestCompat.Builder

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

Parameters
attributes AudioAttributesCompat: the AudioAttributesCompat for the focus request.
Return
AudioFocusRequestCompat.Builder: this Builder instance.
Exceptions
NullPointerException thrown when using null for the attributes.

setFocusGain

@NonNull fun setFocusGain(focusGain: Int): AudioFocusRequestCompat.Builder

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
focusGain Int: the type of audio focus gain that will be requested.
Return
AudioFocusRequestCompat.Builder: this Builder instance
Exceptions
IllegalArgumentException thrown when an invalid focus gain type is used

build

fun build(): AudioFocusRequestCompat!

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

Return
AudioFocusRequestCompat!: the AudioFocusRequestCompat instance qualified by all the properties set on this Builder.
Exceptions
IllegalStateException thrown when attempting to build a focus request without a focus change listener set.