Added in API level 26

Summary: Ctors | Methods | Inherited Methods

AudioFocusRequest.Builder

---

Kotlin |Java

public static final class AudioFocusRequest.Builder
extends Object

java.lang.Object
↳	android.media.AudioFocusRequest.Builder

---

Builder class for AudioFocusRequest objects.

See AudioFocusRequest 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
AudioAttributes	attributes with usage set to AudioAttributes.USAGE_MEDIA
pauses on duck	false
supports delayed focus grant	false

Summary

Public constructors
Builder(AudioFocusRequest requestToCopy) Constructs a new Builder with all the properties of the AudioFocusRequest passed as parameter.
Builder(int focusGain) Constructs a new Builder, and specifies how audio focus will be requested.

Public methods
AudioFocusRequest	build() Builds a new AudioFocusRequest instance combining all the information gathered by this Builder's configuration methods.
AudioFocusRequest.Builder	setAcceptsDelayedFocusGain(boolean acceptsDelayedFocusGain) Marks this focus request as compatible with delayed focus.
AudioFocusRequest.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.
AudioFocusRequest.Builder	setFocusGain(int focusGain) Sets the type of focus gain that will be requested.
AudioFocusRequest.Builder	setForceDucking(boolean forceDucking) Marks this focus request as forcing ducking, regardless of the conditions in which the system would or would not enforce ducking.
AudioFocusRequest.Builder	setOnAudioFocusChangeListener(AudioManager.OnAudioFocusChangeListener listener) Sets the listener called when audio focus changes after being requested with AudioManager.requestAudioFocus(AudioFocusRequest), and until being abandoned with AudioManager.abandonAudioFocusRequest(AudioFocusRequest).
AudioFocusRequest.Builder	setOnAudioFocusChangeListener(AudioManager.OnAudioFocusChangeListener listener, Handler handler) Sets the listener called when audio focus changes after being requested with AudioManager.requestAudioFocus(AudioFocusRequest), and until being abandoned with AudioManager.abandonAudioFocusRequest(AudioFocusRequest).
AudioFocusRequest.Builder	setWillPauseWhenDucked(boolean pauseOnDuck) Declare the intended behavior of the application with regards to audio ducking.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public constructors

Builder

Added in API level 26

public Builder (AudioFocusRequest requestToCopy)

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

Parameters
requestToCopy	AudioFocusRequest: the non-null AudioFocusRequest to build a duplicate from.

Throws
IllegalArgumentException	thrown when a null AudioFocusRequest is used.

Builder

Added in API level 26

public Builder (int focusGain)

Constructs a new Builder, and specifies how audio focus will be requested. Valid values for focus requests are AudioManager.AUDIOFOCUS_GAIN, AudioManager.AUDIOFOCUS_GAIN_TRANSIENT, AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK, and AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE.

By default there is no focus change listener, delayed focus is not supported, ducking is suitable for the application, and the AudioAttributes have a usage of AudioAttributes.USAGE_MEDIA.

Parameters
focusGain	int: the type of audio focus gain that will be requested

Throws
IllegalArgumentException	thrown when an invalid focus gain type is used

Public methods

build

Added in API level 26

public AudioFocusRequest build ()

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

Returns
AudioFocusRequest	the AudioFocusRequest instance qualified by all the properties set on this Builder.

Throws
IllegalStateException	thrown when attempting to build a focus request that is set to accept delayed focus, or to pause on duck, but no focus change listener was set.

setAcceptsDelayedFocusGain

Added in API level 26

public AudioFocusRequest.Builder setAcceptsDelayedFocusGain (boolean acceptsDelayedFocusGain)

Marks this focus request as compatible with delayed focus. See more details about delayed focus in the AudioFocusRequest class documentation.

Parameters
acceptsDelayedFocusGain	boolean: 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 setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener, android.os.Handler).

Returns
AudioFocusRequest.Builder	this Builder instance This value cannot be null.

setAudioAttributes

Added in API level 26

public AudioFocusRequest.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 MediaPlayer.setAudioAttributes(AudioAttributes) in MediaPlayer or AudioTrack.Builder.setAudioAttributes(AudioAttributes) in AudioTrack.

Parameters
attributes	AudioAttributes: the AudioAttributes for the focus request. This value cannot be null.

Returns
AudioFocusRequest.Builder	this Builder instance. This value cannot be null.

Throws
NullPointerException	thrown when using null for the attributes.

setFocusGain

Added in API level 26

public AudioFocusRequest.Builder setFocusGain (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 AudioFocusRequest instance.

Parameters
focusGain	int: the type of audio focus gain that will be requested.

Returns
AudioFocusRequest.Builder	this Builder instance This value cannot be null.

Throws
IllegalArgumentException	thrown when an invalid focus gain type is used

setForceDucking

Added in API level 28

public AudioFocusRequest.Builder setForceDucking (boolean forceDucking)

Marks this focus request as forcing ducking, regardless of the conditions in which the system would or would not enforce ducking. Forcing ducking will only be honored when requesting AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK with an AudioAttributes usage of AudioAttributes.USAGE_ASSISTANCE_ACCESSIBILITY, coming from an accessibility service, and will be ignored otherwise.

Parameters
forceDucking	boolean: true to force ducking

Returns
AudioFocusRequest.Builder	this Builder instance This value cannot be null.

setOnAudioFocusChangeListener

Added in API level 26

public AudioFocusRequest.Builder setOnAudioFocusChangeListener (AudioManager.OnAudioFocusChangeListener listener)

Sets the listener called when audio focus changes after being requested with AudioManager.requestAudioFocus(AudioFocusRequest), and until being abandoned with AudioManager.abandonAudioFocusRequest(AudioFocusRequest). 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 Looper associated with the one of the creation of the AudioManager used to request focus (see AudioManager.requestAudioFocus(AudioFocusRequest)).

Parameters
listener	AudioManager.OnAudioFocusChangeListener: the listener receiving the focus change notifications. This value cannot be null.

Returns
AudioFocusRequest.Builder	this Builder instance. This value cannot be null.

Throws
NullPointerException	thrown when a null focus listener is used.

setOnAudioFocusChangeListener

Added in API level 26

public AudioFocusRequest.Builder setOnAudioFocusChangeListener (AudioManager.OnAudioFocusChangeListener listener, 
                Handler handler)

Sets the listener called when audio focus changes after being requested with AudioManager.requestAudioFocus(AudioFocusRequest), and until being abandoned with AudioManager.abandonAudioFocusRequest(AudioFocusRequest). 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	AudioManager.OnAudioFocusChangeListener: the listener receiving the focus change notifications. This value cannot be null.
handler	Handler: the Handler for the thread on which to execute the notifications. This value cannot be null.

Returns
AudioFocusRequest.Builder	this Builder instance. This value cannot be null.

Throws
NullPointerException	thrown when a null focus listener or handler is used.

setWillPauseWhenDucked

Added in API level 26

public AudioFocusRequest.Builder setWillPauseWhenDucked (boolean pauseOnDuck)

Declare the intended behavior of the application with regards to audio ducking. See more details in the AudioFocusRequest class documentation.

Parameters
pauseOnDuck	boolean: use true if the application intends to pause audio playback when losing focus with AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK. If true, note that you must also set a focus listener to receive such an event, with setOnAudioFocusChangeListener(android.media.AudioManager.OnAudioFocusChangeListener, android.os.Handler).

Returns
AudioFocusRequest.Builder	this Builder instance. This value cannot be null.