MediaRecorder.java revision d24b8183b93e781080b2c16c487e60d51c12da31
1/* 2 * Copyright (C) 2007 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 android.view.Surface; 20import android.hardware.Camera; 21import java.io.IOException; 22 23/** 24 * Used to record audio and video. The recording control is based on a 25 * simple state machine (see below). 26 * 27 * <p><img src="{@docRoot}images/mediarecorder_state_diagram.gif" border="0" /> 28 * </p> 29 * 30 * <p>A common case of using MediaRecorder to record audio works as follows: 31 * 32 * <pre>MediaRecorder recorder = new MediaRecorder(); 33 * recorder.setAudioSource(MediaRecorder.AudioSource.MIC); 34 * recorder.setOutputFormat(MediaRecorder.OutputFormat.THREE_GPP); 35 * recorder.setAudioEncoder(MediaRecorder.AudioEncoder.AMR_NB); 36 * recorder.setOutputFile(PATH_NAME); 37 * recorder.prepare(); 38 * recorder.start(); // Recording is now started 39 * ... 40 * recorder.stop(); 41 * recorder.reset(); // You can reuse the object by going back to setAudioSource() step 42 * recorder.release(); // Now the object cannot be reused 43 * </pre> 44 * 45 * <p>See the <a href="{@docRoot}guide/topics/media/index.html">Audio and Video</a> 46 * documentation for additional help with using MediaRecorder. 47 */ 48public class MediaRecorder 49{ 50 static { 51 System.loadLibrary("media_jni"); 52 } 53 54 // The two fields below are accessed by native methods 55 @SuppressWarnings("unused") 56 private int mNativeContext; 57 58 @SuppressWarnings("unused") 59 private Surface mSurface; 60 61 /** 62 * Default constructor. 63 */ 64 public MediaRecorder() { 65 native_setup(); 66 } 67 68 /** 69 * Sets a Camera to use for recording. Use this function to switch 70 * quickly between preview and capture mode without a teardown of 71 * the camera object. Must call before prepare(). 72 * 73 * @param c the Camera to use for recording 74 * FIXME: Temporarily hidden until API approval 75 * @hide 76 */ 77 public native void setCamera(Camera c); 78 79 /** 80 * Sets a Surface to show a preview of recorded media (video). Calls this 81 * before prepare() to make sure that the desirable preview display is 82 * set. 83 * 84 * @param sv the Surface to use for the preview 85 */ 86 public void setPreviewDisplay(Surface sv) { 87 mSurface = sv; 88 } 89 90 /** 91 * Defines the audio source. These constants are used with 92 * {@link MediaRecorder#setAudioSource(int)}. 93 */ 94 public final class AudioSource { 95 /* Do not change these values without updating their counterparts 96 * in include/media/mediarecorder.h! 97 */ 98 private AudioSource() {} 99 public static final int DEFAULT = 0; 100 /** Microphone audio source */ 101 public static final int MIC = 1; 102 } 103 104 /** 105 * Defines the video source. These constants are used with 106 * {@link MediaRecorder#setVideoSource(int)}. 107 * @hide 108 */ 109 public final class VideoSource { 110 /* Do not change these values without updating their counterparts 111 * in include/media/mediarecorder.h! 112 */ 113 private VideoSource() {} 114 public static final int DEFAULT = 0; 115 /** Camera video source */ 116 public static final int CAMERA = 1; 117 } 118 119 /** 120 * Defines the output format. These constants are used with 121 * {@link MediaRecorder#setOutputFormat(int)}. 122 */ 123 public final class OutputFormat { 124 /* Do not change these values without updating their counterparts 125 * in include/media/mediarecorder.h! 126 */ 127 private OutputFormat() {} 128 public static final int DEFAULT = 0; 129 /** 3GPP media file format*/ 130 public static final int THREE_GPP = 1; 131 /** MPEG4 media file format*/ 132 public static final int MPEG_4 = 2; 133 /** Raw AMR file format */ 134 public static final int RAW_AMR = 3; 135 }; 136 137 /** 138 * Defines the audio encoding. These constants are used with 139 * {@link MediaRecorder#setAudioEncoder(int)}. 140 */ 141 public final class AudioEncoder { 142 /* Do not change these values without updating their counterparts 143 * in include/media/mediarecorder.h! 144 */ 145 private AudioEncoder() {} 146 public static final int DEFAULT = 0; 147 /** AMR (Narrowband) audio codec */ 148 public static final int AMR_NB = 1; 149 //public static final AAC = 2; currently unsupported 150 } 151 152 /** 153 * Defines the video encoding. These constants are used with 154 * {@link MediaRecorder#setVideoEncoder(int)}. 155 * @hide 156 */ 157 public final class VideoEncoder { 158 /* Do not change these values without updating their counterparts 159 * in include/media/mediarecorder.h! 160 */ 161 private VideoEncoder() {} 162 public static final int DEFAULT = 0; 163 public static final int H263 = 1; 164 public static final int H264 = 2; 165 public static final int MPEG_4_SP = 3; 166 } 167 168 /** 169 * Sets the audio source to be used for recording. If this method is not 170 * called, the output file will not contain an audio track. The source needs 171 * to be specified before setting recording-parameters or encoders. Call 172 * this only before setOutputFormat(). 173 * 174 * @param audio_source the audio source to use 175 * @throws IllegalStateException if it is called after setOutputFormat() 176 * @see android.media.MediaRecorder.AudioSource 177 */ 178 public native void setAudioSource(int audio_source) 179 throws IllegalStateException; 180 181 /** 182 * Sets the video source to be used for recording. If this method is not 183 * called, the output file will not contain an video track. The source needs 184 * to be specified before setting recording-parameters or encoders. Call 185 * this only before setOutputFormat(). 186 * 187 * @param video_source the video source to use 188 * @throws IllegalStateException if it is called after setOutputFormat() 189 * @see android.media.MediaRecorder.VideoSource 190 * @hide 191 */ 192 public native void setVideoSource(int video_source) 193 throws IllegalStateException; 194 195 /** 196 * Sets the format of the output file produced during recording. Call this 197 * after setAudioSource()/setVideoSource() but before prepare(). 198 * 199 * @param output_format the output format to use. The output format 200 * needs to be specified before setting recording-parameters or encoders. 201 * @throws IllegalStateException if it is called after prepare() or before 202 * setAudioSource()/setVideoSource(). 203 * @see android.media.MediaRecorder.OutputFormat 204 */ 205 public native void setOutputFormat(int output_format) 206 throws IllegalStateException; 207 208 /** 209 * Sets the width and height of the video to be captured. Must be called 210 * after setVideoSource(). Call this after setOutFormat() but before 211 * prepare(). 212 * 213 * @param width the width of the video to be captured 214 * @param height the height of the video to be captured 215 * @throws IllegalStateException if it is called after 216 * prepare() or before setOutputFormat() 217 * @hide 218 */ 219 public native void setVideoSize(int width, int height) 220 throws IllegalStateException; 221 222 /** 223 * Sets the frame rate of the video to be captured. Must be called 224 * after setVideoSource(). Call this after setOutFormat() but before 225 * prepare(). 226 * 227 * @param rate the number of frames per second of video to capture 228 * @throws IllegalStateException if it is called after 229 * prepare() or before setOutputFormat(). 230 * @hide 231 */ 232 public native void setVideoFrameRate(int rate) throws IllegalStateException; 233 234 /** 235 * Sets the audio encoder to be used for recording. If this method is not 236 * called, the output file will not contain an audio track. Call this after 237 * setOutputFormat() but before prepare(). 238 * 239 * @param audio_encoder the audio encoder to use. 240 * @throws IllegalStateException if it is called before 241 * setOutputFormat() or after prepare(). 242 * @see android.media.MediaRecorder.AudioEncoder 243 */ 244 public native void setAudioEncoder(int audio_encoder) 245 throws IllegalStateException; 246 247 /** 248 * Sets the video encoder to be used for recording. If this method is not 249 * called, the output file will not contain an video track. Call this after 250 * setOutputFormat() and before prepare(). 251 * 252 * @param video_encoder the video encoder to use. 253 * @throws IllegalStateException if it is called before 254 * setOutputFormat() or after prepare() 255 * @see android.media.MediaRecorder.VideoEncoder 256 * @hide 257 */ 258 public native void setVideoEncoder(int video_encoder) 259 throws IllegalStateException; 260 261 /** 262 * Sets the path of the output file to be produced. Call this after 263 * setOutputFormat() but before prepare(). 264 * 265 * @param path The pathname to use() 266 * @throws IllegalStateException if it is called before 267 * setOutputFormat() or after prepare() 268 */ 269 public native void setOutputFile(String path) throws IllegalStateException; 270 271 /** 272 * Prepares the recorder to begin capturing and encoding data. This method 273 * must be called after setting up the desired audio and video sources, 274 * encoders, file format, etc., but before start(). 275 * 276 * @throws IllegalStateException if it is called after 277 * start() or before setOutputFormat(). 278 * @throws IOException if prepare fails otherwise. 279 */ 280 public native void prepare() throws IllegalStateException, IOException; 281 282 /** 283 * Begins capturing and encoding data to the file specified with 284 * setOutputFile(). Call this after prepare(). 285 * 286 * @throws IllegalStateException if it is called before 287 * prepare(). 288 */ 289 public native void start() throws IllegalStateException; 290 291 /** 292 * Stops recording. Call this after start(). Once recording is stopped, 293 * you will have to configure it again as if it has just been constructed. 294 * 295 * @throws IllegalStateException if it is called before start() 296 */ 297 public native void stop() throws IllegalStateException; 298 299 /** 300 * Restarts the MediaRecorder to its idle state. After calling 301 * this method, you will have to configure it again as if it had just been 302 * constructed. 303 */ 304 public native void reset(); 305 306 /** 307 * Returns the maximum absolute amplitude that was sampled since the last 308 * call to this method. Call this only after the setAudioSource(). 309 * 310 * @return the maximum absolute amplitude measured since the last call, or 311 * 0 when called for the first time 312 * @throws IllegalStateException if it is called before 313 * the audio source has been set. 314 */ 315 public native int getMaxAmplitude() throws IllegalStateException; 316 317 318 /** 319 * Releases resources associated with this MediaRecorder object. 320 * It is good practice to call this method when you're done 321 * using the MediaRecorder. 322 */ 323 public native void release(); 324 325 private native final void native_setup() throws IllegalStateException; 326 327 private native final void native_finalize(); 328 329 @Override 330 protected void finalize() { native_finalize(); } 331} 332