Skip to content

Most visited

Recently visited

navigation
Added in API level 3

AudioFormat

public class AudioFormat
extends Object

java.lang.Object
   ↳ android.media.AudioFormat


The AudioFormat class is used to access a number of audio format and channel configuration constants. They are for instance used in AudioTrack and AudioRecord, as valid values in individual parameters of constructors like AudioTrack(int, int, int, int, int, int), where the fourth parameter is one of the AudioFormat.ENCODING_* constants. The AudioFormat constants are also used in MediaFormat to specify audio related values commonly used in media, such as for KEY_CHANNEL_MASK.

The AudioFormat.Builder class can be used to create instances of the AudioFormat format class. Refer to AudioFormat.Builder for documentation on the mechanics of the configuration and building of such instances. Here we describe the main concepts that the AudioFormat class allow you to convey in each instance, they are:

  1. sample rate
  2. encoding
  3. channel masks

Closely associated with the AudioFormat is the notion of an audio frame, which is used throughout the documentation to represent the minimum size complete unit of audio data.

Sample rate

Expressed in Hz, the sample rate in an AudioFormat instance expresses the number of audio samples for each channel per second in the content you are playing or recording. It is not the sample rate at which content is rendered or produced. For instance a sound at a media sample rate of 8000Hz can be played on a device operating at a sample rate of 48000Hz; the sample rate conversion is automatically handled by the platform, it will not play at 6x speed.

As of API M, sample rates up to 192kHz are supported for AudioRecord and AudioTrack, with sample rate conversion performed as needed. To improve efficiency and avoid lossy conversions, it is recommended to match the sample rate for AudioRecord and AudioTrack to the endpoint device sample rate, and limit the sample rate to no more than 48kHz unless there are special device capabilities that warrant a higher rate.

Encoding

Audio encoding is used to describe the bit representation of audio data, which can be either linear PCM or compressed audio, such as AC3 or DTS.

For linear PCM, the audio encoding describes the sample size, 8 bits, 16 bits, or 32 bits, and the sample representation, integer or float.

For compressed audio, the encoding specifies the method of compression, for example ENCODING_AC3 and ENCODING_DTS. The compressed audio data is typically stored as bytes in a byte array or ByteBuffer. When a compressed audio encoding is specified for an AudioTrack, it creates a direct (non-mixed) track for output to an endpoint (such as HDMI) capable of decoding the compressed audio. For (most) other endpoints, which are not capable of decoding such compressed audio, you will need to decode the data first, typically by creating a MediaCodec. Alternatively, one may use MediaPlayer for playback of compressed audio files or streams.

When compressed audio is sent out through a direct AudioTrack, it need not be written in exact multiples of the audio access unit; this differs from MediaCodec input buffers.

Channel mask

Channel masks are used in AudioTrack and AudioRecord to describe the samples and their arrangement in the audio frame. They are also used in the endpoint (e.g. a USB audio interface, a DAC connected to headphones) to specify allowable configurations of a particular device.
As of API M, there are two types of channel masks: channel position masks and channel index masks.

Channel position masks
Channel position masks are the original Android channel masks, and are used since API BASE. For input and output, they imply a positional nature - the location of a speaker or a microphone for recording or playback.
For a channel position mask, each allowed channel position corresponds to a bit in the channel mask. If that channel position is present in the audio frame, that bit is set, otherwise it is zero. The order of the bits (from lsb to msb) corresponds to the order of that position's sample in the audio frame.
The canonical channel position masks by channel count are as follows:
channel countchannel position mask
1CHANNEL_OUT_MONO
2CHANNEL_OUT_STEREO
3CHANNEL_OUT_STEREO | CHANNEL_OUT_FRONT_CENTER
4CHANNEL_OUT_QUAD
5CHANNEL_OUT_QUAD | CHANNEL_OUT_FRONT_CENTER
6CHANNEL_OUT_5POINT1
7CHANNEL_OUT_5POINT1 | CHANNEL_OUT_BACK_CENTER
8CHANNEL_OUT_7POINT1_SURROUND

These masks are an ORed composite of individual channel masks. For example CHANNEL_OUT_STEREO is composed of CHANNEL_OUT_FRONT_LEFT and CHANNEL_OUT_FRONT_RIGHT.
Channel index masks
Channel index masks are introduced in API M. They allow the selection of a particular channel from the source or sink endpoint by number, i.e. the first channel, the second channel, and so forth. This avoids problems with artificially assigning positions to channels of an endpoint, or figuring what the ith position bit is within an endpoint's channel position mask etc.
Here's an example where channel index masks address this confusion: dealing with a 4 channel USB device. Using a position mask, and based on the channel count, this would be a CHANNEL_OUT_QUAD device, but really one is only interested in channel 0 through channel 3. The USB device would then have the following individual bit channel masks: CHANNEL_OUT_FRONT_LEFT, CHANNEL_OUT_FRONT_RIGHT, CHANNEL_OUT_BACK_LEFT and CHANNEL_OUT_BACK_RIGHT. But which is channel 0 and which is channel 3?
For a channel index mask, each channel number is represented as a bit in the mask, from the lsb (channel 0) upwards to the msb, numerically this bit value is 1 << channelNumber. A set bit indicates that channel is present in the audio frame, otherwise it is cleared. The order of the bits also correspond to that channel number's sample order in the audio frame.
For the previous 4 channel USB device example, the device would have a channel index mask 0xF. Suppose we wanted to select only the first and the third channels; this would correspond to a channel index mask 0x5 (the first and third bits set). If an AudioTrack uses this channel index mask, the audio frame would consist of two samples, the first sample of each frame routed to channel 0, and the second sample of each frame routed to channel 2. The canonical channel index masks by channel count are given by the formula (1 << channelCount) - 1.
Use cases

Audio Frame

For linear PCM, an audio frame consists of a set of samples captured at the same time, whose count and channel association are given by the channel mask, and whose sample contents are specified by the encoding. For example, a stereo 16 bit PCM frame consists of two 16 bit linear PCM samples, with a frame size of 4 bytes. For compressed audio, an audio frame may alternately refer to an access unit of compressed data bytes that is logically grouped together for decoding and bitstream access (e.g. MediaCodec), or a single byte of compressed data (e.g. AudioTrack.getBufferSizeInFrames()), or the linear PCM frame result from decoding the compressed data (e.g.AudioTrack.getPlaybackHeadPosition()), depending on the context where audio frame is used.

Summary

Nested classes

class AudioFormat.Builder

Builder class for AudioFormat objects. 

Constants

int CHANNEL_CONFIGURATION_DEFAULT

This constant was deprecated in API level 5. Use CHANNEL_OUT_DEFAULT or CHANNEL_IN_DEFAULT instead.

int CHANNEL_CONFIGURATION_INVALID

This constant was deprecated in API level 5. Use CHANNEL_INVALID instead.

int CHANNEL_CONFIGURATION_MONO

This constant was deprecated in API level 5. Use CHANNEL_OUT_MONO or CHANNEL_IN_MONO instead.

int CHANNEL_CONFIGURATION_STEREO

This constant was deprecated in API level 5. Use CHANNEL_OUT_STEREO or CHANNEL_IN_STEREO instead.

int CHANNEL_INVALID

Invalid audio channel mask

int CHANNEL_IN_BACK

int CHANNEL_IN_BACK_PROCESSED

int CHANNEL_IN_DEFAULT

int CHANNEL_IN_FRONT

int CHANNEL_IN_FRONT_PROCESSED

int CHANNEL_IN_LEFT

int CHANNEL_IN_LEFT_PROCESSED

int CHANNEL_IN_MONO

int CHANNEL_IN_PRESSURE

int CHANNEL_IN_RIGHT

int CHANNEL_IN_RIGHT_PROCESSED

int CHANNEL_IN_STEREO

int CHANNEL_IN_VOICE_DNLINK

int CHANNEL_IN_VOICE_UPLINK

int CHANNEL_IN_X_AXIS

int CHANNEL_IN_Y_AXIS

int CHANNEL_IN_Z_AXIS

int CHANNEL_OUT_5POINT1

int CHANNEL_OUT_7POINT1

This constant was deprecated in API level 23. Not the typical 7.1 surround configuration. Use CHANNEL_OUT_7POINT1_SURROUND instead.

int CHANNEL_OUT_7POINT1_SURROUND

int CHANNEL_OUT_BACK_CENTER

int CHANNEL_OUT_BACK_LEFT

int CHANNEL_OUT_BACK_RIGHT

int CHANNEL_OUT_DEFAULT

Default audio channel mask

int CHANNEL_OUT_FRONT_CENTER

int CHANNEL_OUT_FRONT_LEFT

int CHANNEL_OUT_FRONT_LEFT_OF_CENTER

int CHANNEL_OUT_FRONT_RIGHT

int CHANNEL_OUT_FRONT_RIGHT_OF_CENTER

int CHANNEL_OUT_LOW_FREQUENCY

int CHANNEL_OUT_MONO

int CHANNEL_OUT_QUAD

int CHANNEL_OUT_SIDE_LEFT

int CHANNEL_OUT_SIDE_RIGHT

int CHANNEL_OUT_STEREO

int CHANNEL_OUT_SURROUND

int ENCODING_AC3

Audio data format: AC-3 compressed

int ENCODING_DEFAULT

Default audio data format

int ENCODING_DTS

Audio data format: DTS compressed

int ENCODING_DTS_HD

Audio data format: DTS HD compressed

int ENCODING_E_AC3

Audio data format: E-AC-3 compressed

int ENCODING_INVALID

Invalid audio data format

int ENCODING_PCM_16BIT

Audio data format: PCM 16 bit per sample.

int ENCODING_PCM_8BIT

Audio data format: PCM 8 bit per sample.

int ENCODING_PCM_FLOAT

Audio data format: single-precision floating-point per sample

Public methods

int getChannelCount()

Return the channel count.

int getChannelIndexMask()

Return the channel index mask.

int getChannelMask()

Return the channel mask.

int getEncoding()

Return the encoding.

int getSampleRate()

Return the sample rate.

String toString()

Returns a string containing a concise, human-readable description of this object.

Inherited methods

From class java.lang.Object

Constants

CHANNEL_CONFIGURATION_DEFAULT

Added in API level 3
int CHANNEL_CONFIGURATION_DEFAULT

This constant was deprecated in API level 5.
Use CHANNEL_OUT_DEFAULT or CHANNEL_IN_DEFAULT instead.

Constant Value: 1 (0x00000001)

CHANNEL_CONFIGURATION_INVALID

Added in API level 3
int CHANNEL_CONFIGURATION_INVALID

This constant was deprecated in API level 5.
Use CHANNEL_INVALID instead.

Constant Value: 0 (0x00000000)

CHANNEL_CONFIGURATION_MONO

Added in API level 3
int CHANNEL_CONFIGURATION_MONO

This constant was deprecated in API level 5.
Use CHANNEL_OUT_MONO or CHANNEL_IN_MONO instead.

Constant Value: 2 (0x00000002)

CHANNEL_CONFIGURATION_STEREO

Added in API level 3
int CHANNEL_CONFIGURATION_STEREO

This constant was deprecated in API level 5.
Use CHANNEL_OUT_STEREO or CHANNEL_IN_STEREO instead.

Constant Value: 3 (0x00000003)

CHANNEL_INVALID

Added in API level 5
int CHANNEL_INVALID

Invalid audio channel mask

Constant Value: 0 (0x00000000)

CHANNEL_IN_BACK

Added in API level 5
int CHANNEL_IN_BACK

Constant Value: 32 (0x00000020)

CHANNEL_IN_BACK_PROCESSED

Added in API level 5
int CHANNEL_IN_BACK_PROCESSED

Constant Value: 512 (0x00000200)

CHANNEL_IN_DEFAULT

Added in API level 5
int CHANNEL_IN_DEFAULT

Constant Value: 1 (0x00000001)

CHANNEL_IN_FRONT

Added in API level 5
int CHANNEL_IN_FRONT

Constant Value: 16 (0x00000010)

CHANNEL_IN_FRONT_PROCESSED

Added in API level 5
int CHANNEL_IN_FRONT_PROCESSED

Constant Value: 256 (0x00000100)

CHANNEL_IN_LEFT

Added in API level 5
int CHANNEL_IN_LEFT

Constant Value: 4 (0x00000004)

CHANNEL_IN_LEFT_PROCESSED

Added in API level 5
int CHANNEL_IN_LEFT_PROCESSED

Constant Value: 64 (0x00000040)

CHANNEL_IN_MONO

Added in API level 5
int CHANNEL_IN_MONO

Constant Value: 16 (0x00000010)

CHANNEL_IN_PRESSURE

Added in API level 5
int CHANNEL_IN_PRESSURE

Constant Value: 1024 (0x00000400)

CHANNEL_IN_RIGHT

Added in API level 5
int CHANNEL_IN_RIGHT

Constant Value: 8 (0x00000008)

CHANNEL_IN_RIGHT_PROCESSED

Added in API level 5
int CHANNEL_IN_RIGHT_PROCESSED

Constant Value: 128 (0x00000080)

CHANNEL_IN_STEREO

Added in API level 5
int CHANNEL_IN_STEREO

Constant Value: 12 (0x0000000c)

CHANNEL_IN_VOICE_DNLINK

Added in API level 5
int CHANNEL_IN_VOICE_DNLINK

Constant Value: 32768 (0x00008000)

CHANNEL_IN_VOICE_UPLINK

Added in API level 5
int CHANNEL_IN_VOICE_UPLINK

Constant Value: 16384 (0x00004000)

CHANNEL_IN_X_AXIS

Added in API level 5
int CHANNEL_IN_X_AXIS

Constant Value: 2048 (0x00000800)

CHANNEL_IN_Y_AXIS

Added in API level 5
int CHANNEL_IN_Y_AXIS

Constant Value: 4096 (0x00001000)

CHANNEL_IN_Z_AXIS

Added in API level 5
int CHANNEL_IN_Z_AXIS

Constant Value: 8192 (0x00002000)

CHANNEL_OUT_5POINT1

Added in API level 5
int CHANNEL_OUT_5POINT1

Constant Value: 252 (0x000000fc)

CHANNEL_OUT_7POINT1

Added in API level 5
int CHANNEL_OUT_7POINT1

This constant was deprecated in API level 23.
Not the typical 7.1 surround configuration. Use CHANNEL_OUT_7POINT1_SURROUND instead.

Constant Value: 1020 (0x000003fc)

CHANNEL_OUT_7POINT1_SURROUND

Added in API level 23
int CHANNEL_OUT_7POINT1_SURROUND

Constant Value: 6396 (0x000018fc)

CHANNEL_OUT_BACK_CENTER

Added in API level 5
int CHANNEL_OUT_BACK_CENTER

Constant Value: 1024 (0x00000400)

CHANNEL_OUT_BACK_LEFT

Added in API level 5
int CHANNEL_OUT_BACK_LEFT

Constant Value: 64 (0x00000040)

CHANNEL_OUT_BACK_RIGHT

Added in API level 5
int CHANNEL_OUT_BACK_RIGHT

Constant Value: 128 (0x00000080)

CHANNEL_OUT_DEFAULT

Added in API level 5
int CHANNEL_OUT_DEFAULT

Default audio channel mask

Constant Value: 1 (0x00000001)

CHANNEL_OUT_FRONT_CENTER

Added in API level 5
int CHANNEL_OUT_FRONT_CENTER

Constant Value: 16 (0x00000010)

CHANNEL_OUT_FRONT_LEFT

Added in API level 5
int CHANNEL_OUT_FRONT_LEFT

Constant Value: 4 (0x00000004)

CHANNEL_OUT_FRONT_LEFT_OF_CENTER

Added in API level 5
int CHANNEL_OUT_FRONT_LEFT_OF_CENTER

Constant Value: 256 (0x00000100)

CHANNEL_OUT_FRONT_RIGHT

Added in API level 5
int CHANNEL_OUT_FRONT_RIGHT

Constant Value: 8 (0x00000008)

CHANNEL_OUT_FRONT_RIGHT_OF_CENTER

Added in API level 5
int CHANNEL_OUT_FRONT_RIGHT_OF_CENTER

Constant Value: 512 (0x00000200)

CHANNEL_OUT_LOW_FREQUENCY

Added in API level 5
int CHANNEL_OUT_LOW_FREQUENCY

Constant Value: 32 (0x00000020)

CHANNEL_OUT_MONO

Added in API level 5
int CHANNEL_OUT_MONO

Constant Value: 4 (0x00000004)

CHANNEL_OUT_QUAD

Added in API level 5
int CHANNEL_OUT_QUAD

Constant Value: 204 (0x000000cc)

CHANNEL_OUT_SIDE_LEFT

Added in API level 21
int CHANNEL_OUT_SIDE_LEFT

Constant Value: 2048 (0x00000800)

CHANNEL_OUT_SIDE_RIGHT

Added in API level 21
int CHANNEL_OUT_SIDE_RIGHT

Constant Value: 4096 (0x00001000)

CHANNEL_OUT_STEREO

Added in API level 5
int CHANNEL_OUT_STEREO

Constant Value: 12 (0x0000000c)

CHANNEL_OUT_SURROUND

Added in API level 5
int CHANNEL_OUT_SURROUND

Constant Value: 1052 (0x0000041c)

ENCODING_AC3

Added in API level 21
int ENCODING_AC3

Audio data format: AC-3 compressed

Constant Value: 5 (0x00000005)

ENCODING_DEFAULT

Added in API level 3
int ENCODING_DEFAULT

Default audio data format

Constant Value: 1 (0x00000001)

ENCODING_DTS

Added in API level 23
int ENCODING_DTS

Audio data format: DTS compressed

Constant Value: 7 (0x00000007)

ENCODING_DTS_HD

Added in API level 23
int ENCODING_DTS_HD

Audio data format: DTS HD compressed

Constant Value: 8 (0x00000008)

ENCODING_E_AC3

Added in API level 21
int ENCODING_E_AC3

Audio data format: E-AC-3 compressed

Constant Value: 6 (0x00000006)

ENCODING_INVALID

Added in API level 3
int ENCODING_INVALID

Invalid audio data format

Constant Value: 0 (0x00000000)

ENCODING_PCM_16BIT

Added in API level 3
int ENCODING_PCM_16BIT

Audio data format: PCM 16 bit per sample. Guaranteed to be supported by devices.

Constant Value: 2 (0x00000002)

ENCODING_PCM_8BIT

Added in API level 3
int ENCODING_PCM_8BIT

Audio data format: PCM 8 bit per sample. Not guaranteed to be supported by devices.

Constant Value: 3 (0x00000003)

ENCODING_PCM_FLOAT

Added in API level 21
int ENCODING_PCM_FLOAT

Audio data format: single-precision floating-point per sample

Constant Value: 4 (0x00000004)

Public methods

getChannelCount

Added in API level 23
int getChannelCount ()

Return the channel count.

Returns
int the channel count derived from the channel position mask or the channel index mask. Zero is returned if both the channel position mask and the channel index mask are not set.

getChannelIndexMask

Added in API level 23
int getChannelIndexMask ()

Return the channel index mask. See the section on channel masks for more information about the difference between index-based masks, and position-based masks (as returned by getChannelMask()).

Returns
int one of the values that can be set in setChannelIndexMask(int) or CHANNEL_INVALID if not set or an invalid mask was used.

getChannelMask

Added in API level 21
int getChannelMask ()

Return the channel mask. See the section on channel masks for more information about the difference between index-based masks(as returned by getChannelIndexMask()) and the position-based mask returned by this function.

Returns
int one of the values that can be set in setChannelMask(int) or CHANNEL_INVALID if not set.

getEncoding

Added in API level 21
int getEncoding ()

Return the encoding. See the section on encodings for more information about the different types of supported audio encoding.

Returns
int one of the values that can be set in setEncoding(int) or ENCODING_INVALID if not set.

getSampleRate

Added in API level 21
int getSampleRate ()

Return the sample rate.

Returns
int one of the values that can be set in setSampleRate(int) or 0 if not set.

toString

Added in API level 3
String toString ()

Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression:

   getClass().getName() + '@' + Integer.toHexString(hashCode())

See Writing a useful toString method if you intend implementing your own toString method.

Returns
String a printable representation of this object.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.