public static class AudioFormat.Builder extends Object
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.
Constructor and Description |
---|
Builder()
Constructs a new Builder with none of the format characteristics set.
|
Builder(AudioFormat af)
Constructs a new Builder from a given
AudioFormat . |
Modifier and Type | Method and Description |
---|---|
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.
|
public Builder()
public Builder(AudioFormat af)
AudioFormat
.af
- the AudioFormat
object whose data will be reused in the new Builder.public AudioFormat build()
AudioFormat
object.AudioFormat
objectpublic AudioFormat.Builder setEncoding(int encoding) throws IllegalArgumentException
encoding
- one of AudioFormat.ENCODING_DEFAULT
,
AudioFormat.ENCODING_PCM_8BIT
,
AudioFormat.ENCODING_PCM_16BIT
,
AudioFormat.ENCODING_PCM_FLOAT
,
AudioFormat.ENCODING_AC3
,
AudioFormat.ENCODING_E_AC3
.
AudioFormat.ENCODING_DTS
,
AudioFormat.ENCODING_DTS_HD
.IllegalArgumentException
public AudioFormat.Builder setChannelMask(int channelMask)
setChannelIndexMask(int)
to specify channels
based on endpoint numbered channels. This Parameters:
channelMask
- 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.
Builder
instance.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 setChannelIndexMask(int channelIndexMask)
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.
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.
Builder
instance.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 setSampleRate(int sampleRate) throws IllegalArgumentException
sampleRate
- the sample rate expressed in HzIllegalArgumentException