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