AudioFormat.java revision d2bebb3ab86177c0d27664af86b30b7dce2c9bcb
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 17package android.media; 18 19import android.annotation.IntDef; 20 21import java.lang.annotation.Retention; 22import java.lang.annotation.RetentionPolicy; 23 24/** 25 * The AudioFormat class is used to access a number of audio format and 26 * channel configuration constants. They are for instance used 27 * in {@link AudioTrack} and {@link AudioRecord}. 28 * 29 */ 30public class AudioFormat { 31 32 //--------------------------------------------------------- 33 // Constants 34 //-------------------- 35 /** Invalid audio data format */ 36 public static final int ENCODING_INVALID = 0; 37 /** Default audio data format */ 38 public static final int ENCODING_DEFAULT = 1; 39 40 // These values must be kept in sync with core/jni/android_media_AudioFormat.h 41 /** Audio data format: PCM 16 bit per sample. Guaranteed to be supported by devices. */ 42 public static final int ENCODING_PCM_16BIT = 2; 43 /** Audio data format: PCM 8 bit per sample. Not guaranteed to be supported by devices. */ 44 public static final int ENCODING_PCM_8BIT = 3; 45 /** Audio data format: single-precision floating-point per sample */ 46 public static final int ENCODING_PCM_FLOAT = 4; 47 /** Audio data format: AC-3 compressed */ 48 public static final int ENCODING_AC3 = 5; 49 /** Audio data format: E-AC-3 compressed */ 50 public static final int ENCODING_E_AC3 = 6; 51 52 /** Invalid audio channel configuration */ 53 /** @deprecated use CHANNEL_INVALID instead */ 54 @Deprecated public static final int CHANNEL_CONFIGURATION_INVALID = 0; 55 /** Default audio channel configuration */ 56 /** @deprecated use CHANNEL_OUT_DEFAULT or CHANNEL_IN_DEFAULT instead */ 57 @Deprecated public static final int CHANNEL_CONFIGURATION_DEFAULT = 1; 58 /** Mono audio configuration */ 59 /** @deprecated use CHANNEL_OUT_MONO or CHANNEL_IN_MONO instead */ 60 @Deprecated public static final int CHANNEL_CONFIGURATION_MONO = 2; 61 /** Stereo (2 channel) audio configuration */ 62 /** @deprecated use CHANNEL_OUT_STEREO or CHANNEL_IN_STEREO instead */ 63 @Deprecated public static final int CHANNEL_CONFIGURATION_STEREO = 3; 64 65 /** Invalid audio channel mask */ 66 public static final int CHANNEL_INVALID = 0; 67 /** Default audio channel mask */ 68 public static final int CHANNEL_OUT_DEFAULT = 1; 69 70 // Output channel mask definitions below are translated to the native values defined in 71 // in /system/core/include/system/audio.h in the JNI code of AudioTrack 72 public static final int CHANNEL_OUT_FRONT_LEFT = 0x4; 73 public static final int CHANNEL_OUT_FRONT_RIGHT = 0x8; 74 public static final int CHANNEL_OUT_FRONT_CENTER = 0x10; 75 public static final int CHANNEL_OUT_LOW_FREQUENCY = 0x20; 76 public static final int CHANNEL_OUT_BACK_LEFT = 0x40; 77 public static final int CHANNEL_OUT_BACK_RIGHT = 0x80; 78 public static final int CHANNEL_OUT_FRONT_LEFT_OF_CENTER = 0x100; 79 public static final int CHANNEL_OUT_FRONT_RIGHT_OF_CENTER = 0x200; 80 public static final int CHANNEL_OUT_BACK_CENTER = 0x400; 81 /** @hide CANDIDATE FOR PUBLIC API */ 82 public static final int CHANNEL_OUT_SIDE_LEFT = 0x800; 83 /** @hide CANDIDATE FOR PUBLIC API */ 84 public static final int CHANNEL_OUT_SIDE_RIGHT = 0x1000; 85 /** @hide */ 86 public static final int CHANNEL_OUT_TOP_CENTER = 0x2000; 87 /** @hide */ 88 public static final int CHANNEL_OUT_TOP_FRONT_LEFT = 0x4000; 89 /** @hide */ 90 public static final int CHANNEL_OUT_TOP_FRONT_CENTER = 0x8000; 91 /** @hide */ 92 public static final int CHANNEL_OUT_TOP_FRONT_RIGHT = 0x10000; 93 /** @hide */ 94 public static final int CHANNEL_OUT_TOP_BACK_LEFT = 0x20000; 95 /** @hide */ 96 public static final int CHANNEL_OUT_TOP_BACK_CENTER = 0x40000; 97 /** @hide */ 98 public static final int CHANNEL_OUT_TOP_BACK_RIGHT = 0x80000; 99 100 public static final int CHANNEL_OUT_MONO = CHANNEL_OUT_FRONT_LEFT; 101 public static final int CHANNEL_OUT_STEREO = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT); 102 // aka QUAD_BACK 103 public static final int CHANNEL_OUT_QUAD = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 104 CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT); 105 /** @hide */ 106 public static final int CHANNEL_OUT_QUAD_SIDE = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 107 CHANNEL_OUT_SIDE_LEFT | CHANNEL_OUT_SIDE_RIGHT); 108 public static final int CHANNEL_OUT_SURROUND = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 109 CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_BACK_CENTER); 110 // aka 5POINT1_BACK 111 public static final int CHANNEL_OUT_5POINT1 = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 112 CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY | CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT); 113 /** @hide */ 114 public static final int CHANNEL_OUT_5POINT1_SIDE = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 115 CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY | 116 CHANNEL_OUT_SIDE_LEFT | CHANNEL_OUT_SIDE_RIGHT); 117 // TODO does this need an @deprecated ? 118 // different from AUDIO_CHANNEL_OUT_7POINT1 119 public static final int CHANNEL_OUT_7POINT1 = (CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_RIGHT | 120 CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_LOW_FREQUENCY | CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT | 121 CHANNEL_OUT_FRONT_LEFT_OF_CENTER | CHANNEL_OUT_FRONT_RIGHT_OF_CENTER); 122 /** @hide */ 123 // matches AUDIO_CHANNEL_OUT_7POINT1 124 public static final int CHANNEL_OUT_7POINT1_SURROUND = ( 125 CHANNEL_OUT_FRONT_LEFT | CHANNEL_OUT_FRONT_CENTER | CHANNEL_OUT_FRONT_RIGHT | 126 CHANNEL_OUT_SIDE_LEFT | CHANNEL_OUT_SIDE_RIGHT | 127 CHANNEL_OUT_BACK_LEFT | CHANNEL_OUT_BACK_RIGHT | 128 CHANNEL_OUT_LOW_FREQUENCY); 129 // CHANNEL_OUT_ALL is not yet defined; if added then it should match AUDIO_CHANNEL_OUT_ALL 130 131 /** 132 * @hide 133 * Return the number of channels from an output channel mask 134 * @param mask a combination of the CHANNEL_OUT_* definitions, but not CHANNEL_OUT_DEFAULT 135 * @return number of channels for the mask 136 */ 137 public static int channelCountFromOutChannelMask(int mask) { 138 return Integer.bitCount(mask); 139 } 140 /** 141 * @hide 142 * Return a channel mask ready to be used by native code 143 * @param mask a combination of the CHANNEL_OUT_* definitions, but not CHANNEL_OUT_DEFAULT 144 * @return a native channel mask 145 */ 146 public static int convertChannelOutMaskToNativeMask(int javaMask) { 147 return (javaMask >> 2); 148 } 149 150 /** 151 * @hide 152 * Return a java output channel mask 153 * @param mask a native channel mask 154 * @return a combination of the CHANNEL_OUT_* definitions 155 */ 156 public static int convertNativeChannelMaskToOutMask(int nativeMask) { 157 return (nativeMask << 2); 158 } 159 160 public static final int CHANNEL_IN_DEFAULT = 1; 161 // These directly match native 162 public static final int CHANNEL_IN_LEFT = 0x4; 163 public static final int CHANNEL_IN_RIGHT = 0x8; 164 public static final int CHANNEL_IN_FRONT = 0x10; 165 public static final int CHANNEL_IN_BACK = 0x20; 166 public static final int CHANNEL_IN_LEFT_PROCESSED = 0x40; 167 public static final int CHANNEL_IN_RIGHT_PROCESSED = 0x80; 168 public static final int CHANNEL_IN_FRONT_PROCESSED = 0x100; 169 public static final int CHANNEL_IN_BACK_PROCESSED = 0x200; 170 public static final int CHANNEL_IN_PRESSURE = 0x400; 171 public static final int CHANNEL_IN_X_AXIS = 0x800; 172 public static final int CHANNEL_IN_Y_AXIS = 0x1000; 173 public static final int CHANNEL_IN_Z_AXIS = 0x2000; 174 public static final int CHANNEL_IN_VOICE_UPLINK = 0x4000; 175 public static final int CHANNEL_IN_VOICE_DNLINK = 0x8000; 176 public static final int CHANNEL_IN_MONO = CHANNEL_IN_FRONT; 177 public static final int CHANNEL_IN_STEREO = (CHANNEL_IN_LEFT | CHANNEL_IN_RIGHT); 178 /** @hide */ 179 public static final int CHANNEL_IN_FRONT_BACK = CHANNEL_IN_FRONT | CHANNEL_IN_BACK; 180 // CHANNEL_IN_ALL is not yet defined; if added then it should match AUDIO_CHANNEL_IN_ALL 181 182 /** @hide */ 183 public static int getBytesPerSample(int audioFormat) 184 { 185 switch (audioFormat) { 186 case ENCODING_PCM_8BIT: 187 return 1; 188 case ENCODING_PCM_16BIT: 189 case ENCODING_DEFAULT: 190 return 2; 191 case ENCODING_PCM_FLOAT: 192 return 4; 193 case ENCODING_INVALID: 194 default: 195 throw new IllegalArgumentException("Bad audio format " + audioFormat); 196 } 197 } 198 199 /** @hide */ 200 public static boolean isValidEncoding(int audioFormat) 201 { 202 switch (audioFormat) { 203 case ENCODING_PCM_8BIT: 204 case ENCODING_PCM_16BIT: 205 case ENCODING_PCM_FLOAT: 206 case ENCODING_AC3: 207 case ENCODING_E_AC3: 208 return true; 209 default: 210 return false; 211 } 212 } 213 214 /** @hide */ 215 public static boolean isEncodingLinearPcm(int audioFormat) 216 { 217 switch (audioFormat) { 218 case ENCODING_PCM_8BIT: 219 case ENCODING_PCM_16BIT: 220 case ENCODING_PCM_FLOAT: 221 case ENCODING_DEFAULT: 222 return true; 223 case ENCODING_AC3: 224 case ENCODING_E_AC3: 225 return false; 226 case ENCODING_INVALID: 227 default: 228 throw new IllegalArgumentException("Bad audio format " + audioFormat); 229 } 230 } 231 232 /** @removed */ 233 public AudioFormat() 234 { 235 throw new UnsupportedOperationException("There is no valid usage of this constructor"); 236 } 237 238 /** 239 * Private constructor with an ignored argument to differentiate from the removed default ctor 240 * @param ignoredArgument 241 */ 242 private AudioFormat(int ignoredArgument) { 243 } 244 245 /** @hide */ 246 public final static int AUDIO_FORMAT_HAS_PROPERTY_NONE = 0x0; 247 /** @hide */ 248 public final static int AUDIO_FORMAT_HAS_PROPERTY_ENCODING = 0x1 << 0; 249 /** @hide */ 250 public final static int AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE = 0x1 << 1; 251 /** @hide */ 252 public final static int AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK = 0x1 << 2; 253 254 private int mEncoding; 255 private int mSampleRate; 256 private int mChannelMask; 257 private int mPropertySetMask; 258 259 /** @hide */ 260 public int getEncoding() { 261 return mEncoding; 262 } 263 264 /** @hide */ 265 public int getSampleRate() { 266 return mSampleRate; 267 } 268 269 /** @hide */ 270 public int getChannelMask() { 271 return mChannelMask; 272 } 273 274 /** @hide */ 275 public int getPropertySetMask() { 276 return mPropertySetMask; 277 } 278 279 /** 280 * @hide CANDIDATE FOR PUBLIC API 281 * Builder class for {@link AudioFormat} objects. 282 */ 283 public static class Builder { 284 private int mEncoding = ENCODING_PCM_16BIT; 285 private int mSampleRate = 0; 286 private int mChannelMask = CHANNEL_INVALID; 287 private int mPropertySetMask = AUDIO_FORMAT_HAS_PROPERTY_NONE; 288 289 /** 290 * Constructs a new Builder with the defaults. 291 */ 292 public Builder() { 293 } 294 295 /** 296 * Constructs a new Builder from a given {@link AudioFormat}. 297 * @param af the {@link AudioFormat} object whose data will be reused in the new Builder. 298 */ 299 public Builder(AudioFormat af) { 300 mEncoding = af.mEncoding; 301 mSampleRate = af.mSampleRate; 302 mChannelMask = af.mChannelMask; 303 mPropertySetMask = af.mPropertySetMask; 304 } 305 306 /** 307 * Combines all of the format characteristics that have been set and return a new 308 * {@link AudioFormat} object. 309 * @return a new {@link AudioFormat} object 310 */ 311 public AudioFormat build() { 312 AudioFormat af = new AudioFormat(1980/*ignored*/); 313 af.mEncoding = mEncoding; 314 af.mSampleRate = mSampleRate; 315 af.mChannelMask = mChannelMask; 316 af.mPropertySetMask = mPropertySetMask; 317 return af; 318 } 319 320 /** 321 * Sets the data encoding format. 322 * @param encoding one of {@link AudioFormat#ENCODING_DEFAULT}, 323 * {@link AudioFormat#ENCODING_PCM_8BIT}, 324 * {@link AudioFormat#ENCODING_PCM_16BIT}, 325 * {@link AudioFormat#ENCODING_PCM_FLOAT}, 326 * {@link AudioFormat#ENCODING_AC3}, 327 * {@link AudioFormat#ENCODING_E_AC3}. 328 * @return the same Builder instance. 329 * @throws java.lang.IllegalArgumentException 330 */ 331 public Builder setEncoding(@Encoding int encoding) throws IllegalArgumentException { 332 switch (encoding) { 333 case ENCODING_DEFAULT: 334 mEncoding = ENCODING_PCM_16BIT; 335 break; 336 case ENCODING_PCM_8BIT: 337 case ENCODING_PCM_16BIT: 338 case ENCODING_PCM_FLOAT: 339 case ENCODING_AC3: 340 case ENCODING_E_AC3: 341 mEncoding = encoding; 342 break; 343 case ENCODING_INVALID: 344 default: 345 throw new IllegalArgumentException("Invalid encoding " + encoding); 346 } 347 mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_ENCODING; 348 return this; 349 } 350 351 /** 352 * Sets the channel mask. 353 * @param channelMask describes the configuration of the audio channels. 354 * <p>For output, the mask should be a combination of 355 * {@link AudioFormat#CHANNEL_OUT_FRONT_LEFT}, 356 * {@link AudioFormat#CHANNEL_OUT_FRONT_CENTER}, 357 * {@link AudioFormat#CHANNEL_OUT_FRONT_RIGHT}, 358 * {@link AudioFormat#CHANNEL_OUT_SIDE_LEFT}, 359 * {@link AudioFormat#CHANNEL_OUT_SIDE_RIGHT}, 360 * {@link AudioFormat#CHANNEL_OUT_BACK_LEFT}, 361 * {@link AudioFormat#CHANNEL_OUT_BACK_RIGHT}. 362 * <p>for input, the mask should be {@link AudioFormat#CHANNEL_IN_MONO} or 363 * {@link AudioFormat#CHANNEL_IN_STEREO}. {@link AudioFormat#CHANNEL_IN_MONO} is 364 * guaranteed to work on all devices. 365 * @return the same Builder instance. 366 */ 367 public Builder setChannelMask(int channelMask) { 368 // only validated when used, with input or output context 369 mChannelMask = channelMask; 370 mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_CHANNEL_MASK; 371 return this; 372 } 373 374 /** 375 * Sets the sample rate. 376 * @param sampleRate the sample rate expressed in Hz 377 * @return the same Builder instance. 378 * @throws java.lang.IllegalArgumentException 379 */ 380 public Builder setSampleRate(int sampleRate) throws IllegalArgumentException { 381 if ((sampleRate <= 0) || (sampleRate > 192000)) { 382 throw new IllegalArgumentException("Invalid sample rate " + sampleRate); 383 } 384 mSampleRate = sampleRate; 385 mPropertySetMask |= AUDIO_FORMAT_HAS_PROPERTY_SAMPLE_RATE; 386 return this; 387 } 388 } 389 390 @Override 391 public String toString () { 392 return new String("AudioFormat:" 393 + " props=" + mPropertySetMask 394 + " enc=" + mEncoding 395 + " chan=0x" + Integer.toHexString(mChannelMask) 396 + " rate=" + mSampleRate); 397 } 398 399 /** @hide */ 400 @IntDef({ 401 ENCODING_DEFAULT, 402 ENCODING_PCM_8BIT, 403 ENCODING_PCM_16BIT, 404 ENCODING_PCM_FLOAT, 405 ENCODING_AC3, 406 ENCODING_E_AC3 407 }) 408 @Retention(RetentionPolicy.SOURCE) 409 public @interface Encoding {} 410 411} 412