1 /* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.media; 18 19 import android.annotation.IntDef; 20 import android.annotation.NonNull; 21 22 import java.lang.annotation.Retention; 23 import java.lang.annotation.RetentionPolicy; 24 import java.util.Arrays; 25 26 /** 27 * The {@link AudioFormat} class is used to access a number of audio format and 28 * channel configuration constants. They are for instance used 29 * in {@link AudioTrack} and {@link AudioRecord}, as valid values in individual parameters of 30 * constructors like {@link AudioTrack#AudioTrack(int, int, int, int, int, int)}, where the fourth 31 * parameter is one of the <code>AudioFormat.ENCODING_*</code> constants. 32 * The <code>AudioFormat</code> constants are also used in {@link MediaFormat} to specify 33 * audio related values commonly used in media, such as for {@link MediaFormat#KEY_CHANNEL_MASK}. 34 * <p>The {@link AudioFormat.Builder} class can be used to create instances of 35 * the <code>AudioFormat</code> format class. 36 * Refer to 37 * {@link AudioFormat.Builder} for documentation on the mechanics of the configuration and building 38 * of such instances. Here we describe the main concepts that the <code>AudioFormat</code> class 39 * allow you to convey in each instance, they are: 40 * <ol> 41 * <li><a href="#sampleRate">sample rate</a> 42 * <li><a href="#encoding">encoding</a> 43 * <li><a href="#channelMask">channel masks</a> 44 * </ol> 45 * <p>Closely associated with the <code>AudioFormat</code> is the notion of an 46 * <a href="#audioFrame">audio frame</a>, which is used throughout the documentation 47 * to represent the minimum size complete unit of audio data. 48 * 49 * <h4 id="sampleRate">Sample rate</h4> 50 * <p>Expressed in Hz, the sample rate in an <code>AudioFormat</code> instance expresses the number 51 * of audio samples for each channel per second in the content you are playing or recording. It is 52 * not the sample rate 53 * at which content is rendered or produced. For instance a sound at a media sample rate of 8000Hz 54 * can be played on a device operating at a sample rate of 48000Hz; the sample rate conversion is 55 * automatically handled by the platform, it will not play at 6x speed. 56 * 57 * <p>As of API {@link android.os.Build.VERSION_CODES#M}, 58 * sample rates up to 192kHz are supported 59 * for <code>AudioRecord</code> and <code>AudioTrack</code>, with sample rate conversion 60 * performed as needed. 61 * To improve efficiency and avoid lossy conversions, it is recommended to match the sample rate 62 * for <code>AudioRecord</code> and <code>AudioTrack</code> to the endpoint device 63 * sample rate, and limit the sample rate to no more than 48kHz unless there are special 64 * device capabilities that warrant a higher rate. 65 * 66 * <h4 id="encoding">Encoding</h4> 67 * <p>Audio encoding is used to describe the bit representation of audio data, which can be 68 * either linear PCM or compressed audio, such as AC3 or DTS. 69 * <p>For linear PCM, the audio encoding describes the sample size, 8 bits, 16 bits, or 32 bits, 70 * and the sample representation, integer or float. 71 * <ul> 72 * <li> {@link #ENCODING_PCM_8BIT}: The audio sample is a 8 bit unsigned integer in the 73 * range [0, 255], with a 128 offset for zero. This is typically stored as a Java byte in a 74 * byte array or ByteBuffer. Since the Java byte is <em>signed</em>, 75 * be careful with math operations and conversions as the most significant bit is inverted. 76 * </li> 77 * <li> {@link #ENCODING_PCM_16BIT}: The audio sample is a 16 bit signed integer 78 * typically stored as a Java short in a short array, but when the short 79 * is stored in a ByteBuffer, it is native endian (as compared to the default Java big endian). 80 * The short has full range from [-32768, 32767], 81 * and is sometimes interpreted as fixed point Q.15 data. 82 * </li> 83 * <li> {@link #ENCODING_PCM_FLOAT}: Introduced in 84 * API {@link android.os.Build.VERSION_CODES#LOLLIPOP}, this encoding specifies that 85 * the audio sample is a 32 bit IEEE single precision float. The sample can be 86 * manipulated as a Java float in a float array, though within a ByteBuffer 87 * it is stored in native endian byte order. 88 * The nominal range of <code>ENCODING_PCM_FLOAT</code> audio data is [-1.0, 1.0]. 89 * It is implementation dependent whether the positive maximum of 1.0 is included 90 * in the interval. Values outside of the nominal range are clamped before 91 * sending to the endpoint device. Beware that 92 * the handling of NaN is undefined; subnormals may be treated as zero; and 93 * infinities are generally clamped just like other values for <code>AudioTrack</code> 94 * – try to avoid infinities because they can easily generate a NaN. 95 * <br> 96 * To achieve higher audio bit depth than a signed 16 bit integer short, 97 * it is recommended to use <code>ENCODING_PCM_FLOAT</code> for audio capture, processing, 98 * and playback. 99 * Floats are efficiently manipulated by modern CPUs, 100 * have greater precision than 24 bit signed integers, 101 * and have greater dynamic range than 32 bit signed integers. 102 * <code>AudioRecord</code> as of API {@link android.os.Build.VERSION_CODES#M} and 103 * <code>AudioTrack</code> as of API {@link android.os.Build.VERSION_CODES#LOLLIPOP} 104 * support <code>ENCODING_PCM_FLOAT</code>. 105 * </li> 106 * </ul> 107 * <p>For compressed audio, the encoding specifies the method of compression, 108 * for example {@link #ENCODING_AC3} and {@link #ENCODING_DTS}. The compressed 109 * audio data is typically stored as bytes in 110 * a byte array or ByteBuffer. When a compressed audio encoding is specified 111 * for an <code>AudioTrack</code>, it creates a direct (non-mixed) track 112 * for output to an endpoint (such as HDMI) capable of decoding the compressed audio. 113 * For (most) other endpoints, which are not capable of decoding such compressed audio, 114 * you will need to decode the data first, typically by creating a {@link MediaCodec}. 115 * Alternatively, one may use {@link MediaPlayer} for playback of compressed 116 * audio files or streams. 117 * <p>When compressed audio is sent out through a direct <code>AudioTrack</code>, 118 * it need not be written in exact multiples of the audio access unit; 119 * this differs from <code>MediaCodec</code> input buffers. 120 * 121 * <h4 id="channelMask">Channel mask</h4> 122 * <p>Channel masks are used in <code>AudioTrack</code> and <code>AudioRecord</code> to describe 123 * the samples and their arrangement in the audio frame. They are also used in the endpoint (e.g. 124 * a USB audio interface, a DAC connected to headphones) to specify allowable configurations of a 125 * particular device. 126 * <br>As of API {@link android.os.Build.VERSION_CODES#M}, there are two types of channel masks: 127 * channel position masks and channel index masks. 128 * 129 * <h5 id="channelPositionMask">Channel position masks</h5> 130 * Channel position masks are the original Android channel masks, and are used since API 131 * {@link android.os.Build.VERSION_CODES#BASE}. 132 * For input and output, they imply a positional nature - the location of a speaker or a microphone 133 * for recording or playback. 134 * <br>For a channel position mask, each allowed channel position corresponds to a bit in the 135 * channel mask. If that channel position is present in the audio frame, that bit is set, 136 * otherwise it is zero. The order of the bits (from lsb to msb) corresponds to the order of that 137 * position's sample in the audio frame. 138 * <br>The canonical channel position masks by channel count are as follows: 139 * <br><table> 140 * <tr><td>channel count</td><td>channel position mask</td></tr> 141 * <tr><td>1</td><td>{@link #CHANNEL_OUT_MONO}</td></tr> 142 * <tr><td>2</td><td>{@link #CHANNEL_OUT_STEREO}</td></tr> 143 * <tr><td>3</td><td>{@link #CHANNEL_OUT_STEREO} | {@link #CHANNEL_OUT_FRONT_CENTER}</td></tr> 144 * <tr><td>4</td><td>{@link #CHANNEL_OUT_QUAD}</td></tr> 145 * <tr><td>5</td><td>{@link #CHANNEL_OUT_QUAD} | {@link #CHANNEL_OUT_FRONT_CENTER}</td></tr> 146 * <tr><td>6</td><td>{@link #CHANNEL_OUT_5POINT1}</td></tr> 147 * <tr><td>7</td><td>{@link #CHANNEL_OUT_5POINT1} | {@link #CHANNEL_OUT_BACK_CENTER}</td></tr> 148 * <tr><td>8</td><td>{@link #CHANNEL_OUT_7POINT1_SURROUND}</td></tr> 149 * </table> 150 * <br>These masks are an ORed composite of individual channel masks. For example 151 * {@link #CHANNEL_OUT_STEREO} is composed of {@link #CHANNEL_OUT_FRONT_LEFT} and 152 * {@link #CHANNEL_OUT_FRONT_RIGHT}. 153 * 154 * <h5 id="channelIndexMask">Channel index masks</h5> 155 * Channel index masks are introduced in API {@link android.os.Build.VERSION_CODES#M}. They allow 156 * the selection of a particular channel from the source or sink endpoint by number, i.e. the first 157 * channel, the second channel, and so forth. This avoids problems with artificially assigning 158 * positions to channels of an endpoint, or figuring what the i<sup>th</sup> position bit is within 159 * an endpoint's channel position mask etc. 160 * <br>Here's an example where channel index masks address this confusion: dealing with a 4 channel 161 * USB device. Using a position mask, and based on the channel count, this would be a 162 * {@link #CHANNEL_OUT_QUAD} device, but really one is only interested in channel 0 163 * through channel 3. The USB device would then have the following individual bit channel masks: 164 * {@link #CHANNEL_OUT_FRONT_LEFT}, 165 * {@link #CHANNEL_OUT_FRONT_RIGHT}, {@link #CHANNEL_OUT_BACK_LEFT} 166 * and {@link #CHANNEL_OUT_BACK_RIGHT}. But which is channel 0 and which is 167 * channel 3? 168 * <br>For a channel index mask, each channel number is represented as a bit in the mask, from the 169 * lsb (channel 0) upwards to the msb, numerically this bit value is 170 * <code>1 << channelNumber</code>. 171 * A set bit indicates that channel is present in the audio frame, otherwise it is cleared. 172 * The order of the bits also correspond to that channel number's sample order in the audio frame. 173 * <br>For the previous 4 channel USB device example, the device would have a channel index mask 174 * <code>0xF</code>. Suppose we wanted to select only the first and the third channels; this would 175 * correspond to a channel index mask <code>0x5</code> (the first and third bits set). If an 176 * <code>AudioTrack</code> uses this channel index mask, the audio frame would consist of two 177 * samples, the first sample of each frame routed to channel 0, and the second sample of each frame 178 * routed to channel 2. 179 * The canonical channel index masks by channel count are given by the formula 180 * <code>(1 << channelCount) - 1</code>. 181 * 182 * <h5>Use cases</h5> 183 * <ul> 184 * <li><i>Channel position mask for an endpoint:</i> <code>CHANNEL_OUT_FRONT_LEFT</code>, 185 * <code>CHANNEL_OUT_FRONT_CENTER</code>, etc. for HDMI home theater purposes. 186 * <li><i>Channel position mask for an audio stream:</i> Creating an <code>AudioTrack</code> 187 * to output movie content, where 5.1 multichannel output is to be written. 188 * <li><i>Channel index mask for an endpoint:</i> USB devices for which input and output do not 189 * correspond to left or right speaker or microphone. 190 * <li><i>Channel index mask for an audio stream:</i> An <code>AudioRecord</code> may only want the 191 * third and fourth audio channels of the endpoint (i.e. the second channel pair), and not care the 192 * about position it corresponds to, in which case the channel index mask is <code>0xC</code>. 193 * Multichannel <code>AudioRecord</code> sessions should use channel index masks. 194 * </ul> 195 * <h4 id="audioFrame">Audio Frame</h4> 196 * <p>For linear PCM, an audio frame consists of a set of samples captured at the same time, 197 * whose count and 198 * channel association are given by the <a href="#channelMask">channel mask</a>, 199 * and whose sample contents are specified by the <a href="#encoding">encoding</a>. 200 * For example, a stereo 16 bit PCM frame consists of 201 * two 16 bit linear PCM samples, with a frame size of 4 bytes. 202 * For compressed audio, an audio frame may alternately 203 * refer to an access unit of compressed data bytes that is logically grouped together for 204 * decoding and bitstream access (e.g. {@link MediaCodec}), 205 * or a single byte of compressed data (e.g. {@link AudioTrack#getBufferSizeInFrames() 206 * AudioTrack.getBufferSizeInFrames()}), 207 * or the linear PCM frame result from decoding the compressed data 208 * (e.g.{@link AudioTrack#getPlaybackHeadPosition() 209 * AudioTrack.getPlaybackHeadPosition()}), 210 * depending on the context where audio frame is used. 211 */ 212 public class AudioFormat { 213 214 //--------------------------------------------------------- 215 // Constants 216 //-------------------- 217 /** Invalid audio data format */ 218 public static final int ENCODING_INVALID = 0; 219 /** Default audio data format */ 220 public static final int ENCODING_DEFAULT = 1; 221 222 // These values must be kept in sync with core/jni/android_media_AudioFormat.h 223 // Also sync av/services/audiopolicy/managerdefault/ConfigParsingUtils.h 224 /** Audio data format: PCM 16 bit per sample. Guaranteed to be supported by devices. */ 225 public static final int ENCODING_PCM_16BIT = 2; 226 /** Audio data format: PCM 8 bit per sample. Not guaranteed to be supported by devices. */ 227 public static final int ENCODING_PCM_8BIT = 3; 228 /** Audio data format: single-precision floating-point per sample */ 229 public static final int ENCODING_PCM_FLOAT = 4; 230 /** Audio data format: AC-3 compressed */ 231 public static final int ENCODING_AC3 = 5; 232 /** Audio data format: E-AC-3 compressed */ 233 public static final int ENCODING_E_AC3 = 6; 234 /** Audio data format: DTS compressed */ 235 public static final int ENCODING_DTS = 7; 236 /** Audio data format: DTS HD compressed */ 237 public static final int ENCODING_DTS_HD = 8; 238 /** Audio data format: MP3 compressed 239 * @hide 240 * */ 241 public static final int ENCODING_MP3 = 9; 242 /** Audio data format: AAC LC compressed 243 * @hide 244 * */ 245 public static final int ENCODING_AAC_LC = 10; 246 /** Audio data format: AAC HE V1 compressed 247 * @hide 248 * */ 249 public static final int ENCODING_AAC_HE_V1 = 11; 250 /** Audio data format: AAC HE V2 compressed 251 * @hide 252 * */ 253 public static final int ENCODING_AAC_HE_V2 = 12; 254 255 /** Invalid audio channel configuration */ 256 /** @deprecated Use {@link #CHANNEL_INVALID} instead. */ 257 @Deprecated public static final int CHANNEL_CONFIGURATION_INVALID = 0; 258 /** Default audio channel configuration */ 259 /** @deprecated Use {@link #CHANNEL_OUT_DEFAULT} or {@link #CHANNEL_IN_DEFAULT} instead. */ 260 @Deprecated public static final int CHANNEL_CONFIGURATION_DEFAULT = 1; 261 /** Mono audio configuration */ 262 /** @deprecated Use {@link #CHANNEL_OUT_MONO} or {@link #CHANNEL_IN_MONO} instead. */ 263 @Deprecated public static final int CHANNEL_CONFIGURATION_MONO = 2; 264 /** Stereo (2 channel) audio configuration */ 265 /** @deprecated Use {@link #CHANNEL_OUT_STEREO} or {@link #CHANNEL_IN_STEREO} instead. */ 266 @Deprecated public static final int CHANNEL_CONFIGURATION_STEREO = 3; 267 268 /** Invalid audio channel mask */ 269 public static final int CHANNEL_INVALID = 0; 270 /** Default audio channel mask */ 271 public static final int CHANNEL_OUT_DEFAULT = 1; 272 273 // Output channel mask definitions below are translated to the native values defined in 274 // in /system/media/audio/include/system/audio.h in the JNI code of AudioTrack 275 public static final int CHANNEL_OUT_FRONT_LEFT = 0x4; 276 public static final int CHANNEL_OUT_FRONT_RIGHT = 0x8; 277 public static final int CHANNEL_OUT_FRONT_CENTER = 0x10; 278 public static final int CHANNEL_OUT_LOW_FREQUENCY = 0x20; 279 public static final int CHANNEL_OUT_BACK_LEFT = 0x40; 280 public static final int CHANNEL_OUT_BACK_RIGHT = 0x80; 281 public static final int CHANNEL_OUT_FRONT_LEFT_OF_CENTER = 0x100; 282 public static final int CHANNEL_OUT_FRONT_RIGHT_OF_CENTER = 0x200; 283 public static final int CHANNEL_OUT_BACK_CENTER = 0x400; 284 public static final int CHANNEL_OUT_SIDE_LEFT = 0x800; 285 public static final int CHANNEL_OUT_SIDE_RIGHT = 0x1000; 286 /** @hide */ 287 public static final int CHANNEL_OUT_TOP_CENTER = 0x2000; 288 /** @hide */ 289 public static final int CHANNEL_OUT_TOP_FRONT_LEFT = 0x4000; 290 /** @hide */ 291 public static final int CHANNEL_OUT_TOP_FRONT_CENTER = 0x8000; 292 /** @hide */ 293 public static final int CHANNEL_OUT_TOP_FRONT_RIGHT = 0x10000; 294 /** @hide */ 295 public static final int CHANNEL_OUT_TOP_BACK_LEFT = 0x20000; 296 /** @hide */ 297 public static final int CHANNEL_OUT_TOP_BACK_CENTER = 0x40000; 298 /** @hide */ 299 public static final int CHANNEL_OUT_TOP_BACK_RIGHT = 0x80000; 300 301 public static final int CHANNEL_OUT_MONO = CHANNEL_OUT_FRONT_LEFT; 302 public static final int CHANNEL_OUT_STEREO = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT); 303 // aka QUAD_BACK 304 public static final int CHANNEL_OUT_QUAD = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 305 CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT); 306 /** @hide */ 307 public static final int CHANNEL_OUT_QUAD_SIDE = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 308 CHANNEL_OUT_SIDE_LEFT | CHANNEL_OUT_SIDE_RIGHT); 309 public static final int CHANNEL_OUT_SURROUND = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 310 CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_BACK_CENTER); 311 // aka 5POINT1_BACK 312 public static final int CHANNEL_OUT_5POINT1 = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 313 CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY | CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT); 314 /** @hide */ 315 public static final int CHANNEL_OUT_5POINT1_SIDE = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 316 CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY | 317 CHANNEL_OUT_SIDE_LEFT | CHANNEL_OUT_SIDE_RIGHT); 318 // different from AUDIO_CHANNEL_OUT_7POINT1 used internally, and not accepted by AudioRecord. 319 /** @deprecated Not the typical 7.1 surround configuration. Use {@link #CHANNEL_OUT_7POINT1_SURROUND} instead. */ 320 @Deprecated public static final int CHANNEL_OUT_7POINT1 = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 321 CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY | CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT | 322 CHANNEL_OUT_FRONT_LEFT_OF_CENTER | CHANNEL_OUT_FRONT_RIGHT_OF_CENTER); 323 // matches AUDIO_CHANNEL_OUT_7POINT1 324 public static final int CHANNEL_OUT_7POINT1_SURROUND = ( 325 CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_FRONT_RIGHT | 326 CHANNEL_OUT_SIDE_LEFT | CHANNEL_OUT_SIDE_RIGHT | 327 CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT | 328 CHANNEL_OUT_LOW_FREQUENCY); 329 // CHANNEL_OUT_ALL is not yet defined; if added then it should match AUDIO_CHANNEL_OUT_ALL 330 331 /** 332 * @hide 333 * Return the input channel mask corresponding to an output channel mask. 334 * This can be used for submix rerouting for the mask of the recorder to map to that of the mix. 335 * @param outMask a combination of the CHANNEL_OUT_* definitions, but not CHANNEL_OUT_DEFAULT 336 * @return a combination of CHANNEL_IN_* definitions matching an output channel mask 337 * @throws IllegalArgumentException 338 */ inChannelMaskFromOutChannelMask(int outMask)339 public static int inChannelMaskFromOutChannelMask(int outMask) throws IllegalArgumentException { 340 if (outMask == CHANNEL_OUT_DEFAULT) { 341 throw new IllegalArgumentException( 342 "Illegal CHANNEL_OUT_DEFAULT channel mask for input."); 343 } 344 switch (channelCountFromOutChannelMask(outMask)) { 345 case 1: 346 return CHANNEL_IN_MONO; 347 case 2: 348 return CHANNEL_IN_STEREO; 349 default: 350 throw new IllegalArgumentException("Unsupported channel configuration for input."); 351 } 352 } 353 354 /** 355 * @hide 356 * Return the number of channels from an input channel mask 357 * @param mask a combination of the CHANNEL_IN_* definitions, even CHANNEL_IN_DEFAULT 358 * @return number of channels for the mask 359 */ channelCountFromInChannelMask(int mask)360 public static int channelCountFromInChannelMask(int mask) { 361 return Integer.bitCount(mask); 362 } 363 /** 364 * @hide 365 * Return the number of channels from an output channel mask 366 * @param mask a combination of the CHANNEL_OUT_* definitions, but not CHANNEL_OUT_DEFAULT 367 * @return number of channels for the mask 368 */ channelCountFromOutChannelMask(int mask)369 public static int channelCountFromOutChannelMask(int mask) { 370 return Integer.bitCount(mask); 371 } 372 /** 373 * @hide 374 * Return a channel mask ready to be used by native code 375 * @param mask a combination of the CHANNEL_OUT_* definitions, but not CHANNEL_OUT_DEFAULT 376 * @return a native channel mask 377 */ convertChannelOutMaskToNativeMask(int javaMask)378 public static int convertChannelOutMaskToNativeMask(int javaMask) { 379 return (javaMask >> 2); 380 } 381 382 /** 383 * @hide 384 * Return a java output channel mask 385 * @param mask a native channel mask 386 * @return a combination of the CHANNEL_OUT_* definitions 387 */ convertNativeChannelMaskToOutMask(int nativeMask)388 public static int convertNativeChannelMaskToOutMask(int nativeMask) { 389 return (nativeMask << 2); 390 } 391 392 public static final int CHANNEL_IN_DEFAULT = 1; 393 // These directly match native 394 public static final int CHANNEL_IN_LEFT = 0x4; 395 public static final int CHANNEL_IN_RIGHT = 0x8; 396 public static final int CHANNEL_IN_FRONT = 0x10; 397 public static final int CHANNEL_IN_BACK = 0x20; 398 public static final int CHANNEL_IN_LEFT_PROCESSED = 0x40; 399 public static final int CHANNEL_IN_RIGHT_PROCESSED = 0x80; 400 public static final int CHANNEL_IN_FRONT_PROCESSED = 0x100; 401 public static final int CHANNEL_IN_BACK_PROCESSED = 0x200; 402 public static final int CHANNEL_IN_PRESSURE = 0x400; 403 public static final int CHANNEL_IN_X_AXIS = 0x800; 404 public static final int CHANNEL_IN_Y_AXIS = 0x1000; 405 public static final int CHANNEL_IN_Z_AXIS = 0x2000; 406 public static final int CHANNEL_IN_VOICE_UPLINK = 0x4000; 407 public static final int CHANNEL_IN_VOICE_DNLINK = 0x8000; 408 public static final int CHANNEL_IN_MONO = CHANNEL_IN_FRONT; 409 public static final int CHANNEL_IN_STEREO = (CHANNEL_IN_LEFT | CHANNEL_IN_RIGHT); 410 /** @hide */ 411 public static final int CHANNEL_IN_FRONT_BACK = CHANNEL_IN_FRONT | CHANNEL_IN_BACK; 412 // CHANNEL_IN_ALL is not yet defined; if added then it should match AUDIO_CHANNEL_IN_ALL 413 414 /** @hide */ getBytesPerSample(int audioFormat)415 public static int getBytesPerSample(int audioFormat) 416 { 417 switch (audioFormat) { 418 case ENCODING_PCM_8BIT: 419 return 1; 420 case ENCODING_PCM_16BIT: 421 case ENCODING_DEFAULT: 422 return 2; 423 case ENCODING_PCM_FLOAT: 424 return 4; 425 case ENCODING_INVALID: 426 default: 427 throw new IllegalArgumentException("Bad audio format " + audioFormat); 428 } 429 } 430 431 /** @hide */ isValidEncoding(int audioFormat)432 public static boolean isValidEncoding(int audioFormat) 433 { 434 switch (audioFormat) { 435 case ENCODING_PCM_8BIT: 436 case ENCODING_PCM_16BIT: 437 case ENCODING_PCM_FLOAT: 438 case ENCODING_AC3: 439 case ENCODING_E_AC3: 440 case ENCODING_DTS: 441 case ENCODING_DTS_HD: 442 case ENCODING_MP3: 443 case ENCODING_AAC_LC: 444 case ENCODING_AAC_HE_V1: 445 case ENCODING_AAC_HE_V2: 446 return true; 447 default: 448 return false; 449 } 450 } 451 452 /** @hide */ isPublicEncoding(int audioFormat)453 public static boolean isPublicEncoding(int audioFormat) 454 { 455 switch (audioFormat) { 456 case ENCODING_PCM_8BIT: 457 case ENCODING_PCM_16BIT: 458 case ENCODING_PCM_FLOAT: 459 case ENCODING_AC3: 460 case ENCODING_E_AC3: 461 case ENCODING_DTS: 462 case ENCODING_DTS_HD: 463 return true; 464 default: 465 return false; 466 } 467 } 468 469 /** @hide */ isEncodingLinearPcm(int audioFormat)470 public static boolean isEncodingLinearPcm(int audioFormat) 471 { 472 switch (audioFormat) { 473 case ENCODING_PCM_8BIT: 474 case ENCODING_PCM_16BIT: 475 case ENCODING_PCM_FLOAT: 476 case ENCODING_DEFAULT: 477 return true; 478 case ENCODING_AC3: 479 case ENCODING_E_AC3: 480 case ENCODING_DTS: 481 case ENCODING_DTS_HD: 482 case ENCODING_MP3: 483 case ENCODING_AAC_LC: 484 case ENCODING_AAC_HE_V1: 485 case ENCODING_AAC_HE_V2: 486 return false; 487 case ENCODING_INVALID: 488 default: 489 throw new IllegalArgumentException("Bad audio format " + audioFormat); 490 } 491 } 492 493 /** 494 * Returns an array of public encoding values extracted from an array of 495 * encoding values. 496 * @hide 497 */ filterPublicFormats(int[] formats)498 public static int[] filterPublicFormats(int[] formats) { 499 if (formats == null) { 500 return null; 501 } 502 int[] myCopy = Arrays.copyOf(formats, formats.length); 503 int size = 0; 504 for (int i = 0; i < myCopy.length; i++) { 505 if (isPublicEncoding(myCopy[i])) { 506 if (size != i) { 507 myCopy[size] = myCopy[i]; 508 } 509 size++; 510 } 511 } 512 return Arrays.copyOf(myCopy, size); 513 } 514 515 /** @removed */ AudioFormat()516 public AudioFormat() 517 { 518 throw new UnsupportedOperationException("There is no valid usage of this constructor"); 519 } 520 521 /** 522 * Private constructor with an ignored argument to differentiate from the removed default ctor 523 * @param ignoredArgument 524 */ AudioFormat(int ignoredArgument)525 private AudioFormat(int ignoredArgument) { 526 } 527 528 /** 529 * Constructor used by the JNI 530 */ 531 // Update sound trigger JNI in core/jni/android_hardware_SoundTrigger.cpp when modifying this 532 // constructor AudioFormat(int encoding, int sampleRate, int channelMask, int channelIndexMask)533 private AudioFormat(int encoding, int sampleRate, int channelMask, int channelIndexMask) { 534 mEncoding = encoding; 535 mSampleRate = sampleRate; 536 mChannelMask = channelMask; 537 mChannelIndexMask = channelIndexMask; 538 mPropertySetMask = AUDIO_FORMAT_HAS_PROPERTY_ENCODING | 539 AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE | 540 AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK | 541 AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_INDEX_MASK; 542 } 543 544 /** @hide */ 545 public final static int AUDIO_FORMAT_HAS_PROPERTY_NONE = 0x0; 546 /** @hide */ 547 public final static int AUDIO_FORMAT_HAS_PROPERTY_ENCODING = 0x1 << 0; 548 /** @hide */ 549 public final static int AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE = 0x1 << 1; 550 /** @hide */ 551 public final static int AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK = 0x1 << 2; 552 /** @hide */ 553 public final static int AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_INDEX_MASK = 0x1 << 3; 554 555 private int mEncoding; 556 private int mSampleRate; 557 private int mChannelMask; 558 private int mChannelIndexMask; 559 private int mPropertySetMask; 560 561 /** 562 * Return the encoding. 563 * See the section on <a href="#encoding">encodings</a> for more information about the different 564 * types of supported audio encoding. 565 * @return one of the values that can be set in {@link Builder#setEncoding(int)} or 566 * {@link AudioFormat#ENCODING_INVALID} if not set. 567 */ getEncoding()568 public int getEncoding() { 569 if ((mPropertySetMask & AUDIO_FORMAT_HAS_PROPERTY_ENCODING) == 0) { 570 return ENCODING_INVALID; 571 } 572 return mEncoding; 573 } 574 575 /** 576 * Return the sample rate. 577 * @return one of the values that can be set in {@link Builder#setSampleRate(int)} or 578 * 0 if not set. 579 */ getSampleRate()580 public int getSampleRate() { 581 if ((mPropertySetMask & AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE) == 0) { 582 return 0; 583 } 584 return mSampleRate; 585 } 586 587 /** 588 * Return the channel mask. 589 * See the section on <a href="#channelMask">channel masks</a> for more information about 590 * the difference between index-based masks(as returned by {@link #getChannelIndexMask()}) and 591 * the position-based mask returned by this function. 592 * @return one of the values that can be set in {@link Builder#setChannelMask(int)} or 593 * {@link AudioFormat#CHANNEL_INVALID} if not set. 594 */ getChannelMask()595 public int getChannelMask() { 596 if ((mPropertySetMask & AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK) == 0) { 597 return CHANNEL_INVALID; 598 } 599 return mChannelMask; 600 } 601 602 /** 603 * Return the channel index mask. 604 * See the section on <a href="#channelMask">channel masks</a> for more information about 605 * the difference between index-based masks, and position-based masks (as returned 606 * by {@link #getChannelMask()}). 607 * @return one of the values that can be set in {@link Builder#setChannelIndexMask(int)} or 608 * {@link AudioFormat#CHANNEL_INVALID} if not set or an invalid mask was used. 609 */ getChannelIndexMask()610 public int getChannelIndexMask() { 611 if ((mPropertySetMask & AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_INDEX_MASK) == 0) { 612 return CHANNEL_INVALID; 613 } 614 return mChannelIndexMask; 615 } 616 617 /** 618 * Return the channel count. 619 * @return the channel count derived from the channel position mask or the channel index mask. 620 * Zero is returned if both the channel position mask and the channel index mask are not set. 621 */ getChannelCount()622 public int getChannelCount() { 623 final int channelIndexCount = Integer.bitCount(getChannelIndexMask()); 624 int channelCount = channelCountFromOutChannelMask(getChannelMask()); 625 if (channelCount == 0) { 626 channelCount = channelIndexCount; 627 } else if (channelCount != channelIndexCount && channelIndexCount != 0) { 628 channelCount = 0; // position and index channel count mismatch 629 } 630 return channelCount; 631 } 632 633 /** @hide */ getPropertySetMask()634 public int getPropertySetMask() { 635 return mPropertySetMask; 636 } 637 638 /** 639 * Builder class for {@link AudioFormat} objects. 640 * Use this class to configure and create an AudioFormat instance. By setting format 641 * characteristics such as audio encoding, channel mask or sample rate, you indicate which 642 * of those are to vary from the default behavior on this device wherever this audio format 643 * is used. See {@link AudioFormat} for a complete description of the different parameters that 644 * can be used to configure an <code>AudioFormat</code> instance. 645 * <p>{@link AudioFormat} is for instance used in 646 * {@link AudioTrack#AudioTrack(AudioAttributes, AudioFormat, int, int, int)}. In this 647 * constructor, every format characteristic set on the <code>Builder</code> (e.g. with 648 * {@link #setSampleRate(int)}) will alter the default values used by an 649 * <code>AudioTrack</code>. In this case for audio playback with <code>AudioTrack</code>, the 650 * sample rate set in the <code>Builder</code> would override the platform output sample rate 651 * which would otherwise be selected by default. 652 */ 653 public static class Builder { 654 private int mEncoding = ENCODING_INVALID; 655 private int mSampleRate = 0; 656 private int mChannelMask = CHANNEL_INVALID; 657 private int mChannelIndexMask = 0; 658 private int mPropertySetMask = AUDIO_FORMAT_HAS_PROPERTY_NONE; 659 660 /** 661 * Constructs a new Builder with none of the format characteristics set. 662 */ Builder()663 public Builder() { 664 } 665 666 /** 667 * Constructs a new Builder from a given {@link AudioFormat}. 668 * @param af the {@link AudioFormat} object whose data will be reused in the new Builder. 669 */ Builder(AudioFormat af)670 public Builder(AudioFormat af) { 671 mEncoding = af.mEncoding; 672 mSampleRate = af.mSampleRate; 673 mChannelMask = af.mChannelMask; 674 mChannelIndexMask = af.mChannelIndexMask; 675 mPropertySetMask = af.mPropertySetMask; 676 } 677 678 /** 679 * Combines all of the format characteristics that have been set and return a new 680 * {@link AudioFormat} object. 681 * @return a new {@link AudioFormat} object 682 */ build()683 public AudioFormat build() { 684 AudioFormat af = new AudioFormat(1980/*ignored*/); 685 af.mEncoding = mEncoding; 686 af.mSampleRate = mSampleRate; 687 af.mChannelMask = mChannelMask; 688 af.mChannelIndexMask = mChannelIndexMask; 689 af.mPropertySetMask = mPropertySetMask; 690 return af; 691 } 692 693 /** 694 * Sets the data encoding format. 695 * @param encoding one of {@link AudioFormat#ENCODING_DEFAULT}, 696 * {@link AudioFormat#ENCODING_PCM_8BIT}, 697 * {@link AudioFormat#ENCODING_PCM_16BIT}, 698 * {@link AudioFormat#ENCODING_PCM_FLOAT}, 699 * {@link AudioFormat#ENCODING_AC3}, 700 * {@link AudioFormat#ENCODING_E_AC3}. 701 * {@link AudioFormat#ENCODING_DTS}, 702 * {@link AudioFormat#ENCODING_DTS_HD}. 703 * @return the same Builder instance. 704 * @throws java.lang.IllegalArgumentException 705 */ setEncoding(@ncoding int encoding)706 public Builder setEncoding(@Encoding int encoding) throws IllegalArgumentException { 707 switch (encoding) { 708 case ENCODING_DEFAULT: 709 mEncoding = ENCODING_PCM_16BIT; 710 break; 711 case ENCODING_PCM_8BIT: 712 case ENCODING_PCM_16BIT: 713 case ENCODING_PCM_FLOAT: 714 case ENCODING_AC3: 715 case ENCODING_E_AC3: 716 case ENCODING_DTS: 717 case ENCODING_DTS_HD: 718 mEncoding = encoding; 719 break; 720 case ENCODING_INVALID: 721 default: 722 throw new IllegalArgumentException("Invalid encoding " + encoding); 723 } 724 mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_ENCODING; 725 return this; 726 } 727 728 /** 729 * Sets the channel position mask. 730 * The channel position mask specifies the association between audio samples in a frame 731 * with named endpoint channels. The samples in the frame correspond to the 732 * named set bits in the channel position mask, in ascending bit order. 733 * See {@link #setChannelIndexMask(int)} to specify channels 734 * based on endpoint numbered channels. This <a href="#channelPositionMask>description of 735 * channel position masks</a> covers the concept in more details. 736 * @param channelMask describes the configuration of the audio channels. 737 * <p> For output, the channelMask can be an OR-ed combination of 738 * channel position masks, e.g. 739 * {@link AudioFormat#CHANNEL_OUT_FRONT_LEFT}, 740 * {@link AudioFormat#CHANNEL_OUT_FRONT_RIGHT}, 741 * {@link AudioFormat#CHANNEL_OUT_FRONT_CENTER}, 742 * {@link AudioFormat#CHANNEL_OUT_LOW_FREQUENCY} 743 * {@link AudioFormat#CHANNEL_OUT_BACK_LEFT}, 744 * {@link AudioFormat#CHANNEL_OUT_BACK_RIGHT}, 745 * {@link AudioFormat#CHANNEL_OUT_BACK_CENTER}, 746 * {@link AudioFormat#CHANNEL_OUT_SIDE_LEFT}, 747 * {@link AudioFormat#CHANNEL_OUT_SIDE_RIGHT}. 748 * <p> For a valid {@link AudioTrack} channel position mask, 749 * the following conditions apply: 750 * <br> (1) at most eight channel positions may be used; 751 * <br> (2) right/left pairs should be matched. 752 * <p> For input or {@link AudioRecord}, the mask should be 753 * {@link AudioFormat#CHANNEL_IN_MONO} or 754 * {@link AudioFormat#CHANNEL_IN_STEREO}. {@link AudioFormat#CHANNEL_IN_MONO} is 755 * guaranteed to work on all devices. 756 * @return the same <code>Builder</code> instance. 757 * @throws IllegalArgumentException if the channel mask is invalid or 758 * if both channel index mask and channel position mask 759 * are specified but do not have the same channel count. 760 */ setChannelMask(int channelMask)761 public @NonNull Builder setChannelMask(int channelMask) { 762 if (channelMask == 0) { 763 throw new IllegalArgumentException("Invalid zero channel mask"); 764 } else if (/* channelMask != 0 && */ mChannelIndexMask != 0 && 765 Integer.bitCount(channelMask) != Integer.bitCount(mChannelIndexMask)) { 766 throw new IllegalArgumentException("Mismatched channel count for mask " + 767 Integer.toHexString(channelMask).toUpperCase()); 768 } 769 mChannelMask = channelMask; 770 mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK; 771 return this; 772 } 773 774 /** 775 * Sets the channel index mask. 776 * A channel index mask specifies the association of audio samples in the frame 777 * with numbered endpoint channels. The i-th bit in the channel index 778 * mask corresponds to the i-th endpoint channel. 779 * For example, an endpoint with four channels is represented 780 * as index mask bits 0 through 3. This <a href="#channelIndexMask>description of channel 781 * index masks</a> covers the concept in more details. 782 * See {@link #setChannelMask(int)} for a positional mask interpretation. 783 * <p> Both {@link AudioTrack} and {@link AudioRecord} support 784 * a channel index mask. 785 * If a channel index mask is specified it is used, 786 * otherwise the channel position mask specified 787 * by <code>setChannelMask</code> is used. 788 * For <code>AudioTrack</code> and <code>AudioRecord</code>, 789 * a channel position mask is not required if a channel index mask is specified. 790 * 791 * @param channelIndexMask describes the configuration of the audio channels. 792 * <p> For output, the <code>channelIndexMask</code> is an OR-ed combination of 793 * bits representing the mapping of <code>AudioTrack</code> write samples 794 * to output sink channels. 795 * For example, a mask of <code>0xa</code>, or binary <code>1010</code>, 796 * means the <code>AudioTrack</code> write frame consists of two samples, 797 * which are routed to the second and the fourth channels of the output sink. 798 * Unmatched output sink channels are zero filled and unmatched 799 * <code>AudioTrack</code> write samples are dropped. 800 * <p> For input, the <code>channelIndexMask</code> is an OR-ed combination of 801 * bits representing the mapping of input source channels to 802 * <code>AudioRecord</code> read samples. 803 * For example, a mask of <code>0x5</code>, or binary 804 * <code>101</code>, will read from the first and third channel of the input 805 * source device and store them in the first and second sample of the 806 * <code>AudioRecord</code> read frame. 807 * Unmatched input source channels are dropped and 808 * unmatched <code>AudioRecord</code> read samples are zero filled. 809 * @return the same <code>Builder</code> instance. 810 * @throws IllegalArgumentException if the channel index mask is invalid or 811 * if both channel index mask and channel position mask 812 * are specified but do not have the same channel count. 813 */ setChannelIndexMask(int channelIndexMask)814 public @NonNull Builder setChannelIndexMask(int channelIndexMask) { 815 if (channelIndexMask == 0) { 816 throw new IllegalArgumentException("Invalid zero channel index mask"); 817 } else if (/* channelIndexMask != 0 && */ mChannelMask != 0 && 818 Integer.bitCount(channelIndexMask) != Integer.bitCount(mChannelMask)) { 819 throw new IllegalArgumentException("Mismatched channel count for index mask " + 820 Integer.toHexString(channelIndexMask).toUpperCase()); 821 } 822 mChannelIndexMask = channelIndexMask; 823 mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_INDEX_MASK; 824 return this; 825 } 826 827 /** 828 * Sets the sample rate. 829 * @param sampleRate the sample rate expressed in Hz 830 * @return the same Builder instance. 831 * @throws java.lang.IllegalArgumentException 832 */ setSampleRate(int sampleRate)833 public Builder setSampleRate(int sampleRate) throws IllegalArgumentException { 834 if ((sampleRate <= 0) || (sampleRate > 192000)) { 835 throw new IllegalArgumentException("Invalid sample rate " + sampleRate); 836 } 837 mSampleRate = sampleRate; 838 mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE; 839 return this; 840 } 841 } 842 843 @Override toString()844 public String toString () { 845 return new String("AudioFormat:" 846 + " props=" + mPropertySetMask 847 + " enc=" + mEncoding 848 + " chan=0x" + Integer.toHexString(mChannelMask).toUpperCase() 849 + " chan_index=0x" + Integer.toHexString(mChannelIndexMask).toUpperCase() 850 + " rate=" + mSampleRate); 851 } 852 853 /** @hide */ 854 @IntDef({ 855 ENCODING_DEFAULT, 856 ENCODING_PCM_8BIT, 857 ENCODING_PCM_16BIT, 858 ENCODING_PCM_FLOAT, 859 ENCODING_AC3, 860 ENCODING_E_AC3, 861 ENCODING_DTS, 862 ENCODING_DTS_HD 863 }) 864 @Retention(RetentionPolicy.SOURCE) 865 public @interface Encoding {} 866 867 } 868