Added in API level 23

Summary: Ctors | Methods | Inherited Methods

AudioTrack.Builder

Kotlin |Java

public static class AudioTrack.Builder
extends Object

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

Builder class for AudioTrack objects. Use this class to configure and create an AudioTrack instance. By setting audio attributes and audio format parameters, you indicate which of those vary from the default behavior on the device.

Here is an example where Builder is used to specify all AudioFormat parameters, to be used by a new AudioTrack instance:

 AudioTrack player = new AudioTrack.Builder()
         .setAudioAttributes(new AudioAttributes.Builder()
                  .setUsage(AudioAttributes.USAGE_ALARM)
                  .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
                  .build())
         .setAudioFormat(new AudioFormat.Builder()
                 .setEncoding(AudioFormat.ENCODING_PCM_16BIT)
                 .setSampleRate(44100)
                 .setChannelMask(AudioFormat.CHANNEL_OUT_STEREO)
                 .build())
         .setBufferSizeInBytes(minBuffSize)
         .build();

If the audio attributes are not set with setAudioAttributes(android.media.AudioAttributes), attributes comprising AudioAttributes.USAGE_MEDIA will be used.
If the audio format is not specified or is incomplete, its channel configuration will be AudioFormat.CHANNEL_OUT_STEREO and the encoding will be AudioFormat.ENCODING_PCM_16BIT. The sample rate will depend on the device actually selected for playback and can be queried with AudioTrack.getSampleRate() method.
If the buffer size is not specified with setBufferSizeInBytes(int), and the mode is AudioTrack.MODE_STREAM, the minimum buffer size is used.
If the transfer mode is not specified with setTransferMode(int), MODE_STREAM will be used.
If the session ID is not specified with setSessionId(int), a new one will be generated.
Offload is false by default.

Summary

Public constructors
`Builder()` Constructs a new Builder with the default values as described above.

Public methods
`AudioTrack`	`build()` Builds an `AudioTrack` instance initialized with all the parameters set on this `Builder`.
`AudioTrack.Builder`	`setAudioAttributes(AudioAttributes attributes)` Sets the `AudioAttributes`.
`AudioTrack.Builder`	`setAudioFormat(AudioFormat format)` Sets the format of the audio data to be played by the `AudioTrack`.
`AudioTrack.Builder`	`setBufferSizeInBytes(int bufferSizeInBytes)` Sets the total size (in bytes) of the buffer where audio data is read from for playback.
`AudioTrack.Builder`	`setContext(Context context)` Sets the context the track belongs to.
`AudioTrack.Builder`	`setEncapsulationMode(int encapsulationMode)` Sets the encapsulation mode.
`AudioTrack.Builder`	`setOffloadedPlayback(boolean offload)` Sets whether this track will play through the offloaded audio path.
`AudioTrack.Builder`	`setPerformanceMode(int performanceMode)` Sets the `AudioTrack` performance mode.
`AudioTrack.Builder`	`setSessionId(int sessionId)` Sets the session ID the `AudioTrack` will be attached to.
`AudioTrack.Builder`	`setTransferMode(int mode)` Sets the mode under which buffers of audio data are transferred from the `AudioTrack` to the framework.

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 23

public Builder ()

Constructs a new Builder with the default values as described above.

Public methods

build

Added in API level 23

public AudioTrack build ()

Builds an AudioTrack instance initialized with all the parameters set on this Builder.

Returns
`AudioTrack`	a new successfully initialized `AudioTrack` instance. This value cannot be `null`.

Throws
`UnsupportedOperationException`	if the parameters set on the `Builder` were incompatible, or if they are not supported by the device, or if the device was not available.

setAudioAttributes

Added in API level 23

public AudioTrack.Builder setAudioAttributes (AudioAttributes attributes)

Sets the AudioAttributes.

Parameters
`attributes`	`AudioAttributes`: a non-null `AudioAttributes` instance that describes the audio data to be played.

Returns
`AudioTrack.Builder`	the same Builder instance. This value cannot be `null`.

Throws
	java.lang.IllegalArgumentException
`IllegalArgumentException`

setAudioFormat

Added in API level 23

public AudioTrack.Builder setAudioFormat (AudioFormat format)

Sets the format of the audio data to be played by the AudioTrack. See AudioFormat.Builder for configuring the audio format parameters such as encoding, channel mask and sample rate.

Parameters
`format`	`AudioFormat`: a non-null `AudioFormat` instance.

Returns
`AudioTrack.Builder`	the same Builder instance. This value cannot be `null`.

Throws
	java.lang.IllegalArgumentException
`IllegalArgumentException`

setBufferSizeInBytes

Added in API level 23

public AudioTrack.Builder setBufferSizeInBytes (int bufferSizeInBytes)

Sets the total size (in bytes) of the buffer where audio data is read from for playback. If using the AudioTrack in streaming mode (see AudioTrack.MODE_STREAM, you can write data into this buffer in smaller chunks than this size. See AudioTrack.getMinBufferSize(int, int, int) to determine the estimated minimum buffer size for the creation of an AudioTrack instance in streaming mode.
If using the AudioTrack in static mode (see AudioTrack.MODE_STATIC), this is the maximum size of the sound that will be played by this instance.

Parameters
`bufferSizeInBytes`	`int`: Value is 0 or greater

Returns
`AudioTrack.Builder`	the same Builder instance. This value cannot be `null`.

Throws
	java.lang.IllegalArgumentException
`IllegalArgumentException`

setContext

Added in API level 34

public AudioTrack.Builder setContext (Context context)

Sets the context the track belongs to. This context will be used to pull information, such as AttributionSource and device specific audio session ids, which will be associated with the AudioTrack. However, the context itself will not be retained by the AudioTrack.

Parameters
`context`	`Context`: a non-null `Context` instance

Returns
`AudioTrack.Builder`	the same Builder instance. This value cannot be `null`.

setEncapsulationMode

Added in API level 30

public AudioTrack.Builder setEncapsulationMode (int encapsulationMode)

Sets the encapsulation mode. Encapsulation mode allows metadata to be sent together with the audio data payload in a ByteBuffer. This requires a compatible hardware audio codec.

Parameters
`encapsulationMode`	`int`: one of `AudioTrack.ENCAPSULATION_MODE_NONE`, or `AudioTrack.ENCAPSULATION_MODE_ELEMENTARY_STREAM`. Value is one of the following: `AudioTrack.ENCAPSULATION_MODE_NONE` `AudioTrack.ENCAPSULATION_MODE_ELEMENTARY_STREAM`

Returns
`AudioTrack.Builder`	the same Builder instance. This value cannot be `null`.

setOffloadedPlayback

Added in API level 29

public AudioTrack.Builder setOffloadedPlayback (boolean offload)

Sets whether this track will play through the offloaded audio path. When set to true, at build time, the audio format will be checked against AudioManager.isOffloadedPlaybackSupported(AudioFormat,AudioAttributes) to verify the audio format used by this track is supported on the device's offload path (if any).
Offload is only supported for media audio streams, and therefore requires that the usage be AudioAttributes.USAGE_MEDIA.

Parameters
`offload`	`boolean`: true to require the offload path for playback.

Returns
`AudioTrack.Builder`	the same Builder instance. This value cannot be `null`.

setPerformanceMode

Added in API level 26

public AudioTrack.Builder setPerformanceMode (int performanceMode)

Sets the AudioTrack performance mode. This is an advisory request which may not be supported by the particular device, and the framework is free to ignore such request if it is incompatible with other requests or hardware.

Parameters
`performanceMode`	`int`: one of `AudioTrack.PERFORMANCE_MODE_NONE`, `AudioTrack.PERFORMANCE_MODE_LOW_LATENCY`, or `AudioTrack.PERFORMANCE_MODE_POWER_SAVING`. Value is one of the following: `AudioTrack.PERFORMANCE_MODE_NONE` `AudioTrack.PERFORMANCE_MODE_LOW_LATENCY` `AudioTrack.PERFORMANCE_MODE_POWER_SAVING`

Returns
`AudioTrack.Builder`	the same Builder instance. This value cannot be `null`.

Throws
`IllegalArgumentException`	if `performanceMode` is not valid.

setSessionId

Added in API level 23

public AudioTrack.Builder setSessionId (int sessionId)

Sets the session ID the AudioTrack will be attached to. Note, that if there's a device specific session id asociated with the context, explicitly setting a session id using this method will override it (see Builder.setContext(Context)).

Parameters
`sessionId`	`int`: a strictly positive ID number retrieved from another `AudioTrack` via `AudioTrack.getAudioSessionId()` or allocated by `AudioManager` via `AudioManager.generateAudioSessionId()`, or `AudioManager.AUDIO_SESSION_ID_GENERATE`. Value is 1 or greater

Returns
`AudioTrack.Builder`	the same Builder instance. This value cannot be `null`.

Throws
	java.lang.IllegalArgumentException
`IllegalArgumentException`

setTransferMode

Added in API level 23

public AudioTrack.Builder setTransferMode (int mode)

Sets the mode under which buffers of audio data are transferred from the AudioTrack to the framework.

Parameters
`mode`	`int`: one of `AudioTrack.MODE_STREAM`, `AudioTrack.MODE_STATIC`. Value is one of the following: `AudioTrack.MODE_STATIC` `AudioTrack.MODE_STREAM`

Returns
`AudioTrack.Builder`	the same Builder instance. This value cannot be `null`.

Throws
	java.lang.IllegalArgumentException
`IllegalArgumentException`