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