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 /** 110 * @hide 111 */ 112 public static final String MIMETYPE_AUDIO_EAC3 = "audio/eac3"; 113 114 /** 115 * MIME type for WebVTT subtitle data. 116 */ 117 public static final String MIMETYPE_TEXT_VTT = "text/vtt"; 118 119 /** 120 * MIME type for CEA-608 closed caption data. 121 */ 122 public static final String MIMETYPE_TEXT_CEA_608 = "text/cea-608"; 123 124 private Map<String, Object> mMap; 125 126 /** 127 * A key describing the mime type of the MediaFormat. 128 * The associated value is a string. 129 */ 130 public static final String KEY_MIME = "mime"; 131 132 /** 133 * A key describing the language of the content, using either ISO 639-1 134 * or 639-2/T codes. The associated value is a string. 135 */ 136 public static final String KEY_LANGUAGE = "language"; 137 138 /** 139 * A key describing the sample rate of an audio format. 140 * The associated value is an integer 141 */ 142 public static final String KEY_SAMPLE_RATE = "sample-rate"; 143 144 /** 145 * A key describing the number of channels in an audio format. 146 * The associated value is an integer 147 */ 148 public static final String KEY_CHANNEL_COUNT = "channel-count"; 149 150 /** 151 * A key describing the width of the content in a video format. 152 * The associated value is an integer 153 */ 154 public static final String KEY_WIDTH = "width"; 155 156 /** 157 * A key describing the height of the content in a video format. 158 * The associated value is an integer 159 */ 160 public static final String KEY_HEIGHT = "height"; 161 162 /** 163 * A key describing the maximum expected width of the content in a video 164 * decoder format, in case there are resolution changes in the video content. 165 * The associated value is an integer 166 */ 167 public static final String KEY_MAX_WIDTH = "max-width"; 168 169 /** 170 * A key describing the maximum expected height of the content in a video 171 * decoder format, in case there are resolution changes in the video content. 172 * The associated value is an integer 173 */ 174 public static final String KEY_MAX_HEIGHT = "max-height"; 175 176 /** A key describing the maximum size in bytes of a buffer of data 177 * described by this MediaFormat. 178 * The associated value is an integer 179 */ 180 public static final String KEY_MAX_INPUT_SIZE = "max-input-size"; 181 182 /** 183 * A key describing the bitrate in bits/sec. 184 * The associated value is an integer 185 */ 186 public static final String KEY_BIT_RATE = "bitrate"; 187 188 /** 189 * A key describing the color format of the content in a video format. 190 * Constants are declared in {@link android.media.MediaCodecInfo.CodecCapabilities}. 191 */ 192 public static final String KEY_COLOR_FORMAT = "color-format"; 193 194 /** 195 * A key describing the frame rate of a video format in frames/sec. 196 * The associated value is an integer or a float. 197 */ 198 public static final String KEY_FRAME_RATE = "frame-rate"; 199 200 /** 201 * A key describing the capture rate of a video format in frames/sec. 202 * <p> 203 * When capture rate is different than the frame rate, it means that the 204 * video is acquired at a different rate than the playback, which produces 205 * slow motion or timelapse effect during playback. Application can use the 206 * value of this key to tell the relative speed ratio between capture and 207 * playback rates when the video was recorded. 208 * </p> 209 * <p> 210 * The associated value is an integer or a float. 211 * </p> 212 */ 213 public static final String KEY_CAPTURE_RATE = "capture-rate"; 214 215 /** 216 * A key describing the frequency of I frames expressed in secs 217 * between I frames. 218 * The associated value is an integer. 219 */ 220 public static final String KEY_I_FRAME_INTERVAL = "i-frame-interval"; 221 222 /** 223 * A key describing the temporal layering schema. This is an optional parameter 224 * that applies only to video encoders. Use {@link MediaCodec#getInputFormat} 225 * after {@link MediaCodec#configure configure} to query if the encoder supports 226 * the desired schema. Supported values are {@code webrtc.vp8.1-layer}, 227 * {@code webrtc.vp8.2-layer}, {@code webrtc.vp8.3-layer}, and {@code none}. 228 * If the encoder does not support temporal layering, the input format will 229 * not have an entry with this key. 230 * The associated value is a string. 231 */ 232 public static final String KEY_TEMPORAL_LAYERING = "ts-schema"; 233 234 /** 235 * @hide 236 */ 237 public static final String KEY_STRIDE = "stride"; 238 /** 239 * @hide 240 */ 241 public static final String KEY_SLICE_HEIGHT = "slice-height"; 242 243 /** 244 * Applies only when configuring a video encoder in "surface-input" mode. 245 * The associated value is a long and gives the time in microseconds 246 * after which the frame previously submitted to the encoder will be 247 * repeated (once) if no new frame became available since. 248 */ 249 public static final String KEY_REPEAT_PREVIOUS_FRAME_AFTER 250 = "repeat-previous-frame-after"; 251 252 /** 253 * If specified when configuring a video decoder rendering to a surface, 254 * causes the decoder to output "blank", i.e. black frames to the surface 255 * when stopped to clear out any previously displayed contents. 256 * The associated value is an integer of value 1. 257 */ 258 public static final String KEY_PUSH_BLANK_BUFFERS_ON_STOP 259 = "push-blank-buffers-on-shutdown"; 260 261 /** 262 * A key describing the duration (in microseconds) of the content. 263 * The associated value is a long. 264 */ 265 public static final String KEY_DURATION = "durationUs"; 266 267 /** 268 * A key mapping to a value of 1 if the content is AAC audio and 269 * audio frames are prefixed with an ADTS header. 270 * The associated value is an integer (0 or 1). 271 * This key is only supported when _decoding_ content, it cannot 272 * be used to configure an encoder to emit ADTS output. 273 */ 274 public static final String KEY_IS_ADTS = "is-adts"; 275 276 /** 277 * A key describing the channel composition of audio content. This mask 278 * is composed of bits drawn from channel mask definitions in {@link android.media.AudioFormat}. 279 * The associated value is an integer. 280 */ 281 public static final String KEY_CHANNEL_MASK = "channel-mask"; 282 283 /** 284 * A key describing the AAC profile to be used (AAC audio formats only). 285 * Constants are declared in {@link android.media.MediaCodecInfo.CodecProfileLevel}. 286 */ 287 public static final String KEY_AAC_PROFILE = "aac-profile"; 288 289 /** 290 * A key describing the AAC SBR mode to be used (AAC audio formats only). 291 * The associated value is an integer and can be set to following values: 292 * <ul> 293 * <li>0 - no SBR should be applied</li> 294 * <li>1 - single rate SBR</li> 295 * <li>2 - double rate SBR</li> 296 * </ul> 297 * Note: If this key is not defined the default SRB mode for the desired AAC profile will 298 * be used. 299 * <p>This key is only used during encoding. 300 */ 301 public static final String KEY_AAC_SBR_MODE = "aac-sbr-mode"; 302 303 /** 304 * A key describing the maximum number of channels that can be output by the AAC decoder. 305 * By default, the decoder will output the same number of channels as present in the encoded 306 * stream, if supported. Set this value to limit the number of output channels, and use 307 * the downmix information in the stream, if available. 308 * <p>Values larger than the number of channels in the content to decode are ignored. 309 * <p>This key is only used during decoding. 310 */ 311 public static final String KEY_AAC_MAX_OUTPUT_CHANNEL_COUNT = "aac-max-output-channel_count"; 312 313 /** 314 * A key describing a gain to be applied so that the output loudness matches the 315 * Target Reference Level. This is typically used to normalize loudness across program items. 316 * The gain is derived as the difference between the Target Reference Level and the 317 * Program Reference Level. The latter can be given in the bitstream and indicates the actual 318 * loudness value of the program item. 319 * <p>The value is given as an integer value between 320 * 0 and 127, and is calculated as -0.25 * Target Reference Level in dBFS. 321 * Therefore, it represents the range of Full Scale (0 dBFS) to -31.75 dBFS. 322 * <p>This key is only used during decoding. 323 */ 324 public static final String KEY_AAC_DRC_TARGET_REFERENCE_LEVEL = "aac-target-ref-level"; 325 326 /** 327 * A key describing the target reference level that was assumed at the encoder for 328 * calculation of attenuation gains for clipping prevention. This information can be provided 329 * if it is known, otherwise a worst-case assumption is used. 330 * <p>The value is given as an integer value between 331 * 0 and 127, and is calculated as -0.25 * Target Reference Level in dBFS. 332 * Therefore, it represents the range of Full Scale (0 dBFS) to -31.75 dBFS. 333 * The default value is the worst-case assumption of 127. 334 * <p>The value is ignored when heavy compression is used (see 335 * {@link #KEY_AAC_DRC_HEAVY_COMPRESSION}). 336 * <p>This key is only used during decoding. 337 */ 338 public static final String KEY_AAC_ENCODED_TARGET_LEVEL = "aac-encoded-target-level"; 339 340 /** 341 * A key describing the boost factor allowing to adapt the dynamics of the output to the 342 * actual listening requirements. This relies on DRC gain sequences that can be transmitted in 343 * the encoded bitstream to be able to reduce the dynamics of the output signal upon request. 344 * This factor enables the user to select how much of the gains are applied. 345 * <p>Positive gains (boost) and negative gains (attenuation, see 346 * {@link #KEY_AAC_DRC_ATTENUATION_FACTOR}) can be controlled separately for a better match 347 * to different use-cases. 348 * <p>Typically, attenuation gains are sent for loud signal segments, and boost gains are sent 349 * for soft signal segments. If the output is listened to in a noisy environment, for example, 350 * the boost factor is used to enable the positive gains, i.e. to amplify soft signal segments 351 * beyond the noise floor. But for listening late at night, the attenuation 352 * factor is used to enable the negative gains, to prevent loud signal from surprising 353 * the listener. In applications which generally need a low dynamic range, both the boost factor 354 * and the attenuation factor are used in order to enable all DRC gains. 355 * <p>In order to prevent clipping, it is also recommended to apply the attenuation factors 356 * in case of a downmix and/or loudness normalization to high target reference levels. 357 * <p>Both the boost and the attenuation factor parameters are given as integer values 358 * between 0 and 127, representing the range of the factor of 0 (i.e. don't apply) 359 * to 1 (i.e. fully apply boost/attenuation factors respectively). 360 * <p>This key is only used during decoding. 361 */ 362 public static final String KEY_AAC_DRC_BOOST_FACTOR = "aac-drc-boost-level"; 363 364 /** 365 * A key describing the attenuation factor allowing to adapt the dynamics of the output to the 366 * actual listening requirements. 367 * See {@link #KEY_AAC_DRC_BOOST_FACTOR} for a description of the role of this attenuation 368 * factor and the value range. 369 * <p>This key is only used during decoding. 370 */ 371 public static final String KEY_AAC_DRC_ATTENUATION_FACTOR = "aac-drc-cut-level"; 372 373 /** 374 * A key describing the selection of the heavy compression profile for DRC. 375 * Two separate DRC gain sequences can be transmitted in one bitstream: MPEG-4 DRC light 376 * compression, and DVB-specific heavy compression. When selecting the application of the heavy 377 * compression, one of the sequences is selected: 378 * <ul> 379 * <li>0 enables light compression,</li> 380 * <li>1 enables heavy compression instead. 381 * </ul> 382 * Note that only light compression offers the features of scaling of DRC gains 383 * (see {@link #KEY_AAC_DRC_BOOST_FACTOR} and {@link #KEY_AAC_DRC_ATTENUATION_FACTOR} for the 384 * boost and attenuation factors, and frequency-selective (multiband) DRC. 385 * Light compression usually contains clipping prevention for stereo downmixing while heavy 386 * compression, if additionally provided in the bitstream, is usually stronger, and contains 387 * clipping prevention for stereo and mono downmixing. 388 * <p>The default is light compression. 389 * <p>This key is only used during decoding. 390 */ 391 public static final String KEY_AAC_DRC_HEAVY_COMPRESSION = "aac-drc-heavy-compression"; 392 393 /** 394 * A key describing the FLAC compression level to be used (FLAC audio format only). 395 * The associated value is an integer ranging from 0 (fastest, least compression) 396 * to 8 (slowest, most compression). 397 */ 398 public static final String KEY_FLAC_COMPRESSION_LEVEL = "flac-compression-level"; 399 400 /** 401 * A key describing the encoding complexity. 402 * The associated value is an integer. These values are device and codec specific, 403 * but lower values generally result in faster and/or less power-hungry encoding. 404 * 405 * @see MediaCodecInfo.EncoderCapabilities#getComplexityRange() 406 */ 407 public static final String KEY_COMPLEXITY = "complexity"; 408 409 /** 410 * A key describing the desired encoding quality. 411 * The associated value is an integer. This key is only supported for encoders 412 * that are configured in constant-quality mode. These values are device and 413 * codec specific, but lower values generally result in more efficient 414 * (smaller-sized) encoding. 415 * 416 * @hide 417 * 418 * @see MediaCodecInfo.EncoderCapabilities#getQualityRange() 419 */ 420 public static final String KEY_QUALITY = "quality"; 421 422 /** 423 * A key describing the desired profile to be used by an encoder. 424 * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}. 425 * This key is only supported for codecs that specify a profile. 426 * 427 * @see MediaCodecInfo.CodecCapabilities#profileLevels 428 */ 429 public static final String KEY_PROFILE = "profile"; 430 431 /** 432 * A key describing the desired bitrate mode to be used by an encoder. 433 * Constants are declared in {@link MediaCodecInfo.CodecCapabilities}. 434 * 435 * @see MediaCodecInfo.EncoderCapabilities#isBitrateModeSupported(int) 436 */ 437 public static final String KEY_BITRATE_MODE = "bitrate-mode"; 438 439 /** 440 * A key describing the audio session ID of the AudioTrack associated 441 * to a tunneled video codec. 442 * The associated value is an integer. 443 * 444 * @see MediaCodecInfo.CodecCapabilities#FEATURE_TunneledPlayback 445 */ 446 public static final String KEY_AUDIO_SESSION_ID = "audio-session-id"; 447 448 /** 449 * A key for boolean AUTOSELECT behavior for the track. Tracks with AUTOSELECT=true 450 * are considered when automatically selecting a track without specific user 451 * choice, based on the current locale. 452 * This is currently only used for subtitle tracks, when the user selected 453 * 'Default' for the captioning locale. 454 * The associated value is an integer, where non-0 means TRUE. This is an optional 455 * field; if not specified, AUTOSELECT defaults to TRUE. 456 */ 457 public static final String KEY_IS_AUTOSELECT = "is-autoselect"; 458 459 /** 460 * A key for boolean DEFAULT behavior for the track. The track with DEFAULT=true is 461 * selected in the absence of a specific user choice. 462 * This is currently only used for subtitle tracks, when the user selected 463 * 'Default' for the captioning locale. 464 * The associated value is an integer, where non-0 means TRUE. This is an optional 465 * field; if not specified, DEFAULT is considered to be FALSE. 466 */ 467 public static final String KEY_IS_DEFAULT = "is-default"; 468 469 470 /** 471 * A key for the FORCED field for subtitle tracks. True if it is a 472 * forced subtitle track. Forced subtitle tracks are essential for the 473 * content and are shown even when the user turns off Captions. They 474 * are used for example to translate foreign/alien dialogs or signs. 475 * The associated value is an integer, where non-0 means TRUE. This is an 476 * optional field; if not specified, FORCED defaults to FALSE. 477 */ 478 public static final String KEY_IS_FORCED_SUBTITLE = "is-forced-subtitle"; 479 480 /** @hide */ 481 public static final String KEY_IS_TIMED_TEXT = "is-timed-text"; 482 483 /* package private */ MediaFormat(Map<String, Object> map) { 484 mMap = map; 485 } 486 487 /** 488 * Creates an empty MediaFormat 489 */ 490 public MediaFormat() { 491 mMap = new HashMap(); 492 } 493 494 /* package private */ Map<String, Object> getMap() { 495 return mMap; 496 } 497 498 /** 499 * Returns true iff a key of the given name exists in the format. 500 */ 501 public final boolean containsKey(String name) { 502 return mMap.containsKey(name); 503 } 504 505 /** 506 * A key prefix used together with a {@link MediaCodecInfo.CodecCapabilities} 507 * feature name describing a required or optional feature for a codec capabilities 508 * query. 509 * The associated value is an integer, where non-0 value means the feature is 510 * requested to be present, while 0 value means the feature is requested to be not 511 * present. 512 * @see MediaCodecList#findDecoderForFormat 513 * @see MediaCodecList#findEncoderForFormat 514 * @see MediaCodecInfo.CodecCapabilities#isFormatSupported 515 * 516 * @hide 517 */ 518 public static final String KEY_FEATURE_ = "feature-"; 519 520 /** 521 * Returns the value of an integer key. 522 */ 523 public final int getInteger(String name) { 524 return ((Integer)mMap.get(name)).intValue(); 525 } 526 527 /** 528 * Returns the value of an integer key, or the default value if the 529 * key is missing or is for another type value. 530 * @hide 531 */ 532 public final int getInteger(String name, int defaultValue) { 533 try { 534 return getInteger(name); 535 } 536 catch (NullPointerException e) { /* no such field */ } 537 catch (ClassCastException e) { /* field of different type */ } 538 return defaultValue; 539 } 540 541 /** 542 * Returns the value of a long key. 543 */ 544 public final long getLong(String name) { 545 return ((Long)mMap.get(name)).longValue(); 546 } 547 548 /** 549 * Returns the value of a float key. 550 */ 551 public final float getFloat(String name) { 552 return ((Float)mMap.get(name)).floatValue(); 553 } 554 555 /** 556 * Returns the value of a string key. 557 */ 558 public final String getString(String name) { 559 return (String)mMap.get(name); 560 } 561 562 /** 563 * Returns the value of a ByteBuffer key. 564 */ 565 public final ByteBuffer getByteBuffer(String name) { 566 return (ByteBuffer)mMap.get(name); 567 } 568 569 /** 570 * Returns whether a feature is to be enabled ({@code true}) or disabled 571 * ({@code false}). 572 * 573 * @param feature the name of a {@link MediaCodecInfo.CodecCapabilities} feature. 574 * 575 * @throws IllegalArgumentException if the feature was neither set to be enabled 576 * nor to be disabled. 577 */ 578 public boolean getFeatureEnabled(String feature) { 579 Integer enabled = (Integer)mMap.get(KEY_FEATURE_ + feature); 580 if (enabled == null) { 581 throw new IllegalArgumentException("feature is not specified"); 582 } 583 return enabled != 0; 584 } 585 586 /** 587 * Sets the value of an integer key. 588 */ 589 public final void setInteger(String name, int value) { 590 mMap.put(name, new Integer(value)); 591 } 592 593 /** 594 * Sets the value of a long key. 595 */ 596 public final void setLong(String name, long value) { 597 mMap.put(name, new Long(value)); 598 } 599 600 /** 601 * Sets the value of a float key. 602 */ 603 public final void setFloat(String name, float value) { 604 mMap.put(name, new Float(value)); 605 } 606 607 /** 608 * Sets the value of a string key. 609 */ 610 public final void setString(String name, String value) { 611 mMap.put(name, value); 612 } 613 614 /** 615 * Sets the value of a ByteBuffer key. 616 */ 617 public final void setByteBuffer(String name, ByteBuffer bytes) { 618 mMap.put(name, bytes); 619 } 620 621 /** 622 * Sets whether a feature is to be enabled ({@code true}) or disabled 623 * ({@code false}). 624 * 625 * If {@code enabled} is {@code true}, the feature is requested to be present. 626 * Otherwise, the feature is requested to be not present. 627 * 628 * @param feature the name of a {@link MediaCodecInfo.CodecCapabilities} feature. 629 * 630 * @see MediaCodecList#findDecoderForFormat 631 * @see MediaCodecList#findEncoderForFormat 632 * @see MediaCodecInfo.CodecCapabilities#isFormatSupported 633 */ 634 public void setFeatureEnabled(String feature, boolean enabled) { 635 setInteger(KEY_FEATURE_ + feature, enabled ? 1 : 0); 636 } 637 638 /** 639 * Creates a minimal audio format. 640 * @param mime The mime type of the content. 641 * @param sampleRate The sampling rate of the content. 642 * @param channelCount The number of audio channels in the content. 643 */ 644 public static final MediaFormat createAudioFormat( 645 String mime, 646 int sampleRate, 647 int channelCount) { 648 MediaFormat format = new MediaFormat(); 649 format.setString(KEY_MIME, mime); 650 format.setInteger(KEY_SAMPLE_RATE, sampleRate); 651 format.setInteger(KEY_CHANNEL_COUNT, channelCount); 652 653 return format; 654 } 655 656 /** 657 * Creates a minimal subtitle format. 658 * @param mime The mime type of the content. 659 * @param language The language of the content, using either ISO 639-1 or 639-2/T 660 * codes. Specify null or "und" if language information is only included 661 * in the content. (This will also work if there are multiple language 662 * tracks in the content.) 663 */ 664 public static final MediaFormat createSubtitleFormat( 665 String mime, 666 String language) { 667 MediaFormat format = new MediaFormat(); 668 format.setString(KEY_MIME, mime); 669 format.setString(KEY_LANGUAGE, language); 670 671 return format; 672 } 673 674 /** 675 * Creates a minimal video format. 676 * @param mime The mime type of the content. 677 * @param width The width of the content (in pixels) 678 * @param height The height of the content (in pixels) 679 */ 680 public static final MediaFormat createVideoFormat( 681 String mime, 682 int width, 683 int height) { 684 MediaFormat format = new MediaFormat(); 685 format.setString(KEY_MIME, mime); 686 format.setInteger(KEY_WIDTH, width); 687 format.setInteger(KEY_HEIGHT, height); 688 689 return format; 690 } 691 692 @Override 693 public String toString() { 694 return mMap.toString(); 695 } 696} 697