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 17 package android.media; 18 19 import android.annotation.IntDef; 20 21 import java.lang.annotation.Retention; 22 import java.lang.annotation.RetentionPolicy; 23 import java.nio.ByteBuffer; 24 import java.util.HashMap; 25 import java.util.Map; 26 27 /** 28 * Encapsulates the information describing the format of media data, 29 * be it audio or video. 30 * 31 * The format of the media data is specified as string/value pairs. 32 * 33 * Keys common to all audio/video formats, <b>all keys not marked optional are mandatory</b>: 34 * 35 * <table> 36 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 37 * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr> 38 * <tr><td>{@link #KEY_MAX_INPUT_SIZE}</td><td>Integer</td><td>optional, maximum size of a buffer of input data</td></tr> 39 * <tr><td>{@link #KEY_BIT_RATE}</td><td>Integer</td><td><b>encoder-only</b>, desired bitrate in bits/second</td></tr> 40 * </table> 41 * 42 * Video formats have the following keys: 43 * <table> 44 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 45 * <tr><td>{@link #KEY_WIDTH}</td><td>Integer</td><td></td></tr> 46 * <tr><td>{@link #KEY_HEIGHT}</td><td>Integer</td><td></td></tr> 47 * <tr><td>{@link #KEY_COLOR_FORMAT}</td><td>Integer</td><td>set by the user 48 * for encoders, readable in the output format of decoders</b></td></tr> 49 * <tr><td>{@link #KEY_FRAME_RATE}</td><td>Integer or Float</td><td>required for <b>encoders</b>, 50 * optional for <b>decoders</b></td></tr> 51 * <tr><td>{@link #KEY_CAPTURE_RATE}</td><td>Integer</td><td></td></tr> 52 * <tr><td>{@link #KEY_I_FRAME_INTERVAL}</td><td>Integer (or Float)</td><td><b>encoder-only</b>, 53 * time-interval between key frames. 54 * Float support added in {@link android.os.Build.VERSION_CODES#N_MR1}</td></tr> 55 * <tr><td>{@link #KEY_INTRA_REFRESH_PERIOD}</td><td>Integer</td><td><b>encoder-only</b>, optional</td></tr> 56 * <tr><td>{@link #KEY_LATENCY}</td><td>Integer</td><td><b>encoder-only</b>, optional</td></tr> 57 * <tr><td>{@link #KEY_MAX_WIDTH}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution width</td></tr> 58 * <tr><td>{@link #KEY_MAX_HEIGHT}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution height</td></tr> 59 * <tr><td>{@link #KEY_REPEAT_PREVIOUS_FRAME_AFTER}</td><td>Long</td><td><b>encoder in surface-mode 60 * only</b>, optional</td></tr> 61 * <tr><td>{@link #KEY_PUSH_BLANK_BUFFERS_ON_STOP}</td><td>Integer(1)</td><td><b>decoder rendering 62 * to a surface only</b>, optional</td></tr> 63 * <tr><td>{@link #KEY_TEMPORAL_LAYERING}</td><td>String</td><td><b>encoder only</b>, optional, 64 * temporal-layering schema</td></tr> 65 * </table> 66 * Specify both {@link #KEY_MAX_WIDTH} and {@link #KEY_MAX_HEIGHT} to enable 67 * adaptive playback (seamless resolution change) for a video decoder that 68 * supports it ({@link MediaCodecInfo.CodecCapabilities#FEATURE_AdaptivePlayback}). 69 * The values are used as hints for the codec: they are the maximum expected 70 * resolution to prepare for. Depending on codec support, preparing for larger 71 * maximum resolution may require more memory even if that resolution is never 72 * reached. These fields have no effect for codecs that do not support adaptive 73 * playback.<br /><br /> 74 * 75 * Audio formats have the following keys: 76 * <table> 77 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 78 * <tr><td>{@link #KEY_CHANNEL_COUNT}</td><td>Integer</td><td></td></tr> 79 * <tr><td>{@link #KEY_SAMPLE_RATE}</td><td>Integer</td><td></td></tr> 80 * <tr><td>{@link #KEY_PCM_ENCODING}</td><td>Integer</td><td>optional</td></tr> 81 * <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> 82 * <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> 83 * <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> 84 * <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> 85 * <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> 86 * <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> 87 * <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> 88 * <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> 89 * <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> 90 * <tr><td>{@link #KEY_CHANNEL_MASK}</td><td>Integer</td><td>optional, a mask of audio channel assignments</td></tr> 91 * <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> 92 * </table> 93 * 94 * Subtitle formats have the following keys: 95 * <table> 96 * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr> 97 * <tr><td>{@link #KEY_LANGUAGE}</td><td>String</td><td>The language of the content.</td></tr> 98 * </table> 99 */ 100 public final class MediaFormat { 101 public static final String MIMETYPE_VIDEO_VP8 = "video/x-vnd.on2.vp8"; 102 public static final String MIMETYPE_VIDEO_VP9 = "video/x-vnd.on2.vp9"; 103 public static final String MIMETYPE_VIDEO_AVC = "video/avc"; 104 public static final String MIMETYPE_VIDEO_HEVC = "video/hevc"; 105 public static final String MIMETYPE_VIDEO_MPEG4 = "video/mp4v-es"; 106 public static final String MIMETYPE_VIDEO_H263 = "video/3gpp"; 107 public static final String MIMETYPE_VIDEO_MPEG2 = "video/mpeg2"; 108 public static final String MIMETYPE_VIDEO_RAW = "video/raw"; 109 public static final String MIMETYPE_VIDEO_DOLBY_VISION = "video/dolby-vision"; 110 public static final String MIMETYPE_VIDEO_SCRAMBLED = "video/scrambled"; 111 112 public static final String MIMETYPE_AUDIO_AMR_NB = "audio/3gpp"; 113 public static final String MIMETYPE_AUDIO_AMR_WB = "audio/amr-wb"; 114 public static final String MIMETYPE_AUDIO_MPEG = "audio/mpeg"; 115 public static final String MIMETYPE_AUDIO_AAC = "audio/mp4a-latm"; 116 public static final String MIMETYPE_AUDIO_QCELP = "audio/qcelp"; 117 public static final String MIMETYPE_AUDIO_VORBIS = "audio/vorbis"; 118 public static final String MIMETYPE_AUDIO_OPUS = "audio/opus"; 119 public static final String MIMETYPE_AUDIO_G711_ALAW = "audio/g711-alaw"; 120 public static final String MIMETYPE_AUDIO_G711_MLAW = "audio/g711-mlaw"; 121 public static final String MIMETYPE_AUDIO_RAW = "audio/raw"; 122 public static final String MIMETYPE_AUDIO_FLAC = "audio/flac"; 123 public static final String MIMETYPE_AUDIO_MSGSM = "audio/gsm"; 124 public static final String MIMETYPE_AUDIO_AC3 = "audio/ac3"; 125 public static final String MIMETYPE_AUDIO_EAC3 = "audio/eac3"; 126 public static final String MIMETYPE_AUDIO_SCRAMBLED = "audio/scrambled"; 127 128 /** 129 * MIME type for WebVTT subtitle data. 130 */ 131 public static final String MIMETYPE_TEXT_VTT = "text/vtt"; 132 133 /** 134 * MIME type for CEA-608 closed caption data. 135 */ 136 public static final String MIMETYPE_TEXT_CEA_608 = "text/cea-608"; 137 138 private Map<String, Object> mMap; 139 140 /** 141 * A key describing the mime type of the MediaFormat. 142 * The associated value is a string. 143 */ 144 public static final String KEY_MIME = "mime"; 145 146 /** 147 * A key describing the language of the content, using either ISO 639-1 148 * or 639-2/T codes. The associated value is a string. 149 */ 150 public static final String KEY_LANGUAGE = "language"; 151 152 /** 153 * A key describing the sample rate of an audio format. 154 * The associated value is an integer 155 */ 156 public static final String KEY_SAMPLE_RATE = "sample-rate"; 157 158 /** 159 * A key describing the number of channels in an audio format. 160 * The associated value is an integer 161 */ 162 public static final String KEY_CHANNEL_COUNT = "channel-count"; 163 164 /** 165 * A key describing the width of the content in a video format. 166 * The associated value is an integer 167 */ 168 public static final String KEY_WIDTH = "width"; 169 170 /** 171 * A key describing the height of the content in a video format. 172 * The associated value is an integer 173 */ 174 public static final String KEY_HEIGHT = "height"; 175 176 /** 177 * A key describing the maximum expected width of the content in a video 178 * decoder format, in case there are resolution changes in the video content. 179 * The associated value is an integer 180 */ 181 public static final String KEY_MAX_WIDTH = "max-width"; 182 183 /** 184 * A key describing the maximum expected height of the content in a video 185 * decoder format, in case there are resolution changes in the video content. 186 * The associated value is an integer 187 */ 188 public static final String KEY_MAX_HEIGHT = "max-height"; 189 190 /** A key describing the maximum size in bytes of a buffer of data 191 * described by this MediaFormat. 192 * The associated value is an integer 193 */ 194 public static final String KEY_MAX_INPUT_SIZE = "max-input-size"; 195 196 /** 197 * A key describing the average bitrate in bits/sec. 198 * The associated value is an integer 199 */ 200 public static final String KEY_BIT_RATE = "bitrate"; 201 202 /** 203 * A key describing the max bitrate in bits/sec. 204 * This is usually over a one-second sliding window (e.g. over any window of one second). 205 * The associated value is an integer 206 * @hide 207 */ 208 public static final String KEY_MAX_BIT_RATE = "max-bitrate"; 209 210 /** 211 * A key describing the color format of the content in a video format. 212 * Constants are declared in {@link android.media.MediaCodecInfo.CodecCapabilities}. 213 */ 214 public static final String KEY_COLOR_FORMAT = "color-format"; 215 216 /** 217 * A key describing the frame rate of a video format in frames/sec. 218 * The associated value is normally an integer when the value is used by the platform, 219 * but video codecs also accept float configuration values. 220 * Specifically, {@link MediaExtractor#getTrackFormat MediaExtractor} provides an integer 221 * value corresponding to the frame rate information of the track if specified and non-zero. 222 * Otherwise, this key is not present. {@link MediaCodec#configure MediaCodec} accepts both 223 * float and integer values. This represents the desired operating frame rate if the 224 * {@link #KEY_OPERATING_RATE} is not present and {@link #KEY_PRIORITY} is {@code 0} 225 * (realtime). For video encoders this value corresponds to the intended frame rate, 226 * although encoders are expected 227 * to support variable frame rate based on {@link MediaCodec.BufferInfo#presentationTimeUs 228 * buffer timestamp}. This key is not used in the {@code MediaCodec} 229 * {@link MediaCodec#getInputFormat input}/{@link MediaCodec#getOutputFormat output} formats, 230 * nor by {@link MediaMuxer#addTrack MediaMuxer}. 231 */ 232 public static final String KEY_FRAME_RATE = "frame-rate"; 233 234 /** 235 * A key describing the raw audio sample encoding/format. 236 * 237 * <p>The associated value is an integer, using one of the 238 * {@link AudioFormat}.ENCODING_PCM_ values.</p> 239 * 240 * <p>This is an optional key for audio decoders and encoders specifying the 241 * desired raw audio sample format during {@link MediaCodec#configure 242 * MediaCodec.configure(…)} call. Use {@link MediaCodec#getInputFormat 243 * MediaCodec.getInput}/{@link MediaCodec#getOutputFormat OutputFormat(…)} 244 * to confirm the actual format. For the PCM decoder this key specifies both 245 * input and output sample encodings.</p> 246 * 247 * <p>This key is also used by {@link MediaExtractor} to specify the sample 248 * format of audio data, if it is specified.</p> 249 * 250 * <p>If this key is missing, the raw audio sample format is signed 16-bit short.</p> 251 */ 252 public static final String KEY_PCM_ENCODING = "pcm-encoding"; 253 254 /** 255 * A key describing the capture rate of a video format in frames/sec. 256 * <p> 257 * When capture rate is different than the frame rate, it means that the 258 * video is acquired at a different rate than the playback, which produces 259 * slow motion or timelapse effect during playback. Application can use the 260 * value of this key to tell the relative speed ratio between capture and 261 * playback rates when the video was recorded. 262 * </p> 263 * <p> 264 * The associated value is an integer or a float. 265 * </p> 266 */ 267 public static final String KEY_CAPTURE_RATE = "capture-rate"; 268 269 /** 270 * A key describing the frequency of key frames expressed in seconds between key frames. 271 * <p> 272 * This key is used by video encoders. 273 * A negative value means no key frames are requested after the first frame. 274 * A zero value means a stream containing all key frames is requested. 275 * <p class=note> 276 * Most video encoders will convert this value of the number of non-key-frames between 277 * key-frames, using the {@linkplain #KEY_FRAME_RATE frame rate} information; therefore, 278 * if the actual frame rate differs (e.g. input frames are dropped or the frame rate 279 * changes), the <strong>time interval</strong> between key frames will not be the 280 * configured value. 281 * <p> 282 * The associated value is an integer (or float since 283 * {@link android.os.Build.VERSION_CODES#N_MR1}). 284 */ 285 public static final String KEY_I_FRAME_INTERVAL = "i-frame-interval"; 286 287 /** 288 * An optional key describing the period of intra refresh in frames. This is an 289 * optional parameter that applies only to video encoders. If encoder supports it 290 * ({@link MediaCodecInfo.CodecCapabilities#FEATURE_IntraRefresh}), the whole 291 * frame is completely refreshed after the specified period. Also for each frame, 292 * a fix subset of macroblocks must be intra coded which leads to more constant bitrate 293 * than inserting a key frame. This key is recommended for video streaming applications 294 * as it provides low-delay and good error-resilience. This key is ignored if the 295 * video encoder does not support the intra refresh feature. Use the output format to 296 * verify that this feature was enabled. 297 * The associated value is an integer. 298 */ 299 public static final String KEY_INTRA_REFRESH_PERIOD = "intra-refresh-period"; 300 301 /** 302 * A key describing the temporal layering schema. This is an optional parameter 303 * that applies only to video encoders. Use {@link MediaCodec#getOutputFormat} 304 * after {@link MediaCodec#configure configure} to query if the encoder supports 305 * the desired schema. Supported values are {@code webrtc.vp8.N-layer}, 306 * {@code android.generic.N}, {@code android.generic.N+M} and {@code none}, where 307 * {@code N} denotes the total number of non-bidirectional layers (which must be at least 1) 308 * and {@code M} denotes the total number of bidirectional layers (which must be non-negative). 309 * <p class=note>{@code android.generic.*} schemas have been added in {@link 310 * android.os.Build.VERSION_CODES#N_MR1}. 311 * <p> 312 * The encoder may support fewer temporal layers, in which case the output format 313 * will contain the configured schema. If the encoder does not support temporal 314 * layering, the output format will not have an entry with this key. 315 * The associated value is a string. 316 */ 317 public static final String KEY_TEMPORAL_LAYERING = "ts-schema"; 318 319 /** 320 * A key describing the stride of the video bytebuffer layout. 321 * Stride (or row increment) is the difference between the index of a pixel 322 * and that of the pixel directly underneath. For YUV 420 formats, the 323 * stride corresponds to the Y plane; the stride of the U and V planes can 324 * be calculated based on the color format, though it is generally undefined 325 * and depends on the device and release. 326 * The associated value is an integer, representing number of bytes. 327 */ 328 public static final String KEY_STRIDE = "stride"; 329 330 /** 331 * A key describing the plane height of a multi-planar (YUV) video bytebuffer layout. 332 * Slice height (or plane height/vertical stride) is the number of rows that must be skipped 333 * to get from the top of the Y plane to the top of the U plane in the bytebuffer. In essence 334 * the offset of the U plane is sliceHeight * stride. The height of the U/V planes 335 * can be calculated based on the color format, though it is generally undefined 336 * and depends on the device and release. 337 * The associated value is an integer, representing number of rows. 338 */ 339 public static final String KEY_SLICE_HEIGHT = "slice-height"; 340 341 /** 342 * Applies only when configuring a video encoder in "surface-input" mode. 343 * The associated value is a long and gives the time in microseconds 344 * after which the frame previously submitted to the encoder will be 345 * repeated (once) if no new frame became available since. 346 */ 347 public static final String KEY_REPEAT_PREVIOUS_FRAME_AFTER 348 = "repeat-previous-frame-after"; 349 350 /** 351 * If specified when configuring a video decoder rendering to a surface, 352 * causes the decoder to output "blank", i.e. black frames to the surface 353 * when stopped to clear out any previously displayed contents. 354 * The associated value is an integer of value 1. 355 */ 356 public static final String KEY_PUSH_BLANK_BUFFERS_ON_STOP 357 = "push-blank-buffers-on-shutdown"; 358 359 /** 360 * A key describing the duration (in microseconds) of the content. 361 * The associated value is a long. 362 */ 363 public static final String KEY_DURATION = "durationUs"; 364 365 /** 366 * A key mapping to a value of 1 if the content is AAC audio and 367 * audio frames are prefixed with an ADTS header. 368 * The associated value is an integer (0 or 1). 369 * This key is only supported when _decoding_ content, it cannot 370 * be used to configure an encoder to emit ADTS output. 371 */ 372 public static final String KEY_IS_ADTS = "is-adts"; 373 374 /** 375 * A key describing the channel composition of audio content. This mask 376 * is composed of bits drawn from channel mask definitions in {@link android.media.AudioFormat}. 377 * The associated value is an integer. 378 */ 379 public static final String KEY_CHANNEL_MASK = "channel-mask"; 380 381 /** 382 * A key describing the AAC profile to be used (AAC audio formats only). 383 * Constants are declared in {@link android.media.MediaCodecInfo.CodecProfileLevel}. 384 */ 385 public static final String KEY_AAC_PROFILE = "aac-profile"; 386 387 /** 388 * A key describing the AAC SBR mode to be used (AAC audio formats only). 389 * The associated value is an integer and can be set to following values: 390 * <ul> 391 * <li>0 - no SBR should be applied</li> 392 * <li>1 - single rate SBR</li> 393 * <li>2 - double rate SBR</li> 394 * </ul> 395 * Note: If this key is not defined the default SRB mode for the desired AAC profile will 396 * be used. 397 * <p>This key is only used during encoding. 398 */ 399 public static final String KEY_AAC_SBR_MODE = "aac-sbr-mode"; 400 401 /** 402 * A key describing the maximum number of channels that can be output by the AAC decoder. 403 * By default, the decoder will output the same number of channels as present in the encoded 404 * stream, if supported. Set this value to limit the number of output channels, and use 405 * the downmix information in the stream, if available. 406 * <p>Values larger than the number of channels in the content to decode are ignored. 407 * <p>This key is only used during decoding. 408 */ 409 public static final String KEY_AAC_MAX_OUTPUT_CHANNEL_COUNT = "aac-max-output-channel_count"; 410 411 /** 412 * A key describing a gain to be applied so that the output loudness matches the 413 * Target Reference Level. This is typically used to normalize loudness across program items. 414 * The gain is derived as the difference between the Target Reference Level and the 415 * Program Reference Level. The latter can be given in the bitstream and indicates the actual 416 * loudness value of the program item. 417 * <p>The value is given as an integer value between 418 * 0 and 127, and is calculated as -0.25 * Target Reference Level in dBFS. 419 * Therefore, it represents the range of Full Scale (0 dBFS) to -31.75 dBFS. 420 * <p>This key is only used during decoding. 421 */ 422 public static final String KEY_AAC_DRC_TARGET_REFERENCE_LEVEL = "aac-target-ref-level"; 423 424 /** 425 * A key describing the target reference level that was assumed at the encoder for 426 * calculation of attenuation gains for clipping prevention. This information can be provided 427 * if it is known, otherwise a worst-case assumption is used. 428 * <p>The value is given as an integer value between 429 * 0 and 127, and is calculated as -0.25 * Target Reference Level in dBFS. 430 * Therefore, it represents the range of Full Scale (0 dBFS) to -31.75 dBFS. 431 * The default value is the worst-case assumption of 127. 432 * <p>The value is ignored when heavy compression is used (see 433 * {@link #KEY_AAC_DRC_HEAVY_COMPRESSION}). 434 * <p>This key is only used during decoding. 435 */ 436 public static final String KEY_AAC_ENCODED_TARGET_LEVEL = "aac-encoded-target-level"; 437 438 /** 439 * A key describing the boost factor allowing to adapt the dynamics of the output to the 440 * actual listening requirements. This relies on DRC gain sequences that can be transmitted in 441 * the encoded bitstream to be able to reduce the dynamics of the output signal upon request. 442 * This factor enables the user to select how much of the gains are applied. 443 * <p>Positive gains (boost) and negative gains (attenuation, see 444 * {@link #KEY_AAC_DRC_ATTENUATION_FACTOR}) can be controlled separately for a better match 445 * to different use-cases. 446 * <p>Typically, attenuation gains are sent for loud signal segments, and boost gains are sent 447 * for soft signal segments. If the output is listened to in a noisy environment, for example, 448 * the boost factor is used to enable the positive gains, i.e. to amplify soft signal segments 449 * beyond the noise floor. But for listening late at night, the attenuation 450 * factor is used to enable the negative gains, to prevent loud signal from surprising 451 * the listener. In applications which generally need a low dynamic range, both the boost factor 452 * and the attenuation factor are used in order to enable all DRC gains. 453 * <p>In order to prevent clipping, it is also recommended to apply the attenuation factors 454 * in case of a downmix and/or loudness normalization to high target reference levels. 455 * <p>Both the boost and the attenuation factor parameters are given as integer values 456 * between 0 and 127, representing the range of the factor of 0 (i.e. don't apply) 457 * to 1 (i.e. fully apply boost/attenuation factors respectively). 458 * <p>This key is only used during decoding. 459 */ 460 public static final String KEY_AAC_DRC_BOOST_FACTOR = "aac-drc-boost-level"; 461 462 /** 463 * A key describing the attenuation factor allowing to adapt the dynamics of the output to the 464 * actual listening requirements. 465 * See {@link #KEY_AAC_DRC_BOOST_FACTOR} for a description of the role of this attenuation 466 * factor and the value range. 467 * <p>This key is only used during decoding. 468 */ 469 public static final String KEY_AAC_DRC_ATTENUATION_FACTOR = "aac-drc-cut-level"; 470 471 /** 472 * A key describing the selection of the heavy compression profile for DRC. 473 * Two separate DRC gain sequences can be transmitted in one bitstream: MPEG-4 DRC light 474 * compression, and DVB-specific heavy compression. When selecting the application of the heavy 475 * compression, one of the sequences is selected: 476 * <ul> 477 * <li>0 enables light compression,</li> 478 * <li>1 enables heavy compression instead. 479 * </ul> 480 * Note that only light compression offers the features of scaling of DRC gains 481 * (see {@link #KEY_AAC_DRC_BOOST_FACTOR} and {@link #KEY_AAC_DRC_ATTENUATION_FACTOR} for the 482 * boost and attenuation factors, and frequency-selective (multiband) DRC. 483 * Light compression usually contains clipping prevention for stereo downmixing while heavy 484 * compression, if additionally provided in the bitstream, is usually stronger, and contains 485 * clipping prevention for stereo and mono downmixing. 486 * <p>The default is light compression. 487 * <p>This key is only used during decoding. 488 */ 489 public static final String KEY_AAC_DRC_HEAVY_COMPRESSION = "aac-drc-heavy-compression"; 490 491 /** 492 * A key describing the FLAC compression level to be used (FLAC audio format only). 493 * The associated value is an integer ranging from 0 (fastest, least compression) 494 * to 8 (slowest, most compression). 495 */ 496 public static final String KEY_FLAC_COMPRESSION_LEVEL = "flac-compression-level"; 497 498 /** 499 * A key describing the encoding complexity. 500 * The associated value is an integer. These values are device and codec specific, 501 * but lower values generally result in faster and/or less power-hungry encoding. 502 * 503 * @see MediaCodecInfo.EncoderCapabilities#getComplexityRange() 504 */ 505 public static final String KEY_COMPLEXITY = "complexity"; 506 507 /** 508 * A key describing the desired encoding quality. 509 * The associated value is an integer. This key is only supported for encoders 510 * that are configured in constant-quality mode. These values are device and 511 * codec specific, but lower values generally result in more efficient 512 * (smaller-sized) encoding. 513 * 514 * @hide 515 * 516 * @see MediaCodecInfo.EncoderCapabilities#getQualityRange() 517 */ 518 public static final String KEY_QUALITY = "quality"; 519 520 /** 521 * A key describing the desired codec priority. 522 * <p> 523 * The associated value is an integer. Higher value means lower priority. 524 * <p> 525 * Currently, only two levels are supported:<br> 526 * 0: realtime priority - meaning that the codec shall support the given 527 * performance configuration (e.g. framerate) at realtime. This should 528 * only be used by media playback, capture, and possibly by realtime 529 * communication scenarios if best effort performance is not suitable.<br> 530 * 1: non-realtime priority (best effort). 531 * <p> 532 * This is a hint used at codec configuration and resource planning - to understand 533 * the realtime requirements of the application; however, due to the nature of 534 * media components, performance is not guaranteed. 535 * 536 */ 537 public static final String KEY_PRIORITY = "priority"; 538 539 /** 540 * A key describing the desired operating frame rate for video or sample rate for audio 541 * that the codec will need to operate at. 542 * <p> 543 * The associated value is an integer or a float representing frames-per-second or 544 * samples-per-second 545 * <p> 546 * This is used for cases like high-speed/slow-motion video capture, where the video encoder 547 * format contains the target playback rate (e.g. 30fps), but the component must be able to 548 * handle the high operating capture rate (e.g. 240fps). 549 * <p> 550 * This rate will be used by codec for resource planning and setting the operating points. 551 * 552 */ 553 public static final String KEY_OPERATING_RATE = "operating-rate"; 554 555 /** 556 * A key describing the desired profile to be used by an encoder. 557 * The associated value is an integer. 558 * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}. 559 * This key is used as a hint, and is only supported for codecs 560 * that specify a profile. Note: Codecs are free to use all the available 561 * coding tools at the specified profile. 562 * 563 * @see MediaCodecInfo.CodecCapabilities#profileLevels 564 */ 565 public static final String KEY_PROFILE = "profile"; 566 567 /** 568 * A key describing the desired profile to be used by an encoder. 569 * The associated value is an integer. 570 * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}. 571 * This key is used as a further hint when specifying a desired profile, 572 * and is only supported for codecs that specify a level. 573 * <p> 574 * This key is ignored if the {@link #KEY_PROFILE profile} is not specified. 575 * 576 * @see MediaCodecInfo.CodecCapabilities#profileLevels 577 */ 578 public static final String KEY_LEVEL = "level"; 579 580 /** 581 * An optional key describing the desired encoder latency in frames. This is an optional 582 * parameter that applies only to video encoders. If encoder supports it, it should ouput 583 * at least one output frame after being queued the specified number of frames. This key 584 * is ignored if the video encoder does not support the latency feature. Use the output 585 * format to verify that this feature was enabled and the actual value used by the encoder. 586 * <p> 587 * If the key is not specified, the default latency will be implenmentation specific. 588 * The associated value is an integer. 589 */ 590 public static final String KEY_LATENCY = "latency"; 591 592 /** 593 * A key describing the desired clockwise rotation on an output surface. 594 * This key is only used when the codec is configured using an output surface. 595 * The associated value is an integer, representing degrees. Supported values 596 * are 0, 90, 180 or 270. This is an optional field; if not specified, rotation 597 * defaults to 0. 598 * 599 * @see MediaCodecInfo.CodecCapabilities#profileLevels 600 */ 601 public static final String KEY_ROTATION = "rotation-degrees"; 602 603 /** 604 * A key describing the desired bitrate mode to be used by an encoder. 605 * Constants are declared in {@link MediaCodecInfo.CodecCapabilities}. 606 * 607 * @see MediaCodecInfo.EncoderCapabilities#isBitrateModeSupported(int) 608 */ 609 public static final String KEY_BITRATE_MODE = "bitrate-mode"; 610 611 /** 612 * A key describing the audio session ID of the AudioTrack associated 613 * to a tunneled video codec. 614 * The associated value is an integer. 615 * 616 * @see MediaCodecInfo.CodecCapabilities#FEATURE_TunneledPlayback 617 */ 618 public static final String KEY_AUDIO_SESSION_ID = "audio-session-id"; 619 620 /** 621 * A key for boolean AUTOSELECT behavior for the track. Tracks with AUTOSELECT=true 622 * are considered when automatically selecting a track without specific user 623 * choice, based on the current locale. 624 * This is currently only used for subtitle tracks, when the user selected 625 * 'Default' for the captioning locale. 626 * The associated value is an integer, where non-0 means TRUE. This is an optional 627 * field; if not specified, AUTOSELECT defaults to TRUE. 628 */ 629 public static final String KEY_IS_AUTOSELECT = "is-autoselect"; 630 631 /** 632 * A key for boolean DEFAULT behavior for the track. The track with DEFAULT=true is 633 * selected in the absence of a specific user choice. 634 * This is currently only used for subtitle tracks, when the user selected 635 * 'Default' for the captioning locale. 636 * The associated value is an integer, where non-0 means TRUE. This is an optional 637 * field; if not specified, DEFAULT is considered to be FALSE. 638 */ 639 public static final String KEY_IS_DEFAULT = "is-default"; 640 641 642 /** 643 * A key for the FORCED field for subtitle tracks. True if it is a 644 * forced subtitle track. Forced subtitle tracks are essential for the 645 * content and are shown even when the user turns off Captions. They 646 * are used for example to translate foreign/alien dialogs or signs. 647 * The associated value is an integer, where non-0 means TRUE. This is an 648 * optional field; if not specified, FORCED defaults to FALSE. 649 */ 650 public static final String KEY_IS_FORCED_SUBTITLE = "is-forced-subtitle"; 651 652 /** @hide */ 653 public static final String KEY_IS_TIMED_TEXT = "is-timed-text"; 654 655 // The following color aspect values must be in sync with the ones in HardwareAPI.h. 656 /** 657 * An optional key describing the color primaries, white point and 658 * luminance factors for video content. 659 * 660 * The associated value is an integer: 0 if unspecified, or one of the 661 * COLOR_STANDARD_ values. 662 */ 663 public static final String KEY_COLOR_STANDARD = "color-standard"; 664 665 /** BT.709 color chromacity coordinates with KR = 0.2126, KB = 0.0722. */ 666 public static final int COLOR_STANDARD_BT709 = 1; 667 668 /** BT.601 625 color chromacity coordinates with KR = 0.299, KB = 0.114. */ 669 public static final int COLOR_STANDARD_BT601_PAL = 2; 670 671 /** BT.601 525 color chromacity coordinates with KR = 0.299, KB = 0.114. */ 672 public static final int COLOR_STANDARD_BT601_NTSC = 4; 673 674 /** BT.2020 color chromacity coordinates with KR = 0.2627, KB = 0.0593. */ 675 public static final int COLOR_STANDARD_BT2020 = 6; 676 677 /** @hide */ 678 @IntDef({ 679 COLOR_STANDARD_BT709, 680 COLOR_STANDARD_BT601_PAL, 681 COLOR_STANDARD_BT601_NTSC, 682 COLOR_STANDARD_BT2020, 683 }) 684 @Retention(RetentionPolicy.SOURCE) 685 public @interface ColorStandard {} 686 687 /** 688 * An optional key describing the opto-electronic transfer function used 689 * for the video content. 690 * 691 * The associated value is an integer: 0 if unspecified, or one of the 692 * COLOR_TRANSFER_ values. 693 */ 694 public static final String KEY_COLOR_TRANSFER = "color-transfer"; 695 696 /** Linear transfer characteristic curve. */ 697 public static final int COLOR_TRANSFER_LINEAR = 1; 698 699 /** SMPTE 170M transfer characteristic curve used by BT.601/BT.709/BT.2020. This is the curve 700 * used by most non-HDR video content. */ 701 public static final int COLOR_TRANSFER_SDR_VIDEO = 3; 702 703 /** SMPTE ST 2084 transfer function. This is used by some HDR video content. */ 704 public static final int COLOR_TRANSFER_ST2084 = 6; 705 706 /** ARIB STD-B67 hybrid-log-gamma transfer function. This is used by some HDR video content. */ 707 public static final int COLOR_TRANSFER_HLG = 7; 708 709 /** @hide */ 710 @IntDef({ 711 COLOR_TRANSFER_LINEAR, 712 COLOR_TRANSFER_SDR_VIDEO, 713 COLOR_TRANSFER_ST2084, 714 COLOR_TRANSFER_HLG, 715 }) 716 @Retention(RetentionPolicy.SOURCE) 717 public @interface ColorTransfer {} 718 719 /** 720 * An optional key describing the range of the component values of the video content. 721 * 722 * The associated value is an integer: 0 if unspecified, or one of the 723 * COLOR_RANGE_ values. 724 */ 725 public static final String KEY_COLOR_RANGE = "color-range"; 726 727 /** Limited range. Y component values range from 16 to 235 for 8-bit content. 728 * Cr, Cy values range from 16 to 240 for 8-bit content. 729 * This is the default for video content. */ 730 public static final int COLOR_RANGE_LIMITED = 2; 731 732 /** Full range. Y, Cr and Cb component values range from 0 to 255 for 8-bit content. */ 733 public static final int COLOR_RANGE_FULL = 1; 734 735 /** @hide */ 736 @IntDef({ 737 COLOR_RANGE_LIMITED, 738 COLOR_RANGE_FULL, 739 }) 740 @Retention(RetentionPolicy.SOURCE) 741 public @interface ColorRange {} 742 743 /** 744 * An optional key describing the static metadata of HDR (high-dynamic-range) video content. 745 * 746 * The associated value is a ByteBuffer. This buffer contains the raw contents of the 747 * Static Metadata Descriptor (including the descriptor ID) of an HDMI Dynamic Range and 748 * Mastering InfoFrame as defined by CTA-861.3. This key must be provided to video decoders 749 * for HDR video content unless this information is contained in the bitstream and the video 750 * decoder supports an HDR-capable profile. This key must be provided to video encoders for 751 * HDR video content. 752 */ 753 public static final String KEY_HDR_STATIC_INFO = "hdr-static-info"; 754 755 /** 756 * A key describing a unique ID for the content of a media track. 757 * 758 * <p>This key is used by {@link MediaExtractor}. Some extractors provide multiple encodings 759 * of the same track (e.g. float audio tracks for FLAC and WAV may be expressed as two 760 * tracks via MediaExtractor: a normal PCM track for backward compatibility, and a float PCM 761 * track for added fidelity. Similarly, Dolby Vision extractor may provide a baseline SDR 762 * version of a DV track.) This key can be used to identify which MediaExtractor tracks refer 763 * to the same underlying content. 764 * </p> 765 * 766 * The associated value is an integer. 767 */ 768 public static final String KEY_TRACK_ID = "track-id"; 769 770 /** 771 * A key describing the system id of the conditional access system used to scramble 772 * a media track. 773 * <p> 774 * This key is set by {@link MediaExtractor} if the track is scrambled with a conditional 775 * access system. 776 * <p> 777 * The associated value is an integer. 778 * @hide 779 */ 780 public static final String KEY_CA_SYSTEM_ID = "ca-system-id"; 781 782 /** 783 * A key describing the {@link MediaCas.Session} object associated with a media track. 784 * <p> 785 * This key is set by {@link MediaExtractor} if the track is scrambled with a conditional 786 * access system. 787 * <p> 788 * The associated value is a ByteBuffer. 789 * @hide 790 */ 791 public static final String KEY_CA_SESSION_ID = "ca-session-id"; 792 MediaFormat(Map<String, Object> map)793 /* package private */ MediaFormat(Map<String, Object> map) { 794 mMap = map; 795 } 796 797 /** 798 * Creates an empty MediaFormat 799 */ MediaFormat()800 public MediaFormat() { 801 mMap = new HashMap(); 802 } 803 getMap()804 /* package private */ Map<String, Object> getMap() { 805 return mMap; 806 } 807 808 /** 809 * Returns true iff a key of the given name exists in the format. 810 */ containsKey(String name)811 public final boolean containsKey(String name) { 812 return mMap.containsKey(name); 813 } 814 815 /** 816 * A key prefix used together with a {@link MediaCodecInfo.CodecCapabilities} 817 * feature name describing a required or optional feature for a codec capabilities 818 * query. 819 * The associated value is an integer, where non-0 value means the feature is 820 * requested to be present, while 0 value means the feature is requested to be not 821 * present. 822 * @see MediaCodecList#findDecoderForFormat 823 * @see MediaCodecList#findEncoderForFormat 824 * @see MediaCodecInfo.CodecCapabilities#isFormatSupported 825 * 826 * @hide 827 */ 828 public static final String KEY_FEATURE_ = "feature-"; 829 830 /** 831 * Returns the value of an integer key. 832 */ getInteger(String name)833 public final int getInteger(String name) { 834 return ((Integer)mMap.get(name)).intValue(); 835 } 836 837 /** 838 * Returns the value of an integer key, or the default value if the 839 * key is missing or is for another type value. 840 * @hide 841 */ getInteger(String name, int defaultValue)842 public final int getInteger(String name, int defaultValue) { 843 try { 844 return getInteger(name); 845 } 846 catch (NullPointerException e) { /* no such field */ } 847 catch (ClassCastException e) { /* field of different type */ } 848 return defaultValue; 849 } 850 851 /** 852 * Returns the value of a long key. 853 */ getLong(String name)854 public final long getLong(String name) { 855 return ((Long)mMap.get(name)).longValue(); 856 } 857 858 /** 859 * Returns the value of a float key. 860 */ getFloat(String name)861 public final float getFloat(String name) { 862 return ((Float)mMap.get(name)).floatValue(); 863 } 864 865 /** 866 * Returns the value of a string key. 867 */ getString(String name)868 public final String getString(String name) { 869 return (String)mMap.get(name); 870 } 871 872 /** 873 * Returns the value of a ByteBuffer key. 874 */ getByteBuffer(String name)875 public final ByteBuffer getByteBuffer(String name) { 876 return (ByteBuffer)mMap.get(name); 877 } 878 879 /** 880 * Returns whether a feature is to be enabled ({@code true}) or disabled 881 * ({@code false}). 882 * 883 * @param feature the name of a {@link MediaCodecInfo.CodecCapabilities} feature. 884 * 885 * @throws IllegalArgumentException if the feature was neither set to be enabled 886 * nor to be disabled. 887 */ getFeatureEnabled(String feature)888 public boolean getFeatureEnabled(String feature) { 889 Integer enabled = (Integer)mMap.get(KEY_FEATURE_ + feature); 890 if (enabled == null) { 891 throw new IllegalArgumentException("feature is not specified"); 892 } 893 return enabled != 0; 894 } 895 896 /** 897 * Sets the value of an integer key. 898 */ setInteger(String name, int value)899 public final void setInteger(String name, int value) { 900 mMap.put(name, Integer.valueOf(value)); 901 } 902 903 /** 904 * Sets the value of a long key. 905 */ setLong(String name, long value)906 public final void setLong(String name, long value) { 907 mMap.put(name, Long.valueOf(value)); 908 } 909 910 /** 911 * Sets the value of a float key. 912 */ setFloat(String name, float value)913 public final void setFloat(String name, float value) { 914 mMap.put(name, new Float(value)); 915 } 916 917 /** 918 * Sets the value of a string key. 919 */ setString(String name, String value)920 public final void setString(String name, String value) { 921 mMap.put(name, value); 922 } 923 924 /** 925 * Sets the value of a ByteBuffer key. 926 */ setByteBuffer(String name, ByteBuffer bytes)927 public final void setByteBuffer(String name, ByteBuffer bytes) { 928 mMap.put(name, bytes); 929 } 930 931 /** 932 * Sets whether a feature is to be enabled ({@code true}) or disabled 933 * ({@code false}). 934 * 935 * If {@code enabled} is {@code true}, the feature is requested to be present. 936 * Otherwise, the feature is requested to be not present. 937 * 938 * @param feature the name of a {@link MediaCodecInfo.CodecCapabilities} feature. 939 * 940 * @see MediaCodecList#findDecoderForFormat 941 * @see MediaCodecList#findEncoderForFormat 942 * @see MediaCodecInfo.CodecCapabilities#isFormatSupported 943 */ setFeatureEnabled(String feature, boolean enabled)944 public void setFeatureEnabled(String feature, boolean enabled) { 945 setInteger(KEY_FEATURE_ + feature, enabled ? 1 : 0); 946 } 947 948 /** 949 * Creates a minimal audio format. 950 * @param mime The mime type of the content. 951 * @param sampleRate The sampling rate of the content. 952 * @param channelCount The number of audio channels in the content. 953 */ createAudioFormat( String mime, int sampleRate, int channelCount)954 public static final MediaFormat createAudioFormat( 955 String mime, 956 int sampleRate, 957 int channelCount) { 958 MediaFormat format = new MediaFormat(); 959 format.setString(KEY_MIME, mime); 960 format.setInteger(KEY_SAMPLE_RATE, sampleRate); 961 format.setInteger(KEY_CHANNEL_COUNT, channelCount); 962 963 return format; 964 } 965 966 /** 967 * Creates a minimal subtitle format. 968 * @param mime The mime type of the content. 969 * @param language The language of the content, using either ISO 639-1 or 639-2/T 970 * codes. Specify null or "und" if language information is only included 971 * in the content. (This will also work if there are multiple language 972 * tracks in the content.) 973 */ createSubtitleFormat( String mime, String language)974 public static final MediaFormat createSubtitleFormat( 975 String mime, 976 String language) { 977 MediaFormat format = new MediaFormat(); 978 format.setString(KEY_MIME, mime); 979 format.setString(KEY_LANGUAGE, language); 980 981 return format; 982 } 983 984 /** 985 * Creates a minimal video format. 986 * @param mime The mime type of the content. 987 * @param width The width of the content (in pixels) 988 * @param height The height of the content (in pixels) 989 */ createVideoFormat( String mime, int width, int height)990 public static final MediaFormat createVideoFormat( 991 String mime, 992 int width, 993 int height) { 994 MediaFormat format = new MediaFormat(); 995 format.setString(KEY_MIME, mime); 996 format.setInteger(KEY_WIDTH, width); 997 format.setInteger(KEY_HEIGHT, height); 998 999 return format; 1000 } 1001 1002 @Override toString()1003 public String toString() { 1004 return mMap.toString(); 1005 } 1006 } 1007