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.IntRange; 21 import android.annotation.NonNull; 22 import android.annotation.TestApi; 23 import android.compat.annotation.UnsupportedAppUsage; 24 import android.os.Build; 25 import android.os.Parcel; 26 import android.os.Parcelable; 27 28 import java.lang.annotation.Retention; 29 import java.lang.annotation.RetentionPolicy; 30 import java.util.Arrays; 31 import java.util.Objects; 32 33 /** 34 * The {@link AudioFormat} class is used to access a number of audio format and 35 * channel configuration constants. They are for instance used 36 * in {@link AudioTrack} and {@link AudioRecord}, as valid values in individual parameters of 37 * constructors like {@link AudioTrack#AudioTrack(int, int, int, int, int, int)}, where the fourth 38 * parameter is one of the <code>AudioFormat.ENCODING_*</code> constants. 39 * The <code>AudioFormat</code> constants are also used in {@link MediaFormat} to specify 40 * audio related values commonly used in media, such as for {@link MediaFormat#KEY_CHANNEL_MASK}. 41 * <p>The {@link AudioFormat.Builder} class can be used to create instances of 42 * the <code>AudioFormat</code> format class. 43 * Refer to 44 * {@link AudioFormat.Builder} for documentation on the mechanics of the configuration and building 45 * of such instances. Here we describe the main concepts that the <code>AudioFormat</code> class 46 * allow you to convey in each instance, they are: 47 * <ol> 48 * <li><a href="#sampleRate">sample rate</a> 49 * <li><a href="#encoding">encoding</a> 50 * <li><a href="#channelMask">channel masks</a> 51 * </ol> 52 * <p>Closely associated with the <code>AudioFormat</code> is the notion of an 53 * <a href="#audioFrame">audio frame</a>, which is used throughout the documentation 54 * to represent the minimum size complete unit of audio data. 55 * 56 * <h4 id="sampleRate">Sample rate</h4> 57 * <p>Expressed in Hz, the sample rate in an <code>AudioFormat</code> instance expresses the number 58 * of audio samples for each channel per second in the content you are playing or recording. It is 59 * not the sample rate 60 * at which content is rendered or produced. For instance a sound at a media sample rate of 8000Hz 61 * can be played on a device operating at a sample rate of 48000Hz; the sample rate conversion is 62 * automatically handled by the platform, it will not play at 6x speed. 63 * 64 * <p>As of API {@link android.os.Build.VERSION_CODES#M}, 65 * sample rates up to 192kHz are supported 66 * for <code>AudioRecord</code> and <code>AudioTrack</code>, with sample rate conversion 67 * performed as needed. 68 * To improve efficiency and avoid lossy conversions, it is recommended to match the sample rate 69 * for <code>AudioRecord</code> and <code>AudioTrack</code> to the endpoint device 70 * sample rate, and limit the sample rate to no more than 48kHz unless there are special 71 * device capabilities that warrant a higher rate. 72 * 73 * <h4 id="encoding">Encoding</h4> 74 * <p>Audio encoding is used to describe the bit representation of audio data, which can be 75 * either linear PCM or compressed audio, such as AC3 or DTS. 76 * <p>For linear PCM, the audio encoding describes the sample size, 8 bits, 16 bits, or 32 bits, 77 * and the sample representation, integer or float. 78 * <ul> 79 * <li> {@link #ENCODING_PCM_8BIT}: The audio sample is a 8 bit unsigned integer in the 80 * range [0, 255], with a 128 offset for zero. This is typically stored as a Java byte in a 81 * byte array or ByteBuffer. Since the Java byte is <em>signed</em>, 82 * be careful with math operations and conversions as the most significant bit is inverted. 83 * </li> 84 * <li> {@link #ENCODING_PCM_16BIT}: The audio sample is a 16 bit signed integer 85 * typically stored as a Java short in a short array, but when the short 86 * is stored in a ByteBuffer, it is native endian (as compared to the default Java big endian). 87 * The short has full range from [-32768, 32767], 88 * and is sometimes interpreted as fixed point Q.15 data. 89 * </li> 90 * <li> {@link #ENCODING_PCM_FLOAT}: Introduced in 91 * API {@link android.os.Build.VERSION_CODES#LOLLIPOP}, this encoding specifies that 92 * the audio sample is a 32 bit IEEE single precision float. The sample can be 93 * manipulated as a Java float in a float array, though within a ByteBuffer 94 * it is stored in native endian byte order. 95 * The nominal range of <code>ENCODING_PCM_FLOAT</code> audio data is [-1.0, 1.0]. 96 * It is implementation dependent whether the positive maximum of 1.0 is included 97 * in the interval. Values outside of the nominal range are clamped before 98 * sending to the endpoint device. Beware that 99 * the handling of NaN is undefined; subnormals may be treated as zero; and 100 * infinities are generally clamped just like other values for <code>AudioTrack</code> 101 * – try to avoid infinities because they can easily generate a NaN. 102 * <br> 103 * To achieve higher audio bit depth than a signed 16 bit integer short, 104 * it is recommended to use <code>ENCODING_PCM_FLOAT</code> for audio capture, processing, 105 * and playback. 106 * Floats are efficiently manipulated by modern CPUs, 107 * have greater precision than 24 bit signed integers, 108 * and have greater dynamic range than 32 bit signed integers. 109 * <code>AudioRecord</code> as of API {@link android.os.Build.VERSION_CODES#M} and 110 * <code>AudioTrack</code> as of API {@link android.os.Build.VERSION_CODES#LOLLIPOP} 111 * support <code>ENCODING_PCM_FLOAT</code>. 112 * </li> 113 * <li> {@link #ENCODING_PCM_24BIT_PACKED}: Introduced in 114 * API {@link android.os.Build.VERSION_CODES#S}, 115 * this encoding specifies the audio sample is an 116 * extended precision 24 bit signed integer 117 * stored as a 3 Java bytes in a {@code ByteBuffer} or byte array in native endian 118 * (see {@link java.nio.ByteOrder#nativeOrder()}). 119 * Each sample has full range from [-8388608, 8388607], 120 * and can be interpreted as fixed point Q.23 data. 121 * </li> 122 * <li> {@link #ENCODING_PCM_32BIT}: Introduced in 123 * API {@link android.os.Build.VERSION_CODES#S}, 124 * this encoding specifies the audio sample is an 125 * extended precision 32 bit signed integer 126 * stored as a 4 Java bytes in a {@code ByteBuffer} or byte array in native endian 127 * (see {@link java.nio.ByteOrder#nativeOrder()}). 128 * Each sample has full range from [-2147483648, 2147483647], 129 * and can be interpreted as fixed point Q.31 data. 130 * </li> 131 * </ul> 132 * <p>For compressed audio, the encoding specifies the method of compression, 133 * for example {@link #ENCODING_AC3} and {@link #ENCODING_DTS}. The compressed 134 * audio data is typically stored as bytes in 135 * a byte array or ByteBuffer. When a compressed audio encoding is specified 136 * for an <code>AudioTrack</code>, it creates a direct (non-mixed) track 137 * for output to an endpoint (such as HDMI) capable of decoding the compressed audio. 138 * For (most) other endpoints, which are not capable of decoding such compressed audio, 139 * you will need to decode the data first, typically by creating a {@link MediaCodec}. 140 * Alternatively, one may use {@link MediaPlayer} for playback of compressed 141 * audio files or streams. 142 * <p>When compressed audio is sent out through a direct <code>AudioTrack</code>, 143 * it need not be written in exact multiples of the audio access unit; 144 * this differs from <code>MediaCodec</code> input buffers. 145 * 146 * <h4 id="channelMask">Channel mask</h4> 147 * <p>Channel masks are used in <code>AudioTrack</code> and <code>AudioRecord</code> to describe 148 * the samples and their arrangement in the audio frame. They are also used in the endpoint (e.g. 149 * a USB audio interface, a DAC connected to headphones) to specify allowable configurations of a 150 * particular device. 151 * <br>As of API {@link android.os.Build.VERSION_CODES#M}, there are two types of channel masks: 152 * channel position masks and channel index masks. 153 * 154 * <h5 id="channelPositionMask">Channel position masks</h5> 155 * Channel position masks are the original Android channel masks, and are used since API 156 * {@link android.os.Build.VERSION_CODES#BASE}. 157 * For input and output, they imply a positional nature - the location of a speaker or a microphone 158 * for recording or playback. 159 * <br>For a channel position mask, each allowed channel position corresponds to a bit in the 160 * channel mask. If that channel position is present in the audio frame, that bit is set, 161 * otherwise it is zero. The order of the bits (from lsb to msb) corresponds to the order of that 162 * position's sample in the audio frame. 163 * <br>The canonical channel position masks by channel count are as follows: 164 * <br><table> 165 * <tr><td>channel count</td><td>channel position mask</td></tr> 166 * <tr><td>1</td><td>{@link #CHANNEL_OUT_MONO}</td></tr> 167 * <tr><td>2</td><td>{@link #CHANNEL_OUT_STEREO}</td></tr> 168 * <tr><td>3</td><td>{@link #CHANNEL_OUT_STEREO} | {@link #CHANNEL_OUT_FRONT_CENTER}</td></tr> 169 * <tr><td>4</td><td>{@link #CHANNEL_OUT_QUAD}</td></tr> 170 * <tr><td>5</td><td>{@link #CHANNEL_OUT_QUAD} | {@link #CHANNEL_OUT_FRONT_CENTER}</td></tr> 171 * <tr><td>6</td><td>{@link #CHANNEL_OUT_5POINT1}</td></tr> 172 * <tr><td>7</td><td>{@link #CHANNEL_OUT_5POINT1} | {@link #CHANNEL_OUT_BACK_CENTER}</td></tr> 173 * <tr><td>8</td><td>{@link #CHANNEL_OUT_7POINT1_SURROUND}</td></tr> 174 * </table> 175 * <br>These masks are an ORed composite of individual channel masks. For example 176 * {@link #CHANNEL_OUT_STEREO} is composed of {@link #CHANNEL_OUT_FRONT_LEFT} and 177 * {@link #CHANNEL_OUT_FRONT_RIGHT}. 178 * 179 * <h5 id="channelIndexMask">Channel index masks</h5> 180 * Channel index masks are introduced in API {@link android.os.Build.VERSION_CODES#M}. They allow 181 * the selection of a particular channel from the source or sink endpoint by number, i.e. the first 182 * channel, the second channel, and so forth. This avoids problems with artificially assigning 183 * positions to channels of an endpoint, or figuring what the i<sup>th</sup> position bit is within 184 * an endpoint's channel position mask etc. 185 * <br>Here's an example where channel index masks address this confusion: dealing with a 4 channel 186 * USB device. Using a position mask, and based on the channel count, this would be a 187 * {@link #CHANNEL_OUT_QUAD} device, but really one is only interested in channel 0 188 * through channel 3. The USB device would then have the following individual bit channel masks: 189 * {@link #CHANNEL_OUT_FRONT_LEFT}, 190 * {@link #CHANNEL_OUT_FRONT_RIGHT}, {@link #CHANNEL_OUT_BACK_LEFT} 191 * and {@link #CHANNEL_OUT_BACK_RIGHT}. But which is channel 0 and which is 192 * channel 3? 193 * <br>For a channel index mask, each channel number is represented as a bit in the mask, from the 194 * lsb (channel 0) upwards to the msb, numerically this bit value is 195 * <code>1 << channelNumber</code>. 196 * A set bit indicates that channel is present in the audio frame, otherwise it is cleared. 197 * The order of the bits also correspond to that channel number's sample order in the audio frame. 198 * <br>For the previous 4 channel USB device example, the device would have a channel index mask 199 * <code>0xF</code>. Suppose we wanted to select only the first and the third channels; this would 200 * correspond to a channel index mask <code>0x5</code> (the first and third bits set). If an 201 * <code>AudioTrack</code> uses this channel index mask, the audio frame would consist of two 202 * samples, the first sample of each frame routed to channel 0, and the second sample of each frame 203 * routed to channel 2. 204 * The canonical channel index masks by channel count are given by the formula 205 * <code>(1 << channelCount) - 1</code>. 206 * 207 * <h5>Use cases</h5> 208 * <ul> 209 * <li><i>Channel position mask for an endpoint:</i> <code>CHANNEL_OUT_FRONT_LEFT</code>, 210 * <code>CHANNEL_OUT_FRONT_CENTER</code>, etc. for HDMI home theater purposes. 211 * <li><i>Channel position mask for an audio stream:</i> Creating an <code>AudioTrack</code> 212 * to output movie content, where 5.1 multichannel output is to be written. 213 * <li><i>Channel index mask for an endpoint:</i> USB devices for which input and output do not 214 * correspond to left or right speaker or microphone. 215 * <li><i>Channel index mask for an audio stream:</i> An <code>AudioRecord</code> may only want the 216 * third and fourth audio channels of the endpoint (i.e. the second channel pair), and not care the 217 * about position it corresponds to, in which case the channel index mask is <code>0xC</code>. 218 * Multichannel <code>AudioRecord</code> sessions should use channel index masks. 219 * </ul> 220 * <h4 id="audioFrame">Audio Frame</h4> 221 * <p>For linear PCM, an audio frame consists of a set of samples captured at the same time, 222 * whose count and 223 * channel association are given by the <a href="#channelMask">channel mask</a>, 224 * and whose sample contents are specified by the <a href="#encoding">encoding</a>. 225 * For example, a stereo 16 bit PCM frame consists of 226 * two 16 bit linear PCM samples, with a frame size of 4 bytes. 227 * For compressed audio, an audio frame may alternately 228 * refer to an access unit of compressed data bytes that is logically grouped together for 229 * decoding and bitstream access (e.g. {@link MediaCodec}), 230 * or a single byte of compressed data (e.g. {@link AudioTrack#getBufferSizeInFrames() 231 * AudioTrack.getBufferSizeInFrames()}), 232 * or the linear PCM frame result from decoding the compressed data 233 * (e.g.{@link AudioTrack#getPlaybackHeadPosition() 234 * AudioTrack.getPlaybackHeadPosition()}), 235 * depending on the context where audio frame is used. 236 * For the purposes of {@link AudioFormat#getFrameSizeInBytes()}, a compressed data format 237 * returns a frame size of 1 byte. 238 */ 239 public final class AudioFormat implements Parcelable { 240 241 //--------------------------------------------------------- 242 // Constants 243 //-------------------- 244 /** Invalid audio data format */ 245 public static final int ENCODING_INVALID = 0; 246 /** Default audio data format */ 247 public static final int ENCODING_DEFAULT = 1; 248 249 // These values must be kept in sync with core/jni/android_media_AudioFormat.h 250 // Also sync av/services/audiopolicy/managerdefault/ConfigParsingUtils.h 251 /** Audio data format: PCM 16 bit per sample. Guaranteed to be supported by devices. */ 252 public static final int ENCODING_PCM_16BIT = 2; 253 /** Audio data format: PCM 8 bit per sample. Not guaranteed to be supported by devices. */ 254 public static final int ENCODING_PCM_8BIT = 3; 255 /** Audio data format: single-precision floating-point per sample */ 256 public static final int ENCODING_PCM_FLOAT = 4; 257 /** Audio data format: AC-3 compressed, also known as Dolby Digital */ 258 public static final int ENCODING_AC3 = 5; 259 /** Audio data format: E-AC-3 compressed, also known as Dolby Digital Plus or DD+ */ 260 public static final int ENCODING_E_AC3 = 6; 261 /** Audio data format: DTS compressed */ 262 public static final int ENCODING_DTS = 7; 263 /** Audio data format: DTS HD compressed */ 264 public static final int ENCODING_DTS_HD = 8; 265 /** Audio data format: MP3 compressed */ 266 public static final int ENCODING_MP3 = 9; 267 /** Audio data format: AAC LC compressed */ 268 public static final int ENCODING_AAC_LC = 10; 269 /** Audio data format: AAC HE V1 compressed */ 270 public static final int ENCODING_AAC_HE_V1 = 11; 271 /** Audio data format: AAC HE V2 compressed */ 272 public static final int ENCODING_AAC_HE_V2 = 12; 273 274 /** Audio data format: compressed audio wrapped in PCM for HDMI 275 * or S/PDIF passthrough. 276 * For devices whose SDK version is less than {@link android.os.Build.VERSION_CODES#S}, the 277 * channel mask of IEC61937 track must be {@link #CHANNEL_OUT_STEREO}. 278 * Data should be written to the stream in a short[] array. 279 * If the data is written in a byte[] array then there may be endian problems 280 * on some platforms when converting to short internally. 281 */ 282 public static final int ENCODING_IEC61937 = 13; 283 /** Audio data format: DOLBY TRUEHD compressed 284 **/ 285 public static final int ENCODING_DOLBY_TRUEHD = 14; 286 /** Audio data format: AAC ELD compressed */ 287 public static final int ENCODING_AAC_ELD = 15; 288 /** Audio data format: AAC xHE compressed */ 289 public static final int ENCODING_AAC_XHE = 16; 290 /** Audio data format: AC-4 sync frame transport format */ 291 public static final int ENCODING_AC4 = 17; 292 /** Audio data format: E-AC-3-JOC compressed 293 * E-AC-3-JOC streams can be decoded by downstream devices supporting {@link #ENCODING_E_AC3}. 294 * Use {@link #ENCODING_E_AC3} as the AudioTrack encoding when the downstream device 295 * supports {@link #ENCODING_E_AC3} but not {@link #ENCODING_E_AC3_JOC}. 296 **/ 297 public static final int ENCODING_E_AC3_JOC = 18; 298 /** Audio data format: Dolby MAT (Metadata-enhanced Audio Transmission) 299 * Dolby MAT bitstreams are used to transmit Dolby TrueHD, channel-based PCM, or PCM with 300 * metadata (object audio) over HDMI (e.g. Dolby Atmos content). 301 **/ 302 public static final int ENCODING_DOLBY_MAT = 19; 303 /** Audio data format: OPUS compressed. */ 304 public static final int ENCODING_OPUS = 20; 305 306 /** @hide 307 * We do not permit legacy short array reads or writes for encodings 308 * introduced after this threshold. 309 */ 310 public static final int ENCODING_LEGACY_SHORT_ARRAY_THRESHOLD = ENCODING_OPUS; 311 312 /** Audio data format: PCM 24 bit per sample packed as 3 bytes. 313 * 314 * The bytes are in little-endian order, so the least significant byte 315 * comes first in the byte array. 316 * 317 * Not guaranteed to be supported by devices, may be emulated if not supported. */ 318 public static final int ENCODING_PCM_24BIT_PACKED = 21; 319 /** Audio data format: PCM 32 bit per sample. 320 * Not guaranteed to be supported by devices, may be emulated if not supported. */ 321 public static final int ENCODING_PCM_32BIT = 22; 322 323 /** Audio data format: MPEG-H baseline profile, level 3 */ 324 public static final int ENCODING_MPEGH_BL_L3 = 23; 325 /** Audio data format: MPEG-H baseline profile, level 4 */ 326 public static final int ENCODING_MPEGH_BL_L4 = 24; 327 /** Audio data format: MPEG-H low complexity profile, level 3 */ 328 public static final int ENCODING_MPEGH_LC_L3 = 25; 329 /** Audio data format: MPEG-H low complexity profile, level 4 */ 330 public static final int ENCODING_MPEGH_LC_L4 = 26; 331 /** Audio data format: DTS UHD compressed */ 332 public static final int ENCODING_DTS_UHD = 27; 333 /** Audio data format: DRA compressed */ 334 public static final int ENCODING_DRA = 28; 335 336 /** @hide */ toLogFriendlyEncoding(int enc)337 public static String toLogFriendlyEncoding(int enc) { 338 switch(enc) { 339 case ENCODING_INVALID: 340 return "ENCODING_INVALID"; 341 case ENCODING_PCM_16BIT: 342 return "ENCODING_PCM_16BIT"; 343 case ENCODING_PCM_8BIT: 344 return "ENCODING_PCM_8BIT"; 345 case ENCODING_PCM_FLOAT: 346 return "ENCODING_PCM_FLOAT"; 347 case ENCODING_AC3: 348 return "ENCODING_AC3"; 349 case ENCODING_E_AC3: 350 return "ENCODING_E_AC3"; 351 case ENCODING_DTS: 352 return "ENCODING_DTS"; 353 case ENCODING_DTS_HD: 354 return "ENCODING_DTS_HD"; 355 case ENCODING_MP3: 356 return "ENCODING_MP3"; 357 case ENCODING_AAC_LC: 358 return "ENCODING_AAC_LC"; 359 case ENCODING_AAC_HE_V1: 360 return "ENCODING_AAC_HE_V1"; 361 case ENCODING_AAC_HE_V2: 362 return "ENCODING_AAC_HE_V2"; 363 case ENCODING_IEC61937: 364 return "ENCODING_IEC61937"; 365 case ENCODING_DOLBY_TRUEHD: 366 return "ENCODING_DOLBY_TRUEHD"; 367 case ENCODING_AAC_ELD: 368 return "ENCODING_AAC_ELD"; 369 case ENCODING_AAC_XHE: 370 return "ENCODING_AAC_XHE"; 371 case ENCODING_AC4: 372 return "ENCODING_AC4"; 373 case ENCODING_E_AC3_JOC: 374 return "ENCODING_E_AC3_JOC"; 375 case ENCODING_DOLBY_MAT: 376 return "ENCODING_DOLBY_MAT"; 377 case ENCODING_OPUS: 378 return "ENCODING_OPUS"; 379 case ENCODING_PCM_24BIT_PACKED: 380 return "ENCODING_PCM_24BIT_PACKED"; 381 case ENCODING_PCM_32BIT: 382 return "ENCODING_PCM_32BIT"; 383 case ENCODING_MPEGH_BL_L3: 384 return "ENCODING_MPEGH_BL_L3"; 385 case ENCODING_MPEGH_BL_L4: 386 return "ENCODING_MPEGH_BL_L4"; 387 case ENCODING_MPEGH_LC_L3: 388 return "ENCODING_MPEGH_LC_L3"; 389 case ENCODING_MPEGH_LC_L4: 390 return "ENCODING_MPEGH_LC_L4"; 391 case ENCODING_DTS_UHD: 392 return "ENCODING_DTS_UHD"; 393 case ENCODING_DRA: 394 return "ENCODING_DRA"; 395 default : 396 return "invalid encoding " + enc; 397 } 398 } 399 400 /** Invalid audio channel configuration */ 401 /** @deprecated Use {@link #CHANNEL_INVALID} instead. */ 402 @Deprecated public static final int CHANNEL_CONFIGURATION_INVALID = 0; 403 /** Default audio channel configuration */ 404 /** @deprecated Use {@link #CHANNEL_OUT_DEFAULT} or {@link #CHANNEL_IN_DEFAULT} instead. */ 405 @Deprecated public static final int CHANNEL_CONFIGURATION_DEFAULT = 1; 406 /** Mono audio configuration */ 407 /** @deprecated Use {@link #CHANNEL_OUT_MONO} or {@link #CHANNEL_IN_MONO} instead. */ 408 @Deprecated public static final int CHANNEL_CONFIGURATION_MONO = 2; 409 /** Stereo (2 channel) audio configuration */ 410 /** @deprecated Use {@link #CHANNEL_OUT_STEREO} or {@link #CHANNEL_IN_STEREO} instead. */ 411 @Deprecated public static final int CHANNEL_CONFIGURATION_STEREO = 3; 412 413 /** Invalid audio channel mask */ 414 public static final int CHANNEL_INVALID = 0; 415 /** Default audio channel mask */ 416 public static final int CHANNEL_OUT_DEFAULT = 1; 417 418 // Output channel mask definitions below are translated to the native values defined in 419 // in /system/media/audio/include/system/audio.h in the JNI code of AudioTrack 420 public static final int CHANNEL_OUT_FRONT_LEFT = 0x4; 421 public static final int CHANNEL_OUT_FRONT_RIGHT = 0x8; 422 public static final int CHANNEL_OUT_FRONT_CENTER = 0x10; 423 public static final int CHANNEL_OUT_LOW_FREQUENCY = 0x20; 424 public static final int CHANNEL_OUT_BACK_LEFT = 0x40; 425 public static final int CHANNEL_OUT_BACK_RIGHT = 0x80; 426 public static final int CHANNEL_OUT_FRONT_LEFT_OF_CENTER = 0x100; 427 public static final int CHANNEL_OUT_FRONT_RIGHT_OF_CENTER = 0x200; 428 public static final int CHANNEL_OUT_BACK_CENTER = 0x400; 429 public static final int CHANNEL_OUT_SIDE_LEFT = 0x800; 430 public static final int CHANNEL_OUT_SIDE_RIGHT = 0x1000; 431 /** @hide */ 432 public static final int CHANNEL_OUT_TOP_CENTER = 0x2000; 433 /** @hide */ 434 public static final int CHANNEL_OUT_TOP_FRONT_LEFT = 0x4000; 435 /** @hide */ 436 public static final int CHANNEL_OUT_TOP_FRONT_CENTER = 0x8000; 437 /** @hide */ 438 public static final int CHANNEL_OUT_TOP_FRONT_RIGHT = 0x10000; 439 /** @hide */ 440 public static final int CHANNEL_OUT_TOP_BACK_LEFT = 0x20000; 441 /** @hide */ 442 public static final int CHANNEL_OUT_TOP_BACK_CENTER = 0x40000; 443 /** @hide */ 444 public static final int CHANNEL_OUT_TOP_BACK_RIGHT = 0x80000; 445 /** @hide */ 446 public static final int CHANNEL_OUT_TOP_SIDE_LEFT = 0x100000; 447 /** @hide */ 448 public static final int CHANNEL_OUT_TOP_SIDE_RIGHT = 0x200000; 449 /** @hide */ 450 public static final int CHANNEL_OUT_BOTTOM_FRONT_LEFT = 0x400000; 451 /** @hide */ 452 public static final int CHANNEL_OUT_BOTTOM_FRONT_CENTER = 0x800000; 453 /** @hide */ 454 public static final int CHANNEL_OUT_BOTTOM_FRONT_RIGHT = 0x1000000; 455 /** @hide */ 456 public static final int CHANNEL_OUT_LOW_FREQUENCY_2 = 0x2000000; 457 458 public static final int CHANNEL_OUT_MONO = CHANNEL_OUT_FRONT_LEFT; 459 public static final int CHANNEL_OUT_STEREO = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT); 460 // aka QUAD_BACK 461 public static final int CHANNEL_OUT_QUAD = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 462 CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT); 463 /** @hide */ 464 public static final int CHANNEL_OUT_QUAD_SIDE = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 465 CHANNEL_OUT_SIDE_LEFT | CHANNEL_OUT_SIDE_RIGHT); 466 public static final int CHANNEL_OUT_SURROUND = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 467 CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_BACK_CENTER); 468 // aka 5POINT1_BACK 469 public static final int CHANNEL_OUT_5POINT1 = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 470 CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY | CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT); 471 /** @hide */ 472 public static final int CHANNEL_OUT_5POINT1_SIDE = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 473 CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY | 474 CHANNEL_OUT_SIDE_LEFT | CHANNEL_OUT_SIDE_RIGHT); 475 // different from AUDIO_CHANNEL_OUT_7POINT1 used internally, and not accepted by AudioRecord. 476 /** @deprecated Not the typical 7.1 surround configuration. Use {@link #CHANNEL_OUT_7POINT1_SURROUND} instead. */ 477 @Deprecated public static final int CHANNEL_OUT_7POINT1 = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 478 CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY | CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT | 479 CHANNEL_OUT_FRONT_LEFT_OF_CENTER | CHANNEL_OUT_FRONT_RIGHT_OF_CENTER); 480 // matches AUDIO_CHANNEL_OUT_7POINT1 481 public static final int CHANNEL_OUT_7POINT1_SURROUND = ( 482 CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_FRONT_RIGHT | 483 CHANNEL_OUT_SIDE_LEFT | CHANNEL_OUT_SIDE_RIGHT | 484 CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT | 485 CHANNEL_OUT_LOW_FREQUENCY); 486 /** @hide */ 487 public static final int CHANNEL_OUT_5POINT1POINT2 = (CHANNEL_OUT_5POINT1 | 488 CHANNEL_OUT_TOP_SIDE_LEFT | CHANNEL_OUT_TOP_SIDE_RIGHT); 489 /** @hide */ 490 public static final int CHANNEL_OUT_5POINT1POINT4 = (CHANNEL_OUT_5POINT1 | 491 CHANNEL_OUT_TOP_FRONT_LEFT | CHANNEL_OUT_TOP_FRONT_RIGHT | 492 CHANNEL_OUT_TOP_BACK_LEFT | CHANNEL_OUT_TOP_BACK_RIGHT); 493 /** @hide */ 494 public static final int CHANNEL_OUT_7POINT1POINT2 = (CHANNEL_OUT_7POINT1_SURROUND | 495 CHANNEL_OUT_TOP_SIDE_LEFT | CHANNEL_OUT_TOP_SIDE_RIGHT); 496 /** @hide */ 497 public static final int CHANNEL_OUT_7POINT1POINT4 = (CHANNEL_OUT_7POINT1_SURROUND | 498 CHANNEL_OUT_TOP_FRONT_LEFT | CHANNEL_OUT_TOP_FRONT_RIGHT | 499 CHANNEL_OUT_TOP_BACK_LEFT | CHANNEL_OUT_TOP_BACK_RIGHT); 500 /** @hide */ 501 public static final int CHANNEL_OUT_13POINT_360RA = ( 502 CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_FRONT_RIGHT | 503 CHANNEL_OUT_SIDE_LEFT | CHANNEL_OUT_SIDE_RIGHT | 504 CHANNEL_OUT_TOP_FRONT_LEFT | CHANNEL_OUT_TOP_FRONT_CENTER | 505 CHANNEL_OUT_TOP_FRONT_RIGHT | 506 CHANNEL_OUT_TOP_BACK_LEFT | CHANNEL_OUT_TOP_BACK_RIGHT | 507 CHANNEL_OUT_BOTTOM_FRONT_LEFT | CHANNEL_OUT_BOTTOM_FRONT_CENTER | 508 CHANNEL_OUT_BOTTOM_FRONT_RIGHT); 509 /** @hide */ 510 public static final int CHANNEL_OUT_22POINT2 = (CHANNEL_OUT_7POINT1POINT4 | 511 CHANNEL_OUT_FRONT_LEFT_OF_CENTER | CHANNEL_OUT_FRONT_RIGHT_OF_CENTER | 512 CHANNEL_OUT_BACK_CENTER | CHANNEL_OUT_TOP_CENTER | 513 CHANNEL_OUT_TOP_FRONT_CENTER | CHANNEL_OUT_TOP_BACK_CENTER | 514 CHANNEL_OUT_TOP_SIDE_LEFT | CHANNEL_OUT_TOP_SIDE_RIGHT | 515 CHANNEL_OUT_BOTTOM_FRONT_LEFT | CHANNEL_OUT_BOTTOM_FRONT_RIGHT | 516 CHANNEL_OUT_BOTTOM_FRONT_CENTER | 517 CHANNEL_OUT_LOW_FREQUENCY_2); 518 // CHANNEL_OUT_ALL is not yet defined; if added then it should match AUDIO_CHANNEL_OUT_ALL 519 520 /** Minimum value for sample rate, 521 * assuming AudioTrack and AudioRecord share the same limitations. 522 * @hide 523 */ 524 // never unhide 525 public static final int SAMPLE_RATE_HZ_MIN = AudioSystem.SAMPLE_RATE_HZ_MIN; 526 /** Maximum value for sample rate, 527 * assuming AudioTrack and AudioRecord share the same limitations. 528 * @hide 529 */ 530 // never unhide 531 public static final int SAMPLE_RATE_HZ_MAX = AudioSystem.SAMPLE_RATE_HZ_MAX; 532 /** Sample rate will be a route-dependent value. 533 * For AudioTrack, it is usually the sink sample rate, 534 * and for AudioRecord it is usually the source sample rate. 535 */ 536 public static final int SAMPLE_RATE_UNSPECIFIED = 0; 537 538 /** 539 * @hide 540 * Return the input channel mask corresponding to an output channel mask. 541 * This can be used for submix rerouting for the mask of the recorder to map to that of the mix. 542 * @param outMask a combination of the CHANNEL_OUT_* definitions, but not CHANNEL_OUT_DEFAULT 543 * @return a combination of CHANNEL_IN_* definitions matching an output channel mask 544 * @throws IllegalArgumentException 545 */ inChannelMaskFromOutChannelMask(int outMask)546 public static int inChannelMaskFromOutChannelMask(int outMask) throws IllegalArgumentException { 547 if (outMask == CHANNEL_OUT_DEFAULT) { 548 throw new IllegalArgumentException( 549 "Illegal CHANNEL_OUT_DEFAULT channel mask for input."); 550 } 551 switch (channelCountFromOutChannelMask(outMask)) { 552 case 1: 553 return CHANNEL_IN_MONO; 554 case 2: 555 return CHANNEL_IN_STEREO; 556 default: 557 throw new IllegalArgumentException("Unsupported channel configuration for input."); 558 } 559 } 560 561 /** 562 * @hide 563 * Return the number of channels from an input channel mask 564 * @param mask a combination of the CHANNEL_IN_* definitions, even CHANNEL_IN_DEFAULT 565 * @return number of channels for the mask 566 */ 567 @TestApi channelCountFromInChannelMask(int mask)568 public static int channelCountFromInChannelMask(int mask) { 569 return Integer.bitCount(mask); 570 } 571 /** 572 * @hide 573 * Return the number of channels from an output channel mask 574 * @param mask a combination of the CHANNEL_OUT_* definitions, but not CHANNEL_OUT_DEFAULT 575 * @return number of channels for the mask 576 */ 577 @TestApi channelCountFromOutChannelMask(int mask)578 public static int channelCountFromOutChannelMask(int mask) { 579 return Integer.bitCount(mask); 580 } 581 /** 582 * @hide 583 * Return a channel mask ready to be used by native code 584 * @param mask a combination of the CHANNEL_OUT_* definitions, but not CHANNEL_OUT_DEFAULT 585 * @return a native channel mask 586 */ convertChannelOutMaskToNativeMask(int javaMask)587 public static int convertChannelOutMaskToNativeMask(int javaMask) { 588 return (javaMask >> 2); 589 } 590 591 /** 592 * @hide 593 * Return a java output channel mask 594 * @param mask a native channel mask 595 * @return a combination of the CHANNEL_OUT_* definitions 596 */ convertNativeChannelMaskToOutMask(int nativeMask)597 public static int convertNativeChannelMaskToOutMask(int nativeMask) { 598 return (nativeMask << 2); 599 } 600 601 public static final int CHANNEL_IN_DEFAULT = 1; 602 // These directly match native 603 public static final int CHANNEL_IN_LEFT = 0x4; 604 public static final int CHANNEL_IN_RIGHT = 0x8; 605 public static final int CHANNEL_IN_FRONT = 0x10; 606 public static final int CHANNEL_IN_BACK = 0x20; 607 public static final int CHANNEL_IN_LEFT_PROCESSED = 0x40; 608 public static final int CHANNEL_IN_RIGHT_PROCESSED = 0x80; 609 public static final int CHANNEL_IN_FRONT_PROCESSED = 0x100; 610 public static final int CHANNEL_IN_BACK_PROCESSED = 0x200; 611 public static final int CHANNEL_IN_PRESSURE = 0x400; 612 public static final int CHANNEL_IN_X_AXIS = 0x800; 613 public static final int CHANNEL_IN_Y_AXIS = 0x1000; 614 public static final int CHANNEL_IN_Z_AXIS = 0x2000; 615 public static final int CHANNEL_IN_VOICE_UPLINK = 0x4000; 616 public static final int CHANNEL_IN_VOICE_DNLINK = 0x8000; 617 public static final int CHANNEL_IN_MONO = CHANNEL_IN_FRONT; 618 public static final int CHANNEL_IN_STEREO = (CHANNEL_IN_LEFT | CHANNEL_IN_RIGHT); 619 /** @hide */ 620 public static final int CHANNEL_IN_FRONT_BACK = CHANNEL_IN_FRONT | CHANNEL_IN_BACK; 621 // CHANNEL_IN_ALL is not yet defined; if added then it should match AUDIO_CHANNEL_IN_ALL 622 623 /** @hide */ 624 @TestApi getBytesPerSample(int audioFormat)625 public static int getBytesPerSample(int audioFormat) 626 { 627 switch (audioFormat) { 628 case ENCODING_PCM_8BIT: 629 return 1; 630 case ENCODING_PCM_16BIT: 631 case ENCODING_IEC61937: 632 case ENCODING_DEFAULT: 633 return 2; 634 case ENCODING_PCM_24BIT_PACKED: 635 return 3; 636 case ENCODING_PCM_FLOAT: 637 case ENCODING_PCM_32BIT: 638 return 4; 639 case ENCODING_INVALID: 640 default: 641 throw new IllegalArgumentException("Bad audio format " + audioFormat); 642 } 643 } 644 645 /** @hide */ isValidEncoding(int audioFormat)646 public static boolean isValidEncoding(int audioFormat) 647 { 648 switch (audioFormat) { 649 case ENCODING_PCM_16BIT: 650 case ENCODING_PCM_8BIT: 651 case ENCODING_PCM_FLOAT: 652 case ENCODING_AC3: 653 case ENCODING_E_AC3: 654 case ENCODING_DTS: 655 case ENCODING_DTS_HD: 656 case ENCODING_MP3: 657 case ENCODING_AAC_LC: 658 case ENCODING_AAC_HE_V1: 659 case ENCODING_AAC_HE_V2: 660 case ENCODING_IEC61937: 661 case ENCODING_DOLBY_TRUEHD: 662 case ENCODING_AAC_ELD: 663 case ENCODING_AAC_XHE: 664 case ENCODING_AC4: 665 case ENCODING_E_AC3_JOC: 666 case ENCODING_DOLBY_MAT: 667 case ENCODING_OPUS: 668 case ENCODING_PCM_24BIT_PACKED: 669 case ENCODING_PCM_32BIT: 670 case ENCODING_MPEGH_BL_L3: 671 case ENCODING_MPEGH_BL_L4: 672 case ENCODING_MPEGH_LC_L3: 673 case ENCODING_MPEGH_LC_L4: 674 case ENCODING_DTS_UHD: 675 case ENCODING_DRA: 676 return true; 677 default: 678 return false; 679 } 680 } 681 682 /** @hide */ isPublicEncoding(int audioFormat)683 public static boolean isPublicEncoding(int audioFormat) 684 { 685 switch (audioFormat) { 686 case ENCODING_PCM_16BIT: 687 case ENCODING_PCM_8BIT: 688 case ENCODING_PCM_FLOAT: 689 case ENCODING_AC3: 690 case ENCODING_E_AC3: 691 case ENCODING_DTS: 692 case ENCODING_DTS_HD: 693 case ENCODING_MP3: 694 case ENCODING_AAC_LC: 695 case ENCODING_AAC_HE_V1: 696 case ENCODING_AAC_HE_V2: 697 case ENCODING_IEC61937: 698 case ENCODING_DOLBY_TRUEHD: 699 case ENCODING_AAC_ELD: 700 case ENCODING_AAC_XHE: 701 case ENCODING_AC4: 702 case ENCODING_E_AC3_JOC: 703 case ENCODING_DOLBY_MAT: 704 case ENCODING_OPUS: 705 case ENCODING_PCM_24BIT_PACKED: 706 case ENCODING_PCM_32BIT: 707 case ENCODING_MPEGH_BL_L3: 708 case ENCODING_MPEGH_BL_L4: 709 case ENCODING_MPEGH_LC_L3: 710 case ENCODING_MPEGH_LC_L4: 711 case ENCODING_DTS_UHD: 712 case ENCODING_DRA: 713 return true; 714 default: 715 return false; 716 } 717 } 718 719 /** @hide */ 720 @TestApi isEncodingLinearPcm(int audioFormat)721 public static boolean isEncodingLinearPcm(int audioFormat) 722 { 723 switch (audioFormat) { 724 case ENCODING_PCM_16BIT: 725 case ENCODING_PCM_8BIT: 726 case ENCODING_PCM_FLOAT: 727 case ENCODING_PCM_24BIT_PACKED: 728 case ENCODING_PCM_32BIT: 729 case ENCODING_DEFAULT: 730 return true; 731 case ENCODING_AC3: 732 case ENCODING_E_AC3: 733 case ENCODING_DTS: 734 case ENCODING_DTS_HD: 735 case ENCODING_MP3: 736 case ENCODING_AAC_LC: 737 case ENCODING_AAC_HE_V1: 738 case ENCODING_AAC_HE_V2: 739 case ENCODING_IEC61937: // wrapped in PCM but compressed 740 case ENCODING_DOLBY_TRUEHD: 741 case ENCODING_AAC_ELD: 742 case ENCODING_AAC_XHE: 743 case ENCODING_AC4: 744 case ENCODING_E_AC3_JOC: 745 case ENCODING_DOLBY_MAT: 746 case ENCODING_OPUS: 747 case ENCODING_MPEGH_BL_L3: 748 case ENCODING_MPEGH_BL_L4: 749 case ENCODING_MPEGH_LC_L3: 750 case ENCODING_MPEGH_LC_L4: 751 case ENCODING_DTS_UHD: 752 case ENCODING_DRA: 753 return false; 754 case ENCODING_INVALID: 755 default: 756 throw new IllegalArgumentException("Bad audio format " + audioFormat); 757 } 758 } 759 760 /** @hide */ isEncodingLinearFrames(int audioFormat)761 public static boolean isEncodingLinearFrames(int audioFormat) 762 { 763 switch (audioFormat) { 764 case ENCODING_PCM_16BIT: 765 case ENCODING_PCM_8BIT: 766 case ENCODING_PCM_FLOAT: 767 case ENCODING_IEC61937: // same size as stereo PCM 768 case ENCODING_PCM_24BIT_PACKED: 769 case ENCODING_PCM_32BIT: 770 case ENCODING_DEFAULT: 771 return true; 772 case ENCODING_AC3: 773 case ENCODING_E_AC3: 774 case ENCODING_DTS: 775 case ENCODING_DTS_HD: 776 case ENCODING_MP3: 777 case ENCODING_AAC_LC: 778 case ENCODING_AAC_HE_V1: 779 case ENCODING_AAC_HE_V2: 780 case ENCODING_DOLBY_TRUEHD: 781 case ENCODING_AAC_ELD: 782 case ENCODING_AAC_XHE: 783 case ENCODING_AC4: 784 case ENCODING_E_AC3_JOC: 785 case ENCODING_DOLBY_MAT: 786 case ENCODING_OPUS: 787 case ENCODING_MPEGH_BL_L3: 788 case ENCODING_MPEGH_BL_L4: 789 case ENCODING_MPEGH_LC_L3: 790 case ENCODING_MPEGH_LC_L4: 791 case ENCODING_DTS_UHD: 792 case ENCODING_DRA: 793 return false; 794 case ENCODING_INVALID: 795 default: 796 throw new IllegalArgumentException("Bad audio format " + audioFormat); 797 } 798 } 799 /** 800 * Returns an array of public encoding values extracted from an array of 801 * encoding values. 802 * @hide 803 */ filterPublicFormats(int[] formats)804 public static int[] filterPublicFormats(int[] formats) { 805 if (formats == null) { 806 return null; 807 } 808 int[] myCopy = Arrays.copyOf(formats, formats.length); 809 int size = 0; 810 for (int i = 0; i < myCopy.length; i++) { 811 if (isPublicEncoding(myCopy[i])) { 812 if (size != i) { 813 myCopy[size] = myCopy[i]; 814 } 815 size++; 816 } 817 } 818 return Arrays.copyOf(myCopy, size); 819 } 820 821 /** @removed */ AudioFormat()822 public AudioFormat() 823 { 824 throw new UnsupportedOperationException("There is no valid usage of this constructor"); 825 } 826 827 /** 828 * Constructor used by the JNI. Parameters are not checked for validity. 829 */ 830 // Update sound trigger JNI in core/jni/android_hardware_SoundTrigger.cpp when modifying this 831 // constructor 832 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) AudioFormat(int encoding, int sampleRate, int channelMask, int channelIndexMask)833 private AudioFormat(int encoding, int sampleRate, int channelMask, int channelIndexMask) { 834 this( 835 AUDIO_FORMAT_HAS_PROPERTY_ENCODING 836 | AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE 837 | AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK 838 | AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_INDEX_MASK, 839 encoding, sampleRate, channelMask, channelIndexMask 840 ); 841 } 842 AudioFormat(int propertySetMask, int encoding, int sampleRate, int channelMask, int channelIndexMask)843 private AudioFormat(int propertySetMask, 844 int encoding, int sampleRate, int channelMask, int channelIndexMask) { 845 mPropertySetMask = propertySetMask; 846 mEncoding = (propertySetMask & AUDIO_FORMAT_HAS_PROPERTY_ENCODING) != 0 847 ? encoding : ENCODING_INVALID; 848 mSampleRate = (propertySetMask & AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE) != 0 849 ? sampleRate : SAMPLE_RATE_UNSPECIFIED; 850 mChannelMask = (propertySetMask & AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK) != 0 851 ? channelMask : CHANNEL_INVALID; 852 mChannelIndexMask = (propertySetMask & AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_INDEX_MASK) != 0 853 ? channelIndexMask : CHANNEL_INVALID; 854 855 // Compute derived values. 856 857 final int channelIndexCount = Integer.bitCount(getChannelIndexMask()); 858 int channelCount = channelCountFromOutChannelMask(getChannelMask()); 859 if (channelCount == 0) { 860 channelCount = channelIndexCount; 861 } else if (channelCount != channelIndexCount && channelIndexCount != 0) { 862 channelCount = 0; // position and index channel count mismatch 863 } 864 mChannelCount = channelCount; 865 866 int frameSizeInBytes = 1; 867 try { 868 frameSizeInBytes = getBytesPerSample(mEncoding) * channelCount; 869 } catch (IllegalArgumentException iae) { 870 // ignored 871 } 872 // it is possible that channel count is 0, so ensure we return 1 for 873 // mFrameSizeInBytes for consistency. 874 mFrameSizeInBytes = frameSizeInBytes != 0 ? frameSizeInBytes : 1; 875 } 876 877 /** @hide */ 878 public final static int AUDIO_FORMAT_HAS_PROPERTY_NONE = 0x0; 879 /** @hide */ 880 public final static int AUDIO_FORMAT_HAS_PROPERTY_ENCODING = 0x1 << 0; 881 /** @hide */ 882 public final static int AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE = 0x1 << 1; 883 /** @hide */ 884 public final static int AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK = 0x1 << 2; 885 /** @hide */ 886 public final static int AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_INDEX_MASK = 0x1 << 3; 887 888 // This is an immutable class, all member variables are final. 889 890 // Essential values. 891 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 892 private final int mEncoding; 893 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 894 private final int mSampleRate; 895 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 896 private final int mChannelMask; 897 private final int mChannelIndexMask; 898 private final int mPropertySetMask; 899 900 // Derived values computed in the constructor, cached here. 901 private final int mChannelCount; 902 private final int mFrameSizeInBytes; 903 904 /** 905 * Return the encoding. 906 * See the section on <a href="#encoding">encodings</a> for more information about the different 907 * types of supported audio encoding. 908 * @return one of the values that can be set in {@link Builder#setEncoding(int)} or 909 * {@link AudioFormat#ENCODING_INVALID} if not set. 910 */ getEncoding()911 public int getEncoding() { 912 return mEncoding; 913 } 914 915 /** 916 * Return the sample rate. 917 * @return one of the values that can be set in {@link Builder#setSampleRate(int)} or 918 * {@link #SAMPLE_RATE_UNSPECIFIED} if not set. 919 */ getSampleRate()920 public int getSampleRate() { 921 return mSampleRate; 922 } 923 924 /** 925 * Return the channel mask. 926 * See the section on <a href="#channelMask">channel masks</a> for more information about 927 * the difference between index-based masks(as returned by {@link #getChannelIndexMask()}) and 928 * the position-based mask returned by this function. 929 * @return one of the values that can be set in {@link Builder#setChannelMask(int)} or 930 * {@link AudioFormat#CHANNEL_INVALID} if not set. 931 */ getChannelMask()932 public int getChannelMask() { 933 return mChannelMask; 934 } 935 936 /** 937 * Return the channel index mask. 938 * See the section on <a href="#channelMask">channel masks</a> for more information about 939 * the difference between index-based masks, and position-based masks (as returned 940 * by {@link #getChannelMask()}). 941 * @return one of the values that can be set in {@link Builder#setChannelIndexMask(int)} or 942 * {@link AudioFormat#CHANNEL_INVALID} if not set or an invalid mask was used. 943 */ getChannelIndexMask()944 public int getChannelIndexMask() { 945 return mChannelIndexMask; 946 } 947 948 /** 949 * Return the channel count. 950 * @return the channel count derived from the channel position mask or the channel index mask. 951 * Zero is returned if both the channel position mask and the channel index mask are not set. 952 */ getChannelCount()953 public int getChannelCount() { 954 return mChannelCount; 955 } 956 957 /** 958 * Return the frame size in bytes. 959 * 960 * For PCM or PCM packed compressed data this is the size of a sample multiplied 961 * by the channel count. For all other cases, including invalid/unset channel masks, 962 * this will return 1 byte. 963 * As an example, a stereo 16-bit PCM format would have a frame size of 4 bytes, 964 * an 8 channel float PCM format would have a frame size of 32 bytes, 965 * and a compressed data format (not packed in PCM) would have a frame size of 1 byte. 966 * 967 * Both {@link AudioRecord} or {@link AudioTrack} process data in multiples of 968 * this frame size. 969 * 970 * @return The audio frame size in bytes corresponding to the encoding and the channel mask. 971 */ getFrameSizeInBytes()972 public @IntRange(from = 1) int getFrameSizeInBytes() { 973 return mFrameSizeInBytes; 974 } 975 976 /** @hide */ getPropertySetMask()977 public int getPropertySetMask() { 978 return mPropertySetMask; 979 } 980 981 /** @hide */ toLogFriendlyString()982 public String toLogFriendlyString() { 983 return String.format("%dch %dHz %s", 984 mChannelCount, mSampleRate, toLogFriendlyEncoding(mEncoding)); 985 } 986 987 /** 988 * Builder class for {@link AudioFormat} objects. 989 * Use this class to configure and create an AudioFormat instance. By setting format 990 * characteristics such as audio encoding, channel mask or sample rate, you indicate which 991 * of those are to vary from the default behavior on this device wherever this audio format 992 * is used. See {@link AudioFormat} for a complete description of the different parameters that 993 * can be used to configure an <code>AudioFormat</code> instance. 994 * <p>{@link AudioFormat} is for instance used in 995 * {@link AudioTrack#AudioTrack(AudioAttributes, AudioFormat, int, int, int)}. In this 996 * constructor, every format characteristic set on the <code>Builder</code> (e.g. with 997 * {@link #setSampleRate(int)}) will alter the default values used by an 998 * <code>AudioTrack</code>. In this case for audio playback with <code>AudioTrack</code>, the 999 * sample rate set in the <code>Builder</code> would override the platform output sample rate 1000 * which would otherwise be selected by default. 1001 */ 1002 public static class Builder { 1003 private int mEncoding = ENCODING_INVALID; 1004 private int mSampleRate = SAMPLE_RATE_UNSPECIFIED; 1005 private int mChannelMask = CHANNEL_INVALID; 1006 private int mChannelIndexMask = 0; 1007 private int mPropertySetMask = AUDIO_FORMAT_HAS_PROPERTY_NONE; 1008 1009 /** 1010 * Constructs a new Builder with none of the format characteristics set. 1011 */ Builder()1012 public Builder() { 1013 } 1014 1015 /** 1016 * Constructs a new Builder from a given {@link AudioFormat}. 1017 * @param af the {@link AudioFormat} object whose data will be reused in the new Builder. 1018 */ Builder(AudioFormat af)1019 public Builder(AudioFormat af) { 1020 mEncoding = af.mEncoding; 1021 mSampleRate = af.mSampleRate; 1022 mChannelMask = af.mChannelMask; 1023 mChannelIndexMask = af.mChannelIndexMask; 1024 mPropertySetMask = af.mPropertySetMask; 1025 } 1026 1027 /** 1028 * Combines all of the format characteristics that have been set and return a new 1029 * {@link AudioFormat} object. 1030 * @return a new {@link AudioFormat} object 1031 */ build()1032 public AudioFormat build() { 1033 AudioFormat af = new AudioFormat( 1034 mPropertySetMask, 1035 mEncoding, 1036 mSampleRate, 1037 mChannelMask, 1038 mChannelIndexMask 1039 ); 1040 return af; 1041 } 1042 1043 /** 1044 * Sets the data encoding format. 1045 * @param encoding the specified encoding or default. 1046 * @return the same Builder instance. 1047 * @throws java.lang.IllegalArgumentException 1048 */ setEncoding(@ncoding int encoding)1049 public Builder setEncoding(@Encoding int encoding) throws IllegalArgumentException { 1050 switch (encoding) { 1051 case ENCODING_DEFAULT: 1052 mEncoding = ENCODING_PCM_16BIT; 1053 break; 1054 case ENCODING_PCM_16BIT: 1055 case ENCODING_PCM_8BIT: 1056 case ENCODING_PCM_FLOAT: 1057 case ENCODING_AC3: 1058 case ENCODING_E_AC3: 1059 case ENCODING_DTS: 1060 case ENCODING_DTS_HD: 1061 case ENCODING_MP3: 1062 case ENCODING_AAC_LC: 1063 case ENCODING_AAC_HE_V1: 1064 case ENCODING_AAC_HE_V2: 1065 case ENCODING_IEC61937: 1066 case ENCODING_DOLBY_TRUEHD: 1067 case ENCODING_AAC_ELD: 1068 case ENCODING_AAC_XHE: 1069 case ENCODING_AC4: 1070 case ENCODING_E_AC3_JOC: 1071 case ENCODING_DOLBY_MAT: 1072 case ENCODING_OPUS: 1073 case ENCODING_PCM_24BIT_PACKED: 1074 case ENCODING_PCM_32BIT: 1075 case ENCODING_MPEGH_BL_L3: 1076 case ENCODING_MPEGH_BL_L4: 1077 case ENCODING_MPEGH_LC_L3: 1078 case ENCODING_MPEGH_LC_L4: 1079 case ENCODING_DTS_UHD: 1080 case ENCODING_DRA: 1081 mEncoding = encoding; 1082 break; 1083 case ENCODING_INVALID: 1084 default: 1085 throw new IllegalArgumentException("Invalid encoding " + encoding); 1086 } 1087 mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_ENCODING; 1088 return this; 1089 } 1090 1091 /** 1092 * Sets the channel position mask. 1093 * The channel position mask specifies the association between audio samples in a frame 1094 * with named endpoint channels. The samples in the frame correspond to the 1095 * named set bits in the channel position mask, in ascending bit order. 1096 * See {@link #setChannelIndexMask(int)} to specify channels 1097 * based on endpoint numbered channels. This <a href="#channelPositionMask">description of 1098 * channel position masks</a> covers the concept in more details. 1099 * @param channelMask describes the configuration of the audio channels. 1100 * <p> For output, the channelMask can be an OR-ed combination of 1101 * channel position masks, e.g. 1102 * {@link AudioFormat#CHANNEL_OUT_FRONT_LEFT}, 1103 * {@link AudioFormat#CHANNEL_OUT_FRONT_RIGHT}, 1104 * {@link AudioFormat#CHANNEL_OUT_FRONT_CENTER}, 1105 * {@link AudioFormat#CHANNEL_OUT_LOW_FREQUENCY} 1106 * {@link AudioFormat#CHANNEL_OUT_BACK_LEFT}, 1107 * {@link AudioFormat#CHANNEL_OUT_BACK_RIGHT}, 1108 * {@link AudioFormat#CHANNEL_OUT_BACK_CENTER}, 1109 * {@link AudioFormat#CHANNEL_OUT_SIDE_LEFT}, 1110 * {@link AudioFormat#CHANNEL_OUT_SIDE_RIGHT}. 1111 * <p> For a valid {@link AudioTrack} channel position mask, 1112 * the following conditions apply: 1113 * <br> (1) at most eight channel positions may be used; 1114 * <br> (2) right/left pairs should be matched. 1115 * <p> For input or {@link AudioRecord}, the mask should be 1116 * {@link AudioFormat#CHANNEL_IN_MONO} or 1117 * {@link AudioFormat#CHANNEL_IN_STEREO}. {@link AudioFormat#CHANNEL_IN_MONO} is 1118 * guaranteed to work on all devices. 1119 * @return the same <code>Builder</code> instance. 1120 * @throws IllegalArgumentException if the channel mask is invalid or 1121 * if both channel index mask and channel position mask 1122 * are specified but do not have the same channel count. 1123 */ setChannelMask(int channelMask)1124 public @NonNull Builder setChannelMask(int channelMask) { 1125 if (channelMask == CHANNEL_INVALID) { 1126 throw new IllegalArgumentException("Invalid zero channel mask"); 1127 } else if (/* channelMask != 0 && */ mChannelIndexMask != 0 && 1128 Integer.bitCount(channelMask) != Integer.bitCount(mChannelIndexMask)) { 1129 throw new IllegalArgumentException("Mismatched channel count for mask " + 1130 Integer.toHexString(channelMask).toUpperCase()); 1131 } 1132 mChannelMask = channelMask; 1133 mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK; 1134 return this; 1135 } 1136 1137 /** 1138 * Sets the channel index mask. 1139 * A channel index mask specifies the association of audio samples in the frame 1140 * with numbered endpoint channels. The i-th bit in the channel index 1141 * mask corresponds to the i-th endpoint channel. 1142 * For example, an endpoint with four channels is represented 1143 * as index mask bits 0 through 3. This <a href="#channelIndexMask>description of channel 1144 * index masks</a> covers the concept in more details. 1145 * See {@link #setChannelMask(int)} for a positional mask interpretation. 1146 * <p> Both {@link AudioTrack} and {@link AudioRecord} support 1147 * a channel index mask. 1148 * If a channel index mask is specified it is used, 1149 * otherwise the channel position mask specified 1150 * by <code>setChannelMask</code> is used. 1151 * For <code>AudioTrack</code> and <code>AudioRecord</code>, 1152 * a channel position mask is not required if a channel index mask is specified. 1153 * 1154 * @param channelIndexMask describes the configuration of the audio channels. 1155 * <p> For output, the <code>channelIndexMask</code> is an OR-ed combination of 1156 * bits representing the mapping of <code>AudioTrack</code> write samples 1157 * to output sink channels. 1158 * For example, a mask of <code>0xa</code>, or binary <code>1010</code>, 1159 * means the <code>AudioTrack</code> write frame consists of two samples, 1160 * which are routed to the second and the fourth channels of the output sink. 1161 * Unmatched output sink channels are zero filled and unmatched 1162 * <code>AudioTrack</code> write samples are dropped. 1163 * <p> For input, the <code>channelIndexMask</code> is an OR-ed combination of 1164 * bits representing the mapping of input source channels to 1165 * <code>AudioRecord</code> read samples. 1166 * For example, a mask of <code>0x5</code>, or binary 1167 * <code>101</code>, will read from the first and third channel of the input 1168 * source device and store them in the first and second sample of the 1169 * <code>AudioRecord</code> read frame. 1170 * Unmatched input source channels are dropped and 1171 * unmatched <code>AudioRecord</code> read samples are zero filled. 1172 * @return the same <code>Builder</code> instance. 1173 * @throws IllegalArgumentException if the channel index mask is invalid or 1174 * if both channel index mask and channel position mask 1175 * are specified but do not have the same channel count. 1176 */ setChannelIndexMask(int channelIndexMask)1177 public @NonNull Builder setChannelIndexMask(int channelIndexMask) { 1178 if (channelIndexMask == 0) { 1179 throw new IllegalArgumentException("Invalid zero channel index mask"); 1180 } else if (/* channelIndexMask != 0 && */ mChannelMask != 0 && 1181 Integer.bitCount(channelIndexMask) != Integer.bitCount(mChannelMask)) { 1182 throw new IllegalArgumentException("Mismatched channel count for index mask " + 1183 Integer.toHexString(channelIndexMask).toUpperCase()); 1184 } 1185 mChannelIndexMask = channelIndexMask; 1186 mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_INDEX_MASK; 1187 return this; 1188 } 1189 1190 /** 1191 * Sets the sample rate. 1192 * @param sampleRate the sample rate expressed in Hz 1193 * @return the same Builder instance. 1194 * @throws java.lang.IllegalArgumentException 1195 */ setSampleRate(int sampleRate)1196 public Builder setSampleRate(int sampleRate) throws IllegalArgumentException { 1197 // TODO Consider whether to keep the MIN and MAX range checks here. 1198 // It is not necessary and poses the problem of defining the limits independently from 1199 // native implementation or platform capabilities. 1200 if (((sampleRate < SAMPLE_RATE_HZ_MIN) || (sampleRate > SAMPLE_RATE_HZ_MAX)) && 1201 sampleRate != SAMPLE_RATE_UNSPECIFIED) { 1202 throw new IllegalArgumentException("Invalid sample rate " + sampleRate); 1203 } 1204 mSampleRate = sampleRate; 1205 mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE; 1206 return this; 1207 } 1208 } 1209 1210 @Override equals(Object o)1211 public boolean equals(Object o) { 1212 if (this == o) return true; 1213 if (o == null || getClass() != o.getClass()) return false; 1214 1215 AudioFormat that = (AudioFormat) o; 1216 1217 if (mPropertySetMask != that.mPropertySetMask) return false; 1218 1219 // return false if any of the properties is set and the values differ 1220 return !((((mPropertySetMask & AUDIO_FORMAT_HAS_PROPERTY_ENCODING) != 0) 1221 && (mEncoding != that.mEncoding)) 1222 || (((mPropertySetMask & AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE) != 0) 1223 && (mSampleRate != that.mSampleRate)) 1224 || (((mPropertySetMask & AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK) != 0) 1225 && (mChannelMask != that.mChannelMask)) 1226 || (((mPropertySetMask & AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_INDEX_MASK) != 0) 1227 && (mChannelIndexMask != that.mChannelIndexMask))); 1228 } 1229 1230 @Override hashCode()1231 public int hashCode() { 1232 return Objects.hash(mPropertySetMask, mSampleRate, mEncoding, mChannelMask, 1233 mChannelIndexMask); 1234 } 1235 1236 @Override describeContents()1237 public int describeContents() { 1238 return 0; 1239 } 1240 1241 @Override writeToParcel(Parcel dest, int flags)1242 public void writeToParcel(Parcel dest, int flags) { 1243 dest.writeInt(mPropertySetMask); 1244 dest.writeInt(mEncoding); 1245 dest.writeInt(mSampleRate); 1246 dest.writeInt(mChannelMask); 1247 dest.writeInt(mChannelIndexMask); 1248 } 1249 AudioFormat(Parcel in)1250 private AudioFormat(Parcel in) { 1251 this( 1252 in.readInt(), // propertySetMask 1253 in.readInt(), // encoding 1254 in.readInt(), // sampleRate 1255 in.readInt(), // channelMask 1256 in.readInt() // channelIndexMask 1257 ); 1258 } 1259 1260 public static final @android.annotation.NonNull Parcelable.Creator<AudioFormat> CREATOR = 1261 new Parcelable.Creator<AudioFormat>() { 1262 public AudioFormat createFromParcel(Parcel p) { 1263 return new AudioFormat(p); 1264 } 1265 public AudioFormat[] newArray(int size) { 1266 return new AudioFormat[size]; 1267 } 1268 }; 1269 1270 @Override toString()1271 public String toString () { 1272 return new String("AudioFormat:" 1273 + " props=" + mPropertySetMask 1274 + " enc=" + mEncoding 1275 + " chan=0x" + Integer.toHexString(mChannelMask).toUpperCase() 1276 + " chan_index=0x" + Integer.toHexString(mChannelIndexMask).toUpperCase() 1277 + " rate=" + mSampleRate); 1278 } 1279 1280 /** @hide */ 1281 @IntDef(flag = false, prefix = "ENCODING", value = { 1282 ENCODING_DEFAULT, 1283 ENCODING_PCM_16BIT, 1284 ENCODING_PCM_8BIT, 1285 ENCODING_PCM_FLOAT, 1286 ENCODING_AC3, 1287 ENCODING_E_AC3, 1288 ENCODING_DTS, 1289 ENCODING_DTS_HD, 1290 ENCODING_MP3, 1291 ENCODING_AAC_LC, 1292 ENCODING_AAC_HE_V1, 1293 ENCODING_AAC_HE_V2, 1294 ENCODING_IEC61937, 1295 ENCODING_DOLBY_TRUEHD, 1296 ENCODING_AAC_ELD, 1297 ENCODING_AAC_XHE, 1298 ENCODING_AC4, 1299 ENCODING_E_AC3_JOC, 1300 ENCODING_DOLBY_MAT, 1301 ENCODING_OPUS, 1302 ENCODING_PCM_24BIT_PACKED, 1303 ENCODING_PCM_32BIT, 1304 ENCODING_MPEGH_BL_L3, 1305 ENCODING_MPEGH_BL_L4, 1306 ENCODING_MPEGH_LC_L3, 1307 ENCODING_MPEGH_LC_L4, 1308 ENCODING_DTS_UHD, 1309 ENCODING_DRA } 1310 ) 1311 @Retention(RetentionPolicy.SOURCE) 1312 public @interface Encoding {} 1313 1314 /** @hide */ 1315 public static final int[] SURROUND_SOUND_ENCODING = { 1316 ENCODING_AC3, 1317 ENCODING_E_AC3, 1318 ENCODING_DTS, 1319 ENCODING_DTS_HD, 1320 ENCODING_AAC_LC, 1321 ENCODING_DOLBY_TRUEHD, 1322 ENCODING_AC4, 1323 ENCODING_E_AC3_JOC, 1324 ENCODING_DOLBY_MAT, 1325 ENCODING_MPEGH_BL_L3, 1326 ENCODING_MPEGH_BL_L4, 1327 ENCODING_MPEGH_LC_L3, 1328 ENCODING_MPEGH_LC_L4, 1329 ENCODING_DTS_UHD, 1330 ENCODING_DRA 1331 }; 1332 1333 /** @hide */ 1334 @IntDef(flag = false, prefix = "ENCODING", value = { 1335 ENCODING_AC3, 1336 ENCODING_E_AC3, 1337 ENCODING_DTS, 1338 ENCODING_DTS_HD, 1339 ENCODING_AAC_LC, 1340 ENCODING_DOLBY_TRUEHD, 1341 ENCODING_AC4, 1342 ENCODING_E_AC3_JOC, 1343 ENCODING_DOLBY_MAT, 1344 ENCODING_MPEGH_BL_L3, 1345 ENCODING_MPEGH_BL_L4, 1346 ENCODING_MPEGH_LC_L3, 1347 ENCODING_MPEGH_LC_L4, 1348 ENCODING_DTS_UHD, 1349 ENCODING_DRA } 1350 ) 1351 @Retention(RetentionPolicy.SOURCE) 1352 public @interface SurroundSoundEncoding {} 1353 1354 /** 1355 * @hide 1356 * 1357 * Return default name for a surround format. This is not an International name. 1358 * It is just a default to use if an international name is not available. 1359 * 1360 * @param audioFormat a surround format 1361 * @return short default name for the format. 1362 */ toDisplayName(@urroundSoundEncoding int audioFormat)1363 public static String toDisplayName(@SurroundSoundEncoding int audioFormat) { 1364 switch (audioFormat) { 1365 case ENCODING_AC3: 1366 return "Dolby Digital"; 1367 case ENCODING_E_AC3: 1368 return "Dolby Digital Plus"; 1369 case ENCODING_DTS: 1370 return "DTS"; 1371 case ENCODING_DTS_HD: 1372 return "DTS HD"; 1373 case ENCODING_AAC_LC: 1374 return "AAC"; 1375 case ENCODING_DOLBY_TRUEHD: 1376 return "Dolby TrueHD"; 1377 case ENCODING_AC4: 1378 return "Dolby AC-4"; 1379 case ENCODING_E_AC3_JOC: 1380 return "Dolby Atmos in Dolby Digital Plus"; 1381 case ENCODING_DOLBY_MAT: 1382 return "Dolby MAT"; 1383 case ENCODING_MPEGH_BL_L3: 1384 return "MPEG-H 3D Audio baseline profile level 3"; 1385 case ENCODING_MPEGH_BL_L4: 1386 return "MPEG-H 3D Audio baseline profile level 4"; 1387 case ENCODING_MPEGH_LC_L3: 1388 return "MPEG-H 3D Audio low complexity profile level 3"; 1389 case ENCODING_MPEGH_LC_L4: 1390 return "MPEG-H 3D Audio low complexity profile level 4"; 1391 case ENCODING_DTS_UHD: 1392 return "DTS UHD"; 1393 case ENCODING_DRA: 1394 return "DRA"; 1395 default: 1396 return "Unknown surround sound format"; 1397 } 1398 } 1399 1400 } 1401