Builder

class Builder
kotlin.Any
   ↳ android.media.AudioFormat.Builder

Builder class for AudioFormat objects. Use this class to configure and create an AudioFormat instance. By setting format characteristics such as audio encoding, channel mask or sample rate, you indicate which of those are to vary from the default behavior on this device wherever this audio format is used. See AudioFormat for a complete description of the different parameters that can be used to configure an AudioFormat instance.

AudioFormat is for instance used in AudioTrack#AudioTrack(AudioAttributes, AudioFormat, int, int, int). In this constructor, every format characteristic set on the Builder (e.g. with #setSampleRate(int)) will alter the default values used by an AudioTrack. In this case for audio playback with AudioTrack, the sample rate set in the Builder would override the platform output sample rate which would otherwise be selected by default.
Requires API level 21 (Android 5.0, Lollipop)

Summary

Public constructors

Constructs a new Builder with none of the format characteristics set.

Constructs a new Builder from a given AudioFormat.

Public methods
open AudioFormat.Builder
setChannelIndexMask(channelIndexMask: Int)

Sets the channel index mask.

open AudioFormat.Builder!
setSampleRate(sampleRate: Int)

Sets the sample rate.

open AudioFormat.Builder!
setEncoding(encoding: Int)

Sets the data encoding format.

open AudioFormat.Builder
setChannelMask(channelMask: Int)

Sets the channel position mask.

open AudioFormat!

Combines all of the format characteristics that have been set and return a new AudioFormat object.

Public constructors

<init>

Builder()

Constructs a new Builder with none of the format characteristics set.

<init>

Builder(af: AudioFormat!)

Constructs a new Builder from a given AudioFormat.

Parameters
af AudioFormat!: the AudioFormat object whose data will be reused in the new Builder.

Public methods

setChannelIndexMask

added in API level 23
open fun setChannelIndexMask(channelIndexMask: Int): AudioFormat.Builder

Sets the channel index mask. A channel index mask specifies the association of audio samples in the frame with numbered endpoint channels. The i-th bit in the channel index mask corresponds to the i-th endpoint channel. For example, an endpoint with four channels is represented as index mask bits 0 through 3. This #setChannelMask(int) for a positional mask interpretation.

Both AudioTrack and AudioRecord support a channel index mask. If a channel index mask is specified it is used, otherwise the channel position mask specified by setChannelMask is used. For AudioTrack and AudioRecord, a channel position mask is not required if a channel index mask is specified.
Requires API level 23 (Android 6.0, Marshmallow)

Parameters
channelIndexMask Int: describes the configuration of the audio channels.

For output, the channelIndexMask is an OR-ed combination of bits representing the mapping of AudioTrack write samples to output sink channels. For example, a mask of 0xa, or binary 1010, means the AudioTrack write frame consists of two samples, which are routed to the second and the fourth channels of the output sink. Unmatched output sink channels are zero filled and unmatched AudioTrack write samples are dropped.

For input, the channelIndexMask is an OR-ed combination of bits representing the mapping of input source channels to AudioRecord read samples. For example, a mask of 0x5, or binary 101, will read from the first and third channel of the input source device and store them in the first and second sample of the AudioRecord read frame. Unmatched input source channels are dropped and unmatched AudioRecord read samples are zero filled.

Return
AudioFormat.Builder: the same Builder instance. This value will never be null.
Exceptions
IllegalArgumentException if the channel index mask is invalid or if both channel index mask and channel position mask are specified but do not have the same channel count.

setSampleRate

added in API level 21
open fun setSampleRate(sampleRate: Int): AudioFormat.Builder!

Sets the sample rate.
Requires API level 21 (Android 5.0, Lollipop)

Parameters
sampleRate Int: the sample rate expressed in Hz
Return
AudioFormat.Builder!: the same Builder instance.
Exceptions
java.lang.IllegalArgumentException

setChannelMask

added in API level 21
open fun setChannelMask(channelMask: Int): AudioFormat.Builder

Sets the channel position mask. The channel position mask specifies the association between audio samples in a frame with named endpoint channels. The samples in the frame correspond to the named set bits in the channel position mask, in ascending bit order. See #setChannelIndexMask(int) to specify channels based on endpoint numbered channels. This

Parameters
channelMask Int: describes the configuration of the audio channels.

For output, the channelMask can be an OR-ed combination of channel position masks, e.g. AudioFormat#CHANNEL_OUT_FRONT_LEFT, AudioFormat#CHANNEL_OUT_FRONT_RIGHT, AudioFormat#CHANNEL_OUT_FRONT_CENTER, AudioFormat#CHANNEL_OUT_LOW_FREQUENCY AudioFormat#CHANNEL_OUT_BACK_LEFT, AudioFormat#CHANNEL_OUT_BACK_RIGHT, AudioFormat#CHANNEL_OUT_BACK_CENTER, AudioFormat#CHANNEL_OUT_SIDE_LEFT, AudioFormat#CHANNEL_OUT_SIDE_RIGHT.

For a valid AudioTrack channel position mask, the following conditions apply:
(1) at most eight channel positions may be used;
(2) right/left pairs should be matched.

For input or AudioRecord, the mask should be AudioFormat#CHANNEL_IN_MONO or AudioFormat#CHANNEL_IN_STEREO. AudioFormat#CHANNEL_IN_MONO is guaranteed to work on all devices.

Return
AudioFormat.Builder: the same Builder instance. This value will never be null.
Exceptions
IllegalArgumentException if the channel mask is invalid or if both channel index mask and channel position mask are specified but do not have the same channel count.

build

added in API level 21
open fun build(): AudioFormat!

Combines all of the format characteristics that have been set and return a new AudioFormat object.
Requires API level 21 (Android 5.0, Lollipop)

Return
AudioFormat!: a new AudioFormat object