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 import android.annotation.NonNull; 21 import android.annotation.Nullable; 22 import android.compat.annotation.UnsupportedAppUsage; 23 24 import java.lang.annotation.Retention; 25 import java.lang.annotation.RetentionPolicy; 26 import java.nio.ByteBuffer; 27 import java.nio.ByteOrder; 28 import java.util.AbstractSet; 29 import java.util.HashMap; 30 import java.util.Iterator; 31 import java.util.Map; 32 import java.util.Set; 33 import java.util.stream.Collectors; 34 35 /** 36 * Encapsulates the information describing the format of media data, be it audio or video, as 37 * well as optional feature metadata. 38 * <p> 39 * The format of the media data is specified as key/value pairs. Keys are strings. Values can 40 * be integer, long, float, String or ByteBuffer. 41 * <p> 42 * The feature metadata is specificed as string/boolean pairs. 43 * <p> 44 * Keys common to all audio/video formats, <b>all keys not marked optional are mandatory</b>: 45 * 46 * <table> 47 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 48 * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr> 49 * <tr><td>{@link #KEY_CODECS_STRING}</td><td>String</td><td>optional, the RFC 6381 codecs string of the MediaFormat</td></tr> 50 * <tr><td>{@link #KEY_MAX_INPUT_SIZE}</td><td>Integer</td><td>optional, maximum size of a buffer of input data</td></tr> 51 * <tr><td>{@link #KEY_PIXEL_ASPECT_RATIO_WIDTH}</td><td>Integer</td><td>optional, the pixel aspect ratio width</td></tr> 52 * <tr><td>{@link #KEY_PIXEL_ASPECT_RATIO_HEIGHT}</td><td>Integer</td><td>optional, the pixel aspect ratio height</td></tr> 53 * <tr><td>{@link #KEY_BIT_RATE}</td><td>Integer</td><td><b>encoder-only</b>, desired bitrate in bits/second</td></tr> 54 * <tr><td>{@link #KEY_DURATION}</td><td>long</td><td>the duration of the content (in microseconds)</td></tr> 55 * </table> 56 * 57 * Video formats have the following keys: 58 * <table> 59 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 60 * <tr><td>{@link #KEY_WIDTH}</td><td>Integer</td><td></td></tr> 61 * <tr><td>{@link #KEY_HEIGHT}</td><td>Integer</td><td></td></tr> 62 * <tr><td>{@link #KEY_COLOR_FORMAT}</td><td>Integer</td><td>set by the user 63 * for encoders, readable in the output format of decoders</b></td></tr> 64 * <tr><td>{@link #KEY_FRAME_RATE}</td><td>Integer or Float</td><td>required for <b>encoders</b>, 65 * optional for <b>decoders</b></td></tr> 66 * <tr><td>{@link #KEY_CAPTURE_RATE}</td><td>Integer</td><td></td></tr> 67 * <tr><td>{@link #KEY_I_FRAME_INTERVAL}</td><td>Integer (or Float)</td><td><b>encoder-only</b>, 68 * time-interval between key frames. 69 * Float support added in {@link android.os.Build.VERSION_CODES#N_MR1}</td></tr> 70 * <tr><td>{@link #KEY_INTRA_REFRESH_PERIOD}</td><td>Integer</td><td><b>encoder-only</b>, optional</td></tr> 71 * <tr><td>{@link #KEY_LATENCY}</td><td>Integer</td><td><b>encoder-only</b>, optional</td></tr> 72 * <tr><td>{@link #KEY_MAX_WIDTH}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution width</td></tr> 73 * <tr><td>{@link #KEY_MAX_HEIGHT}</td><td>Integer</td><td><b>decoder-only</b>, optional, max-resolution height</td></tr> 74 * <tr><td>{@link #KEY_REPEAT_PREVIOUS_FRAME_AFTER}</td><td>Long</td><td><b>encoder in surface-mode 75 * only</b>, optional</td></tr> 76 * <tr><td>{@link #KEY_PUSH_BLANK_BUFFERS_ON_STOP}</td><td>Integer(1)</td><td><b>decoder rendering 77 * to a surface only</b>, optional</td></tr> 78 * <tr><td>{@link #KEY_TEMPORAL_LAYERING}</td><td>String</td><td><b>encoder only</b>, optional, 79 * temporal-layering schema</td></tr> 80 * </table> 81 * Specify both {@link #KEY_MAX_WIDTH} and {@link #KEY_MAX_HEIGHT} to enable 82 * adaptive playback (seamless resolution change) for a video decoder that 83 * supports it ({@link MediaCodecInfo.CodecCapabilities#FEATURE_AdaptivePlayback}). 84 * The values are used as hints for the codec: they are the maximum expected 85 * resolution to prepare for. Depending on codec support, preparing for larger 86 * maximum resolution may require more memory even if that resolution is never 87 * reached. These fields have no effect for codecs that do not support adaptive 88 * playback.<br /><br /> 89 * 90 * Audio formats have the following keys: 91 * <table> 92 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr> 93 * <tr><td>{@link #KEY_CHANNEL_COUNT}</td><td>Integer</td><td></td></tr> 94 * <tr><td>{@link #KEY_SAMPLE_RATE}</td><td>Integer</td><td></td></tr> 95 * <tr><td>{@link #KEY_PCM_ENCODING}</td><td>Integer</td><td>optional</td></tr> 96 * <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> 97 * <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> 98 * <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> 99 * <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> 100 * <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> 101 * <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> 102 * <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> 103 * <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> 104 * <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> 105 * <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> 106 * <tr><td>{@link #KEY_AAC_DRC_OUTPUT_LOUDNESS}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, returns the DRC output loudness.</td></tr> 107 * <tr><td>{@link #KEY_AAC_DRC_ALBUM_MODE}</td><td>Integer</td><td><b>decoder-only</b>, optional, if content is AAC audio, specifies the whether MPEG-D DRC Album Mode is active or not.</td></tr> 108 * <tr><td>{@link #KEY_CHANNEL_MASK}</td><td>Integer</td><td>optional, a mask of audio channel assignments</td></tr> 109 * <tr><td>{@link #KEY_ENCODER_DELAY}</td><td>Integer</td><td>optional, the number of frames to trim from the start of the decoded audio stream.</td></tr> 110 * <tr><td>{@link #KEY_ENCODER_PADDING}</td><td>Integer</td><td>optional, the number of frames to trim from the end of the decoded audio stream.</td></tr> 111 * <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> 112 * <tr><td>{@link #KEY_MPEGH_PROFILE_LEVEL_INDICATION}</td><td>Integer</td> 113 * <td><b>decoder-only</b>, optional, if content is MPEG-H audio, 114 * specifies the profile and level of the stream.</td></tr> 115 * <tr><td>{@link #KEY_MPEGH_COMPATIBLE_SETS}</td><td>ByteBuffer</td> 116 * <td><b>decoder-only</b>, optional, if content is MPEG-H audio, 117 * specifies the compatible sets (profile and level) of the stream.</td></tr> 118 * <tr><td>{@link #KEY_MPEGH_REFERENCE_CHANNEL_LAYOUT}</td> 119 * <td>Integer</td><td><b>decoder-only</b>, optional, if content is MPEG-H audio, 120 * specifies the preferred reference channel layout of the stream.</td></tr> 121 * </table> 122 * 123 * Subtitle formats have the following keys: 124 * <table> 125 * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr> 126 * <tr><td>{@link #KEY_LANGUAGE}</td><td>String</td><td>The language of the content.</td></tr> 127 * <tr><td>{@link #KEY_CAPTION_SERVICE_NUMBER}</td><td>int</td><td>optional, the closed-caption service or channel number.</td></tr> 128 * </table> 129 * 130 * Image formats have the following keys: 131 * <table> 132 * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr> 133 * <tr><td>{@link #KEY_WIDTH}</td><td>Integer</td><td></td></tr> 134 * <tr><td>{@link #KEY_HEIGHT}</td><td>Integer</td><td></td></tr> 135 * <tr><td>{@link #KEY_COLOR_FORMAT}</td><td>Integer</td><td>set by the user 136 * for encoders, readable in the output format of decoders</b></td></tr> 137 * <tr><td>{@link #KEY_TILE_WIDTH}</td><td>Integer</td><td>required if the image has grid</td></tr> 138 * <tr><td>{@link #KEY_TILE_HEIGHT}</td><td>Integer</td><td>required if the image has grid</td></tr> 139 * <tr><td>{@link #KEY_GRID_ROWS}</td><td>Integer</td><td>required if the image has grid</td></tr> 140 * <tr><td>{@link #KEY_GRID_COLUMNS}</td><td>Integer</td><td>required if the image has grid</td></tr> 141 * </table> 142 */ 143 public final class MediaFormat { 144 public static final String MIMETYPE_VIDEO_VP8 = "video/x-vnd.on2.vp8"; 145 public static final String MIMETYPE_VIDEO_VP9 = "video/x-vnd.on2.vp9"; 146 public static final String MIMETYPE_VIDEO_AV1 = "video/av01"; 147 public static final String MIMETYPE_VIDEO_AVC = "video/avc"; 148 public static final String MIMETYPE_VIDEO_HEVC = "video/hevc"; 149 public static final String MIMETYPE_VIDEO_MPEG4 = "video/mp4v-es"; 150 public static final String MIMETYPE_VIDEO_H263 = "video/3gpp"; 151 public static final String MIMETYPE_VIDEO_MPEG2 = "video/mpeg2"; 152 public static final String MIMETYPE_VIDEO_RAW = "video/raw"; 153 public static final String MIMETYPE_VIDEO_DOLBY_VISION = "video/dolby-vision"; 154 public static final String MIMETYPE_VIDEO_SCRAMBLED = "video/scrambled"; 155 156 public static final String MIMETYPE_AUDIO_AMR_NB = "audio/3gpp"; 157 public static final String MIMETYPE_AUDIO_AMR_WB = "audio/amr-wb"; 158 public static final String MIMETYPE_AUDIO_MPEG = "audio/mpeg"; 159 public static final String MIMETYPE_AUDIO_AAC = "audio/mp4a-latm"; 160 public static final String MIMETYPE_AUDIO_QCELP = "audio/qcelp"; 161 public static final String MIMETYPE_AUDIO_VORBIS = "audio/vorbis"; 162 public static final String MIMETYPE_AUDIO_OPUS = "audio/opus"; 163 public static final String MIMETYPE_AUDIO_G711_ALAW = "audio/g711-alaw"; 164 public static final String MIMETYPE_AUDIO_G711_MLAW = "audio/g711-mlaw"; 165 public static final String MIMETYPE_AUDIO_RAW = "audio/raw"; 166 public static final String MIMETYPE_AUDIO_FLAC = "audio/flac"; 167 public static final String MIMETYPE_AUDIO_MSGSM = "audio/gsm"; 168 public static final String MIMETYPE_AUDIO_AC3 = "audio/ac3"; 169 public static final String MIMETYPE_AUDIO_EAC3 = "audio/eac3"; 170 public static final String MIMETYPE_AUDIO_EAC3_JOC = "audio/eac3-joc"; 171 public static final String MIMETYPE_AUDIO_AC4 = "audio/ac4"; 172 public static final String MIMETYPE_AUDIO_SCRAMBLED = "audio/scrambled"; 173 /** MIME type for MPEG-H Audio single stream */ 174 public static final String MIMETYPE_AUDIO_MPEGH_MHA1 = "audio/mha1"; 175 /** MIME type for MPEG-H Audio single stream, encapsulated in MHAS */ 176 public static final String MIMETYPE_AUDIO_MPEGH_MHM1 = "audio/mhm1"; 177 /** MIME type for DTS Digital Surround (up to 5.1 channels) audio stream, aka DTS-CA. */ 178 public static final String MIMETYPE_AUDIO_DTS = "audio/vnd.dts"; 179 /** 180 * MIME type for DTS HD (up to 7.1 channels) audio stream. 181 * With codec profile DTS_HDProfileHRA represents DTS HD High Resolution Audio. 182 * With codec profile DTS_HDProfileMA represents DTS HD Master Audio. 183 * With codec profile DTS_HDProfileLBR represents DTS Express. 184 */ 185 public static final String MIMETYPE_AUDIO_DTS_HD = "audio/vnd.dts.hd"; 186 /** 187 * MIME type for DTS UHD (object-based) audio stream, aka DTS:X. 188 * With codec profile DTS_UHDProfileP1 represents DTS-UHD P1. 189 * With codec profile DTS_UHDProfileP2 represents DTS-UHD P2. 190 */ 191 public static final String MIMETYPE_AUDIO_DTS_UHD = "audio/vnd.dts.uhd"; 192 /** MIME type for Dynamic Resolution Adaptation (DRA) audio stream. */ 193 public static final String MIMETYPE_AUDIO_DRA = "audio/vnd.dra"; 194 /** MIME type for Dolby Metadata-enhanced Audio Transmission (MAT) audio stream. */ 195 public static final String MIMETYPE_AUDIO_DOLBY_MAT = "audio/vnd.dolby.mat"; 196 /** MIME type for Dolby TrueHD audio format, based on Meridian Lossless Packing (MLP). */ 197 public static final String MIMETYPE_AUDIO_DOLBY_TRUEHD = "audio/vnd.dolby.mlp"; 198 /** 199 * MIME type for AAC Low Complexity (LC) audio stream. Uses the scheme defined by 200 * RFC 6381 with OTI of MPEG-4 (40) and AOT of AAC LC (2) from ISO/IEC 14496-3. 201 */ 202 public static final String MIMETYPE_AUDIO_AAC_LC = "audio/mp4a.40.02"; 203 /** 204 * MIME type for HE-AAC v1 (LC + SBR) audio stream. Uses the scheme defined by 205 * RFC 6381 with OTI of MPEG-4 (40) and AOT of AAC SBR (5) from ISO/IEC 14496-3. 206 */ 207 public static final String MIMETYPE_AUDIO_AAC_HE_V1 = "audio/mp4a.40.05"; 208 /** 209 * MIME type for HE-AAC v2 (LC + SBR + PS) audio stream. Uses the scheme defined by 210 * RFC 6381 with OTI of MPEG-4 (40) and AOT of PS (29) from ISO/IEC 14496-3. 211 */ 212 public static final String MIMETYPE_AUDIO_AAC_HE_V2 = "audio/mp4a.40.29"; 213 /** 214 * MIME type for AAC Enhanced Low Delay (ELD) audio stream. Uses the scheme defined by 215 * RFC 6381 with OTI of MPEG-4 (40) and AOT of ELD (39) from ISO/IEC 14496-3. 216 */ 217 public static final String MIMETYPE_AUDIO_AAC_ELD = "audio/mp4a.40.39"; 218 /** 219 * MIME type for AAC XHE audio stream. Uses the scheme defined by 220 * RFC 6381 with OTI of MPEG-4 (40) and AOT of USAC (42) from ISO/IEC 14496-3. 221 */ 222 public static final String MIMETYPE_AUDIO_AAC_XHE = "audio/mp4a.40.42"; 223 /** 224 * MIME type for MPEG-H Baseline (BL) Profile L3 audio stream. Uses the scheme defined by 225 * RFC 6381 with mpegh3daProfileLevelIndication for main profile/L3 (0x3) from ISO/IEC 23008-3. 226 */ 227 public static final String MIMETYPE_AUDIO_MPEGH_BL_L3 = "audio/mhm1.03"; 228 /** 229 * MIME type for MPEG-H Baseline (BL) Profile L4 audio stream. Uses the scheme defined by 230 * RFC 6381 with mpegh3daProfileLevelIndication for main profile/L4 (0x4) from ISO/IEC 23008-3. 231 */ 232 public static final String MIMETYPE_AUDIO_MPEGH_BL_L4 = "audio/mhm1.04"; 233 /** 234 * MIME type for MPEG-H Low Complexity (LC) L3 audio stream. Uses the scheme defined by 235 * RFC 6381 with mpegh3daProfileLevelIndication for LC profile/L3 (0xD) from ISO/IEC 23008-3. 236 */ 237 public static final String MIMETYPE_AUDIO_MPEGH_LC_L3 = "audio/mhm1.0d"; 238 /** 239 * MIME type for MPEG-H Low Complexity (LC) L4 audio stream. Uses the scheme defined by 240 * RFC 6381 with mpegh3daProfileLevelIndication for LC profile/L4 (0xE) from ISO/IEC 23008-3. 241 */ 242 public static final String MIMETYPE_AUDIO_MPEGH_LC_L4 = "audio/mhm1.0e"; 243 /** 244 * MIME type for the IEC61937 audio stream encapsulation. This type isn't defined by IANA. 245 */ 246 public static final String MIMETYPE_AUDIO_IEC61937 = "audio/x-iec61937"; 247 248 /** 249 * MIME type for HEIF still image data encoded in HEVC. 250 * 251 * To decode such an image, {@link MediaCodec} decoder for 252 * {@link #MIMETYPE_VIDEO_HEVC} shall be used. The client needs to form 253 * the correct {@link #MediaFormat} based on additional information in 254 * the track format (shown in the next paragraph), and send it to 255 * {@link MediaCodec#configure}. 256 * 257 * The track's MediaFormat will come with {@link #KEY_WIDTH} and 258 * {@link #KEY_HEIGHT} keys, which describes the width and height 259 * of the image. If the image doesn't contain grid (i.e. none of 260 * {@link #KEY_TILE_WIDTH}, {@link #KEY_TILE_HEIGHT}, 261 * {@link #KEY_GRID_ROWS}, {@link #KEY_GRID_COLUMNS} are present), the 262 * track will contain a single sample of coded data for the entire image, 263 * and the image width and height should be used to set up the decoder. 264 * 265 * If the image does come with grid, each sample from the track will 266 * contain one tile in the grid, of which the size is described by 267 * {@link #KEY_TILE_WIDTH} and {@link #KEY_TILE_HEIGHT}. This size 268 * (instead of {@link #KEY_WIDTH} and {@link #KEY_HEIGHT}) should be 269 * used to set up the decoder. The track contains {@link #KEY_GRID_ROWS} 270 * by {@link #KEY_GRID_COLUMNS} samples in row-major, top-row first, 271 * left-to-right order. The output image should be reconstructed by 272 * first tiling the decoding results of the tiles in the correct order, 273 * then trimming (before rotation is applied) on the bottom and right 274 * side, if the tiled area is larger than the image width and height. 275 */ 276 public static final String MIMETYPE_IMAGE_ANDROID_HEIC = "image/vnd.android.heic"; 277 278 /** 279 * MIME type for AVIF still image data encoded in AV1. 280 * 281 * To decode such an image, {@link MediaCodec} decoder for 282 * {@link #MIMETYPE_VIDEO_AV1} shall be used. The client needs to form 283 * the correct {@link #MediaFormat} based on additional information in 284 * the track format (shown in the next paragraph), and send it to 285 * {@link MediaCodec#configure}. 286 * 287 * The track's MediaFormat will come with {@link #KEY_WIDTH} and 288 * {@link #KEY_HEIGHT} keys, which describes the width and height 289 * of the image. If the image doesn't contain grid (i.e. none of 290 * {@link #KEY_TILE_WIDTH}, {@link #KEY_TILE_HEIGHT}, 291 * {@link #KEY_GRID_ROWS}, {@link #KEY_GRID_COLUMNS} are present), the 292 * track will contain a single sample of coded data for the entire image, 293 * and the image width and height should be used to set up the decoder. 294 * 295 * If the image does come with grid, each sample from the track will 296 * contain one tile in the grid, of which the size is described by 297 * {@link #KEY_TILE_WIDTH} and {@link #KEY_TILE_HEIGHT}. This size 298 * (instead of {@link #KEY_WIDTH} and {@link #KEY_HEIGHT}) should be 299 * used to set up the decoder. The track contains {@link #KEY_GRID_ROWS} 300 * by {@link #KEY_GRID_COLUMNS} samples in row-major, top-row first, 301 * left-to-right order. The output image should be reconstructed by 302 * first tiling the decoding results of the tiles in the correct order, 303 * then trimming (before rotation is applied) on the bottom and right 304 * side, if the tiled area is larger than the image width and height. 305 */ 306 public static final String MIMETYPE_IMAGE_AVIF = "image/avif"; 307 308 /** 309 * MIME type for WebVTT subtitle data. 310 */ 311 public static final String MIMETYPE_TEXT_VTT = "text/vtt"; 312 313 /** 314 * MIME type for SubRip (SRT) container. 315 */ 316 public static final String MIMETYPE_TEXT_SUBRIP = "application/x-subrip"; 317 318 /** 319 * MIME type for CEA-608 closed caption data. 320 */ 321 public static final String MIMETYPE_TEXT_CEA_608 = "text/cea-608"; 322 323 /** 324 * MIME type for CEA-708 closed caption data. 325 */ 326 public static final String MIMETYPE_TEXT_CEA_708 = "text/cea-708"; 327 328 @UnsupportedAppUsage 329 private Map<String, Object> mMap; 330 331 /** 332 * A key describing the log session ID for MediaCodec. The log session ID is a random 32-byte 333 * hexadecimal string that is used to associate metrics from multiple media codec instances 334 * to the same playback or recording session. The value is created as 335 * {@link android.media.metrics.LogSessionId LogSessionId}. Sessions are created in 336 * {@link android.media.metrics.MediaMetricsManager MediaMetricsManager}. 337 * The associated value is a string. 338 */ 339 public static final String LOG_SESSION_ID = "log-session-id"; 340 341 /** 342 * A key describing the mime type of the MediaFormat. 343 * The associated value is a string. 344 */ 345 public static final String KEY_MIME = "mime"; 346 347 /** 348 * A key describing the codecs string of the MediaFormat. See RFC 6381 section 3.2 for the 349 * syntax of the value. The value does not hold {@link MediaCodec}-exposed codec names. 350 * The associated value is a string. 351 * 352 * @see MediaParser.TrackData#mediaFormat 353 */ 354 public static final String KEY_CODECS_STRING = "codecs-string"; 355 356 /** 357 * An optional key describing the low latency decoding mode. This is an optional parameter 358 * that applies only to decoders. If enabled, the decoder doesn't hold input and output 359 * data more than required by the codec standards. 360 * The associated value is an integer (0 or 1): 1 when low-latency decoding is enabled, 361 * 0 otherwise. The default value is 0. 362 */ 363 public static final String KEY_LOW_LATENCY = "low-latency"; 364 365 /** 366 * A key describing the language of the content, using either ISO 639-1 367 * or 639-2/T codes. The associated value is a string. 368 */ 369 public static final String KEY_LANGUAGE = "language"; 370 371 /** 372 * A key describing the closed caption service number. For CEA-608 caption tracks, holds the 373 * channel number. For CEA-708, holds the service number. 374 * The associated value is an int. 375 */ 376 public static final String KEY_CAPTION_SERVICE_NUMBER = "caption-service-number"; 377 378 /** 379 * A key describing the sample rate of an audio format. 380 * The associated value is an integer 381 */ 382 public static final String KEY_SAMPLE_RATE = "sample-rate"; 383 384 /** 385 * A key describing the number of channels in an audio format. 386 * The associated value is an integer 387 */ 388 public static final String KEY_CHANNEL_COUNT = "channel-count"; 389 390 /** 391 * A key describing the width of the content in a video format. 392 * The associated value is an integer 393 */ 394 public static final String KEY_WIDTH = "width"; 395 396 /** 397 * A key describing the height of the content in a video format. 398 * The associated value is an integer 399 */ 400 public static final String KEY_HEIGHT = "height"; 401 402 /** 403 * A key describing the bottom-coordinate (y) of the crop rectangle. 404 * This is the bottom-most row included in the crop frame, 405 * where row indices start at 0. 406 * Additional information on the crop rectangle semantics can be found at 407 * {@link android.media.MediaCodec}. 408 */ 409 public static final String KEY_CROP_BOTTOM = "crop-bottom"; 410 411 /** 412 * A key describing the left-coordinate (x) of the crop rectangle. 413 * This is the left-most column included in the crop frame, 414 * where column indices start at 0. 415 * Additional information on the crop rectangle semantics can be found at 416 * {@link android.media.MediaCodec}. 417 */ 418 public static final String KEY_CROP_LEFT = "crop-left"; 419 420 /** 421 * A key describing the right-coordinate (x) of the crop rectangle. 422 * This is the right-most column included in the crop frame, 423 * where column indices start at 0. 424 * Additional information on the crop rectangle semantics can be found at 425 * {@link android.media.MediaCodec}. 426 */ 427 public static final String KEY_CROP_RIGHT = "crop-right"; 428 429 /** 430 * A key describing the top-coordinate (y) of the crop rectangle. 431 * This is the top-most row included in the crop frame, 432 * where row indices start at 0. 433 * Additional information on the crop rectangle semantics can be found at 434 * {@link android.media.MediaCodec}. 435 */ 436 public static final String KEY_CROP_TOP = "crop-top"; 437 438 /** 439 * A key describing the maximum expected width of the content in a video 440 * decoder format, in case there are resolution changes in the video content. 441 * The associated value is an integer 442 */ 443 public static final String KEY_MAX_WIDTH = "max-width"; 444 445 /** 446 * A key describing the maximum expected height of the content in a video 447 * decoder format, in case there are resolution changes in the video content. 448 * The associated value is an integer 449 */ 450 public static final String KEY_MAX_HEIGHT = "max-height"; 451 452 /** A key describing the maximum size in bytes of a buffer of data 453 * described by this MediaFormat. 454 * The associated value is an integer 455 */ 456 public static final String KEY_MAX_INPUT_SIZE = "max-input-size"; 457 458 /** 459 * A key describing the pixel aspect ratio width. 460 * The associated value is an integer 461 */ 462 public static final String KEY_PIXEL_ASPECT_RATIO_WIDTH = "sar-width"; 463 464 /** 465 * A key describing the pixel aspect ratio height. 466 * The associated value is an integer 467 */ 468 public static final String KEY_PIXEL_ASPECT_RATIO_HEIGHT = "sar-height"; 469 470 /** 471 * A key describing the average bitrate in bits/sec. 472 * The associated value is an integer 473 */ 474 public static final String KEY_BIT_RATE = "bitrate"; 475 476 /** 477 * A key describing the hardware AV sync id. 478 * The associated value is an integer 479 * 480 * See android.media.tv.tuner.Tuner#getAvSyncHwId. 481 */ 482 public static final String KEY_HARDWARE_AV_SYNC_ID = "hw-av-sync-id"; 483 484 /** 485 * A key describing the max bitrate in bits/sec. 486 * This is usually over a one-second sliding window (e.g. over any window of one second). 487 * The associated value is an integer 488 * @hide 489 */ 490 public static final String KEY_MAX_BIT_RATE = "max-bitrate"; 491 492 /** 493 * A key describing the color format of the content in a video format. 494 * Constants are declared in {@link android.media.MediaCodecInfo.CodecCapabilities}. 495 */ 496 public static final String KEY_COLOR_FORMAT = "color-format"; 497 498 /** 499 * A key describing the frame rate of a video format in frames/sec. 500 * <p> 501 * The associated value is normally an integer when the value is used by the platform, 502 * but video codecs also accept float configuration values. 503 * Specifically, {@link MediaExtractor#getTrackFormat MediaExtractor} provides an integer 504 * value corresponding to the frame rate information of the track if specified and non-zero. 505 * Otherwise, this key is not present. {@link MediaCodec#configure MediaCodec} accepts both 506 * float and integer values. 507 * <p> 508 * This represents the desired operating frame rate if the 509 * {@link #KEY_OPERATING_RATE} is not present and {@link #KEY_PRIORITY} is {@code 0} 510 * (realtime). Otherwise, this is just informational. 511 * <p> 512 * For video encoders this value corresponds to the intended frame rate (the rate at which 513 * the application intends to send frames to the encoder, as calculated by the buffer 514 * timestamps, and not from the actual real-time rate that the frames are sent to 515 * the encoder). Encoders use this hint for rate control, specifically for the initial 516 * frames, as encoders are expected to support variable frame rate (for rate control) based 517 * on the actual {@link MediaCodec.BufferInfo#presentationTimeUs buffer timestamps} of 518 * subsequent frames. 519 * <p> 520 * This key is not used in the {@code MediaCodec} 521 * {@link MediaCodec#getInputFormat input}/{@link MediaCodec#getOutputFormat output} formats, 522 * nor by {@link MediaMuxer#addTrack MediaMuxer}. 523 */ 524 public static final String KEY_FRAME_RATE = "frame-rate"; 525 526 /** 527 * A key describing the width (in pixels) of each tile of the content in a 528 * {@link #MIMETYPE_IMAGE_ANDROID_HEIC} / {@link #MIMETYPE_IMAGE_AVIF} track. 529 * The associated value is an integer. 530 * 531 * Refer to {@link #MIMETYPE_IMAGE_ANDROID_HEIC} / {@link #MIMETYPE_IMAGE_AVIF} on decoding 532 * instructions of such tracks. 533 * 534 * @see #KEY_TILE_HEIGHT 535 * @see #KEY_GRID_ROWS 536 * @see #KEY_GRID_COLUMNS 537 */ 538 public static final String KEY_TILE_WIDTH = "tile-width"; 539 540 /** 541 * A key describing the height (in pixels) of each tile of the content in a 542 * {@link #MIMETYPE_IMAGE_ANDROID_HEIC} / {@link #MIMETYPE_IMAGE_AVIF} track. 543 * The associated value is an integer. 544 * 545 * Refer to {@link #MIMETYPE_IMAGE_ANDROID_HEIC} / {@link #MIMETYPE_IMAGE_AVIF} on decoding 546 * instructions of such tracks. 547 * 548 * @see #KEY_TILE_WIDTH 549 * @see #KEY_GRID_ROWS 550 * @see #KEY_GRID_COLUMNS 551 */ 552 public static final String KEY_TILE_HEIGHT = "tile-height"; 553 554 /** 555 * A key describing the number of grid rows in the content in a 556 * {@link #MIMETYPE_IMAGE_ANDROID_HEIC} / {@link #MIMETYPE_IMAGE_AVIF} track. 557 * The associated value is an integer. 558 * 559 * Refer to {@link #MIMETYPE_IMAGE_ANDROID_HEIC} / {@link #MIMETYPE_IMAGE_AVIF} on decoding 560 * instructions of such tracks. 561 * 562 * @see #KEY_TILE_WIDTH 563 * @see #KEY_TILE_HEIGHT 564 * @see #KEY_GRID_COLUMNS 565 */ 566 public static final String KEY_GRID_ROWS = "grid-rows"; 567 568 /** 569 * A key describing the number of grid columns in the content in a 570 * {@link #MIMETYPE_IMAGE_ANDROID_HEIC} / {@link #MIMETYPE_IMAGE_AVIF} track. 571 * The associated value is an integer. 572 * 573 * Refer to {@link #MIMETYPE_IMAGE_ANDROID_HEIC} / {@link #MIMETYPE_IMAGE_AVIF} on decoding 574 * instructions of such tracks. 575 * 576 * @see #KEY_TILE_WIDTH 577 * @see #KEY_TILE_HEIGHT 578 * @see #KEY_GRID_ROWS 579 */ 580 public static final String KEY_GRID_COLUMNS = "grid-cols"; 581 582 /** 583 * A key describing the raw audio sample encoding/format. 584 * 585 * <p>The associated value is an integer, using one of the 586 * {@link AudioFormat}.ENCODING_PCM_ values.</p> 587 * 588 * <p>This is an optional key for audio decoders and encoders specifying the 589 * desired raw audio sample format during {@link MediaCodec#configure 590 * MediaCodec.configure(…)} call. Use {@link MediaCodec#getInputFormat 591 * MediaCodec.getInput}/{@link MediaCodec#getOutputFormat OutputFormat(…)} 592 * to confirm the actual format. For the PCM decoder this key specifies both 593 * input and output sample encodings.</p> 594 * 595 * <p>This key is also used by {@link MediaExtractor} to specify the sample 596 * format of audio data, if it is specified.</p> 597 * 598 * <p>If this key is missing, the raw audio sample format is signed 16-bit short.</p> 599 */ 600 public static final String KEY_PCM_ENCODING = "pcm-encoding"; 601 602 /** 603 * A key describing the capture rate of a video format in frames/sec. 604 * <p> 605 * When capture rate is different than the frame rate, it means that the 606 * video is acquired at a different rate than the playback, which produces 607 * slow motion or timelapse effect during playback. Application can use the 608 * value of this key to tell the relative speed ratio between capture and 609 * playback rates when the video was recorded. 610 * </p> 611 * <p> 612 * The associated value is an integer or a float. 613 * </p> 614 */ 615 public static final String KEY_CAPTURE_RATE = "capture-rate"; 616 617 /** 618 * A key for retrieving the slow-motion marker information associated with a video track. 619 * <p> 620 * The associated value is a ByteBuffer in {@link ByteOrder#BIG_ENDIAN} 621 * (networking order) of the following format: 622 * </p> 623 * <pre class="prettyprint"> 624 * float(32) playbackRate; 625 * unsigned int(32) numMarkers; 626 * for (i = 0;i < numMarkers; i++) { 627 * int(64) timestampUs; 628 * float(32) speedRatio; 629 * }</pre> 630 * The meaning of each field is as follows: 631 * <table border="1" width="90%" align="center" cellpadding="5"> 632 * <tbody> 633 * <tr> 634 * <td>playbackRate</td> 635 * <td>The frame rate at which the playback should happen (or the flattened 636 * clip should be).</td> 637 * </tr> 638 * <tr> 639 * <td>numMarkers</td> 640 * <td>The number of slow-motion markers that follows.</td> 641 * </tr> 642 * <tr> 643 * <td>timestampUs</td> 644 * <td>The starting point of a new segment.</td> 645 * </tr> 646 * <tr> 647 * <td>speedRatio</td> 648 * <td>The playback speed for that segment. The playback speed is a floating 649 * point number, indicating how fast the time progresses relative to that 650 * written in the container. (Eg. 4.0 means time goes 4x as fast, which 651 * makes 30fps become 120fps.)</td> 652 * </tr> 653 * </table> 654 * <p> 655 * The following constraints apply to the timestampUs of the markers: 656 * </p> 657 * <li>The timestampUs shall be monotonically increasing.</li> 658 * <li>The timestampUs shall fall within the time span of the video track.</li> 659 * <li>The first timestampUs should match that of the first video sample.</li> 660 */ 661 public static final String KEY_SLOW_MOTION_MARKERS = "slow-motion-markers"; 662 663 /** 664 * A key describing the frequency of key frames expressed in seconds between key frames. 665 * <p> 666 * This key is used by video encoders. 667 * A negative value means no key frames are requested after the first frame. 668 * A zero value means a stream containing all key frames is requested. 669 * <p class=note> 670 * Most video encoders will convert this value of the number of non-key-frames between 671 * key-frames, using the {@linkplain #KEY_FRAME_RATE frame rate} information; therefore, 672 * if the actual frame rate differs (e.g. input frames are dropped or the frame rate 673 * changes), the <strong>time interval</strong> between key frames will not be the 674 * configured value. 675 * <p> 676 * The associated value is an integer (or float since 677 * {@link android.os.Build.VERSION_CODES#N_MR1}). 678 */ 679 public static final String KEY_I_FRAME_INTERVAL = "i-frame-interval"; 680 681 /** 682 * An optional key describing the period of intra refresh in frames. This is an 683 * optional parameter that applies only to video encoders. If encoder supports it 684 * ({@link MediaCodecInfo.CodecCapabilities#FEATURE_IntraRefresh}), the whole 685 * frame is completely refreshed after the specified period. Also for each frame, 686 * a fix subset of macroblocks must be intra coded which leads to more constant bitrate 687 * than inserting a key frame. This key is recommended for video streaming applications 688 * as it provides low-delay and good error-resilience. This key is ignored if the 689 * video encoder does not support the intra refresh feature. Use the output format to 690 * verify that this feature was enabled. 691 * The associated value is an integer. 692 */ 693 public static final String KEY_INTRA_REFRESH_PERIOD = "intra-refresh-period"; 694 695 /** 696 * An optional key describing whether encoders prepend headers to sync frames (e.g. 697 * SPS and PPS to IDR frames for H.264). This is an optional parameter that applies only 698 * to video encoders. A video encoder may not support this feature; the component will fail 699 * to configure in that case. For other components, this key is ignored. 700 * 701 * The value is an integer, with 1 indicating to prepend headers to every sync frames, 702 * or 0 otherwise. The default value is 0. 703 */ 704 public static final String KEY_PREPEND_HEADER_TO_SYNC_FRAMES = "prepend-sps-pps-to-idr-frames"; 705 706 /** 707 * A key describing the temporal layering schema. This is an optional parameter 708 * that applies only to video encoders. Use {@link MediaCodec#getOutputFormat} 709 * after {@link MediaCodec#configure configure} to query if the encoder supports 710 * the desired schema. Supported values are {@code webrtc.vp8.N-layer}, 711 * {@code android.generic.N}, {@code android.generic.N+M} and {@code none}, where 712 * {@code N} denotes the total number of non-bidirectional layers (which must be at least 1) 713 * and {@code M} denotes the total number of bidirectional layers (which must be non-negative). 714 * <p class=note>{@code android.generic.*} schemas have been added in {@link 715 * android.os.Build.VERSION_CODES#N_MR1}. 716 * <p> 717 * The encoder may support fewer temporal layers, in which case the output format 718 * will contain the configured schema. If the encoder does not support temporal 719 * layering, the output format will not have an entry with this key. 720 * The associated value is a string. 721 */ 722 public static final String KEY_TEMPORAL_LAYERING = "ts-schema"; 723 724 /** 725 * A key describing the stride of the video bytebuffer layout. 726 * Stride (or row increment) is the difference between the index of a pixel 727 * and that of the pixel directly underneath. For YUV 420 formats, the 728 * stride corresponds to the Y plane; the stride of the U and V planes can 729 * be calculated based on the color format, though it is generally undefined 730 * and depends on the device and release. 731 * The associated value is an integer, representing number of bytes. 732 */ 733 public static final String KEY_STRIDE = "stride"; 734 735 /** 736 * A key describing the plane height of a multi-planar (YUV) video bytebuffer layout. 737 * Slice height (or plane height/vertical stride) is the number of rows that must be skipped 738 * to get from the top of the Y plane to the top of the U plane in the bytebuffer. In essence 739 * the offset of the U plane is sliceHeight * stride. The height of the U/V planes 740 * can be calculated based on the color format, though it is generally undefined 741 * and depends on the device and release. 742 * The associated value is an integer, representing number of rows. 743 */ 744 public static final String KEY_SLICE_HEIGHT = "slice-height"; 745 746 /** 747 * Applies only when configuring a video encoder in "surface-input" mode. 748 * The associated value is a long and gives the time in microseconds 749 * after which the frame previously submitted to the encoder will be 750 * repeated (once) if no new frame became available since. 751 */ 752 public static final String KEY_REPEAT_PREVIOUS_FRAME_AFTER 753 = "repeat-previous-frame-after"; 754 755 /** 756 * Instruct the video encoder in "surface-input" mode to drop excessive 757 * frames from the source, so that the input frame rate to the encoder 758 * does not exceed the specified fps. 759 * 760 * The associated value is a float, representing the max frame rate to 761 * feed the encoder at. 762 * 763 */ 764 public static final String KEY_MAX_FPS_TO_ENCODER 765 = "max-fps-to-encoder"; 766 767 /** 768 * Instruct the video encoder in "surface-input" mode to limit the gap of 769 * timestamp between any two adjacent frames fed to the encoder to the 770 * specified amount (in micro-second). 771 * 772 * The associated value is a long int. When positive, it represents the max 773 * timestamp gap between two adjacent frames fed to the encoder. When negative, 774 * the absolute value represents a fixed timestamp gap between any two adjacent 775 * frames fed to the encoder. Note that this will also apply even when the 776 * original timestamp goes backward in time. Under normal conditions, such frames 777 * would be dropped and not sent to the encoder. 778 * 779 * The output timestamp will be restored to the original timestamp and will 780 * not be affected. 781 * 782 * This is used in some special scenarios where input frames arrive sparingly 783 * but it's undesirable to allocate more bits to any single frame, or when it's 784 * important to ensure all frames are captured (rather than captured in the 785 * correct order). 786 * 787 */ 788 public static final String KEY_MAX_PTS_GAP_TO_ENCODER 789 = "max-pts-gap-to-encoder"; 790 791 /** 792 * If specified when configuring a video encoder that's in "surface-input" 793 * mode, it will instruct the encoder to put the surface source in suspended 794 * state when it's connected. No video frames will be accepted until a resume 795 * operation (see {@link MediaCodec#PARAMETER_KEY_SUSPEND}), optionally with 796 * timestamp specified via {@link MediaCodec#PARAMETER_KEY_SUSPEND_TIME}, is 797 * received. 798 * 799 * The value is an integer, with 1 indicating to create with the surface 800 * source suspended, or 0 otherwise. The default value is 0. 801 * 802 * If this key is not set or set to 0, the surface source will accept buffers 803 * as soon as it's connected to the encoder (although they may not be encoded 804 * immediately). This key can be used when the client wants to prepare the 805 * encoder session in advance, but do not want to accept buffers immediately. 806 */ 807 public static final String KEY_CREATE_INPUT_SURFACE_SUSPENDED 808 = "create-input-buffers-suspended"; 809 810 /** 811 * If specified when configuring a video decoder rendering to a surface, 812 * causes the decoder to output "blank", i.e. black frames to the surface 813 * when stopped to clear out any previously displayed contents. 814 * The associated value is an integer of value 1. 815 */ 816 public static final String KEY_PUSH_BLANK_BUFFERS_ON_STOP 817 = "push-blank-buffers-on-shutdown"; 818 819 /** 820 * A key describing the duration (in microseconds) of the content. 821 * The associated value is a long. 822 */ 823 public static final String KEY_DURATION = "durationUs"; 824 825 /** 826 * A key mapping to a value of 1 if the content is AAC audio and 827 * audio frames are prefixed with an ADTS header. 828 * The associated value is an integer (0 or 1). 829 * This key is only supported when _decoding_ content, it cannot 830 * be used to configure an encoder to emit ADTS output. 831 */ 832 public static final String KEY_IS_ADTS = "is-adts"; 833 834 /** 835 * A key describing the channel composition of audio content. This mask 836 * is composed of bits drawn from channel mask definitions in {@link android.media.AudioFormat}. 837 * The associated value is an integer. 838 */ 839 public static final String KEY_CHANNEL_MASK = "channel-mask"; 840 841 /** 842 * A key describing the maximum number of channels that can be output by an audio decoder. 843 * By default, the decoder will output the same number of channels as present in the encoded 844 * stream, if supported. Set this value to limit the number of output channels, and use 845 * the downmix information in the stream, if available. 846 * <p>Values larger than the number of channels in the content to decode behave like the number 847 * of channels in the content (if applicable), for instance passing 99 for a 5.1 audio stream 848 * behaves like passing 6. 849 * <p>This key is only used during decoding. 850 */ 851 public static final String KEY_MAX_OUTPUT_CHANNEL_COUNT = 852 "max-output-channel-count"; 853 854 /** 855 * A key describing the number of frames to trim from the start of the decoded audio stream. 856 * The associated value is an integer. 857 */ 858 public static final String KEY_ENCODER_DELAY = "encoder-delay"; 859 860 /** 861 * A key describing the number of frames to trim from the end of the decoded audio stream. 862 * The associated value is an integer. 863 */ 864 public static final String KEY_ENCODER_PADDING = "encoder-padding"; 865 866 /** 867 * A key describing the AAC profile to be used (AAC audio formats only). 868 * Constants are declared in {@link android.media.MediaCodecInfo.CodecProfileLevel}. 869 */ 870 public static final String KEY_AAC_PROFILE = "aac-profile"; 871 872 /** 873 * A key describing the AAC SBR mode to be used (AAC audio formats only). 874 * The associated value is an integer and can be set to following values: 875 * <ul> 876 * <li>0 - no SBR should be applied</li> 877 * <li>1 - single rate SBR</li> 878 * <li>2 - double rate SBR</li> 879 * </ul> 880 * Note: If this key is not defined the default SRB mode for the desired AAC profile will 881 * be used. 882 * <p>This key is only used during encoding. 883 */ 884 public static final String KEY_AAC_SBR_MODE = "aac-sbr-mode"; 885 886 /** 887 * A key describing the maximum number of channels that can be output by the AAC decoder. 888 * By default, the decoder will output the same number of channels as present in the encoded 889 * stream, if supported. Set this value to limit the number of output channels, and use 890 * the downmix information in the stream, if available. 891 * <p>Values larger than the number of channels in the content to decode behave just 892 * like the actual channel count of the content (e.g. passing 99 for the decoding of 5.1 content 893 * will behave like using 6). 894 * <p>This key is only used during decoding. 895 * @deprecated Use the non-AAC-specific key {@link #KEY_MAX_OUTPUT_CHANNEL_COUNT} instead 896 */ 897 public static final String KEY_AAC_MAX_OUTPUT_CHANNEL_COUNT = "aac-max-output-channel_count"; 898 899 /** 900 * A key describing the Target Reference Level (Target Loudness). 901 * <p>For normalizing loudness across program items, a gain is applied to the audio output so 902 * that the output loudness matches the Target Reference Level. The gain is derived as the 903 * difference between the Target Reference Level and the Program Reference Level (Program 904 * Loudness). The latter can be given in the bitstream and indicates the actual loudness value 905 * of the program item.</p> 906 * <p>The Target Reference Level controls loudness normalization for both MPEG-4 DRC and 907 * MPEG-D DRC. 908 * <p>The value is given as an integer value between 909 * 40 and 127, and is calculated as -4 * Target Reference Level in LKFS. 910 * Therefore, it represents the range of -10 to -31.75 LKFS. 911 * <p>For MPEG-4 DRC, a value of -1 switches off loudness normalization and DRC processing.</p> 912 * <p>For MPEG-D DRC, a value of -1 switches off loudness normalization only. For DRC processing 913 * options of MPEG-D DRC, see {@link #KEY_AAC_DRC_EFFECT_TYPE}</p> 914 * <p>The default value on mobile devices is 64 (-16 LKFS). 915 * <p>This key is only used during decoding. 916 */ 917 public static final String KEY_AAC_DRC_TARGET_REFERENCE_LEVEL = "aac-target-ref-level"; 918 919 /** 920 * A key describing for selecting the DRC effect type for MPEG-D DRC. 921 * The supported values are defined in ISO/IEC 23003-4:2015 and are described as follows: 922 * <table> 923 * <tr><th>Value</th><th>Effect</th></tr> 924 * <tr><th>-1</th><th>Off</th></tr> 925 * <tr><th>0</th><th>None</th></tr> 926 * <tr><th>1</th><th>Late night</th></tr> 927 * <tr><th>2</th><th>Noisy environment</th></tr> 928 * <tr><th>3</th><th>Limited playback range</th></tr> 929 * <tr><th>4</th><th>Low playback level</th></tr> 930 * <tr><th>5</th><th>Dialog enhancement</th></tr> 931 * <tr><th>6</th><th>General compression</th></tr> 932 * </table> 933 * <p>The value -1 (Off) disables DRC processing, while loudness normalization may still be 934 * active and dependent on {@link #KEY_AAC_DRC_TARGET_REFERENCE_LEVEL}.<br> 935 * The value 0 (None) automatically enables DRC processing if necessary to prevent signal 936 * clipping<br> 937 * The value 6 (General compression) can be used for enabling MPEG-D DRC without particular 938 * DRC effect type request.<br> 939 * The default DRC effect type is 3 ("Limited playback range") on mobile devices. 940 * <p>This key is only used during decoding. 941 */ 942 public static final String KEY_AAC_DRC_EFFECT_TYPE = "aac-drc-effect-type"; 943 944 /** 945 * A key describing the target reference level that was assumed at the encoder for 946 * calculation of attenuation gains for clipping prevention. 947 * <p>If it is known, this information can be provided as an integer value between 948 * 0 and 127, which is calculated as -4 * Encoded Target Level in LKFS. 949 * If the Encoded Target Level is unknown, the value can be set to -1. 950 * <p>The default value is -1 (unknown). 951 * <p>The value is ignored when heavy compression (see {@link #KEY_AAC_DRC_HEAVY_COMPRESSION}) 952 * or MPEG-D DRC is used. 953 * <p>This key is only used during decoding. 954 */ 955 public static final String KEY_AAC_ENCODED_TARGET_LEVEL = "aac-encoded-target-level"; 956 957 /** 958 * A key describing the boost factor allowing to adapt the dynamics of the output to the 959 * actual listening requirements. This relies on DRC gain sequences that can be transmitted in 960 * the encoded bitstream to be able to reduce the dynamics of the output signal upon request. 961 * This factor enables the user to select how much of the gains are applied. 962 * <p>Positive gains (boost) and negative gains (attenuation, see 963 * {@link #KEY_AAC_DRC_ATTENUATION_FACTOR}) can be controlled separately for a better match 964 * to different use-cases. 965 * <p>Typically, attenuation gains are sent for loud signal segments, and boost gains are sent 966 * for soft signal segments. If the output is listened to in a noisy environment, for example, 967 * the boost factor is used to enable the positive gains, i.e. to amplify soft signal segments 968 * beyond the noise floor. But for listening late at night, the attenuation 969 * factor is used to enable the negative gains, to prevent loud signal from surprising 970 * the listener. In applications which generally need a low dynamic range, both the boost factor 971 * and the attenuation factor are used in order to enable all DRC gains. 972 * <p>In order to prevent clipping, it is also recommended to apply the attenuation gains 973 * in case of a downmix and/or loudness normalization to high target reference levels. 974 * <p>Both the boost and the attenuation factor parameters are given as integer values 975 * between 0 and 127, representing the range of the factor of 0 (i.e. don't apply) 976 * to 1 (i.e. fully apply boost/attenuation gains respectively). 977 * <p>The default value is 127 (fully apply boost DRC gains). 978 * <p>This key is only used during decoding. 979 */ 980 public static final String KEY_AAC_DRC_BOOST_FACTOR = "aac-drc-boost-level"; 981 982 /** 983 * A key describing the attenuation factor allowing to adapt the dynamics of the output to the 984 * actual listening requirements. 985 * See {@link #KEY_AAC_DRC_BOOST_FACTOR} for a description of the role of this attenuation 986 * factor and the value range. 987 * <p>The default value is 127 (fully apply attenuation DRC gains). 988 * <p>This key is only used during decoding. 989 */ 990 public static final String KEY_AAC_DRC_ATTENUATION_FACTOR = "aac-drc-cut-level"; 991 992 /** 993 * A key describing the selection of the heavy compression profile for MPEG-4 DRC. 994 * <p>Two separate DRC gain sequences can be transmitted in one bitstream: light compression 995 * and heavy compression. When selecting the application of the heavy compression, one of 996 * the sequences is selected: 997 * <ul> 998 * <li>0 enables light compression,</li> 999 * <li>1 enables heavy compression instead. 1000 * </ul> 1001 * Note that heavy compression doesn't offer the features of scaling of DRC gains 1002 * (see {@link #KEY_AAC_DRC_BOOST_FACTOR} and {@link #KEY_AAC_DRC_ATTENUATION_FACTOR} for the 1003 * boost and attenuation factors), and frequency-selective (multiband) DRC. 1004 * Light compression usually contains clipping prevention for stereo downmixing while heavy 1005 * compression, if additionally provided in the bitstream, is usually stronger, and contains 1006 * clipping prevention for stereo and mono downmixing. 1007 * <p>The default is 1 (heavy compression). 1008 * <p>This key is only used during decoding. 1009 */ 1010 public static final String KEY_AAC_DRC_HEAVY_COMPRESSION = "aac-drc-heavy-compression"; 1011 1012 /** 1013 * A key to retrieve the output loudness of a decoded bitstream. 1014 * <p>If loudness normalization is active, the value corresponds to the Target Reference Level 1015 * (see {@link #KEY_AAC_DRC_TARGET_REFERENCE_LEVEL}).<br> 1016 * If loudness normalization is not active, the value corresponds to the loudness metadata 1017 * given in the bitstream. 1018 * <p>The value is retrieved with getInteger() and is given as an integer value between 0 and 1019 * 231. It is calculated as -4 * Output Loudness in LKFS. Therefore, it represents the range of 1020 * 0 to -57.75 LKFS. 1021 * <p>A value of -1 indicates that no loudness metadata is present in the bitstream. 1022 * <p>Loudness metadata can originate from MPEG-4 DRC or MPEG-D DRC. 1023 * <p>This key is only used during decoding. 1024 */ 1025 public static final String KEY_AAC_DRC_OUTPUT_LOUDNESS = "aac-drc-output-loudness"; 1026 1027 /** 1028 * A key describing the album mode for MPEG-D DRC as defined in ISO/IEC 23003-4. 1029 * <p>The associated value is an integer and can be set to following values: 1030 * <table> 1031 * <tr><th>Value</th><th>Album Mode</th></tr> 1032 * <tr><th>0</th><th>disabled</th></tr> 1033 * <tr><th>1</th><th>enabled</th></tr> 1034 * </table> 1035 * <p>Disabled album mode leads to application of gain sequences for fading in and out, if 1036 * provided in the bitstream. Enabled album mode makes use of dedicated album loudness 1037 * information, if provided in the bitstream. 1038 * <p>The default value is 0 (album mode disabled). 1039 * <p>This key is only used during decoding. 1040 */ 1041 public static final String KEY_AAC_DRC_ALBUM_MODE = "aac-drc-album-mode"; 1042 1043 /** 1044 * A key describing the FLAC compression level to be used (FLAC audio format only). 1045 * The associated value is an integer ranging from 0 (fastest, least compression) 1046 * to 8 (slowest, most compression). 1047 */ 1048 public static final String KEY_FLAC_COMPRESSION_LEVEL = "flac-compression-level"; 1049 1050 /** 1051 * A key describing the MPEG-H stream profile-level indication. 1052 * 1053 * See ISO_IEC_23008-3;2019 MHADecoderConfigurationRecord mpegh3daProfileLevelIndication. 1054 */ 1055 public static final String KEY_MPEGH_PROFILE_LEVEL_INDICATION = 1056 "mpegh-profile-level-indication"; 1057 1058 /** 1059 * A key describing the MPEG-H stream compatible sets. 1060 * 1061 * See FDAmd_2 of ISO_IEC_23008-3;2019 MHAProfileAndLevelCompatibilitySetBox. 1062 */ 1063 public static final String KEY_MPEGH_COMPATIBLE_SETS = "mpegh-compatible-sets"; 1064 1065 /** 1066 * A key describing the MPEG-H stream reference channel layout. 1067 * 1068 * See ISO_IEC_23008-3;2019 MHADecoderConfigurationRecord referenceChannelLayout 1069 * and ISO_IEC_23001‐8 ChannelConfiguration value. 1070 */ 1071 public static final String KEY_MPEGH_REFERENCE_CHANNEL_LAYOUT = 1072 "mpegh-reference-channel-layout"; 1073 1074 /** 1075 * A key describing the encoding complexity. 1076 * The associated value is an integer. These values are device and codec specific, 1077 * but lower values generally result in faster and/or less power-hungry encoding. 1078 * 1079 * @see MediaCodecInfo.EncoderCapabilities#getComplexityRange() 1080 */ 1081 public static final String KEY_COMPLEXITY = "complexity"; 1082 1083 /** 1084 * A key describing the desired encoding quality. 1085 * The associated value is an integer. This key is only supported for encoders 1086 * that are configured in constant-quality mode. These values are device and 1087 * codec specific, but lower values generally result in more efficient 1088 * (smaller-sized) encoding. 1089 * 1090 * @see MediaCodecInfo.EncoderCapabilities#getQualityRange() 1091 */ 1092 public static final String KEY_QUALITY = "quality"; 1093 1094 /** 1095 * A key describing the desired codec priority. 1096 * <p> 1097 * The associated value is an integer. Higher value means lower priority. 1098 * <p> 1099 * Currently, only two levels are supported:<br> 1100 * 0: realtime priority - meaning that the codec shall support the given 1101 * performance configuration (e.g. framerate) at realtime. This should 1102 * only be used by media playback, capture, and possibly by realtime 1103 * communication scenarios if best effort performance is not suitable.<br> 1104 * 1: non-realtime priority (best effort). 1105 * <p> 1106 * This is a hint used at codec configuration and resource planning - to understand 1107 * the realtime requirements of the application; however, due to the nature of 1108 * media components, performance is not guaranteed. 1109 * 1110 */ 1111 public static final String KEY_PRIORITY = "priority"; 1112 1113 /** 1114 * A key describing the desired operating frame rate for video or sample rate for audio 1115 * that the codec will need to operate at. 1116 * <p> 1117 * The associated value is an integer or a float representing frames-per-second or 1118 * samples-per-second 1119 * <p> 1120 * This is used for cases like high-speed/slow-motion video capture, where the video encoder 1121 * format contains the target playback rate (e.g. 30fps), but the component must be able to 1122 * handle the high operating capture rate (e.g. 240fps). 1123 * <p> 1124 * This rate will be used by codec for resource planning and setting the operating points. 1125 * 1126 */ 1127 public static final String KEY_OPERATING_RATE = "operating-rate"; 1128 1129 /** 1130 * A key describing the desired profile to be used by an encoder. 1131 * <p> 1132 * The associated value is an integer. 1133 * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}. 1134 * This key is used as a hint, and is only supported for codecs 1135 * that specify a profile. When configuring profile, encoder configuration 1136 * may fail if other parameters are not compatible with the desired 1137 * profile or if the desired profile is not supported, but it may also 1138 * fail silently (where the encoder ends up using a different, compatible profile.) 1139 * <p> 1140 * It is recommended that the profile is set for all encoders. For more information, see 1141 * the <i>Encoder Profiles</i> section of the {@link MediaCodec} API reference. 1142 * <p class="note"> 1143 * <strong>Note:</strong> Codecs are free to use all the available 1144 * coding tools at the specified profile, but may ultimately choose to not do so. 1145 * <p class="note"> 1146 * <strong>Note:</strong> When configuring video encoders, profile (if set) must be 1147 * set together with {@link #KEY_LEVEL level}. 1148 * 1149 * @see MediaCodecInfo.CodecCapabilities#profileLevels 1150 */ 1151 public static final String KEY_PROFILE = "profile"; 1152 1153 /** 1154 * A key describing the desired profile to be used by an encoder. 1155 * <p> 1156 * The associated value is an integer. 1157 * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}. 1158 * This key is used as a further hint when specifying a desired profile, 1159 * and is only supported for codecs that specify a level. 1160 * <p> 1161 * This key is ignored if the {@link #KEY_PROFILE profile} is not specified. 1162 * Otherwise, the value should be a level compatible with the configured encoding 1163 * parameters. 1164 * <p class="note"> 1165 * <strong>Note:</strong> This key cannot be used to constrain the encoder's 1166 * output to a maximum encoding level. Encoders are free to target a different 1167 * level if the configured encoding parameters dictate it. Nevertheless, 1168 * encoders shall use (and encode) a level sufficient to decode the generated 1169 * bitstream, though they may exceed the (Video) Buffering Verifier limits for 1170 * that encoded level. 1171 * 1172 * @see MediaCodecInfo.CodecCapabilities#profileLevels 1173 */ 1174 public static final String KEY_LEVEL = "level"; 1175 1176 /** 1177 * An optional key describing the desired encoder latency in frames. This is an optional 1178 * parameter that applies only to video encoders. If encoder supports it, it should ouput 1179 * at least one output frame after being queued the specified number of frames. This key 1180 * is ignored if the video encoder does not support the latency feature. Use the output 1181 * format to verify that this feature was enabled and the actual value used by the encoder. 1182 * <p> 1183 * If the key is not specified, the default latency will be implenmentation specific. 1184 * The associated value is an integer. 1185 */ 1186 public static final String KEY_LATENCY = "latency"; 1187 1188 /** 1189 * An optional key describing the maximum number of non-display-order coded frames. 1190 * This is an optional parameter that applies only to video encoders. Application should 1191 * check the value for this key in the output format to see if codec will produce 1192 * non-display-order coded frames. If encoder supports it, the output frames' order will be 1193 * different from the display order and each frame's display order could be retrived from 1194 * {@link MediaCodec.BufferInfo#presentationTimeUs}. Before API level 27, application may 1195 * receive non-display-order coded frames even though the application did not request it. 1196 * Note: Application should not rearrange the frames to display order before feeding them 1197 * to {@link MediaMuxer#writeSampleData}. 1198 * <p> 1199 * The default value is 0. 1200 */ 1201 public static final String KEY_OUTPUT_REORDER_DEPTH = "output-reorder-depth"; 1202 1203 /** 1204 * A key describing the desired clockwise rotation on an output surface. 1205 * This key is only used when the codec is configured using an output surface. 1206 * The associated value is an integer, representing degrees. Supported values 1207 * are 0, 90, 180 or 270. This is an optional field; if not specified, rotation 1208 * defaults to 0. 1209 * 1210 * @see MediaCodecInfo.CodecCapabilities#profileLevels 1211 */ 1212 public static final String KEY_ROTATION = "rotation-degrees"; 1213 1214 /** 1215 * A key describing the desired bitrate mode to be used by an encoder. 1216 * Constants are declared in {@link MediaCodecInfo.EncoderCapabilities}. 1217 * 1218 * @see MediaCodecInfo.EncoderCapabilities#isBitrateModeSupported(int) 1219 */ 1220 public static final String KEY_BITRATE_MODE = "bitrate-mode"; 1221 1222 /** 1223 * A key describing the maximum Quantization Parameter allowed for encoding video. 1224 * This key applies to all three video picture types (I, P, and B). 1225 * The value is used directly for picture type I; a per-mime formula is used 1226 * to calculate the value for the remaining picture types. 1227 * 1228 * This calculation can be avoided by directly specifying values for each picture type 1229 * using the type-specific keys {@link #KEY_VIDEO_QP_I_MAX}, {@link #KEY_VIDEO_QP_P_MAX}, 1230 * and {@link #KEY_VIDEO_QP_B_MAX}. 1231 * 1232 * The associated value is an integer. 1233 */ 1234 public static final String KEY_VIDEO_QP_MAX = "video-qp-max"; 1235 1236 /** 1237 * A key describing the minimum Quantization Parameter allowed for encoding video. 1238 * This key applies to all three video frame types (I, P, and B). 1239 * The value is used directly for picture type I; a per-mime formula is used 1240 * to calculate the value for the remaining picture types. 1241 * 1242 * This calculation can be avoided by directly specifying values for each picture type 1243 * using the type-specific keys {@link #KEY_VIDEO_QP_I_MIN}, {@link #KEY_VIDEO_QP_P_MIN}, 1244 * and {@link #KEY_VIDEO_QP_B_MIN}. 1245 * 1246 * The associated value is an integer. 1247 */ 1248 public static final String KEY_VIDEO_QP_MIN = "video-qp-min"; 1249 1250 /** 1251 * A key describing the maximum Quantization Parameter allowed for encoding video. 1252 * This value applies to video I-frames. 1253 * 1254 * The associated value is an integer. 1255 */ 1256 public static final String KEY_VIDEO_QP_I_MAX = "video-qp-i-max"; 1257 1258 /** 1259 * A key describing the minimum Quantization Parameter allowed for encoding video. 1260 * This value applies to video I-frames. 1261 * 1262 * The associated value is an integer. 1263 */ 1264 public static final String KEY_VIDEO_QP_I_MIN = "video-qp-i-min"; 1265 1266 /** 1267 * A key describing the maximum Quantization Parameter allowed for encoding video. 1268 * This value applies to video P-frames. 1269 * 1270 * The associated value is an integer. 1271 */ 1272 public static final String KEY_VIDEO_QP_P_MAX = "video-qp-p-max"; 1273 1274 /** 1275 * A key describing the minimum Quantization Parameter allowed for encoding video. 1276 * This value applies to video P-frames. 1277 * 1278 * The associated value is an integer. 1279 */ 1280 public static final String KEY_VIDEO_QP_P_MIN = "video-qp-p-min"; 1281 1282 /** 1283 * A key describing the maximum Quantization Parameter allowed for encoding video. 1284 * This value applies to video B-frames. 1285 * 1286 * The associated value is an integer. 1287 */ 1288 public static final String KEY_VIDEO_QP_B_MAX = "video-qp-b-max"; 1289 1290 /** 1291 * A key describing the minimum Quantization Parameter allowed for encoding video. 1292 * This value applies to video B-frames. 1293 * 1294 * The associated value is an integer. 1295 */ 1296 public static final String KEY_VIDEO_QP_B_MIN = "video-qp-b-min"; 1297 1298 /** 1299 * A key describing the level of encoding statistics information emitted from video encoder. 1300 * 1301 * The associated value is an integer. 1302 */ 1303 public static final String KEY_VIDEO_ENCODING_STATISTICS_LEVEL = 1304 "video-encoding-statistics-level"; 1305 1306 /** 1307 * Encoding Statistics Level None. 1308 * Encoder generates no information about Encoding statistics. 1309 */ 1310 public static final int VIDEO_ENCODING_STATISTICS_LEVEL_NONE = 0; 1311 1312 /** 1313 * Encoding Statistics Level 1. 1314 * Encoder generates {@link MediaFormat#KEY_PICTURE_TYPE} and 1315 * {@link MediaFormat#KEY_VIDEO_QP_AVERAGE} for each frame. 1316 */ 1317 public static final int VIDEO_ENCODING_STATISTICS_LEVEL_1 = 1; 1318 1319 /** @hide */ 1320 @IntDef({ 1321 VIDEO_ENCODING_STATISTICS_LEVEL_NONE, 1322 VIDEO_ENCODING_STATISTICS_LEVEL_1, 1323 }) 1324 @Retention(RetentionPolicy.SOURCE) 1325 public @interface VideoEncodingStatisticsLevel {} 1326 1327 /** 1328 * A key describing the per-frame average block QP (Quantization Parameter). 1329 * This is a part of a video 'Encoding Statistics' export feature. 1330 * This value is emitted from video encoder for a video frame. 1331 * The average value is rounded to the nearest integer value. 1332 * 1333 * The associated value is an integer. 1334 */ 1335 public static final String KEY_VIDEO_QP_AVERAGE = "video-qp-average"; 1336 1337 /** 1338 * A key describing the picture type of the encoded frame. 1339 * This is a part of a video 'Encoding Statistics' export feature. 1340 * This value is emitted from video encoder for a video frame. 1341 * 1342 * The associated value is an integer. 1343 */ 1344 public static final String KEY_PICTURE_TYPE = "picture-type"; 1345 1346 /** Picture Type is unknown. */ 1347 public static final int PICTURE_TYPE_UNKNOWN = 0; 1348 1349 /** Picture Type is I Frame. */ 1350 public static final int PICTURE_TYPE_I = 1; 1351 1352 /** Picture Type is P Frame. */ 1353 public static final int PICTURE_TYPE_P = 2; 1354 1355 /** Picture Type is B Frame. */ 1356 public static final int PICTURE_TYPE_B = 3; 1357 1358 /** @hide */ 1359 @IntDef({ 1360 PICTURE_TYPE_UNKNOWN, 1361 PICTURE_TYPE_I, 1362 PICTURE_TYPE_P, 1363 PICTURE_TYPE_B, 1364 }) 1365 @Retention(RetentionPolicy.SOURCE) 1366 public @interface PictureType {} 1367 1368 /** 1369 * A key describing the audio session ID of the AudioTrack associated 1370 * to a tunneled video codec. 1371 * The associated value is an integer. 1372 * 1373 * @see MediaCodecInfo.CodecCapabilities#FEATURE_TunneledPlayback 1374 */ 1375 public static final String KEY_AUDIO_SESSION_ID = "audio-session-id"; 1376 1377 /** 1378 * A key describing the audio hardware sync ID of the AudioTrack associated 1379 * to a tunneled video codec. The associated value is an integer. 1380 * 1381 * @hide 1382 * 1383 * @see MediaCodecInfo.CodecCapabilities#FEATURE_TunneledPlayback 1384 * @see AudioManager#getAudioHwSyncForSession 1385 */ 1386 public static final String KEY_AUDIO_HW_SYNC = "audio-hw-sync"; 1387 1388 /** 1389 * A key for boolean AUTOSELECT behavior for the track. Tracks with AUTOSELECT=true 1390 * are considered when automatically selecting a track without specific user 1391 * choice, based on the current locale. 1392 * This is currently only used for subtitle tracks, when the user selected 1393 * 'Default' for the captioning locale. 1394 * The associated value is an integer, where non-0 means TRUE. This is an optional 1395 * field; if not specified, AUTOSELECT defaults to TRUE. 1396 */ 1397 public static final String KEY_IS_AUTOSELECT = "is-autoselect"; 1398 1399 /** 1400 * A key for boolean DEFAULT behavior for the track. The track with DEFAULT=true is 1401 * selected in the absence of a specific user choice. 1402 * This is currently used in two scenarios: 1403 * 1) for subtitle tracks, when the user selected 'Default' for the captioning locale. 1404 * 2) for a {@link #MIMETYPE_IMAGE_ANDROID_HEIC} / {@link #MIMETYPE_IMAGE_AVIF} track, 1405 * indicating the image is the primary item in the file. 1406 * 1407 * The associated value is an integer, where non-0 means TRUE. This is an optional 1408 * field; if not specified, DEFAULT is considered to be FALSE. 1409 */ 1410 public static final String KEY_IS_DEFAULT = "is-default"; 1411 1412 /** 1413 * A key for the FORCED field for subtitle tracks. True if it is a 1414 * forced subtitle track. Forced subtitle tracks are essential for the 1415 * content and are shown even when the user turns off Captions. They 1416 * are used for example to translate foreign/alien dialogs or signs. 1417 * The associated value is an integer, where non-0 means TRUE. This is an 1418 * optional field; if not specified, FORCED defaults to FALSE. 1419 */ 1420 public static final String KEY_IS_FORCED_SUBTITLE = "is-forced-subtitle"; 1421 1422 /** 1423 * A key describing the number of haptic channels in an audio format. 1424 * The associated value is an integer. 1425 */ 1426 public static final String KEY_HAPTIC_CHANNEL_COUNT = "haptic-channel-count"; 1427 1428 /** @hide */ 1429 public static final String KEY_IS_TIMED_TEXT = "is-timed-text"; 1430 1431 // The following color aspect values must be in sync with the ones in HardwareAPI.h. 1432 /** 1433 * An optional key describing the color primaries, white point and 1434 * luminance factors for video content. 1435 * 1436 * The associated value is an integer: 0 if unspecified, or one of the 1437 * COLOR_STANDARD_ values. 1438 */ 1439 public static final String KEY_COLOR_STANDARD = "color-standard"; 1440 1441 /** BT.709 color chromacity coordinates with KR = 0.2126, KB = 0.0722. */ 1442 public static final int COLOR_STANDARD_BT709 = 1; 1443 1444 /** BT.601 625 color chromacity coordinates with KR = 0.299, KB = 0.114. */ 1445 public static final int COLOR_STANDARD_BT601_PAL = 2; 1446 1447 /** BT.601 525 color chromacity coordinates with KR = 0.299, KB = 0.114. */ 1448 public static final int COLOR_STANDARD_BT601_NTSC = 4; 1449 1450 /** BT.2020 color chromacity coordinates with KR = 0.2627, KB = 0.0593. */ 1451 public static final int COLOR_STANDARD_BT2020 = 6; 1452 1453 /** @hide */ 1454 @IntDef({ 1455 COLOR_STANDARD_BT709, 1456 COLOR_STANDARD_BT601_PAL, 1457 COLOR_STANDARD_BT601_NTSC, 1458 COLOR_STANDARD_BT2020, 1459 }) 1460 @Retention(RetentionPolicy.SOURCE) 1461 public @interface ColorStandard {} 1462 1463 /** 1464 * An optional key describing the opto-electronic transfer function used 1465 * for the video content. 1466 * 1467 * The associated value is an integer: 0 if unspecified, or one of the 1468 * COLOR_TRANSFER_ values. 1469 */ 1470 public static final String KEY_COLOR_TRANSFER = "color-transfer"; 1471 1472 /** Linear transfer characteristic curve. */ 1473 public static final int COLOR_TRANSFER_LINEAR = 1; 1474 1475 /** SMPTE 170M transfer characteristic curve used by BT.601/BT.709/BT.2020. This is the curve 1476 * used by most non-HDR video content. */ 1477 public static final int COLOR_TRANSFER_SDR_VIDEO = 3; 1478 1479 /** SMPTE ST 2084 transfer function. This is used by some HDR video content. */ 1480 public static final int COLOR_TRANSFER_ST2084 = 6; 1481 1482 /** ARIB STD-B67 hybrid-log-gamma transfer function. This is used by some HDR video content. */ 1483 public static final int COLOR_TRANSFER_HLG = 7; 1484 1485 /** @hide */ 1486 @IntDef({ 1487 COLOR_TRANSFER_LINEAR, 1488 COLOR_TRANSFER_SDR_VIDEO, 1489 COLOR_TRANSFER_ST2084, 1490 COLOR_TRANSFER_HLG, 1491 }) 1492 @Retention(RetentionPolicy.SOURCE) 1493 public @interface ColorTransfer {} 1494 1495 /** 1496 * An optional key describing the range of the component values of the video content. 1497 * 1498 * The associated value is an integer: 0 if unspecified, or one of the 1499 * COLOR_RANGE_ values. 1500 */ 1501 public static final String KEY_COLOR_RANGE = "color-range"; 1502 1503 /** Limited range. Y component values range from 16 to 235 for 8-bit content. 1504 * Cr, Cy values range from 16 to 240 for 8-bit content. 1505 * This is the default for video content. */ 1506 public static final int COLOR_RANGE_LIMITED = 2; 1507 1508 /** Full range. Y, Cr and Cb component values range from 0 to 255 for 8-bit content. */ 1509 public static final int COLOR_RANGE_FULL = 1; 1510 1511 /** @hide */ 1512 @IntDef({ 1513 COLOR_RANGE_LIMITED, 1514 COLOR_RANGE_FULL, 1515 }) 1516 @Retention(RetentionPolicy.SOURCE) 1517 public @interface ColorRange {} 1518 1519 /** 1520 * An optional key describing the static metadata of HDR (high-dynamic-range) video content. 1521 * 1522 * The associated value is a ByteBuffer. This buffer contains the raw contents of the 1523 * Static Metadata Descriptor (including the descriptor ID) of an HDMI Dynamic Range and 1524 * Mastering InfoFrame as defined by CTA-861.3. This key must be provided to video decoders 1525 * for HDR video content unless this information is contained in the bitstream and the video 1526 * decoder supports an HDR-capable profile. This key must be provided to video encoders for 1527 * HDR video content. 1528 */ 1529 public static final String KEY_HDR_STATIC_INFO = "hdr-static-info"; 1530 1531 /** 1532 * An optional key describing the HDR10+ metadata of the video content. 1533 * 1534 * The associated value is a ByteBuffer containing HDR10+ metadata conforming to the 1535 * user_data_registered_itu_t_t35() syntax of SEI message for ST 2094-40. This key will 1536 * be present on: 1537 *<p> 1538 * - The formats of output buffers of a decoder configured for HDR10+ profiles (such as 1539 * {@link MediaCodecInfo.CodecProfileLevel#VP9Profile2HDR10Plus}, {@link 1540 * MediaCodecInfo.CodecProfileLevel#VP9Profile3HDR10Plus} or {@link 1541 * MediaCodecInfo.CodecProfileLevel#HEVCProfileMain10HDR10Plus}), or 1542 *<p> 1543 * - The formats of output buffers of an encoder configured for an HDR10+ profiles that 1544 * uses out-of-band metadata (such as {@link 1545 * MediaCodecInfo.CodecProfileLevel#VP9Profile2HDR10Plus} or {@link 1546 * MediaCodecInfo.CodecProfileLevel#VP9Profile3HDR10Plus}). 1547 * 1548 * @see MediaCodec#PARAMETER_KEY_HDR10_PLUS_INFO 1549 */ 1550 public static final String KEY_HDR10_PLUS_INFO = "hdr10-plus-info"; 1551 1552 /** 1553 * An optional key describing the opto-electronic transfer function 1554 * requested for the output video content. 1555 * 1556 * The associated value is an integer: 0 if unspecified, or one of the 1557 * COLOR_TRANSFER_ values. When unspecified the component will not touch the 1558 * video content; otherwise the component will tone-map the raw video frame 1559 * to match the requested transfer function. 1560 * 1561 * After configure, component's input format will contain this key to note 1562 * whether the request is supported or not. If the value in the input format 1563 * is the same as the requested value, the request is supported. The value 1564 * is set to 0 if unsupported. 1565 */ 1566 public static final String KEY_COLOR_TRANSFER_REQUEST = "color-transfer-request"; 1567 1568 /** 1569 * A key describing a unique ID for the content of a media track. 1570 * 1571 * <p>This key is used by {@link MediaExtractor}. Some extractors provide multiple encodings 1572 * of the same track (e.g. float audio tracks for FLAC and WAV may be expressed as two 1573 * tracks via MediaExtractor: a normal PCM track for backward compatibility, and a float PCM 1574 * track for added fidelity. Similarly, Dolby Vision extractor may provide a baseline SDR 1575 * version of a DV track.) This key can be used to identify which MediaExtractor tracks refer 1576 * to the same underlying content. 1577 * </p> 1578 * 1579 * The associated value is an integer. 1580 */ 1581 public static final String KEY_TRACK_ID = "track-id"; 1582 1583 /** 1584 * A key describing the system id of the conditional access system used to scramble 1585 * a media track. 1586 * <p> 1587 * This key is set by {@link MediaExtractor} if the track is scrambled with a conditional 1588 * access system, regardless of the presence of a valid {@link MediaCas} object. 1589 * <p> 1590 * The associated value is an integer. 1591 * @hide 1592 */ 1593 public static final String KEY_CA_SYSTEM_ID = "ca-system-id"; 1594 1595 /** 1596 * A key describing the {@link MediaCas.Session} object associated with a media track. 1597 * <p> 1598 * This key is set by {@link MediaExtractor} if the track is scrambled with a conditional 1599 * access system, after it receives a valid {@link MediaCas} object. 1600 * <p> 1601 * The associated value is a ByteBuffer. 1602 * @hide 1603 */ 1604 public static final String KEY_CA_SESSION_ID = "ca-session-id"; 1605 1606 /** 1607 * A key describing the private data in the CA_descriptor associated with a media track. 1608 * <p> 1609 * This key is set by {@link MediaExtractor} if the track is scrambled with a conditional 1610 * access system, before it receives a valid {@link MediaCas} object. 1611 * <p> 1612 * The associated value is a ByteBuffer. 1613 * @hide 1614 */ 1615 public static final String KEY_CA_PRIVATE_DATA = "ca-private-data"; 1616 1617 /** 1618 * A key describing the maximum number of B frames between I or P frames, 1619 * to be used by a video encoder. 1620 * The associated value is an integer. The default value is 0, which means 1621 * that no B frames are allowed. Note that non-zero value does not guarantee 1622 * B frames; it's up to the encoder to decide. 1623 */ 1624 public static final String KEY_MAX_B_FRAMES = "max-bframes"; 1625 1626 /** 1627 * A key for applications to opt out of allowing 1628 * a Surface to discard undisplayed/unconsumed frames 1629 * as means to catch up after falling behind. 1630 * This value is an integer. 1631 * The value 0 indicates the surface is not allowed to drop frames. 1632 * The value 1 indicates the surface is allowed to drop frames. 1633 * 1634 * {@link MediaCodec} describes the semantics. 1635 */ 1636 public static final String KEY_ALLOW_FRAME_DROP = "allow-frame-drop"; 1637 MediaFormat(@onNull Map<String, Object> map)1638 /* package private */ MediaFormat(@NonNull Map<String, Object> map) { 1639 mMap = map; 1640 } 1641 1642 /** 1643 * Creates an empty MediaFormat 1644 */ MediaFormat()1645 public MediaFormat() { 1646 mMap = new HashMap(); 1647 } 1648 1649 @UnsupportedAppUsage getMap()1650 /* package private */ Map<String, Object> getMap() { 1651 return mMap; 1652 } 1653 1654 /** 1655 * Returns true iff a key of the given name exists in the format. 1656 */ containsKey(@onNull String name)1657 public final boolean containsKey(@NonNull String name) { 1658 return mMap.containsKey(name); 1659 } 1660 1661 /** 1662 * Returns true iff a feature of the given name exists in the format. 1663 */ containsFeature(@onNull String name)1664 public final boolean containsFeature(@NonNull String name) { 1665 return mMap.containsKey(KEY_FEATURE_ + name); 1666 } 1667 1668 public static final int TYPE_NULL = 0; 1669 public static final int TYPE_INTEGER = 1; 1670 public static final int TYPE_LONG = 2; 1671 public static final int TYPE_FLOAT = 3; 1672 public static final int TYPE_STRING = 4; 1673 public static final int TYPE_BYTE_BUFFER = 5; 1674 1675 /** @hide */ 1676 @IntDef({ 1677 TYPE_NULL, 1678 TYPE_INTEGER, 1679 TYPE_LONG, 1680 TYPE_FLOAT, 1681 TYPE_STRING, 1682 TYPE_BYTE_BUFFER 1683 }) 1684 @Retention(RetentionPolicy.SOURCE) 1685 public @interface Type {} 1686 1687 /** 1688 * Returns the value type for a key. If the key does not exist, it returns TYPE_NULL. 1689 */ getValueTypeForKey(@onNull String name)1690 public final @Type int getValueTypeForKey(@NonNull String name) { 1691 Object value = mMap.get(name); 1692 if (value == null) { 1693 return TYPE_NULL; 1694 } else if (value instanceof Integer) { 1695 return TYPE_INTEGER; 1696 } else if (value instanceof Long) { 1697 return TYPE_LONG; 1698 } else if (value instanceof Float) { 1699 return TYPE_FLOAT; 1700 } else if (value instanceof String) { 1701 return TYPE_STRING; 1702 } else if (value instanceof ByteBuffer) { 1703 return TYPE_BYTE_BUFFER; 1704 } 1705 throw new RuntimeException("invalid value for key"); 1706 } 1707 1708 /** 1709 * A key prefix used together with a {@link MediaCodecInfo.CodecCapabilities} 1710 * feature name describing a required or optional feature for a codec capabilities 1711 * query. 1712 * The associated value is an integer, where non-0 value means the feature is 1713 * requested to be present, while 0 value means the feature is requested to be not 1714 * present. 1715 * @see MediaCodecList#findDecoderForFormat 1716 * @see MediaCodecList#findEncoderForFormat 1717 * @see MediaCodecInfo.CodecCapabilities#isFormatSupported 1718 * 1719 * @hide 1720 */ 1721 public static final String KEY_FEATURE_ = "feature-"; 1722 1723 /** 1724 * Returns the value of a numeric key. This is provided as a convenience method for keys 1725 * that may take multiple numeric types, such as {@link #KEY_FRAME_RATE}, or {@link 1726 * #KEY_I_FRAME_INTERVAL}. 1727 * 1728 * @return null if the key does not exist or the stored value for the key is null 1729 * @throws ClassCastException if the stored value for the key is ByteBuffer or String 1730 */ getNumber(@onNull String name)1731 public final @Nullable Number getNumber(@NonNull String name) { 1732 return (Number) mMap.get(name); 1733 } 1734 1735 /** 1736 * Returns the value of a numeric key, or the default value if the key is missing. 1737 * 1738 * @return defaultValue if the key does not exist or the stored value for the key is null 1739 * @throws ClassCastException if the stored value for the key is ByteBuffer or String 1740 */ getNumber(@onNull String name, @NonNull Number defaultValue)1741 public final @NonNull Number getNumber(@NonNull String name, @NonNull Number defaultValue) { 1742 Number ret = getNumber(name); 1743 return ret == null ? defaultValue : ret; 1744 } 1745 1746 /** 1747 * Returns the value of an integer key. 1748 * 1749 * @throws NullPointerException if the key does not exist or the stored value for the key is 1750 * null 1751 * @throws ClassCastException if the stored value for the key is long, float, ByteBuffer or 1752 * String 1753 */ getInteger(@onNull String name)1754 public final int getInteger(@NonNull String name) { 1755 return (int) mMap.get(name); 1756 } 1757 1758 /** 1759 * Returns the value of an integer key, or the default value if the key is missing. 1760 * 1761 * @return defaultValue if the key does not exist or the stored value for the key is null 1762 * @throws ClassCastException if the stored value for the key is long, float, ByteBuffer or 1763 * String 1764 */ getInteger(@onNull String name, int defaultValue)1765 public final int getInteger(@NonNull String name, int defaultValue) { 1766 try { 1767 return getInteger(name); 1768 } catch (NullPointerException e) { 1769 /* no such field or field is null */ 1770 return defaultValue; 1771 } 1772 } 1773 1774 /** 1775 * Returns the value of a long key. 1776 * 1777 * @throws NullPointerException if the key does not exist or the stored value for the key is 1778 * null 1779 * @throws ClassCastException if the stored value for the key is int, float, ByteBuffer or 1780 * String 1781 */ getLong(@onNull String name)1782 public final long getLong(@NonNull String name) { 1783 return (long) mMap.get(name); 1784 } 1785 1786 /** 1787 * Returns the value of a long key, or the default value if the key is missing. 1788 * 1789 * @return defaultValue if the key does not exist or the stored value for the key is null 1790 * @throws ClassCastException if the stored value for the key is int, float, ByteBuffer or 1791 * String 1792 */ getLong(@onNull String name, long defaultValue)1793 public final long getLong(@NonNull String name, long defaultValue) { 1794 try { 1795 return getLong(name); 1796 } catch (NullPointerException e) { 1797 /* no such field or field is null */ 1798 return defaultValue; 1799 } 1800 } 1801 1802 /** 1803 * Returns the value of a float key. 1804 * 1805 * @throws NullPointerException if the key does not exist or the stored value for the key is 1806 * null 1807 * @throws ClassCastException if the stored value for the key is int, long, ByteBuffer or 1808 * String 1809 */ getFloat(@onNull String name)1810 public final float getFloat(@NonNull String name) { 1811 return (float) mMap.get(name); 1812 } 1813 1814 /** 1815 * Returns the value of a float key, or the default value if the key is missing. 1816 * 1817 * @return defaultValue if the key does not exist or the stored value for the key is null 1818 * @throws ClassCastException if the stored value for the key is int, long, ByteBuffer or 1819 * String 1820 */ getFloat(@onNull String name, float defaultValue)1821 public final float getFloat(@NonNull String name, float defaultValue) { 1822 Object value = mMap.get(name); 1823 return value != null ? (float) value : defaultValue; 1824 } 1825 1826 /** 1827 * Returns the value of a string key. 1828 * 1829 * @return null if the key does not exist or the stored value for the key is null 1830 * @throws ClassCastException if the stored value for the key is int, long, float or ByteBuffer 1831 */ getString(@onNull String name)1832 public final @Nullable String getString(@NonNull String name) { 1833 return (String)mMap.get(name); 1834 } 1835 1836 /** 1837 * Returns the value of a string key, or the default value if the key is missing. 1838 * 1839 * @return defaultValue if the key does not exist or the stored value for the key is null 1840 * @throws ClassCastException if the stored value for the key is int, long, float or ByteBuffer 1841 */ getString(@onNull String name, @NonNull String defaultValue)1842 public final @NonNull String getString(@NonNull String name, @NonNull String defaultValue) { 1843 String ret = getString(name); 1844 return ret == null ? defaultValue : ret; 1845 } 1846 1847 /** 1848 * Returns the value of a ByteBuffer key. 1849 * 1850 * @return null if the key does not exist or the stored value for the key is null 1851 * @throws ClassCastException if the stored value for the key is int, long, float or String 1852 */ getByteBuffer(@onNull String name)1853 public final @Nullable ByteBuffer getByteBuffer(@NonNull String name) { 1854 return (ByteBuffer)mMap.get(name); 1855 } 1856 1857 /** 1858 * Returns the value of a ByteBuffer key, or the default value if the key is missing. 1859 * 1860 * @return defaultValue if the key does not exist or the stored value for the key is null 1861 * @throws ClassCastException if the stored value for the key is int, long, float or String 1862 */ getByteBuffer( @onNull String name, @NonNull ByteBuffer defaultValue)1863 public final @NonNull ByteBuffer getByteBuffer( 1864 @NonNull String name, @NonNull ByteBuffer defaultValue) { 1865 ByteBuffer ret = getByteBuffer(name); 1866 return ret == null ? defaultValue : ret; 1867 } 1868 1869 /** 1870 * Returns whether a feature is to be enabled ({@code true}) or disabled 1871 * ({@code false}). 1872 * 1873 * @param feature the name of a {@link MediaCodecInfo.CodecCapabilities} feature. 1874 * 1875 * @throws IllegalArgumentException if the feature was neither set to be enabled 1876 * nor to be disabled. 1877 */ getFeatureEnabled(@onNull String feature)1878 public boolean getFeatureEnabled(@NonNull String feature) { 1879 Integer enabled = (Integer)mMap.get(KEY_FEATURE_ + feature); 1880 if (enabled == null) { 1881 throw new IllegalArgumentException("feature is not specified"); 1882 } 1883 return enabled != 0; 1884 } 1885 1886 /** 1887 * Sets the value of an integer key. 1888 */ setInteger(@onNull String name, int value)1889 public final void setInteger(@NonNull String name, int value) { 1890 mMap.put(name, value); 1891 } 1892 1893 /** 1894 * Sets the value of a long key. 1895 */ setLong(@onNull String name, long value)1896 public final void setLong(@NonNull String name, long value) { 1897 mMap.put(name, value); 1898 } 1899 1900 /** 1901 * Sets the value of a float key. 1902 */ setFloat(@onNull String name, float value)1903 public final void setFloat(@NonNull String name, float value) { 1904 mMap.put(name, value); 1905 } 1906 1907 /** 1908 * Sets the value of a string key. 1909 * <p> 1910 * If value is {@code null}, it sets a null value that behaves similarly to a missing key. 1911 * This could be used prior to API level {@link android os.Build.VERSION_CODES#Q} to effectively 1912 * remove a key. 1913 */ setString(@onNull String name, @Nullable String value)1914 public final void setString(@NonNull String name, @Nullable String value) { 1915 mMap.put(name, value); 1916 } 1917 1918 /** 1919 * Sets the value of a ByteBuffer key. 1920 * <p> 1921 * If value is {@code null}, it sets a null value that behaves similarly to a missing key. 1922 * This could be used prior to API level {@link android os.Build.VERSION_CODES#Q} to effectively 1923 * remove a key. 1924 */ setByteBuffer(@onNull String name, @Nullable ByteBuffer bytes)1925 public final void setByteBuffer(@NonNull String name, @Nullable ByteBuffer bytes) { 1926 mMap.put(name, bytes); 1927 } 1928 1929 /** 1930 * Removes a value of a given key if present. Has no effect if the key is not present. 1931 */ removeKey(@onNull String name)1932 public final void removeKey(@NonNull String name) { 1933 // exclude feature mappings 1934 if (!name.startsWith(KEY_FEATURE_)) { 1935 mMap.remove(name); 1936 } 1937 } 1938 1939 /** 1940 * Removes a given feature setting if present. Has no effect if the feature setting is not 1941 * present. 1942 */ removeFeature(@onNull String name)1943 public final void removeFeature(@NonNull String name) { 1944 mMap.remove(KEY_FEATURE_ + name); 1945 } 1946 1947 /** 1948 * A Partial set view for a portion of the keys in a MediaFormat object. 1949 * 1950 * This class is needed as we want to return a portion of the actual format keys in getKeys() 1951 * and another portion of the keys in getFeatures(), and still allow the view properties. 1952 */ 1953 private abstract class FilteredMappedKeySet extends AbstractSet<String> { 1954 private Set<String> mKeys; 1955 1956 // Returns true if this set should include this key keepKey(String key)1957 abstract protected boolean keepKey(String key); 1958 1959 // Maps a key from the underlying key set into its new value in this key set mapKeyToItem(String key)1960 abstract protected String mapKeyToItem(String key); 1961 1962 // Maps a key from this key set into its original value in the underlying key set mapItemToKey(String item)1963 abstract protected String mapItemToKey(String item); 1964 FilteredMappedKeySet()1965 public FilteredMappedKeySet() { 1966 mKeys = mMap.keySet(); 1967 } 1968 1969 // speed up contains and remove from abstract implementation (that would iterate 1970 // over each element) 1971 @Override contains(Object o)1972 public boolean contains(Object o) { 1973 if (o instanceof String) { 1974 String key = mapItemToKey((String)o); 1975 return keepKey(key) && mKeys.contains(key); 1976 } 1977 return false; 1978 } 1979 1980 @Override remove(Object o)1981 public boolean remove(Object o) { 1982 if (o instanceof String) { 1983 String key = mapItemToKey((String)o); 1984 if (keepKey(key) && mKeys.remove(key)) { 1985 mMap.remove(key); 1986 return true; 1987 } 1988 } 1989 return false; 1990 } 1991 1992 private class KeyIterator implements Iterator<String> { 1993 Iterator<String> mIterator; 1994 String mLast; 1995 KeyIterator()1996 public KeyIterator() { 1997 // We must create a copy of the filtered stream, as remove operation has to modify 1998 // the underlying data structure (mMap), so the iterator's operation is undefined. 1999 // Use a list as it is likely less memory consuming than the other alternative: set. 2000 mIterator = 2001 mKeys.stream().filter(k -> keepKey(k)).collect(Collectors.toList()).iterator(); 2002 } 2003 2004 @Override hasNext()2005 public boolean hasNext() { 2006 return mIterator.hasNext(); 2007 } 2008 2009 @Override next()2010 public String next() { 2011 mLast = mIterator.next(); 2012 return mapKeyToItem(mLast); 2013 } 2014 2015 @Override remove()2016 public void remove() { 2017 mIterator.remove(); 2018 mMap.remove(mLast); 2019 } 2020 } 2021 2022 @Override iterator()2023 public Iterator<String> iterator() { 2024 return new KeyIterator(); 2025 } 2026 2027 @Override size()2028 public int size() { 2029 return (int) mKeys.stream().filter(this::keepKey).count(); 2030 } 2031 } 2032 2033 /** 2034 * A Partial set view for a portion of the keys in a MediaFormat object for keys that 2035 * don't start with a prefix, such as "feature-" 2036 */ 2037 private class UnprefixedKeySet extends FilteredMappedKeySet { 2038 private String mPrefix; 2039 UnprefixedKeySet(String prefix)2040 public UnprefixedKeySet(String prefix) { 2041 super(); 2042 mPrefix = prefix; 2043 } 2044 keepKey(String key)2045 protected boolean keepKey(String key) { 2046 return !key.startsWith(mPrefix); 2047 } 2048 mapKeyToItem(String key)2049 protected String mapKeyToItem(String key) { 2050 return key; 2051 } 2052 mapItemToKey(String item)2053 protected String mapItemToKey(String item) { 2054 return item; 2055 } 2056 } 2057 2058 /** 2059 * A Partial set view for a portion of the keys in a MediaFormat object for keys that 2060 * start with a prefix, such as "feature-", with the prefix removed 2061 */ 2062 private class PrefixedKeySetWithPrefixRemoved extends FilteredMappedKeySet { 2063 private String mPrefix; 2064 private int mPrefixLength; 2065 PrefixedKeySetWithPrefixRemoved(String prefix)2066 public PrefixedKeySetWithPrefixRemoved(String prefix) { 2067 super(); 2068 mPrefix = prefix; 2069 mPrefixLength = prefix.length(); 2070 } 2071 keepKey(String key)2072 protected boolean keepKey(String key) { 2073 return key.startsWith(mPrefix); 2074 } 2075 mapKeyToItem(String key)2076 protected String mapKeyToItem(String key) { 2077 return key.substring(mPrefixLength); 2078 } 2079 mapItemToKey(String item)2080 protected String mapItemToKey(String item) { 2081 return mPrefix + item; 2082 } 2083 } 2084 2085 2086 /** 2087 * Returns a {@link java.util.Set Set} view of the keys contained in this MediaFormat. 2088 * 2089 * The set is backed by the MediaFormat object, so changes to the format are reflected in the 2090 * set, and vice-versa. If the format is modified while an iteration over the set is in progress 2091 * (except through the iterator's own remove operation), the results of the iteration are 2092 * undefined. The set supports element removal, which removes the corresponding mapping from the 2093 * format, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. 2094 * It does not support the add or addAll operations. 2095 */ getKeys()2096 public final @NonNull java.util.Set<String> getKeys() { 2097 return new UnprefixedKeySet(KEY_FEATURE_); 2098 } 2099 2100 /** 2101 * Returns a {@link java.util.Set Set} view of the features contained in this MediaFormat. 2102 * 2103 * The set is backed by the MediaFormat object, so changes to the format are reflected in the 2104 * set, and vice-versa. If the format is modified while an iteration over the set is in progress 2105 * (except through the iterator's own remove operation), the results of the iteration are 2106 * undefined. The set supports element removal, which removes the corresponding mapping from the 2107 * format, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations. 2108 * It does not support the add or addAll operations. 2109 */ getFeatures()2110 public final @NonNull java.util.Set<String> getFeatures() { 2111 return new PrefixedKeySetWithPrefixRemoved(KEY_FEATURE_); 2112 } 2113 2114 /** 2115 * Create a copy of a media format object. 2116 */ MediaFormat(@onNull MediaFormat other)2117 public MediaFormat(@NonNull MediaFormat other) { 2118 this(); 2119 mMap.putAll(other.mMap); 2120 } 2121 2122 /** 2123 * Sets whether a feature is to be enabled ({@code true}) or disabled 2124 * ({@code false}). 2125 * 2126 * If {@code enabled} is {@code true}, the feature is requested to be present. 2127 * Otherwise, the feature is requested to be not present. 2128 * 2129 * @param feature the name of a {@link MediaCodecInfo.CodecCapabilities} feature. 2130 * 2131 * @see MediaCodecList#findDecoderForFormat 2132 * @see MediaCodecList#findEncoderForFormat 2133 * @see MediaCodecInfo.CodecCapabilities#isFormatSupported 2134 */ setFeatureEnabled(@onNull String feature, boolean enabled)2135 public void setFeatureEnabled(@NonNull String feature, boolean enabled) { 2136 setInteger(KEY_FEATURE_ + feature, enabled ? 1 : 0); 2137 } 2138 2139 /** 2140 * Creates a minimal audio format. 2141 * @param mime The mime type of the content. 2142 * @param sampleRate The sampling rate of the content. 2143 * @param channelCount The number of audio channels in the content. 2144 */ createAudioFormat( @onNull String mime, int sampleRate, int channelCount)2145 public static final @NonNull MediaFormat createAudioFormat( 2146 @NonNull String mime, 2147 int sampleRate, 2148 int channelCount) { 2149 MediaFormat format = new MediaFormat(); 2150 format.setString(KEY_MIME, mime); 2151 format.setInteger(KEY_SAMPLE_RATE, sampleRate); 2152 format.setInteger(KEY_CHANNEL_COUNT, channelCount); 2153 2154 return format; 2155 } 2156 2157 /** 2158 * Creates a minimal subtitle format. 2159 * @param mime The mime type of the content. 2160 * @param language The language of the content, using either ISO 639-1 or 639-2/T 2161 * codes. Specify null or "und" if language information is only included 2162 * in the content. (This will also work if there are multiple language 2163 * tracks in the content.) 2164 */ createSubtitleFormat( @onNull String mime, String language)2165 public static final @NonNull MediaFormat createSubtitleFormat( 2166 @NonNull String mime, 2167 String language) { 2168 MediaFormat format = new MediaFormat(); 2169 format.setString(KEY_MIME, mime); 2170 format.setString(KEY_LANGUAGE, language); 2171 2172 return format; 2173 } 2174 2175 /** 2176 * Creates a minimal video format. 2177 * @param mime The mime type of the content. 2178 * @param width The width of the content (in pixels) 2179 * @param height The height of the content (in pixels) 2180 */ createVideoFormat( @onNull String mime, int width, int height)2181 public static final @NonNull MediaFormat createVideoFormat( 2182 @NonNull String mime, 2183 int width, 2184 int height) { 2185 MediaFormat format = new MediaFormat(); 2186 format.setString(KEY_MIME, mime); 2187 format.setInteger(KEY_WIDTH, width); 2188 format.setInteger(KEY_HEIGHT, height); 2189 2190 return format; 2191 } 2192 2193 @Override toString()2194 public @NonNull String toString() { 2195 return mMap.toString(); 2196 } 2197 } 2198
