AudioFormat.Builder - Android SDK

Summary: Ctors | Methods | Inherited Methods | [Expand All]

Added in API level 21

public static class

AudioFormat.Builder

extends Object

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

Class Overview

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(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.

Summary

Public Constructors
	AudioFormat.Builder() Constructs a new Builder with none of the format characteristics set.
	AudioFormat.Builder(AudioFormat af) Constructs a new Builder from a given `AudioFormat`.

Public Methods
AudioFormat	build() Combines all of the format characteristics that have been set and return a new `AudioFormat` object.
AudioFormat.Builder	setChannelIndexMask(int channelIndexMask) Sets the channel index mask.
AudioFormat.Builder	setChannelMask(int channelMask) Sets the channel position mask.
AudioFormat.Builder	setEncoding(int encoding) Sets the data encoding format.
AudioFormat.Builder	setSampleRate(int sampleRate) Sets the sample rate.

[Expand]

Inherited Methods

From class java.lang.Object

Object	clone() Creates and returns a copy of this `Object`.
boolean	equals(Object o) Compares this instance with the specified object and indicates if they are equal.
void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
final Class<?>	getClass() Returns the unique instance of `Class` that represents this object's class.
int	hashCode() Returns an integer hash code for this object.
final void	notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
final void	notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the `wait()` methods) to be woken up.
String	toString() Returns a string containing a concise, human-readable description of this object.
final void	wait() Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object.
final void	wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.
final void	wait(long millis) Causes the calling thread to wait until another thread calls the `notify()` or `notifyAll()` method of this object or until the specified timeout expires.

Public Constructors

public AudioFormat.Builder ()

Added in API level 21

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

public AudioFormat.Builder (AudioFormat af)

Added in API level 21

Constructs a new Builder from a given AudioFormat.

Parameters

af	the `AudioFormat` object whose data will be reused in the new Builder.

Public Methods

public AudioFormat build ()

Added in API level 21

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

Returns

a new AudioFormat object

public AudioFormat.Builder setChannelIndexMask (int channelIndexMask)

Added in API level 23

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.

Parameters

channelIndexMask

channelIndexMask	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.

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.

Returns

the same Builder instance.

Throws

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.

public AudioFormat.Builder setChannelMask (int channelMask)

Added in API level 21

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

channelMask	describes the configuration of the audio channels. For output, the channelMask can be an OR-ed combination of channel position masks, e.g. `CHANNEL_OUT_FRONT_LEFT`, `CHANNEL_OUT_FRONT_RIGHT`, `CHANNEL_OUT_FRONT_CENTER`, `CHANNEL_OUT_LOW_FREQUENCY` `CHANNEL_OUT_BACK_LEFT`, `CHANNEL_OUT_BACK_RIGHT`, `CHANNEL_OUT_BACK_CENTER`, `CHANNEL_OUT_SIDE_LEFT`, `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 `CHANNEL_IN_MONO` or `CHANNEL_IN_STEREO`. `CHANNEL_IN_MONO` is guaranteed to work on all devices.

describes the configuration of the audio channels.

For output, the channelMask can be an OR-ed combination of channel position masks, e.g. CHANNEL_OUT_FRONT_LEFT, CHANNEL_OUT_FRONT_RIGHT, CHANNEL_OUT_FRONT_CENTER, CHANNEL_OUT_LOW_FREQUENCY CHANNEL_OUT_BACK_LEFT, CHANNEL_OUT_BACK_RIGHT, CHANNEL_OUT_BACK_CENTER, CHANNEL_OUT_SIDE_LEFT, 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 CHANNEL_IN_MONO or CHANNEL_IN_STEREO. CHANNEL_IN_MONO is guaranteed to work on all devices.

Returns

the same Builder instance.

Throws

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.

public AudioFormat.Builder setEncoding (int encoding)

Added in API level 21

Sets the data encoding format.

Parameters

encoding	one of `ENCODING_DEFAULT`, `ENCODING_PCM_8BIT`, `ENCODING_PCM_16BIT`, `ENCODING_PCM_FLOAT`, `ENCODING_AC3`, `ENCODING_E_AC3`. `ENCODING_DTS`, `ENCODING_DTS_HD`.

Returns

the same Builder instance.

Throws

IllegalArgumentException

public AudioFormat.Builder setSampleRate (int sampleRate)

Added in API level 21

Sets the sample rate.

Parameters

sampleRate	the sample rate expressed in Hz

Returns

the same Builder instance.

Throws

IllegalArgumentException

Results

Interfaces

Classes

Exceptions

AudioFormat.Builder

Class Overview

Summary

Public Constructors

public AudioFormat.Builder ()

public AudioFormat.Builder (AudioFormat af)

Parameters

Public Methods

public AudioFormat build ()

Returns

public AudioFormat.Builder setChannelIndexMask (int channelIndexMask)

Parameters

Returns

Throws

public AudioFormat.Builder setChannelMask (int channelMask)

Parameters

Returns

Throws

public AudioFormat.Builder setEncoding (int encoding)

Parameters

Returns

Throws

public AudioFormat.Builder setSampleRate (int sampleRate)

Parameters

Returns

Throws