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