/*
* Copyright (C) 2008 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.media;
import android.annotation.IntDef;
import android.annotation.NonNull;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.util.Arrays;
/**
* The {@link AudioFormat} class is used to access a number of audio format and
* channel configuration constants. They are for instance used
* in {@link AudioTrack} and {@link AudioRecord}, as valid values in individual parameters of
* constructors like {@link AudioTrack#AudioTrack(int, int, int, int, int, int)}, where the fourth
* parameter is one of the <code>AudioFormat.ENCODING_*</code> constants.
* The <code>AudioFormat</code> constants are also used in {@link MediaFormat} to specify
* audio related values commonly used in media, such as for {@link MediaFormat#KEY_CHANNEL_MASK}.
* <p>The {@link AudioFormat.Builder} class can be used to create instances of
* the <code>AudioFormat</code> format class.
* Refer to
* {@link AudioFormat.Builder} for documentation on the mechanics of the configuration and building
* of such instances. Here we describe the main concepts that the <code>AudioFormat</code> class
* allow you to convey in each instance, they are:
* <ol>
* <li><a href="#sampleRate">sample rate</a>
* <li><a href="#encoding">encoding</a>
* <li><a href="#channelMask">channel masks</a>
* </ol>
* <p>Closely associated with the <code>AudioFormat</code> is the notion of an
* <a href="#audioFrame">audio frame</a>, which is used throughout the documentation
* to represent the minimum size complete unit of audio data.
*
* <h4 id="sampleRate">Sample rate</h4>
* <p>Expressed in Hz, the sample rate in an <code>AudioFormat</code> 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.
*
* <p>As of API {@link android.os.Build.VERSION_CODES#M},
* sample rates up to 192kHz are supported
* for <code>AudioRecord</code> and <code>AudioTrack</code>, with sample rate conversion
* performed as needed.
* To improve efficiency and avoid lossy conversions, it is recommended to match the sample rate
* for <code>AudioRecord</code> and <code>AudioTrack</code> 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.
*
* <h4 id="encoding">Encoding</h4>
* <p>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.
* <p>For linear PCM, the audio encoding describes the sample size, 8 bits, 16 bits, or 32 bits,
* and the sample representation, integer or float.
* <ul>
* <li> {@link #ENCODING_PCM_8BIT}: The audio sample is a 8 bit unsigned integer in the
* range [0, 255], with a 128 offset for zero. This is typically stored as a Java byte in a
* byte array or ByteBuffer. Since the Java byte is <em>signed</em>,
* be careful with math operations and conversions as the most significant bit is inverted.
* </li>
* <li> {@link #ENCODING_PCM_16BIT}: The audio sample is a 16 bit signed integer
* typically stored as a Java short in a short array, but when the short
* is stored in a ByteBuffer, it is native endian (as compared to the default Java big endian).
* The short has full range from [-32768, 32767],
* and is sometimes interpreted as fixed point Q.15 data.
* </li>
* <li> {@link #ENCODING_PCM_FLOAT}: Introduced in
* API {@link android.os.Build.VERSION_CODES#LOLLIPOP}, this encoding specifies that
* the audio sample is a 32 bit IEEE single precision float. The sample can be
* manipulated as a Java float in a float array, though within a ByteBuffer
* it is stored in native endian byte order.
* The nominal range of <code>ENCODING_PCM_FLOAT</code> audio data is [-1.0, 1.0].
* It is implementation dependent whether the positive maximum of 1.0 is included
* in the interval. Values outside of the nominal range are clamped before
* sending to the endpoint device. Beware that
* the handling of NaN is undefined; subnormals may be treated as zero; and
* infinities are generally clamped just like other values for <code>AudioTrack</code>
* – try to avoid infinities because they can easily generate a NaN.
* <br>
* To achieve higher audio bit depth than a signed 16 bit integer short,
* it is recommended to use <code>ENCODING_PCM_FLOAT</code> for audio capture, processing,
* and playback.
* Floats are efficiently manipulated by modern CPUs,
* have greater precision than 24 bit signed integers,
* and have greater dynamic range than 32 bit signed integers.
* <code>AudioRecord</code> as of API {@link android.os.Build.VERSION_CODES#M} and
* <code>AudioTrack</code> as of API {@link android.os.Build.VERSION_CODES#LOLLIPOP}
* support <code>ENCODING_PCM_FLOAT</code>.
* </li>
* </ul>
* <p>For compressed audio, the encoding specifies the method of compression,
* for example {@link #ENCODING_AC3} and {@link #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 <code>AudioTrack</code>, 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 {@link MediaCodec}.
* Alternatively, one may use {@link MediaPlayer} for playback of compressed
* audio files or streams.
* <p>When compressed audio is sent out through a direct <code>AudioTrack</code>,
* it need not be written in exact multiples of the audio access unit;
* this differs from <code>MediaCodec</code> input buffers.
*
* <h4 id="channelMask">Channel mask</h4>
* <p>Channel masks are used in <code>AudioTrack</code> and <code>AudioRecord</code> 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.
* <br>As of API {@link android.os.Build.VERSION_CODES#M}, there are two types of channel masks:
* channel position masks and channel index masks.
*
* <h5 id="channelPositionMask">Channel position masks</h5>
* Channel position masks are the original Android channel masks, and are used since API
* {@link android.os.Build.VERSION_CODES#BASE}.
* For input and output, they imply a positional nature - the location of a speaker or a microphone
* for recording or playback.
* <br>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.
* <br>The canonical channel position masks by channel count are as follows:
* <br><table>
* <tr><td>channel count</td><td>channel position mask</td></tr>
* <tr><td>1</td><td>{@link #CHANNEL_OUT_MONO}</td></tr>
* <tr><td>2</td><td>{@link #CHANNEL_OUT_STEREO}</td></tr>
* <tr><td>3</td><td>{@link #CHANNEL_OUT_STEREO} | {@link #CHANNEL_OUT_FRONT_CENTER}</td></tr>
* <tr><td>4</td><td>{@link #CHANNEL_OUT_QUAD}</td></tr>
* <tr><td>5</td><td>{@link #CHANNEL_OUT_QUAD} | {@link #CHANNEL_OUT_FRONT_CENTER}</td></tr>
* <tr><td>6</td><td>{@link #CHANNEL_OUT_5POINT1}</td></tr>
* <tr><td>7</td><td>{@link #CHANNEL_OUT_5POINT1} | {@link #CHANNEL_OUT_BACK_CENTER}</td></tr>
* <tr><td>8</td><td>{@link #CHANNEL_OUT_7POINT1_SURROUND}</td></tr>
* </table>
* <br>These masks are an ORed composite of individual channel masks. For example
* {@link #CHANNEL_OUT_STEREO} is composed of {@link #CHANNEL_OUT_FRONT_LEFT} and
* {@link #CHANNEL_OUT_FRONT_RIGHT}.
*
* <h5 id="channelIndexMask">Channel index masks</h5>
* Channel index masks are introduced in API {@link android.os.Build.VERSION_CODES#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 i<sup>th</sup> position bit is within
* an endpoint's channel position mask etc.
* <br>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
* {@link #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:
* {@link #CHANNEL_OUT_FRONT_LEFT},
* {@link #CHANNEL_OUT_FRONT_RIGHT}, {@link #CHANNEL_OUT_BACK_LEFT}
* and {@link #CHANNEL_OUT_BACK_RIGHT}. But which is channel 0 and which is
* channel 3?
* <br>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
* <code>1 << channelNumber</code>.
* 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.
* <br>For the previous 4 channel USB device example, the device would have a channel index mask
* <code>0xF</code>. Suppose we wanted to select only the first and the third channels; this would
* correspond to a channel index mask <code>0x5</code> (the first and third bits set). If an
* <code>AudioTrack</code> 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
* <code>(1 << channelCount) - 1</code>.
*
* <h5>Use cases</h5>
* <ul>
* <li><i>Channel position mask for an endpoint:</i> <code>CHANNEL_OUT_FRONT_LEFT</code>,
* <code>CHANNEL_OUT_FRONT_CENTER</code>, etc. for HDMI home theater purposes.
* <li><i>Channel position mask for an audio stream:</i> Creating an <code>AudioTrack</code>
* to output movie content, where 5.1 multichannel output is to be written.
* <li><i>Channel index mask for an endpoint:</i> USB devices for which input and output do not
* correspond to left or right speaker or microphone.
* <li><i>Channel index mask for an audio stream:</i> An <code>AudioRecord</code> may only want the
* third and fourth audio channels of the endpoint (i.e. the second channel pair), and not care the
* about position it corresponds to, in which case the channel index mask is <code>0xC</code>.
* Multichannel <code>AudioRecord</code> sessions should use channel index masks.
* </ul>
* <h4 id="audioFrame">Audio Frame</h4>
* <p>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 <a href="#channelMask">channel mask</a>,
* and whose sample contents are specified by the <a href="#encoding">encoding</a>.
* 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. {@link MediaCodec}),
* or a single byte of compressed data (e.g. {@link AudioTrack#getBufferSizeInFrames()
* AudioTrack.getBufferSizeInFrames()}),
* or the linear PCM frame result from decoding the compressed data
* (e.g.{@link AudioTrack#getPlaybackHeadPosition()
* AudioTrack.getPlaybackHeadPosition()}),
* depending on the context where audio frame is used.
*/
public class AudioFormat {
//---------------------------------------------------------
// Constants
//--------------------
/** Invalid audio data format */
public static final int ENCODING_INVALID = 0;
/** Default audio data format */
public static final int ENCODING_DEFAULT = 1;
// These values must be kept in sync with core/jni/android_media_AudioFormat.h
// Also sync av/services/audiopolicy/managerdefault/ConfigParsingUtils.h
/** Audio data format: PCM 16 bit per sample. Guaranteed to be supported by devices. */
public static final int ENCODING_PCM_16BIT = 2;
/** Audio data format: PCM 8 bit per sample. Not guaranteed to be supported by devices. */
public static final int ENCODING_PCM_8BIT = 3;
/** Audio data format: single-precision floating-point per sample */
public static final int ENCODING_PCM_FLOAT = 4;
/** Audio data format: AC-3 compressed */
public static final int ENCODING_AC3 = 5;
/** Audio data format: E-AC-3 compressed */
public static final int ENCODING_E_AC3 = 6;
/** Audio data format: DTS compressed */
public static final int ENCODING_DTS = 7;
/** Audio data format: DTS HD compressed */
public static final int ENCODING_DTS_HD = 8;
/** Audio data format: MP3 compressed
* @hide
* */
public static final int ENCODING_MP3 = 9;
/** Audio data format: AAC LC compressed
* @hide
* */
public static final int ENCODING_AAC_LC = 10;
/** Audio data format: AAC HE V1 compressed
* @hide
* */
public static final int ENCODING_AAC_HE_V1 = 11;
/** Audio data format: AAC HE V2 compressed
* @hide
* */
public static final int ENCODING_AAC_HE_V2 = 12;
/** Invalid audio channel configuration */
/** @deprecated Use {@link #CHANNEL_INVALID} instead. */
@Deprecated public static final int CHANNEL_CONFIGURATION_INVALID = 0;
/** Default audio channel configuration */
/** @deprecated Use {@link #CHANNEL_OUT_DEFAULT} or {@link #CHANNEL_IN_DEFAULT} instead. */
@Deprecated public static final int CHANNEL_CONFIGURATION_DEFAULT = 1;
/** Mono audio configuration */
/** @deprecated Use {@link #CHANNEL_OUT_MONO} or {@link #CHANNEL_IN_MONO} instead. */
@Deprecated public static final int CHANNEL_CONFIGURATION_MONO = 2;
/** Stereo (2 channel) audio configuration */
/** @deprecated Use {@link #CHANNEL_OUT_STEREO} or {@link #CHANNEL_IN_STEREO} instead. */
@Deprecated public static final int CHANNEL_CONFIGURATION_STEREO = 3;
/** Invalid audio channel mask */
public static final int CHANNEL_INVALID = 0;
/** Default audio channel mask */
public static final int CHANNEL_OUT_DEFAULT = 1;
// Output channel mask definitions below are translated to the native values defined in
// in /system/media/audio/include/system/audio.h in the JNI code of AudioTrack
public static final int CHANNEL_OUT_FRONT_LEFT = 0x4;
public static final int CHANNEL_OUT_FRONT_RIGHT = 0x8;
public static final int CHANNEL_OUT_FRONT_CENTER = 0x10;
public static final int CHANNEL_OUT_LOW_FREQUENCY = 0x20;
public static final int CHANNEL_OUT_BACK_LEFT = 0x40;
public static final int CHANNEL_OUT_BACK_RIGHT = 0x80;
public static final int CHANNEL_OUT_FRONT_LEFT_OF_CENTER = 0x100;
public static final int CHANNEL_OUT_FRONT_RIGHT_OF_CENTER = 0x200;
public static final int CHANNEL_OUT_BACK_CENTER = 0x400;
public static final int CHANNEL_OUT_SIDE_LEFT = 0x800;
public static final int CHANNEL_OUT_SIDE_RIGHT = 0x1000;
/** @hide */
public static final int CHANNEL_OUT_TOP_CENTER = 0x2000;
/** @hide */
public static final int CHANNEL_OUT_TOP_FRONT_LEFT = 0x4000;
/** @hide */
public static final int CHANNEL_OUT_TOP_FRONT_CENTER = 0x8000;
/** @hide */
public static final int CHANNEL_OUT_TOP_FRONT_RIGHT = 0x10000;
/** @hide */
public static final int CHANNEL_OUT_TOP_BACK_LEFT = 0x20000;
/** @hide */
public static final int CHANNEL_OUT_TOP_BACK_CENTER = 0x40000;
/** @hide */
public static final int CHANNEL_OUT_TOP_BACK_RIGHT = 0x80000;
public static final int CHANNEL_OUT_MONO = CHANNEL_OUT_FRONT_LEFT;
public static final int CHANNEL_OUT_STEREO = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT);
// aka QUAD_BACK
public static final int CHANNEL_OUT_QUAD = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT |
CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT);
/** @hide */
public static final int CHANNEL_OUT_QUAD_SIDE = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT |
CHANNEL_OUT_SIDE_LEFT | CHANNEL_OUT_SIDE_RIGHT);
public static final int CHANNEL_OUT_SURROUND = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT |
CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_BACK_CENTER);
// aka 5POINT1_BACK
public static final int CHANNEL_OUT_5POINT1 = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT |
CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY | CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT);
/** @hide */
public static final int CHANNEL_OUT_5POINT1_SIDE = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT |
CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY |
CHANNEL_OUT_SIDE_LEFT | CHANNEL_OUT_SIDE_RIGHT);
// different from AUDIO_CHANNEL_OUT_7POINT1 used internally, and not accepted by AudioRecord.
/** @deprecated Not the typical 7.1 surround configuration. Use {@link #CHANNEL_OUT_7POINT1_SURROUND} instead. */
@Deprecated public static final int CHANNEL_OUT_7POINT1 = (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_FRONT_LEFT_OF_CENTER | CHANNEL_OUT_FRONT_RIGHT_OF_CENTER);
// matches AUDIO_CHANNEL_OUT_7POINT1
public static final int CHANNEL_OUT_7POINT1_SURROUND = (
CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_FRONT_RIGHT |
CHANNEL_OUT_SIDE_LEFT | CHANNEL_OUT_SIDE_RIGHT |
CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT |
CHANNEL_OUT_LOW_FREQUENCY);
// CHANNEL_OUT_ALL is not yet defined; if added then it should match AUDIO_CHANNEL_OUT_ALL
/**
* @hide
* Return the input channel mask corresponding to an output channel mask.
* This can be used for submix rerouting for the mask of the recorder to map to that of the mix.
* @param outMask a combination of the CHANNEL_OUT_* definitions, but not CHANNEL_OUT_DEFAULT
* @return a combination of CHANNEL_IN_* definitions matching an output channel mask
* @throws IllegalArgumentException
*/
public static int inChannelMaskFromOutChannelMask(int outMask) throws IllegalArgumentException {
if (outMask == CHANNEL_OUT_DEFAULT) {
throw new IllegalArgumentException(
"Illegal CHANNEL_OUT_DEFAULT channel mask for input.");
}
switch (channelCountFromOutChannelMask(outMask)) {
case 1:
return CHANNEL_IN_MONO;
case 2:
return CHANNEL_IN_STEREO;
default:
throw new IllegalArgumentException("Unsupported channel configuration for input.");
}
}
/**
* @hide
* Return the number of channels from an input channel mask
* @param mask a combination of the CHANNEL_IN_* definitions, even CHANNEL_IN_DEFAULT
* @return number of channels for the mask
*/
public static int channelCountFromInChannelMask(int mask) {
return Integer.bitCount(mask);
}
/**
* @hide
* Return the number of channels from an output channel mask
* @param mask a combination of the CHANNEL_OUT_* definitions, but not CHANNEL_OUT_DEFAULT
* @return number of channels for the mask
*/
public static int channelCountFromOutChannelMask(int mask) {
return Integer.bitCount(mask);
}
/**
* @hide
* Return a channel mask ready to be used by native code
* @param mask a combination of the CHANNEL_OUT_* definitions, but not CHANNEL_OUT_DEFAULT
* @return a native channel mask
*/
public static int convertChannelOutMaskToNativeMask(int javaMask) {
return (javaMask >> 2);
}
/**
* @hide
* Return a java output channel mask
* @param mask a native channel mask
* @return a combination of the CHANNEL_OUT_* definitions
*/
public static int convertNativeChannelMaskToOutMask(int nativeMask) {
return (nativeMask << 2);
}
public static final int CHANNEL_IN_DEFAULT = 1;
// These directly match native
public static final int CHANNEL_IN_LEFT = 0x4;
public static final int CHANNEL_IN_RIGHT = 0x8;
public static final int CHANNEL_IN_FRONT = 0x10;
public static final int CHANNEL_IN_BACK = 0x20;
public static final int CHANNEL_IN_LEFT_PROCESSED = 0x40;
public static final int CHANNEL_IN_RIGHT_PROCESSED = 0x80;
public static final int CHANNEL_IN_FRONT_PROCESSED = 0x100;
public static final int CHANNEL_IN_BACK_PROCESSED = 0x200;
public static final int CHANNEL_IN_PRESSURE = 0x400;
public static final int CHANNEL_IN_X_AXIS = 0x800;
public static final int CHANNEL_IN_Y_AXIS = 0x1000;
public static final int CHANNEL_IN_Z_AXIS = 0x2000;
public static final int CHANNEL_IN_VOICE_UPLINK = 0x4000;
public static final int CHANNEL_IN_VOICE_DNLINK = 0x8000;
public static final int CHANNEL_IN_MONO = CHANNEL_IN_FRONT;
public static final int CHANNEL_IN_STEREO = (CHANNEL_IN_LEFT | CHANNEL_IN_RIGHT);
/** @hide */
public static final int CHANNEL_IN_FRONT_BACK = CHANNEL_IN_FRONT | CHANNEL_IN_BACK;
// CHANNEL_IN_ALL is not yet defined; if added then it should match AUDIO_CHANNEL_IN_ALL
/** @hide */
public static int getBytesPerSample(int audioFormat)
{
switch (audioFormat) {
case ENCODING_PCM_8BIT:
return 1;
case ENCODING_PCM_16BIT:
case ENCODING_DEFAULT:
return 2;
case ENCODING_PCM_FLOAT:
return 4;
case ENCODING_INVALID:
default:
throw new IllegalArgumentException("Bad audio format " + audioFormat);
}
}
/** @hide */
public static boolean isValidEncoding(int audioFormat)
{
switch (audioFormat) {
case ENCODING_PCM_8BIT:
case ENCODING_PCM_16BIT:
case ENCODING_PCM_FLOAT:
case ENCODING_AC3:
case ENCODING_E_AC3:
case ENCODING_DTS:
case ENCODING_DTS_HD:
case ENCODING_MP3:
case ENCODING_AAC_LC:
case ENCODING_AAC_HE_V1:
case ENCODING_AAC_HE_V2:
return true;
default:
return false;
}
}
/** @hide */
public static boolean isPublicEncoding(int audioFormat)
{
switch (audioFormat) {
case ENCODING_PCM_8BIT:
case ENCODING_PCM_16BIT:
case ENCODING_PCM_FLOAT:
case ENCODING_AC3:
case ENCODING_E_AC3:
case ENCODING_DTS:
case ENCODING_DTS_HD:
return true;
default:
return false;
}
}
/** @hide */
public static boolean isEncodingLinearPcm(int audioFormat)
{
switch (audioFormat) {
case ENCODING_PCM_8BIT:
case ENCODING_PCM_16BIT:
case ENCODING_PCM_FLOAT:
case ENCODING_DEFAULT:
return true;
case ENCODING_AC3:
case ENCODING_E_AC3:
case ENCODING_DTS:
case ENCODING_DTS_HD:
case ENCODING_MP3:
case ENCODING_AAC_LC:
case ENCODING_AAC_HE_V1:
case ENCODING_AAC_HE_V2:
return false;
case ENCODING_INVALID:
default:
throw new IllegalArgumentException("Bad audio format " + audioFormat);
}
}
/**
* Returns an array of public encoding values extracted from an array of
* encoding values.
* @hide
*/
public static int[] filterPublicFormats(int[] formats) {
if (formats == null) {
return null;
}
int[] myCopy = Arrays.copyOf(formats, formats.length);
int size = 0;
for (int i = 0; i < myCopy.length; i++) {
if (isPublicEncoding(myCopy[i])) {
if (size != i) {
myCopy[size] = myCopy[i];
}
size++;
}
}
return Arrays.copyOf(myCopy, size);
}
/** @removed */
public AudioFormat()
{
throw new UnsupportedOperationException("There is no valid usage of this constructor");
}
/**
* Private constructor with an ignored argument to differentiate from the removed default ctor
* @param ignoredArgument
*/
private AudioFormat(int ignoredArgument) {
}
/**
* Constructor used by the JNI
*/
// Update sound trigger JNI in core/jni/android_hardware_SoundTrigger.cpp when modifying this
// constructor
private AudioFormat(int encoding, int sampleRate, int channelMask, int channelIndexMask) {
mEncoding = encoding;
mSampleRate = sampleRate;
mChannelMask = channelMask;
mChannelIndexMask = channelIndexMask;
mPropertySetMask = AUDIO_FORMAT_HAS_PROPERTY_ENCODING |
AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE |
AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK |
AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_INDEX_MASK;
}
/** @hide */
public final static int AUDIO_FORMAT_HAS_PROPERTY_NONE = 0x0;
/** @hide */
public final static int AUDIO_FORMAT_HAS_PROPERTY_ENCODING = 0x1 << 0;
/** @hide */
public final static int AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE = 0x1 << 1;
/** @hide */
public final static int AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK = 0x1 << 2;
/** @hide */
public final static int AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_INDEX_MASK = 0x1 << 3;
private int mEncoding;
private int mSampleRate;
private int mChannelMask;
private int mChannelIndexMask;
private int mPropertySetMask;
/**
* Return the encoding.
* See the section on <a href="#encoding">encodings</a> for more information about the different
* types of supported audio encoding.
* @return one of the values that can be set in {@link Builder#setEncoding(int)} or
* {@link AudioFormat#ENCODING_INVALID} if not set.
*/
public int getEncoding() {
if ((mPropertySetMask & AUDIO_FORMAT_HAS_PROPERTY_ENCODING) == 0) {
return ENCODING_INVALID;
}
return mEncoding;
}
/**
* Return the sample rate.
* @return one of the values that can be set in {@link Builder#setSampleRate(int)} or
* 0 if not set.
*/
public int getSampleRate() {
if ((mPropertySetMask & AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE) == 0) {
return 0;
}
return mSampleRate;
}
/**
* Return the channel mask.
* See the section on <a href="#channelMask">channel masks</a> for more information about
* the difference between index-based masks(as returned by {@link #getChannelIndexMask()}) and
* the position-based mask returned by this function.
* @return one of the values that can be set in {@link Builder#setChannelMask(int)} or
* {@link AudioFormat#CHANNEL_INVALID} if not set.
*/
public int getChannelMask() {
if ((mPropertySetMask & AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK) == 0) {
return CHANNEL_INVALID;
}
return mChannelMask;
}
/**
* Return the channel index mask.
* See the section on <a href="#channelMask">channel masks</a> for more information about
* the difference between index-based masks, and position-based masks (as returned
* by {@link #getChannelMask()}).
* @return one of the values that can be set in {@link Builder#setChannelIndexMask(int)} or
* {@link AudioFormat#CHANNEL_INVALID} if not set or an invalid mask was used.
*/
public int getChannelIndexMask() {
if ((mPropertySetMask & AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_INDEX_MASK) == 0) {
return CHANNEL_INVALID;
}
return mChannelIndexMask;
}
/**
* Return the channel count.
* @return 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.
*/
public int getChannelCount() {
final int channelIndexCount = Integer.bitCount(getChannelIndexMask());
int channelCount = channelCountFromOutChannelMask(getChannelMask());
if (channelCount == 0) {
channelCount = channelIndexCount;
} else if (channelCount != channelIndexCount && channelIndexCount != 0) {
channelCount = 0; // position and index channel count mismatch
}
return channelCount;
}
/** @hide */
public int getPropertySetMask() {
return mPropertySetMask;
}
/**
* Builder class for {@link 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 {@link AudioFormat} for a complete description of the different parameters that
* can be used to configure an <code>AudioFormat</code> instance.
* <p>{@link AudioFormat} is for instance used in
* {@link AudioTrack#AudioTrack(AudioAttributes, AudioFormat, int, int, int)}. In this
* constructor, every format characteristic set on the <code>Builder</code> (e.g. with
* {@link #setSampleRate(int)}) will alter the default values used by an
* <code>AudioTrack</code>. In this case for audio playback with <code>AudioTrack</code>, the
* sample rate set in the <code>Builder</code> would override the platform output sample rate
* which would otherwise be selected by default.
*/
public static class Builder {
private int mEncoding = ENCODING_INVALID;
private int mSampleRate = 0;
private int mChannelMask = CHANNEL_INVALID;
private int mChannelIndexMask = 0;
private int mPropertySetMask = AUDIO_FORMAT_HAS_PROPERTY_NONE;
/**
* Constructs a new Builder with none of the format characteristics set.
*/
public Builder() {
}
/**
* Constructs a new Builder from a given {@link AudioFormat}.
* @param af the {@link AudioFormat} object whose data will be reused in the new Builder.
*/
public Builder(AudioFormat af) {
mEncoding = af.mEncoding;
mSampleRate = af.mSampleRate;
mChannelMask = af.mChannelMask;
mChannelIndexMask = af.mChannelIndexMask;
mPropertySetMask = af.mPropertySetMask;
}
/**
* Combines all of the format characteristics that have been set and return a new
* {@link AudioFormat} object.
* @return a new {@link AudioFormat} object
*/
public AudioFormat build() {
AudioFormat af = new AudioFormat(1980/*ignored*/);
af.mEncoding = mEncoding;
af.mSampleRate = mSampleRate;
af.mChannelMask = mChannelMask;
af.mChannelIndexMask = mChannelIndexMask;
af.mPropertySetMask = mPropertySetMask;
return af;
}
/**
* Sets the data encoding format.
* @param encoding one of {@link AudioFormat#ENCODING_DEFAULT},
* {@link AudioFormat#ENCODING_PCM_8BIT},
* {@link AudioFormat#ENCODING_PCM_16BIT},
* {@link AudioFormat#ENCODING_PCM_FLOAT},
* {@link AudioFormat#ENCODING_AC3},
* {@link AudioFormat#ENCODING_E_AC3}.
* {@link AudioFormat#ENCODING_DTS},
* {@link AudioFormat#ENCODING_DTS_HD}.
* @return the same Builder instance.
* @throws java.lang.IllegalArgumentException
*/
public Builder setEncoding(@Encoding int encoding) throws IllegalArgumentException {
switch (encoding) {
case ENCODING_DEFAULT:
mEncoding = ENCODING_PCM_16BIT;
break;
case ENCODING_PCM_8BIT:
case ENCODING_PCM_16BIT:
case ENCODING_PCM_FLOAT:
case ENCODING_AC3:
case ENCODING_E_AC3:
case ENCODING_DTS:
case ENCODING_DTS_HD:
mEncoding = encoding;
break;
case ENCODING_INVALID:
default:
throw new IllegalArgumentException("Invalid encoding " + encoding);
}
mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_ENCODING;
return this;
}
/**
* 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 {@link #setChannelIndexMask(int)} to specify channels
* based on endpoint numbered channels. This <a href="#channelPositionMask>description of
* channel position masks</a> covers the concept in more details.
* @param channelMask describes the configuration of the audio channels.
* <p> For output, the channelMask can be an OR-ed combination of
* channel position masks, e.g.
* {@link AudioFormat#CHANNEL_OUT_FRONT_LEFT},
* {@link AudioFormat#CHANNEL_OUT_FRONT_RIGHT},
* {@link AudioFormat#CHANNEL_OUT_FRONT_CENTER},
* {@link AudioFormat#CHANNEL_OUT_LOW_FREQUENCY}
* {@link AudioFormat#CHANNEL_OUT_BACK_LEFT},
* {@link AudioFormat#CHANNEL_OUT_BACK_RIGHT},
* {@link AudioFormat#CHANNEL_OUT_BACK_CENTER},
* {@link AudioFormat#CHANNEL_OUT_SIDE_LEFT},
* {@link AudioFormat#CHANNEL_OUT_SIDE_RIGHT}.
* <p> For a valid {@link AudioTrack} channel position mask,
* the following conditions apply:
* <br> (1) at most eight channel positions may be used;
* <br> (2) right/left pairs should be matched.
* <p> For input or {@link AudioRecord}, the mask should be
* {@link AudioFormat#CHANNEL_IN_MONO} or
* {@link AudioFormat#CHANNEL_IN_STEREO}. {@link AudioFormat#CHANNEL_IN_MONO} is
* guaranteed to work on all devices.
* @return the same <code>Builder</code> 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 @NonNull Builder setChannelMask(int channelMask) {
if (channelMask == 0) {
throw new IllegalArgumentException("Invalid zero channel mask");
} else if (/* channelMask != 0 && */ mChannelIndexMask != 0 &&
Integer.bitCount(channelMask) != Integer.bitCount(mChannelIndexMask)) {
throw new IllegalArgumentException("Mismatched channel count for mask " +
Integer.toHexString(channelMask).toUpperCase());
}
mChannelMask = channelMask;
mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK;
return this;
}
/**
* 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 <a href="#channelIndexMask>description of channel
* index masks</a> covers the concept in more details.
* See {@link #setChannelMask(int)} for a positional mask interpretation.
* <p> Both {@link AudioTrack} and {@link AudioRecord} support
* a channel index mask.
* If a channel index mask is specified it is used,
* otherwise the channel position mask specified
* by <code>setChannelMask</code> is used.
* For <code>AudioTrack</code> and <code>AudioRecord</code>,
* a channel position mask is not required if a channel index mask is specified.
*
* @param channelIndexMask describes the configuration of the audio channels.
* <p> For output, the <code>channelIndexMask</code> is an OR-ed combination of
* bits representing the mapping of <code>AudioTrack</code> write samples
* to output sink channels.
* For example, a mask of <code>0xa</code>, or binary <code>1010</code>,
* means the <code>AudioTrack</code> 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
* <code>AudioTrack</code> write samples are dropped.
* <p> For input, the <code>channelIndexMask</code> is an OR-ed combination of
* bits representing the mapping of input source channels to
* <code>AudioRecord</code> read samples.
* For example, a mask of <code>0x5</code>, or binary
* <code>101</code>, will read from the first and third channel of the input
* source device and store them in the first and second sample of the
* <code>AudioRecord</code> read frame.
* Unmatched input source channels are dropped and
* unmatched <code>AudioRecord</code> read samples are zero filled.
* @return the same <code>Builder</code> 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 @NonNull Builder setChannelIndexMask(int channelIndexMask) {
if (channelIndexMask == 0) {
throw new IllegalArgumentException("Invalid zero channel index mask");
} else if (/* channelIndexMask != 0 && */ mChannelMask != 0 &&
Integer.bitCount(channelIndexMask) != Integer.bitCount(mChannelMask)) {
throw new IllegalArgumentException("Mismatched channel count for index mask " +
Integer.toHexString(channelIndexMask).toUpperCase());
}
mChannelIndexMask = channelIndexMask;
mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_INDEX_MASK;
return this;
}
/**
* Sets the sample rate.
* @param sampleRate the sample rate expressed in Hz
* @return the same Builder instance.
* @throws java.lang.IllegalArgumentException
*/
public Builder setSampleRate(int sampleRate) throws IllegalArgumentException {
if ((sampleRate <= 0) || (sampleRate > 192000)) {
throw new IllegalArgumentException("Invalid sample rate " + sampleRate);
}
mSampleRate = sampleRate;
mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE;
return this;
}
}
@Override
public String toString () {
return new String("AudioFormat:"
+ " props=" + mPropertySetMask
+ " enc=" + mEncoding
+ " chan=0x" + Integer.toHexString(mChannelMask).toUpperCase()
+ " chan_index=0x" + Integer.toHexString(mChannelIndexMask).toUpperCase()
+ " rate=" + mSampleRate);
}
/** @hide */
@IntDef({
ENCODING_DEFAULT,
ENCODING_PCM_8BIT,
ENCODING_PCM_16BIT,
ENCODING_PCM_FLOAT,
ENCODING_AC3,
ENCODING_E_AC3,
ENCODING_DTS,
ENCODING_DTS_HD
})
@Retention(RetentionPolicy.SOURCE)
public @interface Encoding {}
}