MediaFormat.java revision 60d610bf103379277a4b29a7ead4f013f6128e4e 
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
17package android.media;
18
19import java.nio.ByteBuffer;
20import java.util.HashMap;
21import java.util.Map;
22
23/**
24 * Encapsulates the information describing the format of media data,
25 * be it audio or video.
26 *
27 * The format of the media data is specified as string/value pairs.
28 *
29 * Keys common to all formats:
30 *
31 * <table>
32 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr>
33 * <tr><td>{@link #KEY_MIME}</td><td>String</td><td>The type of the format.</td></tr>
34 * <tr><td>{@link #KEY_MAX_INPUT_SIZE}</td><td>Integer</td><td>optional, maximum size of a buffer of input data</td></tr>
35 * <tr><td>{@link #KEY_BIT_RATE}</td><td>Integer</td><td><b>encoder-only</b>, desired bitrate in bits/second</td></tr>
36 * </table>
37 *
38 * Video formats have the following keys:
39 * <table>
40 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr>
41 * <tr><td>{@link #KEY_WIDTH}</td><td>Integer</td><td></td></tr>
42 * <tr><td>{@link #KEY_HEIGHT}</td><td>Integer</td><td></td></tr>
43 * <tr><td>{@link #KEY_COLOR_FORMAT}</td><td>Integer</td><td><b>encoder-only</b></td></tr>
44 * <tr><td>{@link #KEY_FRAME_RATE}</td><td>Integer or Float</td><td><b>encoder-only</b></td></tr>
45 * <tr><td>{@link #KEY_I_FRAME_INTERVAL}</td><td>Integer</td><td><b>encoder-only</b></td></tr>
46 * </table>
47 *
48 * Audio formats have the following keys:
49 * <table>
50 * <tr><th>Name</th><th>Value Type</th><th>Description</th></tr>
51 * <tr><td>{@link #KEY_CHANNEL_COUNT}</td><td>Integer</td><td></td></tr>
52 * <tr><td>{@link #KEY_SAMPLE_RATE}</td><td>Integer</td><td></td></tr>
53 * <tr><td>{@link #KEY_IS_ADTS}</td><td>Integer</td><td>optional, if content is AAC audio, setting this key to 1 indicates that each audio frame is prefixed by the ADTS header.</td></tr>
54 * <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>
55 * <tr><td>{@link #KEY_CHANNEL_MASK}</td><td>Integer</td><td>A mask of audio channel assignments</td></tr>
56 * </table>
57 *
58 */
59public final class MediaFormat {
60    private Map<String, Object> mMap;
61
62    /**
63     * A key describing the mime type of the MediaFormat.
64     * The associated value is a string.
65     */
66    public static final String KEY_MIME = "mime";
67
68    /**
69     * A key describing the sample rate of an audio format.
70     * The associated value is an integer
71     */
72    public static final String KEY_SAMPLE_RATE = "sample-rate";
73
74    /**
75     * A key describing the number of channels in an audio format.
76     * The associated value is an integer
77     */
78    public static final String KEY_CHANNEL_COUNT = "channel-count";
79
80    /**
81     * A key describing the width of the content in a video format.
82     * The associated value is an integer
83     */
84    public static final String KEY_WIDTH = "width";
85
86    /**
87     * A key describing the height of the content in a video format.
88     * The associated value is an integer
89     */
90    public static final String KEY_HEIGHT = "height";
91
92    /** A key describing the maximum size in bytes of a buffer of data
93     * described by this MediaFormat.
94     * The associated value is an integer
95     */
96    public static final String KEY_MAX_INPUT_SIZE = "max-input-size";
97
98    /**
99     * A key describing the bitrate in bits/sec.
100     * The associated value is an integer
101     */
102    public static final String KEY_BIT_RATE = "bitrate";
103
104    /**
105     * A key describing the color format of the content in a video format.
106     * Constants are declared in {@link android.media.MediaCodecInfo.CodecCapabilities}.
107     */
108    public static final String KEY_COLOR_FORMAT = "color-format";
109
110    /**
111     * A key describing the frame rate of a video format in frames/sec.
112     * The associated value is an integer or a float.
113     */
114    public static final String KEY_FRAME_RATE = "frame-rate";
115
116    /**
117     * A key describing the frequency of I frames expressed in secs
118     * between I frames.
119     * The associated value is an integer.
120     */
121    public static final String KEY_I_FRAME_INTERVAL = "i-frame-interval";
122
123    /**
124     * @hide
125     */
126    public static final String KEY_STRIDE = "stride";
127    /**
128     * @hide
129     */
130    public static final String KEY_SLICE_HEIGHT = "slice-height";
131
132    /**
133     * A key describing the duration (in microseconds) of the content.
134     * The associated value is a long.
135     */
136    public static final String KEY_DURATION = "durationUs";
137
138    /**
139     * A key mapping to a value of 1 if the content is AAC audio and
140     * audio frames are prefixed with an ADTS header.
141     * The associated value is an integer (0 or 1).
142     */
143    public static final String KEY_IS_ADTS = "is-adts";
144
145    /**
146     * A key describing the channel composition of audio content. This mask
147     * is composed of bits drawn from channel mask definitions in {@link android.media.AudioFormat}.
148     * The associated value is an integer.
149     */
150    public static final String KEY_CHANNEL_MASK = "channel-mask";
151
152    /**
153     * A key describing the AAC profile to be used (AAC audio formats only).
154     * Constants are declared in {@link android.media.MediaCodecInfo.CodecCapabilities}.
155     */
156    public static final String KEY_AAC_PROFILE = "aac-profile";
157
158    /* package private */ MediaFormat(Map<String, Object> map) {
159        mMap = map;
160    }
161
162    /**
163     * Creates an empty MediaFormat
164     */
165    public MediaFormat() {
166        mMap = new HashMap();
167    }
168
169    /* package private */ Map<String, Object> getMap() {
170        return mMap;
171    }
172
173    /**
174     * Returns true iff a key of the given name exists in the format.
175     */
176    public final boolean containsKey(String name) {
177        return mMap.containsKey(name);
178    }
179
180    /**
181     * Returns the value of an integer key.
182     */
183    public final int getInteger(String name) {
184        return ((Integer)mMap.get(name)).intValue();
185    }
186
187    /**
188     * Returns the value of a long key.
189     */
190    public final long getLong(String name) {
191        return ((Long)mMap.get(name)).longValue();
192    }
193
194    /**
195     * Returns the value of a float key.
196     */
197    public final float getFloat(String name) {
198        return ((Float)mMap.get(name)).floatValue();
199    }
200
201    /**
202     * Returns the value of a string key.
203     */
204    public final String getString(String name) {
205        return (String)mMap.get(name);
206    }
207
208    /**
209     * Returns the value of a ByteBuffer key.
210     */
211    public final ByteBuffer getByteBuffer(String name) {
212        return (ByteBuffer)mMap.get(name);
213    }
214
215    /**
216     * Sets the value of an integer key.
217     */
218    public final void setInteger(String name, int value) {
219        mMap.put(name, new Integer(value));
220    }
221
222    /**
223     * Sets the value of a long key.
224     */
225    public final void setLong(String name, long value) {
226        mMap.put(name, new Long(value));
227    }
228
229    /**
230     * Sets the value of a float key.
231     */
232    public final void setFloat(String name, float value) {
233        mMap.put(name, new Float(value));
234    }
235
236    /**
237     * Sets the value of a string key.
238     */
239    public final void setString(String name, String value) {
240        mMap.put(name, value);
241    }
242
243    /**
244     * Sets the value of a ByteBuffer key.
245     */
246    public final void setByteBuffer(String name, ByteBuffer bytes) {
247        mMap.put(name, bytes);
248    }
249
250    /**
251     * Creates a minimal audio format.
252     * @param mime The mime type of the content.
253     * @param sampleRate The sampling rate of the content.
254     * @param channelCount The number of audio channels in the content.
255     */
256    public static final MediaFormat createAudioFormat(
257            String mime,
258            int sampleRate,
259            int channelCount) {
260        MediaFormat format = new MediaFormat();
261        format.setString(KEY_MIME, mime);
262        format.setInteger(KEY_SAMPLE_RATE, sampleRate);
263        format.setInteger(KEY_CHANNEL_COUNT, channelCount);
264
265        return format;
266    }
267
268    /**
269     * Creates a minimal video format.
270     * @param mime The mime type of the content.
271     * @param width The width of the content (in pixels)
272     * @param height The height of the content (in pixels)
273     */
274    public static final MediaFormat createVideoFormat(
275            String mime,
276            int width,
277            int height) {
278        MediaFormat format = new MediaFormat();
279        format.setString(KEY_MIME, mime);
280        format.setInteger(KEY_WIDTH, width);
281        format.setInteger(KEY_HEIGHT, height);
282
283        return format;
284    }
285
286    @Override
287    public String toString() {
288        return mMap.toString();
289    }
290}
291