/* * Copyright (C) 2012 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.media; import java.nio.ByteBuffer; import java.util.HashMap; import java.util.Map; /** * Encapsulates the information describing the format of media data, * be it audio or video. * * The format of the media data is specified as string/value pairs. * * Keys common to all audio/video formats, all keys not marked optional are mandatory: * *
Name | Value Type | Description |
---|---|---|
{@link #KEY_MIME} | String | The type of the format. |
{@link #KEY_MAX_INPUT_SIZE} | Integer | optional, maximum size of a buffer of input data |
{@link #KEY_BIT_RATE} | Integer | encoder-only, desired bitrate in bits/second |
Name | Value Type | Description |
---|---|---|
{@link #KEY_WIDTH} | Integer | |
{@link #KEY_HEIGHT} | Integer | |
{@link #KEY_COLOR_FORMAT} | Integer | set by the user * for encoders, readable in the output format of decoders |
{@link #KEY_FRAME_RATE} | Integer or Float | encoder-only |
{@link #KEY_CAPTURE_RATE} | Integer | |
{@link #KEY_I_FRAME_INTERVAL} | Integer | encoder-only |
{@link #KEY_MAX_WIDTH} | Integer | decoder-only, optional, max-resolution width |
{@link #KEY_MAX_HEIGHT} | Integer | decoder-only, optional, max-resolution height |
{@link #KEY_REPEAT_PREVIOUS_FRAME_AFTER} | Long | video encoder in surface-mode only |
{@link #KEY_PUSH_BLANK_BUFFERS_ON_STOP} | Integer(1) | video decoder rendering to a surface only |
Name | Value Type | Description |
---|---|---|
{@link #KEY_CHANNEL_COUNT} | Integer | |
{@link #KEY_SAMPLE_RATE} | Integer | |
{@link #KEY_IS_ADTS} | Integer | optional, if decoding AAC audio content, setting this key to 1 indicates that each audio frame is prefixed by the ADTS header. |
{@link #KEY_AAC_PROFILE} | Integer | encoder-only, optional, if content is AAC audio, specifies the desired profile. |
{@link #KEY_AAC_SBR_MODE} | Integer | encoder-only, optional, if content is AAC audio, specifies the desired SBR mode. |
{@link #KEY_AAC_DRC_TARGET_REFERENCE_LEVEL} | Integer | decoder-only, optional, if content is AAC audio, specifies the target reference level. |
{@link #KEY_AAC_ENCODED_TARGET_LEVEL} | Integer | decoder-only, optional, if content is AAC audio, specifies the target reference level used at encoder. |
{@link #KEY_AAC_DRC_BOOST_FACTOR} | Integer | decoder-only, optional, if content is AAC audio, specifies the DRC boost factor. |
{@link #KEY_AAC_DRC_ATTENUATION_FACTOR} | Integer | decoder-only, optional, if content is AAC audio, specifies the DRC attenuation factor. |
{@link #KEY_AAC_DRC_HEAVY_COMPRESSION} | Integer | decoder-only, optional, if content is AAC audio, specifies whether to use heavy compression. |
{@link #KEY_AAC_MAX_OUTPUT_CHANNEL_COUNT} | Integer | decoder-only, optional, if content is AAC audio, specifies the maximum number of channels the decoder outputs. |
{@link #KEY_CHANNEL_MASK} | Integer | optional, a mask of audio channel assignments |
{@link #KEY_FLAC_COMPRESSION_LEVEL} | Integer | encoder-only, optional, if content is FLAC audio, specifies the desired compression level. |
{@link #KEY_MIME} | String | The type of the format. |
{@link #KEY_LANGUAGE} | String | The language of the content. |
* When capture rate is different than the frame rate, it means that the * video is acquired at a different rate than the playback, which produces * slow motion or timelapse effect during playback. Application can use the * value of this key to tell the relative speed ratio between capture and * playback rates when the video was recorded. *
** The associated value is an integer or a float. *
*/ public static final String KEY_CAPTURE_RATE = "capture-rate"; /** * A key describing the frequency of I frames expressed in secs * between I frames. * The associated value is an integer. */ public static final String KEY_I_FRAME_INTERVAL = "i-frame-interval"; /** * A key describing the temporal layering schema. This is an optional parameter * that applies only to video encoders. Use {@link MediaCodec#getInputFormat} * after {@link MediaCodec#configure configure} to query if the encoder supports * the desired schema. Supported values are {@code webrtc.vp8.1-layer}, * {@code webrtc.vp8.2-layer}, {@code webrtc.vp8.3-layer}, and {@code none}. * If the encoder does not support temporal layering, the input format will * not have an entry with this key. * The associated value is a string. */ public static final String KEY_TEMPORAL_LAYERING = "ts-schema"; /** * A key describing the stride of the video bytebuffer layout. * Stride (or row increment) is the difference between the index of a pixel * and that of the pixel directly underneath. For YUV 420 formats, the * stride corresponds to the Y plane; the stride of the U and V planes can * be calculated based on the color format. * The associated value is an integer, representing number of bytes. */ public static final String KEY_STRIDE = "stride"; /** * A key describing the plane height of a multi-planar (YUV) video bytebuffer layout. * Slice height (or plane height) is the number of rows that must be skipped to get * from the top of the Y plane to the top of the U plane in the bytebuffer. In essence * the offset of the U plane is sliceHeight * stride. The height of the U/V planes * can be calculated based on the color format. * The associated value is an integer, representing number of rows. */ public static final String KEY_SLICE_HEIGHT = "slice-height"; /** * Applies only when configuring a video encoder in "surface-input" mode. * The associated value is a long and gives the time in microseconds * after which the frame previously submitted to the encoder will be * repeated (once) if no new frame became available since. */ public static final String KEY_REPEAT_PREVIOUS_FRAME_AFTER = "repeat-previous-frame-after"; /** * If specified when configuring a video decoder rendering to a surface, * causes the decoder to output "blank", i.e. black frames to the surface * when stopped to clear out any previously displayed contents. * The associated value is an integer of value 1. */ public static final String KEY_PUSH_BLANK_BUFFERS_ON_STOP = "push-blank-buffers-on-shutdown"; /** * A key describing the duration (in microseconds) of the content. * The associated value is a long. */ public static final String KEY_DURATION = "durationUs"; /** * A key mapping to a value of 1 if the content is AAC audio and * audio frames are prefixed with an ADTS header. * The associated value is an integer (0 or 1). * This key is only supported when _decoding_ content, it cannot * be used to configure an encoder to emit ADTS output. */ public static final String KEY_IS_ADTS = "is-adts"; /** * A key describing the channel composition of audio content. This mask * is composed of bits drawn from channel mask definitions in {@link android.media.AudioFormat}. * The associated value is an integer. */ public static final String KEY_CHANNEL_MASK = "channel-mask"; /** * A key describing the AAC profile to be used (AAC audio formats only). * Constants are declared in {@link android.media.MediaCodecInfo.CodecProfileLevel}. */ public static final String KEY_AAC_PROFILE = "aac-profile"; /** * A key describing the AAC SBR mode to be used (AAC audio formats only). * The associated value is an integer and can be set to following values: *This key is only used during encoding. */ public static final String KEY_AAC_SBR_MODE = "aac-sbr-mode"; /** * A key describing the maximum number of channels that can be output by the AAC decoder. * By default, the decoder will output the same number of channels as present in the encoded * stream, if supported. Set this value to limit the number of output channels, and use * the downmix information in the stream, if available. *
Values larger than the number of channels in the content to decode are ignored. *
This key is only used during decoding. */ public static final String KEY_AAC_MAX_OUTPUT_CHANNEL_COUNT = "aac-max-output-channel_count"; /** * A key describing a gain to be applied so that the output loudness matches the * Target Reference Level. This is typically used to normalize loudness across program items. * The gain is derived as the difference between the Target Reference Level and the * Program Reference Level. The latter can be given in the bitstream and indicates the actual * loudness value of the program item. *
The value is given as an integer value between * 0 and 127, and is calculated as -0.25 * Target Reference Level in dBFS. * Therefore, it represents the range of Full Scale (0 dBFS) to -31.75 dBFS. *
This key is only used during decoding. */ public static final String KEY_AAC_DRC_TARGET_REFERENCE_LEVEL = "aac-target-ref-level"; /** * A key describing the target reference level that was assumed at the encoder for * calculation of attenuation gains for clipping prevention. This information can be provided * if it is known, otherwise a worst-case assumption is used. *
The value is given as an integer value between * 0 and 127, and is calculated as -0.25 * Target Reference Level in dBFS. * Therefore, it represents the range of Full Scale (0 dBFS) to -31.75 dBFS. * The default value is the worst-case assumption of 127. *
The value is ignored when heavy compression is used (see * {@link #KEY_AAC_DRC_HEAVY_COMPRESSION}). *
This key is only used during decoding. */ public static final String KEY_AAC_ENCODED_TARGET_LEVEL = "aac-encoded-target-level"; /** * A key describing the boost factor allowing to adapt the dynamics of the output to the * actual listening requirements. This relies on DRC gain sequences that can be transmitted in * the encoded bitstream to be able to reduce the dynamics of the output signal upon request. * This factor enables the user to select how much of the gains are applied. *
Positive gains (boost) and negative gains (attenuation, see * {@link #KEY_AAC_DRC_ATTENUATION_FACTOR}) can be controlled separately for a better match * to different use-cases. *
Typically, attenuation gains are sent for loud signal segments, and boost gains are sent * for soft signal segments. If the output is listened to in a noisy environment, for example, * the boost factor is used to enable the positive gains, i.e. to amplify soft signal segments * beyond the noise floor. But for listening late at night, the attenuation * factor is used to enable the negative gains, to prevent loud signal from surprising * the listener. In applications which generally need a low dynamic range, both the boost factor * and the attenuation factor are used in order to enable all DRC gains. *
In order to prevent clipping, it is also recommended to apply the attenuation factors * in case of a downmix and/or loudness normalization to high target reference levels. *
Both the boost and the attenuation factor parameters are given as integer values * between 0 and 127, representing the range of the factor of 0 (i.e. don't apply) * to 1 (i.e. fully apply boost/attenuation factors respectively). *
This key is only used during decoding. */ public static final String KEY_AAC_DRC_BOOST_FACTOR = "aac-drc-boost-level"; /** * A key describing the attenuation factor allowing to adapt the dynamics of the output to the * actual listening requirements. * See {@link #KEY_AAC_DRC_BOOST_FACTOR} for a description of the role of this attenuation * factor and the value range. *
This key is only used during decoding. */ public static final String KEY_AAC_DRC_ATTENUATION_FACTOR = "aac-drc-cut-level"; /** * A key describing the selection of the heavy compression profile for DRC. * Two separate DRC gain sequences can be transmitted in one bitstream: MPEG-4 DRC light * compression, and DVB-specific heavy compression. When selecting the application of the heavy * compression, one of the sequences is selected: *
The default is light compression. *
This key is only used during decoding. */ public static final String KEY_AAC_DRC_HEAVY_COMPRESSION = "aac-drc-heavy-compression"; /** * A key describing the FLAC compression level to be used (FLAC audio format only). * The associated value is an integer ranging from 0 (fastest, least compression) * to 8 (slowest, most compression). */ public static final String KEY_FLAC_COMPRESSION_LEVEL = "flac-compression-level"; /** * A key describing the encoding complexity. * The associated value is an integer. These values are device and codec specific, * but lower values generally result in faster and/or less power-hungry encoding. * * @see MediaCodecInfo.EncoderCapabilities#getComplexityRange() */ public static final String KEY_COMPLEXITY = "complexity"; /** * A key describing the desired encoding quality. * The associated value is an integer. This key is only supported for encoders * that are configured in constant-quality mode. These values are device and * codec specific, but lower values generally result in more efficient * (smaller-sized) encoding. * * @hide * * @see MediaCodecInfo.EncoderCapabilities#getQualityRange() */ public static final String KEY_QUALITY = "quality"; /** * A key describing the desired codec priority. *
* The associated value is an integer. Higher value means lower priority. *
* Currently, only two levels are supported:
* 0: realtime priority - meaning that the codec shall support the given
* performance configuration (e.g. framerate) at realtime. This should
* only be used by media playback, capture, and possibly by realtime
* communication scenarios if best effort performance is not suitable.
* 1: non-realtime priority (best effort).
*
* This is a hint used at codec configuration and resource planning - to understand * the realtime requirements of the application; however, due to the nature of * media components, performance is not guaranteed. * */ public static final String KEY_PRIORITY = "priority"; /** * A key describing the desired operating frame rate for video or sample rate for audio * that the codec will need to operate at. *
* The associated value is an integer or a float representing frames-per-second or * samples-per-second *
* This is used for cases like high-speed/slow-motion video capture, where the video encoder * format contains the target playback rate (e.g. 30fps), but the component must be able to * handle the high operating capture rate (e.g. 240fps). *
* This rate will be used by codec for resource planning and setting the operating points. * */ public static final String KEY_OPERATING_RATE = "operating-rate"; /** * A key describing the desired profile to be used by an encoder. * The associated value is an integer. * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}. * This key is used as a hint, and is only supported for codecs * that specify a profile. * * @see MediaCodecInfo.CodecCapabilities#profileLevels */ public static final String KEY_PROFILE = "profile"; /** * A key describing the desired profile to be used by an encoder. * The associated value is an integer. * Constants are declared in {@link MediaCodecInfo.CodecProfileLevel}. * This key is used as a further hint when specifying a desired profile, * and is only supported for codecs that specify a level. *
* This key is ignored if the {@link #KEY_PROFILE profile} is not specified.
*
* @see MediaCodecInfo.CodecCapabilities#profileLevels
*/
public static final String KEY_LEVEL = "level";
/**
* A key describing the desired clockwise rotation on an output surface.
* This key is only used when the codec is configured using an output surface.
* The associated value is an integer, representing degrees.
*
* @see MediaCodecInfo.CodecCapabilities#profileLevels
*/
public static final String KEY_ROTATION = "rotation-degrees";
/**
* A key describing the desired bitrate mode to be used by an encoder.
* Constants are declared in {@link MediaCodecInfo.CodecCapabilities}.
*
* @see MediaCodecInfo.EncoderCapabilities#isBitrateModeSupported(int)
*/
public static final String KEY_BITRATE_MODE = "bitrate-mode";
/**
* A key describing the audio session ID of the AudioTrack associated
* to a tunneled video codec.
* The associated value is an integer.
*
* @see MediaCodecInfo.CodecCapabilities#FEATURE_TunneledPlayback
*/
public static final String KEY_AUDIO_SESSION_ID = "audio-session-id";
/**
* A key for boolean AUTOSELECT behavior for the track. Tracks with AUTOSELECT=true
* are considered when automatically selecting a track without specific user
* choice, based on the current locale.
* This is currently only used for subtitle tracks, when the user selected
* 'Default' for the captioning locale.
* The associated value is an integer, where non-0 means TRUE. This is an optional
* field; if not specified, AUTOSELECT defaults to TRUE.
*/
public static final String KEY_IS_AUTOSELECT = "is-autoselect";
/**
* A key for boolean DEFAULT behavior for the track. The track with DEFAULT=true is
* selected in the absence of a specific user choice.
* This is currently only used for subtitle tracks, when the user selected
* 'Default' for the captioning locale.
* The associated value is an integer, where non-0 means TRUE. This is an optional
* field; if not specified, DEFAULT is considered to be FALSE.
*/
public static final String KEY_IS_DEFAULT = "is-default";
/**
* A key for the FORCED field for subtitle tracks. True if it is a
* forced subtitle track. Forced subtitle tracks are essential for the
* content and are shown even when the user turns off Captions. They
* are used for example to translate foreign/alien dialogs or signs.
* The associated value is an integer, where non-0 means TRUE. This is an
* optional field; if not specified, FORCED defaults to FALSE.
*/
public static final String KEY_IS_FORCED_SUBTITLE = "is-forced-subtitle";
/** @hide */
public static final String KEY_IS_TIMED_TEXT = "is-timed-text";
/* package private */ MediaFormat(Map