public class MediaRecorder extends Object
A common case of using MediaRecorder to record audio works as follows:
MediaRecorder recorder = new MediaRecorder(); recorder.setAudioSource(MediaRecorder.AudioSource.MIC); recorder.setOutputFormat(MediaRecorder.OutputFormat.THREE_GPP); recorder.setAudioEncoder(MediaRecorder.AudioEncoder.AMR_NB); recorder.setOutputFile(PATH_NAME); recorder.prepare(); recorder.start(); // Recording is now started ... recorder.stop(); recorder.reset(); // You can reuse the object by going back to setAudioSource() step recorder.release(); // Now the object cannot be reused
Applications may want to register for informational and error
events in order to be informed of some internal update and possible
runtime errors during recording. Registration for such events is
done by setting the appropriate listeners (via calls
(to setOnInfoListener(OnInfoListener)
setOnInfoListener and/or
setOnErrorListener(OnErrorListener)
setOnErrorListener).
In order to receive the respective callback associated with these listeners,
applications are required to create MediaRecorder objects on threads with a
Looper running (the main UI thread by default already has a Looper running).
Note: Currently, MediaRecorder does not work on the emulator.
For more information about how to use MediaRecorder for recording video, read the Camera developer guide. For more information about how to use MediaRecorder for recording sound, read the Audio Capture developer guide.
Modifier and Type | Class and Description |
---|---|
class |
MediaRecorder.AudioEncoder
Defines the audio encoding.
|
class |
MediaRecorder.AudioSource
Defines the audio source.
|
static interface |
MediaRecorder.OnErrorListener
Interface definition for a callback to be invoked when an error
occurs while recording.
|
static interface |
MediaRecorder.OnInfoListener
Interface definition for a callback to be invoked when an error
occurs while recording.
|
class |
MediaRecorder.OutputFormat
Defines the output format.
|
class |
MediaRecorder.VideoEncoder
Defines the video encoding.
|
class |
MediaRecorder.VideoSource
Defines the video source.
|
Modifier and Type | Field and Description |
---|---|
static int |
MEDIA_ERROR_SERVER_DIED
Media server died.
|
static int |
MEDIA_RECORDER_ERROR_UNKNOWN
Unspecified media recorder error.
|
static int |
MEDIA_RECORDER_INFO_MAX_DURATION_REACHED
A maximum duration had been setup and has now been reached.
|
static int |
MEDIA_RECORDER_INFO_MAX_FILESIZE_REACHED
A maximum filesize had been setup and has now been reached.
|
static int |
MEDIA_RECORDER_INFO_UNKNOWN
Unspecified media recorder error.
|
static int |
MEDIA_RECORDER_TRACK_INFO_COMPLETION_STATUS
Signal the completion of the track for the recording session.
|
static int |
MEDIA_RECORDER_TRACK_INFO_DATA_KBYTES
Provide the total number of data (in kilo-bytes) encoded.
|
static int |
MEDIA_RECORDER_TRACK_INFO_DURATION_MS
Provide the track duration information.
|
static int |
MEDIA_RECORDER_TRACK_INFO_ENCODED_FRAMES
Provide the total number of recordd frames.
|
static int |
MEDIA_RECORDER_TRACK_INFO_INITIAL_DELAY_MS
Provide the elapsed time measuring from the start of the recording
till the first output frame of the given track is received, excluding
any intentional start time offset of a recording session for the
purpose of eliminating the recording sound in the recorded file.
|
static int |
MEDIA_RECORDER_TRACK_INFO_LIST_END |
static int |
MEDIA_RECORDER_TRACK_INFO_LIST_START
informational events for individual tracks, for testing purpose.
|
static int |
MEDIA_RECORDER_TRACK_INFO_MAX_CHUNK_DUR_MS
Provide the max chunk duration in time (ms) for the given track.
|
static int |
MEDIA_RECORDER_TRACK_INFO_PROGRESS_IN_TIME
Indicate the recording progress in time (ms) during recording.
|
static int |
MEDIA_RECORDER_TRACK_INFO_START_OFFSET_MS
Provide the start time difference (delay) betweeen this track and
the start of the movie.
|
static int |
MEDIA_RECORDER_TRACK_INFO_TYPE
Indicate the track type: 0 for Audio and 1 for Video.
|
static int |
MEDIA_RECORDER_TRACK_INTER_CHUNK_TIME_MS
Provide the max spacing between neighboring chunks for the given track.
|
Constructor and Description |
---|
MediaRecorder()
Default constructor.
|
Modifier and Type | Method and Description |
---|---|
protected void |
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
static int |
getAudioSourceMax()
Gets the maximum value for audio sources.
|
int |
getMaxAmplitude()
Returns the maximum absolute amplitude that was sampled since the last
call to this method.
|
Surface |
getSurface()
Gets the surface to record from when using SURFACE video source.
|
static boolean |
isSystemOnlyAudioSource(int source) |
void |
pause()
Pauses recording.
|
void |
prepare()
Prepares the recorder to begin capturing and encoding data.
|
void |
release()
Releases resources associated with this MediaRecorder object.
|
void |
reset()
Restarts the MediaRecorder to its idle state.
|
void |
resume()
Resumes recording.
|
void |
setAudioChannels(int numChannels)
Sets the number of audio channels for recording.
|
void |
setAudioEncoder(int audio_encoder)
Sets the audio encoder to be used for recording.
|
void |
setAudioEncodingBitRate(int bitRate)
Sets the audio encoding bit rate for recording.
|
void |
setAudioSamplingRate(int samplingRate)
Sets the audio sampling rate for recording.
|
void |
setAudioSource(int audio_source)
Sets the audio source to be used for recording.
|
void |
setAuxiliaryOutputFile(FileDescriptor fd)
Deprecated.
Time lapse mode video recording using camera still image capture
is not desirable, and will not be supported.
|
void |
setAuxiliaryOutputFile(String path)
Deprecated.
Time lapse mode video recording using camera still image capture
is not desirable, and will not be supported.
|
void |
setCamera(Camera c)
Deprecated.
Use
getSurface() and the android.hardware.camera2 API instead. |
void |
setCaptureRate(double fps)
Set video frame capture rate.
|
void |
setInputSurface(Surface surface)
Configures the recorder to use a persistent surface when using SURFACE video source.
|
void |
setLocation(float latitude,
float longitude)
Set and store the geodata (latitude and longitude) in the output file.
|
void |
setMaxDuration(int max_duration_ms)
Sets the maximum duration (in ms) of the recording session.
|
void |
setMaxFileSize(long max_filesize_bytes)
Sets the maximum filesize (in bytes) of the recording session.
|
void |
setOnErrorListener(MediaRecorder.OnErrorListener l)
Register a callback to be invoked when an error occurs while
recording.
|
void |
setOnInfoListener(MediaRecorder.OnInfoListener listener)
Register a callback to be invoked when an informational event occurs while
recording.
|
void |
setOrientationHint(int degrees)
Sets the orientation hint for output video playback.
|
void |
setOutputFile(FileDescriptor fd)
Pass in the file descriptor of the file to be written.
|
void |
setOutputFile(String path)
Sets the path of the output file to be produced.
|
void |
setOutputFormat(int output_format)
Sets the format of the output file produced during recording.
|
void |
setPreviewDisplay(Surface sv)
Sets a Surface to show a preview of recorded media (video).
|
void |
setProfile(CamcorderProfile profile)
Uses the settings from a CamcorderProfile object for recording.
|
void |
setVideoEncoder(int video_encoder)
Sets the video encoder to be used for recording.
|
void |
setVideoEncodingBitRate(int bitRate)
Sets the video encoding bit rate for recording.
|
void |
setVideoEncodingProfileLevel(int profile,
int level)
Sets the video encoding profile for recording.
|
void |
setVideoFrameRate(int rate)
Sets the frame rate of the video to be captured.
|
void |
setVideoSize(int width,
int height)
Sets the width and height of the video to be captured.
|
void |
setVideoSource(int video_source)
Sets the video source to be used for recording.
|
void |
start()
Begins capturing and encoding data to the file specified with
setOutputFile().
|
void |
stop()
Stops recording.
|
public static final int MEDIA_RECORDER_ERROR_UNKNOWN
public static final int MEDIA_ERROR_SERVER_DIED
public static final int MEDIA_RECORDER_INFO_UNKNOWN
public static final int MEDIA_RECORDER_INFO_MAX_DURATION_REACHED
public static final int MEDIA_RECORDER_INFO_MAX_FILESIZE_REACHED
public static final int MEDIA_RECORDER_TRACK_INFO_LIST_START
public static final int MEDIA_RECORDER_TRACK_INFO_COMPLETION_STATUS
public static final int MEDIA_RECORDER_TRACK_INFO_PROGRESS_IN_TIME
public static final int MEDIA_RECORDER_TRACK_INFO_TYPE
public static final int MEDIA_RECORDER_TRACK_INFO_DURATION_MS
public static final int MEDIA_RECORDER_TRACK_INFO_MAX_CHUNK_DUR_MS
public static final int MEDIA_RECORDER_TRACK_INFO_ENCODED_FRAMES
public static final int MEDIA_RECORDER_TRACK_INTER_CHUNK_TIME_MS
public static final int MEDIA_RECORDER_TRACK_INFO_INITIAL_DELAY_MS
public static final int MEDIA_RECORDER_TRACK_INFO_START_OFFSET_MS
public static final int MEDIA_RECORDER_TRACK_INFO_DATA_KBYTES
public static final int MEDIA_RECORDER_TRACK_INFO_LIST_END
@Deprecated public void setCamera(Camera c)
getSurface()
and the android.hardware.camera2
API instead.Camera
to use for recording.
Use this function to switch quickly between preview and capture mode without a teardown of
the camera object. Camera.unlock()
should be called before
this. Must call before prepare()
.
c
- the Camera to use for recordingpublic Surface getSurface()
May only be called after prepare()
. Frames rendered to the Surface before
start()
will be discarded.
IllegalStateException
- if it is called before prepare()
, after
stop()
, or is called when VideoSource is not set to SURFACE.MediaRecorder.VideoSource
public void setInputSurface(Surface surface)
May only be called before prepare()
. If called, getSurface()
should
not be used and will throw IllegalStateException. Frames rendered to the Surface
before start()
will be discarded.
surface
- a persistent input surface created by
MediaCodec.createPersistentInputSurface()
IllegalStateException
- if it is called after prepare()
and before
stop()
.IllegalArgumentException
- if the surface was not created by
MediaCodec.createPersistentInputSurface()
.MediaCodec.createPersistentInputSurface()
,
MediaRecorder.VideoSource
public void setPreviewDisplay(Surface sv)
setCamera(Camera)
is used and the surface has been
already set to the camera, application do not need to call this. If
this is called with non-null surface, the preview surface of the camera
will be replaced by the new surface. If this method is called with null
surface or not called at all, media recorder will not change the preview
surface of the camera.sv
- the Surface to use for the previewCamera.setPreviewDisplay(android.view.SurfaceHolder)
public static boolean isSystemOnlyAudioSource(int source)
source
- An audio source to testpublic void setAudioSource(int audio_source) throws IllegalStateException
audio_source
- the audio source to useIllegalStateException
- if it is called after setOutputFormat()MediaRecorder.AudioSource
public static final int getAudioSourceMax()
MediaRecorder.AudioSource
public void setVideoSource(int video_source) throws IllegalStateException
video_source
- the video source to useIllegalStateException
- if it is called after setOutputFormat()MediaRecorder.VideoSource
public void setProfile(CamcorderProfile profile)
profile
- the CamcorderProfile to useCamcorderProfile
public void setCaptureRate(double fps)
fps
- Rate at which frames should be captured in frames per second.
The fps can go as low as desired. However the fastest fps will be limited by the hardware.
For resolutions that can be captured by the video camera, the fastest fps can be computed using
Camera.Parameters.getPreviewFpsRange(int[])
. For higher
resolutions the fastest fps may be more restrictive.
Note that the recorder cannot guarantee that frames will be captured at the
given rate due to camera/encoder limitations. However it tries to be as close as
possible.public void setOrientationHint(int degrees)
degrees
- the angle to be rotated clockwise in degrees.
The supported angles are 0, 90, 180, and 270 degrees.IllegalArgumentException
- if the angle is not supported.public void setLocation(float latitude, float longitude)
latitude
- latitude in degrees. Its value must be in the
range [-90, 90].longitude
- longitude in degrees. Its value must be in the
range [-180, 180].IllegalArgumentException
- if the given latitude or
longitude is out of range.public void setOutputFormat(int output_format) throws IllegalStateException
It is recommended to always use 3GP format when using the H.263 video encoder and AMR audio encoder. Using an MPEG-4 container format may confuse some desktop players.
output_format
- the output format to use. The output format
needs to be specified before setting recording-parameters or encoders.IllegalStateException
- if it is called after prepare() or before
setAudioSource()/setVideoSource().MediaRecorder.OutputFormat
public void setVideoSize(int width, int height) throws IllegalStateException
width
- the width of the video to be capturedheight
- the height of the video to be capturedIllegalStateException
- if it is called after
prepare() or before setOutputFormat()public void setVideoFrameRate(int rate) throws IllegalStateException
rate
- the number of frames per second of video to captureIllegalStateException
- if it is called after
prepare() or before setOutputFormat().
NOTE: On some devices that have auto-frame rate, this sets the
maximum frame rate, not a constant frame rate. Actual frame rate
will vary according to lighting conditions.public void setMaxDuration(int max_duration_ms) throws IllegalArgumentException
MediaRecorder.OnInfoListener
with a "what" code of MEDIA_RECORDER_INFO_MAX_DURATION_REACHED
and recording will be stopped. Stopping happens asynchronously, there
is no guarantee that the recorder will have stopped by the time the
listener is notified.max_duration_ms
- the maximum duration in ms (if zero or negative, disables the duration limit)IllegalArgumentException
public void setMaxFileSize(long max_filesize_bytes) throws IllegalArgumentException
MediaRecorder.OnInfoListener
with a "what" code of MEDIA_RECORDER_INFO_MAX_FILESIZE_REACHED
and recording will be stopped. Stopping happens asynchronously, there
is no guarantee that the recorder will have stopped by the time the
listener is notified.max_filesize_bytes
- the maximum filesize in bytes (if zero or negative, disables the limit)IllegalArgumentException
public void setAudioEncoder(int audio_encoder) throws IllegalStateException
audio_encoder
- the audio encoder to use.IllegalStateException
- if it is called before
setOutputFormat() or after prepare().MediaRecorder.AudioEncoder
public void setVideoEncoder(int video_encoder) throws IllegalStateException
video_encoder
- the video encoder to use.IllegalStateException
- if it is called before
setOutputFormat() or after prepare()MediaRecorder.VideoEncoder
public void setAudioSamplingRate(int samplingRate)
samplingRate
- the sampling rate for audio in samples per second.public void setAudioChannels(int numChannels)
numChannels
- the number of audio channels. Usually it is either 1 (mono) or 2
(stereo).public void setAudioEncodingBitRate(int bitRate)
bitRate
- the audio encoding bit rate in bits per second.public void setVideoEncodingBitRate(int bitRate)
bitRate
- the video encoding bit rate in bits per second.public void setVideoEncodingProfileLevel(int profile, int level)
profile
- declared in MediaCodecInfo.CodecProfileLevel
.level
- declared in MediaCodecInfo.CodecProfileLevel
.public void setAuxiliaryOutputFile(FileDescriptor fd)
public void setAuxiliaryOutputFile(String path)
public void setOutputFile(FileDescriptor fd) throws IllegalStateException
fd
- an open file descriptor to be written into.IllegalStateException
- if it is called before
setOutputFormat() or after prepare()public void setOutputFile(String path) throws IllegalStateException
path
- The pathname to use.IllegalStateException
- if it is called before
setOutputFormat() or after prepare()public void prepare() throws IllegalStateException, IOException
IllegalStateException
- if it is called after
start() or before setOutputFormat().IOException
- if prepare fails otherwise.public void start() throws IllegalStateException
Since API level 13, if applications set a camera via
setCamera(Camera)
, the apps can use the camera after this method
call. The apps do not need to lock the camera again. However, if this
method fails, the apps should still lock the camera back. The apps should
not start another recording session during recording.
IllegalStateException
- if it is called before
prepare().public void stop() throws IllegalStateException
IllegalStateException
- if it is called before start()public void pause() throws IllegalStateException
IllegalStateException
- if it is called before start() or after
stop()public void resume() throws IllegalStateException
IllegalStateException
- if it is called before start() or after
stop()pause()
public void reset()
public int getMaxAmplitude() throws IllegalStateException
IllegalStateException
- if it is called before
the audio source has been set.public void setOnErrorListener(MediaRecorder.OnErrorListener l)
l
- the callback that will be runpublic void setOnInfoListener(MediaRecorder.OnInfoListener listener)
listener
- the callback that will be runpublic void release()
protected void finalize()
Object
finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the JavaTM virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.