Files
frameworks_base/media/java/android/media/AudioFormat.java
Jean-Michel Trivi 8dc1031453 Convert record channel mask for dynamic mix
When creating the AudioRecord instance for a dynamic mix, convert
  the output channel mask of the mix to an input channel mask
  to be used by the AudioRecord instance through which the
  mixed audio is rerouted.

Bug 16009464

Change-Id: I3addbe85339f6f06b69acc3f9b8e2a765e5d7305
2014-11-20 12:53:23 -08:00

487 lines
19 KiB
Java

/*
* 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 java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/**
* The 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}.
*
*/
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
/** 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;
/** Invalid audio channel configuration */
/** @deprecated use CHANNEL_INVALID instead */
@Deprecated public static final int CHANNEL_CONFIGURATION_INVALID = 0;
/** Default audio channel configuration */
/** @deprecated use CHANNEL_OUT_DEFAULT or CHANNEL_IN_DEFAULT instead */
@Deprecated public static final int CHANNEL_CONFIGURATION_DEFAULT = 1;
/** Mono audio configuration */
/** @deprecated use CHANNEL_OUT_MONO or CHANNEL_IN_MONO instead */
@Deprecated public static final int CHANNEL_CONFIGURATION_MONO = 2;
/** Stereo (2 channel) audio configuration */
/** @deprecated use CHANNEL_OUT_STEREO or 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/core/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);
// TODO does this need an @deprecated ?
// different from AUDIO_CHANNEL_OUT_7POINT1
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);
/** @hide */
// 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:
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:
return false;
case ENCODING_INVALID:
default:
throw new IllegalArgumentException("Bad audio format " + audioFormat);
}
}
/** @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) {
mEncoding = encoding;
mSampleRate = sampleRate;
mChannelMask = channelMask;
mPropertySetMask = AUDIO_FORMAT_HAS_PROPERTY_ENCODING |
AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE |
AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_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;
private int mEncoding;
private int mSampleRate;
private int mChannelMask;
private int mPropertySetMask;
/**
* Return the 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.
* @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;
}
/** @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.
* <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 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;
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.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}.
* @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:
mEncoding = encoding;
break;
case ENCODING_INVALID:
default:
throw new IllegalArgumentException("Invalid encoding " + encoding);
}
mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_ENCODING;
return this;
}
/**
* Sets the channel mask.
* @param channelMask describes the configuration of the audio channels.
* <p>For output, the mask should be a combination of
* {@link AudioFormat#CHANNEL_OUT_FRONT_LEFT},
* {@link AudioFormat#CHANNEL_OUT_FRONT_CENTER},
* {@link AudioFormat#CHANNEL_OUT_FRONT_RIGHT},
* {@link AudioFormat#CHANNEL_OUT_SIDE_LEFT},
* {@link AudioFormat#CHANNEL_OUT_SIDE_RIGHT},
* {@link AudioFormat#CHANNEL_OUT_BACK_LEFT},
* {@link AudioFormat#CHANNEL_OUT_BACK_RIGHT}.
* <p>for input, 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 Builder instance.
*/
public Builder setChannelMask(int channelMask) {
// only validated when used, with input or output context
mChannelMask = channelMask;
mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_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)
+ " rate=" + mSampleRate);
}
/** @hide */
@IntDef({
ENCODING_DEFAULT,
ENCODING_PCM_8BIT,
ENCODING_PCM_16BIT,
ENCODING_PCM_FLOAT,
ENCODING_AC3,
ENCODING_E_AC3
})
@Retention(RetentionPolicy.SOURCE)
public @interface Encoding {}
}