Added in API level 23

Builder

open class Builder
kotlin.Any
   ↳ 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 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

Constructs a new Builder with the default values as described above.
Public methods
open AudioTrack

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

Sets the AudioAttributes.
open AudioTrack.Builder

Sets the format of the audio data to be played by the AudioTrack.
open AudioTrack.Builder
setBufferSizeInBytes(bufferSizeInBytes: Int)

Sets the total size (in bytes) of the buffer where audio data is read from for playback.
open AudioTrack.Builder
setContext(context: Context)

Sets the context the track belongs to.
open AudioTrack.Builder
setEncapsulationMode(encapsulationMode: Int)

Sets the encapsulation mode.
open AudioTrack.Builder

Sets whether this track will play through the offloaded audio path.
open AudioTrack.Builder
setPerformanceMode(performanceMode: Int)

Sets the AudioTrack performance mode.
open AudioTrack.Builder
setSessionId(sessionId: Int)

Sets the session ID the AudioTrack will be attached to.
open AudioTrack.Builder

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

Public constructors

Builder

Added in API level 23
Builder()

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

Public methods

build

Added in API level 23
open fun build(): AudioTrack

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

Return
AudioTrack a new successfully initialized AudioTrack instance. This value cannot be null.
Exceptions
java.lang.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
open fun setAudioAttributes(attributes: AudioAttributes): AudioTrack.Builder

Sets the AudioAttributes.

Parameters
attributes AudioAttributes: a non-null AudioAttributes instance that describes the audio data to be played.
Return
AudioTrack.Builder the same Builder instance. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException

setAudioFormat

Added in API level 23
open fun setAudioFormat(format: AudioFormat): AudioTrack.Builder

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.
Return
AudioTrack.Builder the same Builder instance. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException

setBufferSizeInBytes

Added in API level 23
open fun setBufferSizeInBytes(bufferSizeInBytes: Int): AudioTrack.Builder

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 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
Return
AudioTrack.Builder the same Builder instance. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException

setContext

Added in API level 34
open fun setContext(context: Context): AudioTrack.Builder

Sets the context the track belongs to. This context will be used to pull information, such as android.content.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
Return
AudioTrack.Builder the same Builder instance. This value cannot be null.

setEncapsulationMode

Added in API level 30
open fun setEncapsulationMode(encapsulationMode: Int): AudioTrack.Builder

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 android.media.AudioTrack#ENCAPSULATION_MODE_NONE, or android.media.AudioTrack#ENCAPSULATION_MODE_ELEMENTARY_STREAM
Return
AudioTrack.Builder the same Builder instance. This value cannot be null.

setOffloadedPlayback

Added in API level 29
open fun setOffloadedPlayback(offload: Boolean): AudioTrack.Builder

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.
Return
AudioTrack.Builder the same Builder instance. This value cannot be null.

setPerformanceMode

Added in API level 26
open fun setPerformanceMode(performanceMode: Int): AudioTrack.Builder

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 android.media.AudioTrack#PERFORMANCE_MODE_NONE, android.media.AudioTrack#PERFORMANCE_MODE_LOW_LATENCY, or android.media.AudioTrack#PERFORMANCE_MODE_POWER_SAVING
Return
AudioTrack.Builder the same Builder instance. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if performanceMode is not valid.

setSessionId

Added in API level 23
open fun setSessionId(sessionId: Int): AudioTrack.Builder

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
Return
AudioTrack.Builder the same Builder instance. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException

setTransferMode

Added in API level 23
open fun setTransferMode(mode: Int): AudioTrack.Builder

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 android.media.AudioTrack#MODE_STATIC, or android.media.AudioTrack#MODE_STREAM
Return
AudioTrack.Builder the same Builder instance. This value cannot be null.
Exceptions
java.lang.IllegalArgumentException