CamcorderProfile.java revision 522632cde516001429549c60bd570c399ffad800 
1/*
2 * Copyright (C) 2010 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
19/**
20 * The CamcorderProfile class is used to retrieve the
21 * predefined camcorder profile settings for camcorder applications.
22 * These settings are read-only.
23 *
24 * The compressed output from a recording session with a given
25 * CamcorderProfile contains two tracks: one for auido and one for video.
26 *
27 * <p>Each profile specifies the following set of parameters:
28 * <ul>
29 * <li> The file output format
30 * <li> Video codec format
31 * <li> Video bit rate in bits per second
32 * <li> Video frame rate in frames per second
33 * <li> Video frame width and height,
34 * <li> Audio codec format
35 * <li> Audio bit rate in bits per second,
36 * <li> Audio sample rate
37 * <li> Number of audio channels for recording.
38 * </ul>
39 */
40public class CamcorderProfile
41{
42    // Do not change these values/ordinals without updating their counterpart
43    // in include/media/MediaProfiles.h!
44
45    /**
46     * Quality level corresponding to the lowest available resolution.
47     */
48    public static final int QUALITY_LOW  = 0;
49
50    /**
51     * Quality level corresponding to the highest available resolution.
52     */
53    public static final int QUALITY_HIGH = 1;
54
55    /**
56     * Quality level corresponding to the qcif (176 x 144) resolution.
57     */
58    public static final int QUALITY_QCIF = 2;
59
60    /**
61     * Quality level corresponding to the cif (352 x 288) resolution.
62     */
63    public static final int QUALITY_CIF = 3;
64
65    /**
66     * Quality level corresponding to the 480p (720 x 480) resolution.
67     */
68    public static final int QUALITY_480P = 4;
69
70    /**
71     * Quality level corresponding to the 720p (1280 x 720) resolution.
72     */
73    public static final int QUALITY_720P = 5;
74
75    /**
76     * Quality level corresponding to the 1080p (1920 x 1088) resolution.
77     */
78    public static final int QUALITY_1080P = 6;
79
80    /**
81     * Time lapse quality level corresponding to the lowest available resolution.
82     */
83    public static final int QUALITY_TIME_LAPSE_LOW  = 1000;
84
85    /**
86     * Time lapse quality level corresponding to the highest available resolution.
87     */
88    public static final int QUALITY_TIME_LAPSE_HIGH = 1001;
89
90    /**
91     * Time lapse quality level corresponding to the qcif (176 x 144) resolution.
92     */
93    public static final int QUALITY_TIME_LAPSE_QCIF = 1002;
94
95    /**
96     * Time lapse quality level corresponding to the cif (352 x 288) resolution.
97     */
98    public static final int QUALITY_TIME_LAPSE_CIF = 1003;
99
100    /**
101     * Time lapse quality level corresponding to the 480p (720 x 480) resolution.
102     */
103    public static final int QUALITY_TIME_LAPSE_480P = 1004;
104
105    /**
106     * Time lapse quality level corresponding to the 720p (1280 x 720) resolution.
107     */
108    public static final int QUALITY_TIME_LAPSE_720P = 1005;
109
110    /**
111     * Time lapse quality level corresponding to the 1080p (1920 x 1088) resolution.
112     */
113    public static final int QUALITY_TIME_LAPSE_1080P = 1006;
114
115    /**
116     * Default recording duration in seconds before the session is terminated.
117     * This is useful for applications like MMS has limited file size requirement.
118     */
119    public int duration;
120
121    /**
122     * The quality level of the camcorder profile
123     */
124    public int quality;
125
126    /**
127     * The file output format of the camcorder profile
128     * @see android.media.MediaRecorder.OutputFormat
129     */
130    public int fileFormat;
131
132    /**
133     * The video encoder being used for the video track
134     * @see android.media.MediaRecorder.VideoEncoder
135     */
136    public int videoCodec;
137
138    /**
139     * The target video output bit rate in bits per second
140     */
141    public int videoBitRate;
142
143    /**
144     * The target video frame rate in frames per second
145     */
146    public int videoFrameRate;
147
148    /**
149     * The target video frame width in pixels
150     */
151    public int videoFrameWidth;
152
153    /**
154     * The target video frame height in pixels
155     */
156    public int videoFrameHeight;
157
158    /**
159     * The audio encoder being used for the audio track.
160     * @see android.media.MediaRecorder.AudioEncoder
161     */
162    public int audioCodec;
163
164    /**
165     * The target audio output bit rate in bits per second
166     */
167    public int audioBitRate;
168
169    /**
170     * The audio sampling rate used for the audio track
171     */
172    public int audioSampleRate;
173
174    /**
175     * The number of audio channels used for the audio track
176     */
177    public int audioChannels;
178
179    /**
180     * Returns the camcorder profile for the default camera at the given
181     * quality level.
182     * @param quality the target quality level for the camcorder profile
183     * @see #get(int, int)
184     */
185    public static CamcorderProfile get(int quality) {
186        return get(android.hardware.Camera.CAMERA_ID_DEFAULT, quality);
187    }
188
189    /**
190     * Returns the camcorder profile for the given camera at the given
191     * quality level.
192     *
193     * Quality levels QUALITY_LOW, QUALITY_HIGH are guaranteed to be supported, while
194     * other levels may or may not be supported. The supported levels can be checked using
195     * {@link #hasProfile(int, int)}.
196     * QUALITY_LOW refers to the lowest quality available, while QUALITY_HIGH refers to
197     * the highest quality available.
198     * QUALITY_LOW/QUALITY_HIGH have to match one of qcif, cif, 480p, 720p, or 1080p.
199     * E.g. if the device supports 480p, 720p, and 1080p, then low is 480p and high is
200     * 1080p.
201     *
202     * A camcorder recording session with higher quality level usually has higher output
203     * bit rate, better video and/or audio recording quality, larger video frame
204     * resolution and higher audio sampling rate, etc, than those with lower quality
205     * level.
206     *
207     * @param cameraId the id for the camera
208     * @param quality the target quality level for the camcorder profile.
209     * @see #QUALITY_LOW
210     * @see #QUALITY_HIGH
211     * @see #QUALITY_QCIF
212     * @see #QUALITY_CIF
213     * @see #QUALITY_480P
214     * @see #QUALITY_720P
215     * @see #QUALITY_1080P
216     * @see #QUALITY_TIME_LAPSE_LOW
217     * @see #QUALITY_TIME_LAPSE_HIGH
218     * @see #QUALITY_TIME_LAPSE_QCIF
219     * @see #QUALITY_TIME_LAPSE_CIF
220     * @see #QUALITY_TIME_LAPSE_480P
221     * @see #QUALITY_TIME_LAPSE_720P
222     * @see #QUALITY_TIME_LAPSE_1080P
223     */
224    public static CamcorderProfile get(int cameraId, int quality) {
225        if (!((quality >= QUALITY_LOW && quality <= QUALITY_1080P) ||
226                (quality >= QUALITY_TIME_LAPSE_LOW && quality <= QUALITY_TIME_LAPSE_1080P))) {
227            String errMessage = "Unsupported quality level: " + quality;
228            throw new IllegalArgumentException(errMessage);
229        }
230        return native_get_camcorder_profile(cameraId, quality);
231    }
232
233    /**
234     * Returns true if camcorder profile exists for the default camera at
235     * the given quality level.
236     * @param quality the target quality level for the camcorder profile
237     */
238    public static boolean hasProfile(int quality) {
239        return hasProfile(android.hardware.Camera.CAMERA_ID_DEFAULT, quality);
240    }
241
242    /**
243     * Returns true if camcorder profile exists for the given camera at
244     * the given quality level.
245     * @param cameraId the id for the camera
246     * @param quality the target quality level for the camcorder profile
247     */
248    public static boolean hasProfile(int cameraId, int quality) {
249        return native_has_camcorder_profile(cameraId, quality);
250    }
251
252    static {
253        System.loadLibrary("media_jni");
254        native_init();
255    }
256
257    // Private constructor called by JNI
258    private CamcorderProfile(int duration,
259                             int quality,
260                             int fileFormat,
261                             int videoCodec,
262                             int videoBitRate,
263                             int videoFrameRate,
264                             int videoWidth,
265                             int videoHeight,
266                             int audioCodec,
267                             int audioBitRate,
268                             int audioSampleRate,
269                             int audioChannels) {
270
271        this.duration         = duration;
272        this.quality          = quality;
273        this.fileFormat       = fileFormat;
274        this.videoCodec       = videoCodec;
275        this.videoBitRate     = videoBitRate;
276        this.videoFrameRate   = videoFrameRate;
277        this.videoFrameWidth  = videoWidth;
278        this.videoFrameHeight = videoHeight;
279        this.audioCodec       = audioCodec;
280        this.audioBitRate     = audioBitRate;
281        this.audioSampleRate  = audioSampleRate;
282        this.audioChannels    = audioChannels;
283    }
284
285    // Methods implemented by JNI
286    private static native final void native_init();
287    private static native final CamcorderProfile native_get_camcorder_profile(
288            int cameraId, int quality);
289    private static native final boolean native_has_camcorder_profile(
290            int cameraId, int quality);
291}
292