MediaFormat.java revision 52c58bb699f274bb87722b8e942f14811af23cf8
1/* 2 * Copyright (C) 2012 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 java.nio.ByteBuffer; 20import java.util.HashMap; 21import java.util.Map; 22 23/** 24 * Encapsulates the information describing the format of media data, 25 * be it audio or video. 26 * 27 * The format of the media data is specified as string/value pairs. 28 * 29 * Keys common to all audio/video formats, <b>all keys not marked optional are mandatory</b>: 30 * 31 * <table> 32 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 33 * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr> 34 * <tr><td>{@link #KEY_MAX_INPUT_SIZE}</td><td>Integer</td><td>optional, maximum size of a buffer of input data</td></tr> 35 * <tr><td>{@link #KEY_BIT_RATE}</td><td>Integer</td><td><b>encoder-only</b>, desired bitrate in bits/second</td></tr> 36 * </table> 37 * 38 * Video formats have the following keys: 39 * <table> 40 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 41 * <tr><td>{@link #KEY_WIDTH}</td><td>Integer</td><td></td></tr> 42 * <tr><td>{@link #KEY_HEIGHT}</td><td>Integer</td><td></td></tr> 43 * <tr><td>{@link #KEY_COLOR_FORMAT}</td><td>Integer</td><td>set by the user 44 * for encoders, readable in the output format of decoders</b></td></tr> 45 * <tr><td>{@link #KEY_FRAME_RATE}</td><td>Integer or Float</td><td><b>encoder-only</b></td></tr> 46 * <tr><td>{@link #KEY_CAPTURE_RATE}</td><td>Integer</td><td></td></tr> 47* <tr><td>{@link #KEY_I_FRAME_INTERVAL}</td><td>Integer</td><td><b>encoder-only</b></td></tr> 48 * <tr><td>{@link #KEY_MAX_WIDTH}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution width</td></tr> 49 * <tr><td>{@link #KEY_MAX_HEIGHT}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution height</td></tr> 50 * <tr><td>{@link #KEY_REPEAT_PREVIOUS_FRAME_AFTER}</td><td>Long</td><td><b>video encoder in surface-mode only</b></td></tr> 51 * <tr><td>{@link #KEY_PUSH_BLANK_BUFFERS_ON_STOP}</td><td>Integer(1)</td><td><b>video decoder rendering to a surface only</b></td></tr> 52 * </table> 53 * Specify both {@link #KEY_MAX_WIDTH} and {@link #KEY_MAX_HEIGHT} to enable 54 * adaptive playback (seamless resolution change) for a video decoder that 55 * supports it ({@link MediaCodecInfo.CodecCapabilities#FEATURE_AdaptivePlayback}). 56 * The values are used as hints for the codec: they are the maximum expected 57 * resolution to prepare for. Depending on codec support, preparing for larger 58 * maximum resolution may require more memory even if that resolution is never 59 * reached. These fields have no effect for codecs that do not support adaptive 60 * playback.<br /><br /> 61 * 62 * Audio formats have the following keys: 63 * <table> 64 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 65 * <tr><td>{@link #KEY_CHANNEL_COUNT}</td><td>Integer</td><td></td></tr> 66 * <tr><td>{@link #KEY_SAMPLE_RATE}</td><td>Integer</td><td></td></tr> 67 * <tr><td>{@link #KEY_IS_ADTS}</td><td>Integer</td><td>optional, if <em>decoding</em> AAC audio content, setting this key to 1 indicates that each audio frame is prefixed by the ADTS header.</td></tr> 68 * <tr><td>{@link #KEY_AAC_PROFILE}</td><td>Integer</td><td><b>encoder-only</b>, optional, if content is AAC audio, specifies the desired profile.</td></tr> 69 * <tr><td>{@link #KEY_AAC_SBR_MODE}</td><td>Integer</td><td><b>encoder-only</b>, optional, if content is AAC audio, specifies the desired SBR mode.</td></tr> 70 * <tr><td>{@link #KEY_AAC_DRC_TARGET_REFERENCE_LEVEL}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies the target reference level.</td></tr> 71 * <tr><td>{@link #KEY_AAC_ENCODED_TARGET_LEVEL}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies the target reference level used at encoder.</td></tr> 72 * <tr><td>{@link #KEY_AAC_DRC_BOOST_FACTOR}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies the DRC boost factor.</td></tr> 73 * <tr><td>{@link #KEY_AAC_DRC_ATTENUATION_FACTOR}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies the DRC attenuation factor.</td></tr> 74 * <tr><td>{@link #KEY_AAC_DRC_HEAVY_COMPRESSION}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies whether to use heavy compression.</td></tr> 75 * <tr><td>{@link #KEY_AAC_MAX_OUTPUT_CHANNEL_COUNT}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies the maximum number of channels the decoder outputs.</td></tr> 76 * <tr><td>{@link #KEY_CHANNEL_MASK}</td><td>Integer</td><td>optional, a mask of audio channel assignments</td></tr> 77 * <tr><td>{@link #KEY_FLAC_COMPRESSION_LEVEL}</td><td>Integer</td><td><b>encoder-only</b>, optional, if content is FLAC audio, specifies the desired compression level.</td></tr> 78 * </table> 79 * 80 * Subtitle formats have the following keys: 81 * <table> 82 * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr> 83 * <tr><td>{@link #KEY_LANGUAGE}</td><td>String</td><td>The language of the content.</td></tr> 84 * </table> 85 */ 86public final class MediaFormat { 87 public static final String MIMETYPE_VIDEO_VP8 = "video/x-vnd.on2.vp8"; 88 public static final String MIMETYPE_VIDEO_VP9 = "video/x-vnd.on2.vp9"; 89 public static final String MIMETYPE_VIDEO_AVC = "video/avc"; 90 public static final String MIMETYPE_VIDEO_HEVC = "video/hevc"; 91 public static final String MIMETYPE_VIDEO_MPEG4 = "video/mp4v-es"; 92 public static final String MIMETYPE_VIDEO_H263 = "video/3gpp"; 93 public static final String MIMETYPE_VIDEO_MPEG2 = "video/mpeg2"; 94 public static final String MIMETYPE_VIDEO_RAW = "video/raw"; 95 96 public static final String MIMETYPE_AUDIO_AMR_NB = "audio/3gpp"; 97 public static final String MIMETYPE_AUDIO_AMR_WB = "audio/amr-wb"; 98 public static final String MIMETYPE_AUDIO_MPEG = "audio/mpeg"; 99 public static final String MIMETYPE_AUDIO_AAC = "audio/mp4a-latm"; 100 public static final String MIMETYPE_AUDIO_QCELP = "audio/qcelp"; 101 public static final String MIMETYPE_AUDIO_VORBIS = "audio/vorbis"; 102 public static final String MIMETYPE_AUDIO_OPUS = "audio/opus"; 103 public static final String MIMETYPE_AUDIO_G711_ALAW = "audio/g711-alaw"; 104 public static final String MIMETYPE_AUDIO_G711_MLAW = "audio/g711-mlaw"; 105 public static final String MIMETYPE_AUDIO_RAW = "audio/raw"; 106 public static final String MIMETYPE_AUDIO_FLAC = "audio/flac"; 107 public static final String MIMETYPE_AUDIO_MSGSM = "audio/gsm"; 108 public static final String MIMETYPE_AUDIO_AC3 = "audio/ac3"; 109 public static final String MIMETYPE_AUDIO_EAC3 = "audio/eac3"; 110 111 /** 112 * MIME type for WebVTT subtitle data. 113 */ 114 public static final String MIMETYPE_TEXT_VTT = "text/vtt"; 115 116 /** 117 * MIME type for CEA-608 closed caption data. 118 */ 119 public static final String MIMETYPE_TEXT_CEA_608 = "text/cea-608"; 120 121 private Map<String, Object> mMap; 122 123 /** 124 * A key describing the mime type of the MediaFormat. 125 * The associated value is a string. 126 */ 127 public static final String KEY_MIME = "mime"; 128 129 /** 130 * A key describing the language of the content, using either ISO 639-1 131 * or 639-2/T codes. The associated value is a string. 132 */ 133 public static final String KEY_LANGUAGE = "language"; 134 135 /** 136 * A key describing the sample rate of an audio format. 137 * The associated value is an integer 138 */ 139 public static final String KEY_SAMPLE_RATE = "sample-rate"; 140 141 /** 142 * A key describing the number of channels in an audio format. 143 * The associated value is an integer 144 */ 145 public static final String KEY_CHANNEL_COUNT = "channel-count"; 146 147 /** 148 * A key describing the width of the content in a video format. 149 * The associated value is an integer 150 */ 151 public static final String KEY_WIDTH = "width"; 152 153 /** 154 * A key describing the height of the content in a video format. 155 * The associated value is an integer 156 */ 157 public static final String KEY_HEIGHT = "height"; 158 159 /** 160 * A key describing the maximum expected width of the content in a video 161 * decoder format, in case there are resolution changes in the video content. 162 * The associated value is an integer 163 */ 164 public static final String KEY_MAX_WIDTH = "max-width"; 165 166 /** 167 * A key describing the maximum expected height of the content in a video 168 * decoder format, in case there are resolution changes in the video content. 169 * The associated value is an integer 170 */ 171 public static final String KEY_MAX_HEIGHT = "max-height"; 172 173 /** A key describing the maximum size in bytes of a buffer of data 174 * described by this MediaFormat. 175 * The associated value is an integer 176 */ 177 public static final String KEY_MAX_INPUT_SIZE = "max-input-size"; 178 179 /** 180 * A key describing the bitrate in bits/sec. 181 * The associated value is an integer 182 */ 183 public static final String KEY_BIT_RATE = "bitrate"; 184 185 /** 186 * A key describing the color format of the content in a video format. 187 * Constants are declared in {@link android.media.MediaCodecInfo.CodecCapabilities}. 188 */ 189 public static final String KEY_COLOR_FORMAT = "color-format"; 190 191 /** 192 * A key describing the frame rate of a video format in frames/sec. 193 * The associated value is an integer or a float. 194 */ 195 public static final String KEY_FRAME_RATE = "frame-rate"; 196 197 /** 198 * A key describing the capture rate of a video format in frames/sec. 199 * <p> 200 * When capture rate is different than the frame rate, it means that the 201 * video is acquired at a different rate than the playback, which produces 202 * slow motion or timelapse effect during playback. Application can use the 203 * value of this key to tell the relative speed ratio between capture and 204 * playback rates when the video was recorded. 205 * </p> 206 * <p> 207 * The associated value is an integer or a float. 208 * </p> 209 */ 210 public static final String KEY_CAPTURE_RATE = "capture-rate"; 211 212 /** 213 * A key describing the frequency of I frames expressed in secs 214 * between I frames. 215 * The associated value is an integer. 216 */ 217 public static final String KEY_I_FRAME_INTERVAL = "i-frame-interval"; 218 219 /** 220 * A key describing the temporal layering schema. This is an optional parameter 221 * that applies only to video encoders. Use {@link MediaCodec#getInputFormat} 222 * after {@link MediaCodec#configure configure} to query if the encoder supports 223 * the desired schema. Supported values are {@code webrtc.vp8.1-layer}, 224 * {@code webrtc.vp8.2-layer}, {@code webrtc.vp8.3-layer}, and {@code none}. 225 * If the encoder does not support temporal layering, the input format will 226 * not have an entry with this key. 227 * The associated value is a string. 228 */ 229 public static final String KEY_TEMPORAL_LAYERING = "ts-schema"; 230 231 /** 232 * A key describing the stride of the video bytebuffer layout. 233 * Stride (or row increment) is the difference between the index of a pixel 234 * and that of the pixel directly underneath. For YUV 420 formats, the 235 * stride corresponds to the Y plane; the stride of the U and V planes can 236 * be calculated based on the color format. 237 * The associated value is an integer, representing number of bytes. 238 */ 239 public static final String KEY_STRIDE = "stride"; 240 241 /** 242 * A key describing the plane height of a multi-planar (YUV) video bytebuffer layout. 243 * Slice height (or plane height) is the number of rows that must be skipped to get 244 * from the top of the Y plane to the top of the U plane in the bytebuffer. In essence 245 * the offset of the U plane is sliceHeight * stride. The height of the U/V planes 246 * can be calculated based on the color format. 247 * The associated value is an integer, representing number of rows. 248 */ 249 public static final String KEY_SLICE_HEIGHT = "slice-height"; 250 251 /** 252 * Applies only when configuring a video encoder in "surface-input" mode. 253 * The associated value is a long and gives the time in microseconds 254 * after which the frame previously submitted to the encoder will be 255 * repeated (once) if no new frame became available since. 256 */ 257 public static final String KEY_REPEAT_PREVIOUS_FRAME_AFTER 258 = "repeat-previous-frame-after"; 259 260 /** 261 * If specified when configuring a video decoder rendering to a surface, 262 * causes the decoder to output "blank", i.e. black frames to the surface 263 * when stopped to clear out any previously displayed contents. 264 * The associated value is an integer of value 1. 265 */ 266 public static final String KEY_PUSH_BLANK_BUFFERS_ON_STOP 267 = "push-blank-buffers-on-shutdown"; 268 269 /** 270 * A key describing the duration (in microseconds) of the content. 271 * The associated value is a long. 272 */ 273 public static final String KEY_DURATION = "durationUs"; 274 275 /** 276 * A key mapping to a value of 1 if the content is AAC audio and 277 * audio frames are prefixed with an ADTS header. 278 * The associated value is an integer (0 or 1). 279 * This key is only supported when _decoding_ content, it cannot 280 * be used to configure an encoder to emit ADTS output. 281 */ 282 public static final String KEY_IS_ADTS = "is-adts"; 283 284 /** 285 * A key describing the channel composition of audio content. This mask 286 * is composed of bits drawn from channel mask definitions in {@link android.media.AudioFormat}. 287 * The associated value is an integer. 288 */ 289 public static final String KEY_CHANNEL_MASK = "channel-mask"; 290 291 /** 292 * A key describing the AAC profile to be used (AAC audio formats only). 293 * Constants are declared in {@link android.media.MediaCodecInfo.CodecProfileLevel}. 294 */ 295 public static final String KEY_AAC_PROFILE = "aac-profile"; 296 297 /** 298 * A key describing the AAC SBR mode to be used (AAC audio formats only). 299 * The associated value is an integer and can be set to following values: 300 * <ul> 301 * <li>0 - no SBR should be applied</li> 302 * <li>1 - single rate SBR</li> 303 * <li>2 - double rate SBR</li> 304 * </ul> 305 * Note: If this key is not defined the default SRB mode for the desired AAC profile will 306 * be used. 307 * <p>This key is only used during encoding. 308 */ 309 public static final String KEY_AAC_SBR_MODE = "aac-sbr-mode"; 310 311 /** 312 * A key describing the maximum number of channels that can be output by the AAC decoder. 313 * By default, the decoder will output the same number of channels as present in the encoded 314 * stream, if supported. Set this value to limit the number of output channels, and use 315 * the downmix information in the stream, if available. 316 * <p>Values larger than the number of channels in the content to decode are ignored. 317 * <p>This key is only used during decoding. 318 */ 319 public static final String KEY_AAC_MAX_OUTPUT_CHANNEL_COUNT = "aac-max-output-channel_count"; 320 321 /** 322 * A key describing a gain to be applied so that the output loudness matches the 323 * Target Reference Level. This is typically used to normalize loudness across program items. 324 * The gain is derived as the difference between the Target Reference Level and the 325 * Program Reference Level. The latter can be given in the bitstream and indicates the actual 326 * loudness value of the program item. 327 * <p>The value is given as an integer value between 328 * 0 and 127, and is calculated as -0.25 * Target Reference Level in dBFS. 329 * Therefore, it represents the range of Full Scale (0 dBFS) to -31.75 dBFS. 330 * <p>This key is only used during decoding. 331 */ 332 public static final String KEY_AAC_DRC_TARGET_REFERENCE_LEVEL = "aac-target-ref-level"; 333 334 /** 335 * A key describing the target reference level that was assumed at the encoder for 336 * calculation of attenuation gains for clipping prevention. This information can be provided 337 * if it is known, otherwise a worst-case assumption is used. 338 * <p>The value is given as an integer value between 339 * 0 and 127, and is calculated as -0.25 * Target Reference Level in dBFS. 340 * Therefore, it represents the range of Full Scale (0 dBFS) to -31.75 dBFS. 341 * The default value is the worst-case assumption of 127. 342 * <p>The value is ignored when heavy compression is used (see 343 * {@link #KEY_AAC_DRC_HEAVY_COMPRESSION}). 344 * <p>This key is only used during decoding. 345 */ 346 public static final String KEY_AAC_ENCODED_TARGET_LEVEL = "aac-encoded-target-level"; 347 348 /** 349 * A key describing the boost factor allowing to adapt the dynamics of the output to the 350 * actual listening requirements. This relies on DRC gain sequences that can be transmitted in 351 * the encoded bitstream to be able to reduce the dynamics of the output signal upon request. 352 * This factor enables the user to select how much of the gains are applied. 353 * <p>Positive gains (boost) and negative gains (attenuation, see 354 * {@link #KEY_AAC_DRC_ATTENUATION_FACTOR}) can be controlled separately for a better match 355 * to different use-cases. 356 * <p>Typically, attenuation gains are sent for loud signal segments, and boost gains are sent 357 * for soft signal segments. If the output is listened to in a noisy environment, for example, 358 * the boost factor is used to enable the positive gains, i.e. to amplify soft signal segments 359 * beyond the noise floor. But for listening late at night, the attenuation 360 * factor is used to enable the negative gains, to prevent loud signal from surprising 361 * the listener. In applications which generally need a low dynamic range, both the boost factor 362 * and the attenuation factor are used in order to enable all DRC gains. 363 * <p>In order to prevent clipping, it is also recommended to apply the attenuation factors 364 * in case of a downmix and/or loudness normalization to high target reference levels. 365 * <p>Both the boost and the attenuation factor parameters are given as integer values 366 * between 0 and 127, representing the range of the factor of 0 (i.e. don't apply) 367 * to 1 (i.e. fully apply boost/attenuation factors respectively). 368 * <p>This key is only used during decoding. 369 */ 370 public static final String KEY_AAC_DRC_BOOST_FACTOR = "aac-drc-boost-level"; 371 372 /** 373 * A key describing the attenuation factor allowing to adapt the dynamics of the output to the 374 * actual listening requirements. 375 * See {@link #KEY_AAC_DRC_BOOST_FACTOR} for a description of the role of this attenuation 376 * factor and the value range. 377 * <p>This key is only used during decoding. 378 */ 379 public static final String KEY_AAC_DRC_ATTENUATION_FACTOR = "aac-drc-cut-level"; 380 381 /** 382 * A key describing the selection of the heavy compression profile for DRC. 383 * Two separate DRC gain sequences can be transmitted in one bitstream: MPEG-4 DRC light 384 * compression, and DVB-specific heavy compression. When selecting the application of the heavy 385 * compression, one of the sequences is selected: 386 * <ul> 387 * <li>0 enables light compression,</li> 388 * <li>1 enables heavy compression instead. 389 * </ul> 390 * Note that only light compression offers the features of scaling of DRC gains 391 * (see {@link #KEY_AAC_DRC_BOOST_FACTOR} and {@link #KEY_AAC_DRC_ATTENUATION_FACTOR} for the 392 * boost and attenuation factors, and frequency-selective (multiband) DRC. 393 * Light compression usually contains clipping prevention for stereo downmixing while heavy 394 * compression, if additionally provided in the bitstream, is usually stronger, and contains 395 * clipping prevention for stereo and mono downmixing. 396 * <p>The default is light compression. 397 * <p>This key is only used during decoding. 398 */ 399 public static final String KEY_AAC_DRC_HEAVY_COMPRESSION = "aac-drc-heavy-compression"; 400 401 /** 402 * A key describing the FLAC compression level to be used (FLAC audio format only). 403 * The associated value is an integer ranging from 0 (fastest, least compression) 404 * to 8 (slowest, most compression). 405 */ 406 public static final String KEY_FLAC_COMPRESSION_LEVEL = "flac-compression-level"; 407 408 /** 409 * A key describing the encoding complexity. 410 * The associated value is an integer. These values are device and codec specific, 411 * but lower values generally result in faster and/or less power-hungry encoding. 412 * 413 * @see MediaCodecInfo.EncoderCapabilities#getComplexityRange() 414 */ 415 public static final String KEY_COMPLEXITY = "complexity"; 416 417 /** 418 * A key describing the desired encoding quality. 419 * The associated value is an integer. This key is only supported for encoders 420 * that are configured in constant-quality mode. These values are device and 421 * codec specific, but lower values generally result in more efficient 422 * (smaller-sized) encoding. 423 * 424 * @hide 425 * 426 * @see MediaCodecInfo.EncoderCapabilities#getQualityRange() 427 */ 428 public static final String KEY_QUALITY = "quality"; 429 430 /** 431 * A key describing the desired codec priority. 432 * <p> 433 * The associated value is an integer. Higher value means lower priority. 434 * <p> 435 * Currently, only two levels are supported:<br> 436 * 0: realtime priority - meaning that the codec shall support the given 437 * performance configuration (e.g. framerate) at realtime. This should 438 * only be used by media playback, capture, and possibly by realtime 439 * communication scenarios if best effort performance is not suitable.<br> 440 * 1: non-realtime priority (best effort). 441 * <p> 442 * This is a hint used at codec configuration and resource planning - to understand 443 * the realtime requirements of the application; however, due to the nature of 444 * media components, performance is not guaranteed. 445 * 446 */ 447 public static final String KEY_PRIORITY = "priority"; 448 449 /** 450 * A key describing the desired operating frame rate for video or sample rate for audio 451 * that the codec will need to operate at. 452 * <p> 453 * The associated value is an integer or a float representing frames-per-second or 454 * samples-per-second 455 * <p> 456 * This is used for cases like high-speed/slow-motion video capture, where the video encoder 457 * format contains the target playback rate (e.g. 30fps), but the component must be able to 458 * handle the high operating capture rate (e.g. 240fps). 459 * <p> 460 * This rate will be used by codec for resource planning and setting the operating points. 461 * 462 */ 463 public static final String KEY_OPERATING_RATE = "operating-rate"; 464 465 /** 466 * A key describing the desired profile to be used by an encoder. 467 * The associated value is an integer. 468 * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}. 469 * This key is used as a hint, and is only supported for codecs 470 * that specify a profile. 471 * 472 * @see MediaCodecInfo.CodecCapabilities#profileLevels 473 */ 474 public static final String KEY_PROFILE = "profile"; 475 476 /** 477 * A key describing the desired profile to be used by an encoder. 478 * The associated value is an integer. 479 * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}. 480 * This key is used as a further hint when specifying a desired profile, 481 * and is only supported for codecs that specify a level. 482 * <p> 483 * This key is ignored if the {@link #KEY_PROFILE profile} is not specified. 484 * 485 * @see MediaCodecInfo.CodecCapabilities#profileLevels 486 */ 487 public static final String KEY_LEVEL = "level"; 488 489 /** 490 * A key describing the desired clockwise rotation on an output surface. 491 * This key is only used when the codec is configured using an output surface. 492 * The associated value is an integer, representing degrees. 493 * 494 * @see MediaCodecInfo.CodecCapabilities#profileLevels 495 */ 496 public static final String KEY_ROTATION = "rotation-degrees"; 497 498 /** 499 * A key describing the desired bitrate mode to be used by an encoder. 500 * Constants are declared in {@link MediaCodecInfo.CodecCapabilities}. 501 * 502 * @see MediaCodecInfo.EncoderCapabilities#isBitrateModeSupported(int) 503 */ 504 public static final String KEY_BITRATE_MODE = "bitrate-mode"; 505 506 /** 507 * A key describing the audio session ID of the AudioTrack associated 508 * to a tunneled video codec. 509 * The associated value is an integer. 510 * 511 * @see MediaCodecInfo.CodecCapabilities#FEATURE_TunneledPlayback 512 */ 513 public static final String KEY_AUDIO_SESSION_ID = "audio-session-id"; 514 515 /** 516 * A key for boolean AUTOSELECT behavior for the track. Tracks with AUTOSELECT=true 517 * are considered when automatically selecting a track without specific user 518 * choice, based on the current locale. 519 * This is currently only used for subtitle tracks, when the user selected 520 * 'Default' for the captioning locale. 521 * The associated value is an integer, where non-0 means TRUE. This is an optional 522 * field; if not specified, AUTOSELECT defaults to TRUE. 523 */ 524 public static final String KEY_IS_AUTOSELECT = "is-autoselect"; 525 526 /** 527 * A key for boolean DEFAULT behavior for the track. The track with DEFAULT=true is 528 * selected in the absence of a specific user choice. 529 * This is currently only used for subtitle tracks, when the user selected 530 * 'Default' for the captioning locale. 531 * The associated value is an integer, where non-0 means TRUE. This is an optional 532 * field; if not specified, DEFAULT is considered to be FALSE. 533 */ 534 public static final String KEY_IS_DEFAULT = "is-default"; 535 536 537 /** 538 * A key for the FORCED field for subtitle tracks. True if it is a 539 * forced subtitle track. Forced subtitle tracks are essential for the 540 * content and are shown even when the user turns off Captions. They 541 * are used for example to translate foreign/alien dialogs or signs. 542 * The associated value is an integer, where non-0 means TRUE. This is an 543 * optional field; if not specified, FORCED defaults to FALSE. 544 */ 545 public static final String KEY_IS_FORCED_SUBTITLE = "is-forced-subtitle"; 546 547 /** @hide */ 548 public static final String KEY_IS_TIMED_TEXT = "is-timed-text"; 549 550 /* package private */ MediaFormat(Map<String, Object> map) { 551 mMap = map; 552 } 553 554 /** 555 * Creates an empty MediaFormat 556 */ 557 public MediaFormat() { 558 mMap = new HashMap(); 559 } 560 561 /* package private */ Map<String, Object> getMap() { 562 return mMap; 563 } 564 565 /** 566 * Returns true iff a key of the given name exists in the format. 567 */ 568 public final boolean containsKey(String name) { 569 return mMap.containsKey(name); 570 } 571 572 /** 573 * A key prefix used together with a {@link MediaCodecInfo.CodecCapabilities} 574 * feature name describing a required or optional feature for a codec capabilities 575 * query. 576 * The associated value is an integer, where non-0 value means the feature is 577 * requested to be present, while 0 value means the feature is requested to be not 578 * present. 579 * @see MediaCodecList#findDecoderForFormat 580 * @see MediaCodecList#findEncoderForFormat 581 * @see MediaCodecInfo.CodecCapabilities#isFormatSupported 582 * 583 * @hide 584 */ 585 public static final String KEY_FEATURE_ = "feature-"; 586 587 /** 588 * Returns the value of an integer key. 589 */ 590 public final int getInteger(String name) { 591 return ((Integer)mMap.get(name)).intValue(); 592 } 593 594 /** 595 * Returns the value of an integer key, or the default value if the 596 * key is missing or is for another type value. 597 * @hide 598 */ 599 public final int getInteger(String name, int defaultValue) { 600 try { 601 return getInteger(name); 602 } 603 catch (NullPointerException e) { /* no such field */ } 604 catch (ClassCastException e) { /* field of different type */ } 605 return defaultValue; 606 } 607 608 /** 609 * Returns the value of a long key. 610 */ 611 public final long getLong(String name) { 612 return ((Long)mMap.get(name)).longValue(); 613 } 614 615 /** 616 * Returns the value of a float key. 617 */ 618 public final float getFloat(String name) { 619 return ((Float)mMap.get(name)).floatValue(); 620 } 621 622 /** 623 * Returns the value of a string key. 624 */ 625 public final String getString(String name) { 626 return (String)mMap.get(name); 627 } 628 629 /** 630 * Returns the value of a ByteBuffer key. 631 */ 632 public final ByteBuffer getByteBuffer(String name) { 633 return (ByteBuffer)mMap.get(name); 634 } 635 636 /** 637 * Returns whether a feature is to be enabled ({@code true}) or disabled 638 * ({@code false}). 639 * 640 * @param feature the name of a {@link MediaCodecInfo.CodecCapabilities} feature. 641 * 642 * @throws IllegalArgumentException if the feature was neither set to be enabled 643 * nor to be disabled. 644 */ 645 public boolean getFeatureEnabled(String feature) { 646 Integer enabled = (Integer)mMap.get(KEY_FEATURE_ + feature); 647 if (enabled == null) { 648 throw new IllegalArgumentException("feature is not specified"); 649 } 650 return enabled != 0; 651 } 652 653 /** 654 * Sets the value of an integer key. 655 */ 656 public final void setInteger(String name, int value) { 657 mMap.put(name, Integer.valueOf(value)); 658 } 659 660 /** 661 * Sets the value of a long key. 662 */ 663 public final void setLong(String name, long value) { 664 mMap.put(name, Long.valueOf(value)); 665 } 666 667 /** 668 * Sets the value of a float key. 669 */ 670 public final void setFloat(String name, float value) { 671 mMap.put(name, new Float(value)); 672 } 673 674 /** 675 * Sets the value of a string key. 676 */ 677 public final void setString(String name, String value) { 678 mMap.put(name, value); 679 } 680 681 /** 682 * Sets the value of a ByteBuffer key. 683 */ 684 public final void setByteBuffer(String name, ByteBuffer bytes) { 685 mMap.put(name, bytes); 686 } 687 688 /** 689 * Sets whether a feature is to be enabled ({@code true}) or disabled 690 * ({@code false}). 691 * 692 * If {@code enabled} is {@code true}, the feature is requested to be present. 693 * Otherwise, the feature is requested to be not present. 694 * 695 * @param feature the name of a {@link MediaCodecInfo.CodecCapabilities} feature. 696 * 697 * @see MediaCodecList#findDecoderForFormat 698 * @see MediaCodecList#findEncoderForFormat 699 * @see MediaCodecInfo.CodecCapabilities#isFormatSupported 700 */ 701 public void setFeatureEnabled(String feature, boolean enabled) { 702 setInteger(KEY_FEATURE_ + feature, enabled ? 1 : 0); 703 } 704 705 /** 706 * Creates a minimal audio format. 707 * @param mime The mime type of the content. 708 * @param sampleRate The sampling rate of the content. 709 * @param channelCount The number of audio channels in the content. 710 */ 711 public static final MediaFormat createAudioFormat( 712 String mime, 713 int sampleRate, 714 int channelCount) { 715 MediaFormat format = new MediaFormat(); 716 format.setString(KEY_MIME, mime); 717 format.setInteger(KEY_SAMPLE_RATE, sampleRate); 718 format.setInteger(KEY_CHANNEL_COUNT, channelCount); 719 720 return format; 721 } 722 723 /** 724 * Creates a minimal subtitle format. 725 * @param mime The mime type of the content. 726 * @param language The language of the content, using either ISO 639-1 or 639-2/T 727 * codes. Specify null or "und" if language information is only included 728 * in the content. (This will also work if there are multiple language 729 * tracks in the content.) 730 */ 731 public static final MediaFormat createSubtitleFormat( 732 String mime, 733 String language) { 734 MediaFormat format = new MediaFormat(); 735 format.setString(KEY_MIME, mime); 736 format.setString(KEY_LANGUAGE, language); 737 738 return format; 739 } 740 741 /** 742 * Creates a minimal video format. 743 * @param mime The mime type of the content. 744 * @param width The width of the content (in pixels) 745 * @param height The height of the content (in pixels) 746 */ 747 public static final MediaFormat createVideoFormat( 748 String mime, 749 int width, 750 int height) { 751 MediaFormat format = new MediaFormat(); 752 format.setString(KEY_MIME, mime); 753 format.setInteger(KEY_WIDTH, width); 754 format.setInteger(KEY_HEIGHT, height); 755 756 return format; 757 } 758 759 @Override 760 public String toString() { 761 return mMap.toString(); 762 } 763} 764