to top
Android APIs
public final class

MediaFormat

extends Object
java.lang.Object
   ↳ android.media.MediaFormat

Class Overview

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:

NameValue TypeDescription
KEY_MIMEStringThe type of the format.
KEY_MAX_INPUT_SIZEIntegeroptional, maximum size of a buffer of input data
KEY_BIT_RATEIntegerencoder-only, desired bitrate in bits/second
Video formats have the following keys:
NameValue TypeDescription
KEY_WIDTHInteger
KEY_HEIGHTInteger
KEY_COLOR_FORMATIntegerset by the user for encoders, readable in the output format of decoders
KEY_FRAME_RATEInteger or Floatencoder-only
KEY_I_FRAME_INTERVALIntegerencoder-only
KEY_MAX_WIDTHIntegerdecoder-only, optional, max-resolution width
KEY_MAX_HEIGHTIntegerdecoder-only, optional, max-resolution height
KEY_REPEAT_PREVIOUS_FRAME_AFTERLongvideo encoder in surface-mode only
KEY_PUSH_BLANK_BUFFERS_ON_STOPInteger(1)video decoder rendering to a surface only
Specify both KEY_MAX_WIDTH and KEY_MAX_HEIGHT to enable adaptive playback (seamless resolution change) for a video decoder that supports it (FEATURE_AdaptivePlayback). The values are used as hints for the codec: they are the maximum expected resolution to prepare for. Depending on codec support, preparing for larger maximum resolution may require more memory even if that resolution is never reached. These fields have no effect for codecs that do not support adaptive playback.

Audio formats have the following keys:
NameValue TypeDescription
KEY_CHANNEL_COUNTInteger
KEY_SAMPLE_RATEInteger
KEY_IS_ADTSIntegeroptional, if decoding AAC audio content, setting this key to 1 indicates that each audio frame is prefixed by the ADTS header.
KEY_AAC_PROFILEIntegerencoder-only, optional, if content is AAC audio, specifies the desired profile.
KEY_CHANNEL_MASKIntegeroptional, a mask of audio channel assignments
KEY_FLAC_COMPRESSION_LEVELIntegerencoder-only, optional, if content is FLAC audio, specifies the desired compression level.
Subtitle formats have the following keys:
KEY_MIMEStringThe type of the format.
KEY_LANGUAGEStringThe language of the content.

Summary

Constants
String KEY_AAC_PROFILE A key describing the AAC profile to be used (AAC audio formats only).
String KEY_BIT_RATE A key describing the bitrate in bits/sec.
String KEY_CHANNEL_COUNT A key describing the number of channels in an audio format.
String KEY_CHANNEL_MASK A key describing the channel composition of audio content.
String KEY_COLOR_FORMAT A key describing the color format of the content in a video format.
String KEY_DURATION A key describing the duration (in microseconds) of the content.
String KEY_FLAC_COMPRESSION_LEVEL A key describing the FLAC compression level to be used (FLAC audio format only).
String KEY_FRAME_RATE A key describing the frame rate of a video format in frames/sec.
String KEY_HEIGHT A key describing the height of the content in a video format.
String KEY_IS_ADTS A key mapping to a value of 1 if the content is AAC audio and audio frames are prefixed with an ADTS header.
String KEY_IS_AUTOSELECT A key for boolean AUTOSELECT behavior for the track.
String KEY_IS_DEFAULT A key for boolean DEFAULT behavior for the track.
String KEY_IS_FORCED_SUBTITLE A key for the FORCED field for subtitle tracks.
String KEY_I_FRAME_INTERVAL A key describing the frequency of I frames expressed in secs between I frames.
String KEY_LANGUAGE A key describing the language of the content, using either ISO 639-1 or 639-2/T codes.
String KEY_MAX_HEIGHT A key describing the maximum expected height of the content in a video decoder format, in case there are resolution changes in the video content.
String KEY_MAX_INPUT_SIZE A key describing the maximum size in bytes of a buffer of data described by this MediaFormat.
String KEY_MAX_WIDTH A key describing the maximum expected width of the content in a video decoder format, in case there are resolution changes in the video content.
String KEY_MIME A key describing the mime type of the MediaFormat.
String KEY_PUSH_BLANK_BUFFERS_ON_STOP If specified when configuring a video decoder rendering to a surface, causes the decoder to output "blank", i.e.
String KEY_REPEAT_PREVIOUS_FRAME_AFTER Applies only when configuring a video encoder in "surface-input" mode.
String KEY_SAMPLE_RATE A key describing the sample rate of an audio format.
String KEY_WIDTH A key describing the width of the content in a video format.
Public Constructors
MediaFormat()
Creates an empty MediaFormat
Public Methods
final boolean containsKey(String name)
Returns true iff a key of the given name exists in the format.
final static MediaFormat createAudioFormat(String mime, int sampleRate, int channelCount)
Creates a minimal audio format.
final static MediaFormat createSubtitleFormat(String mime, String language)
Creates a minimal subtitle format.
final static MediaFormat createVideoFormat(String mime, int width, int height)
Creates a minimal video format.
final ByteBuffer getByteBuffer(String name)
Returns the value of a ByteBuffer key.
final float getFloat(String name)
Returns the value of a float key.
final int getInteger(String name)
Returns the value of an integer key.
final long getLong(String name)
Returns the value of a long key.
final String getString(String name)
Returns the value of a string key.
final void setByteBuffer(String name, ByteBuffer bytes)
Sets the value of a ByteBuffer key.
final void setFloat(String name, float value)
Sets the value of a float key.
final void setInteger(String name, int value)
Sets the value of an integer key.
final void setLong(String name, long value)
Sets the value of a long key.
final void setString(String name, String value)
Sets the value of a string key.
String toString()
Returns a string containing a concise, human-readable description of this object.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String KEY_AAC_PROFILE

Added in API level 16

A key describing the AAC profile to be used (AAC audio formats only). Constants are declared in MediaCodecInfo.CodecProfileLevel.

Constant Value: "aac-profile"

public static final String KEY_BIT_RATE

Added in API level 16

A key describing the bitrate in bits/sec. The associated value is an integer

Constant Value: "bitrate"

public static final String KEY_CHANNEL_COUNT

Added in API level 16

A key describing the number of channels in an audio format. The associated value is an integer

Constant Value: "channel-count"

public static final String KEY_CHANNEL_MASK

Added in API level 16

A key describing the channel composition of audio content. This mask is composed of bits drawn from channel mask definitions in AudioFormat. The associated value is an integer.

Constant Value: "channel-mask"

public static final String KEY_COLOR_FORMAT

Added in API level 16

A key describing the color format of the content in a video format. Constants are declared in MediaCodecInfo.CodecCapabilities.

Constant Value: "color-format"

public static final String KEY_DURATION

Added in API level 16

A key describing the duration (in microseconds) of the content. The associated value is a long.

Constant Value: "durationUs"

public static final String KEY_FLAC_COMPRESSION_LEVEL

Added in API level 16

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).

Constant Value: "flac-compression-level"

public static final String KEY_FRAME_RATE

Added in API level 16

A key describing the frame rate of a video format in frames/sec. The associated value is an integer or a float.

Constant Value: "frame-rate"

public static final String KEY_HEIGHT

Added in API level 16

A key describing the height of the content in a video format. The associated value is an integer

Constant Value: "height"

public static final String KEY_IS_ADTS

Added in API level 16

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.

Constant Value: "is-adts"

public static final String KEY_IS_AUTOSELECT

Added in API level 19

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.

Constant Value: "is-autoselect"

public static final String KEY_IS_DEFAULT

Added in API level 19

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.

Constant Value: "is-default"

public static final String KEY_IS_FORCED_SUBTITLE

Added in API level 19

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.

Constant Value: "is-forced-subtitle"

public static final String KEY_I_FRAME_INTERVAL

Added in API level 16

A key describing the frequency of I frames expressed in secs between I frames. The associated value is an integer.

Constant Value: "i-frame-interval"

public static final String KEY_LANGUAGE

Added in API level 19

A key describing the language of the content, using either ISO 639-1 or 639-2/T codes. The associated value is a string.

Constant Value: "language"

public static final String KEY_MAX_HEIGHT

Added in API level 19

A key describing the maximum expected height of the content in a video decoder format, in case there are resolution changes in the video content. The associated value is an integer

Constant Value: "max-height"

public static final String KEY_MAX_INPUT_SIZE

Added in API level 16

A key describing the maximum size in bytes of a buffer of data described by this MediaFormat. The associated value is an integer

Constant Value: "max-input-size"

public static final String KEY_MAX_WIDTH

Added in API level 19

A key describing the maximum expected width of the content in a video decoder format, in case there are resolution changes in the video content. The associated value is an integer

Constant Value: "max-width"

public static final String KEY_MIME

Added in API level 16

A key describing the mime type of the MediaFormat. The associated value is a string.

Constant Value: "mime"

public static final String KEY_PUSH_BLANK_BUFFERS_ON_STOP

Added in API level 19

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.

Constant Value: "push-blank-buffers-on-shutdown"

public static final String KEY_REPEAT_PREVIOUS_FRAME_AFTER

Added in API level 19

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.

Constant Value: "repeat-previous-frame-after"

public static final String KEY_SAMPLE_RATE

Added in API level 16

A key describing the sample rate of an audio format. The associated value is an integer

Constant Value: "sample-rate"

public static final String KEY_WIDTH

Added in API level 16

A key describing the width of the content in a video format. The associated value is an integer

Constant Value: "width"

Public Constructors

public MediaFormat ()

Added in API level 16

Creates an empty MediaFormat

Public Methods

public final boolean containsKey (String name)

Added in API level 16

Returns true iff a key of the given name exists in the format.

public static final MediaFormat createAudioFormat (String mime, int sampleRate, int channelCount)

Added in API level 16

Creates a minimal audio format.

Parameters
mime The mime type of the content.
sampleRate The sampling rate of the content.
channelCount The number of audio channels in the content.

public static final MediaFormat createSubtitleFormat (String mime, String language)

Added in API level 19

Creates a minimal subtitle format.

Parameters
mime The mime type of the content.
language The language of the content, using either ISO 639-1 or 639-2/T codes. Specify null or "und" if language information is only included in the content. (This will also work if there are multiple language tracks in the content.)

public static final MediaFormat createVideoFormat (String mime, int width, int height)

Added in API level 16

Creates a minimal video format.

Parameters
mime The mime type of the content.
width The width of the content (in pixels)
height The height of the content (in pixels)

public final ByteBuffer getByteBuffer (String name)

Added in API level 16

Returns the value of a ByteBuffer key.

public final float getFloat (String name)

Added in API level 16

Returns the value of a float key.

public final int getInteger (String name)

Added in API level 16

Returns the value of an integer key.

public final long getLong (String name)

Added in API level 16

Returns the value of a long key.

public final String getString (String name)

Added in API level 16

Returns the value of a string key.

public final void setByteBuffer (String name, ByteBuffer bytes)

Added in API level 16

Sets the value of a ByteBuffer key.

public final void setFloat (String name, float value)

Added in API level 16

Sets the value of a float key.

public final void setInteger (String name, int value)

Added in API level 16

Sets the value of an integer key.

public final void setLong (String name, long value)

Added in API level 16

Sets the value of a long key.

public final void setString (String name, String value)

Added in API level 16

Sets the value of a string key.

public String toString ()

Added in API level 16

Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression: 

   getClass().getName() + '@' + Integer.toHexString(hashCode())

See Writing a useful toString method if you intend implementing your own toString method.

Returns
  • a printable representation of this object.