public class

AudioRecord

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

Class Overview

The AudioRecord class manages the audio resources for Java applications to record audio from the audio input hardware of the platform. This is achieved by "pulling" (reading) the data from the AudioRecord object. The application is responsible for polling the AudioRecord object in time using one of the following three methods: read(byte[], int, int), read(short[], int, int) or read(ByteBuffer, int). The choice of which method to use will be based on the audio data storage format that is the most convenient for the user of AudioRecord.

Upon creation, an AudioRecord object initializes its associated audio buffer that it will fill with the new audio data. The size of this buffer, specified during the construction, determines how long an AudioRecord can record before "over-running" data that has not been read yet. Data should be read from the audio hardware in chunks of sizes inferior to the total recording buffer size.

Summary

Nested Classes
public class AudioRecord.OnRecordPositionUpdateListener Interface definition for a callback to be invoked when an AudioRecord has reached a notification marker set by setNotificationMarkerPosition(int) or for periodic updates on the progress of the record head, as set by setPositionNotificationPeriod(int)
Constants
int ERROR Denotes a generic operation failure.
int ERROR_BAD_VALUE Denotes a failure due to the use of an invalid value.
int ERROR_INVALID_OPERATION Denotes a failure due to the improper use of a method.
int RECORDSTATE_RECORDING indicates AudioRecord recording state is recording
int RECORDSTATE_STOPPED indicates AudioRecord recording state is not recording
int STATE_INITIALIZED indicates AudioRecord state is ready to be used
int STATE_UNINITIALIZED indicates AudioRecord state is not successfully initialized.
int SUCCESS Denotes a successful operation.
Public Constructors
AudioRecord(int audioSource, int sampleRateInHz, int channelConfig, int audioFormat, int bufferSizeInBytes)
Class constructor.
Public Methods
int getAudioFormat()
Returns the configured audio data format.
int getAudioSource()
Returns the audio recording source.
int getChannelConfiguration()
Returns the configured channel configuration.
int getChannelCount()
Returns the configured number of channels.
static int getMinBufferSize(int sampleRateInHz, int channelConfig, int audioFormat)
Returns the minimum buffer size required for the successful creation of an AudioRecord object.
int getNotificationMarkerPosition()
Returns the notification marker position expressed in frames.
int getPositionNotificationPeriod()
Returns the notification update period expressed in frames.
int getRecordingState()
Returns the recording state of the AudioRecord instance.
int getSampleRate()
Returns the configured audio data sample rate in Hz
int getState()
Returns the state of the AudioRecord instance.
int read(short[] audioData, int offsetInShorts, int sizeInShorts)
Reads audio data from the audio hardware for recording into a buffer.
int read(byte[] audioData, int offsetInBytes, int sizeInBytes)
Reads audio data from the audio hardware for recording into a buffer.
int read(ByteBuffer audioBuffer, int sizeInBytes)
Reads audio data from the audio hardware for recording into a direct buffer.
void release()
Releases the native AudioRecord resources.
int setNotificationMarkerPosition(int markerInFrames)
int setPositionNotificationPeriod(int periodInFrames)
void setRecordPositionUpdateListener(AudioRecord.OnRecordPositionUpdateListener listener)
Sets the listener the AudioRecord notifies when a previously set marker is reached or for each periodic record head position update.
void setRecordPositionUpdateListener(AudioRecord.OnRecordPositionUpdateListener listener, Handler handler)
Sets the listener the AudioRecord notifies when a previously set marker is reached or for each periodic record head position update.
void startRecording()
Starts recording from the AudioRecord instance.
void stop()
Stops recording.
Protected Methods
void finalize()
Is called before the object's memory is being reclaimed by the VM.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int ERROR

Denotes a generic operation failure.

Constant Value: -1 (0xffffffff)

public static final int ERROR_BAD_VALUE

Denotes a failure due to the use of an invalid value.

Constant Value: -2 (0xfffffffe)

public static final int ERROR_INVALID_OPERATION

Denotes a failure due to the improper use of a method.

Constant Value: -3 (0xfffffffd)

public static final int RECORDSTATE_RECORDING

indicates AudioRecord recording state is recording

Constant Value: 3 (0x00000003)

public static final int RECORDSTATE_STOPPED

indicates AudioRecord recording state is not recording

Constant Value: 1 (0x00000001)

public static final int STATE_INITIALIZED

indicates AudioRecord state is ready to be used

Constant Value: 1 (0x00000001)

public static final int STATE_UNINITIALIZED

indicates AudioRecord state is not successfully initialized.

Constant Value: 0 (0x00000000)

public static final int SUCCESS

Denotes a successful operation.

Constant Value: 0 (0x00000000)

Public Constructors

public AudioRecord (int audioSource, int sampleRateInHz, int channelConfig, int audioFormat, int bufferSizeInBytes)

Class constructor.

Parameters
audioSource the recording source. See MediaRecorder.AudioSource for recording source definitions.
sampleRateInHz the sample rate expressed in Hertz. Examples of rates are (but not limited to) 44100, 22050 and 11025.
channelConfig describes the configuration of the audio channels. See CHANNEL_CONFIGURATION_MONO and CHANNEL_CONFIGURATION_STEREO
audioFormat the format in which the audio data is represented. See ENCODING_PCM_16BIT and ENCODING_PCM_8BIT
bufferSizeInBytes the total size (in bytes) of the buffer where audio data is written to during the recording. New audio data can be read from this buffer in smaller chunks than this size. See getMinBufferSize(int, int, int) to determine the minimum required buffer size for the successful creation of an AudioRecord instance. Using values smaller than getMinBufferSize() will result in an initialization failure.

Public Methods

public int getAudioFormat ()

Returns the configured audio data format. See ENCODING_PCM_16BIT and ENCODING_PCM_8BIT.

public int getAudioSource ()

Returns the audio recording source.

public int getChannelConfiguration ()

Returns the configured channel configuration. See CHANNEL_CONFIGURATION_MONO and CHANNEL_CONFIGURATION_STEREO.

public int getChannelCount ()

Returns the configured number of channels.

public static int getMinBufferSize (int sampleRateInHz, int channelConfig, int audioFormat)

Returns the minimum buffer size required for the successful creation of an AudioRecord object. Note that this size doesn't guarantee a smooth recording under load, and higher values should be chosen according to the expected frequency at which the AudioRecord instance will be polled for new data.

Parameters
sampleRateInHz the sample rate expressed in Hertz.
channelConfig describes the configuration of the audio channels. See CHANNEL_CONFIGURATION_MONO and CHANNEL_CONFIGURATION_STEREO
audioFormat the format in which the audio data is represented. See ENCODING_PCM_16BIT.
Returns
  • ERROR_BAD_VALUE if the recording parameters are not supported by the hardware, or an invalid parameter was passed, or ERROR if the implementation was unable to query the hardware for its output properties, or the minimum buffer size expressed in bytes.

public int getNotificationMarkerPosition ()

Returns the notification marker position expressed in frames.

public int getPositionNotificationPeriod ()

Returns the notification update period expressed in frames.

public int getRecordingState ()

Returns the recording state of the AudioRecord instance.

public int getSampleRate ()

Returns the configured audio data sample rate in Hz

public int getState ()

Returns the state of the AudioRecord instance. This is useful after the AudioRecord instance has been created to check if it was initialized properly. This ensures that the appropriate hardware resources have been acquired.

public int read (short[] audioData, int offsetInShorts, int sizeInShorts)

Reads audio data from the audio hardware for recording into a buffer.

Parameters
audioData the array to which the recorded audio data is written.
offsetInShorts index in audioData from which the data is written expressed in shorts.
sizeInShorts the number of requested shorts.
Returns
  • the number of shorts that were read or or ERROR_INVALID_OPERATION if the object wasn't properly initialized, or ERROR_BAD_VALUE if the parameters don't resolve to valid data and indexes. The number of shorts will not exceed sizeInShorts.

public int read (byte[] audioData, int offsetInBytes, int sizeInBytes)

Reads audio data from the audio hardware for recording into a buffer.

Parameters
audioData the array to which the recorded audio data is written.
offsetInBytes index in audioData from which the data is written expressed in bytes.
sizeInBytes the number of requested bytes.
Returns
  • the number of bytes that were read or or ERROR_INVALID_OPERATION if the object wasn't properly initialized, or ERROR_BAD_VALUE if the parameters don't resolve to valid data and indexes. The number of bytes will not exceed sizeInBytes.

public int read (ByteBuffer audioBuffer, int sizeInBytes)

Reads audio data from the audio hardware for recording into a direct buffer. If this buffer is not a direct buffer, this method will always return 0.

Parameters
audioBuffer the direct buffer to which the recorded audio data is written.
sizeInBytes the number of requested bytes.
Returns
  • the number of bytes that were read or or ERROR_INVALID_OPERATION if the object wasn't properly initialized, or ERROR_BAD_VALUE if the parameters don't resolve to valid data and indexes. The number of bytes will not exceed sizeInBytes.

public void release ()

Releases the native AudioRecord resources. The object can no longer be used and the reference should be set to null after a call to release()

public int setNotificationMarkerPosition (int markerInFrames)

Parameters
markerInFrames marker position expressed in frames
Returns

public int setPositionNotificationPeriod (int periodInFrames)

Parameters
periodInFrames update period expressed in frames
Returns

public void setRecordPositionUpdateListener (AudioRecord.OnRecordPositionUpdateListener listener)

Sets the listener the AudioRecord notifies when a previously set marker is reached or for each periodic record head position update.

public void setRecordPositionUpdateListener (AudioRecord.OnRecordPositionUpdateListener listener, Handler handler)

Sets the listener the AudioRecord notifies when a previously set marker is reached or for each periodic record head position update. Use this method to receive AudioRecord events in the Handler associated with another thread than the one in which you created the AudioTrack instance.

Parameters
handler the Handler that will receive the event notification messages.

public void startRecording ()

Starts recording from the AudioRecord instance.

public void stop ()

Stops recording.

Protected Methods

protected void finalize ()

Is called before the object's memory is being reclaimed by the VM. This can only happen once the VM has detected, during a run of the garbage collector, that the object is no longer reachable by any thread of the running application.

The method can be used to free system resources or perform other cleanup before the object is garbage collected. The default implementation of the method is empty, which is also expected by the VM, but subclasses can override finalize() as required. Uncaught exceptions which are thrown during the execution of this method cause it to terminate immediately but are otherwise ignored.

Note that the VM does guarantee that finalize() is called at most once for any object, but it doesn't guarantee when (if at all) finalize() will be called. For example, object B's finalize() can delay the execution of object A's finalize() method and therefore it can delay the reclamation of A's memory. To be safe, use a ReferenceQueue, because it provides more control over the way the VM deals with references during garbage collection.