Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

AI 146937: Finalize AudioRecord javadoc.

Browse Source 
BUG=1797606

Automated import of CL 146937
This commit is contained in:
Jean-Michel Trivi
2009-04-20 10:45:02 -07:00
committed by The Android Open Source Project
parent 62200dd153
commit a9a66950d6
1 changed files with 46 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
media/java/android/media/AudioRecord.java
View File

@@ -40,7 +40,7 @@ import android.util.Log;
* <p>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 from the audio hardware in chunks of sizes inferior to
* been read yet. Data should be read from the audio hardware in chunks of sizes inferior to
* the total recording buffer size.
*/
public class AudioRecord
@@ -49,20 +49,20 @@ public class AudioRecord
// Constants
//--------------------
/**
* State of an AudioRecord that was not successfully initialized upon creation
* indicates AudioRecord state is not successfully initialized.
*/
public static final int STATE_UNINITIALIZED = 0;
/**
* State of an AudioRecord that is ready to be used
* indicates AudioRecord state is ready to be used
*/
public static final int STATE_INITIALIZED = 1;
/**
* State of an AudioRecord this is not recording
* indicates AudioRecord recording state is not recording
*/
public static final int RECORDSTATE_STOPPED = 1; // matches SL_RECORDSTATE_STOPPED
/**
* State of an AudioRecord this is recording
* indicates AudioRecord recording state is recording
*/
public static final int RECORDSTATE_RECORDING = 3;// matches SL_RECORDSTATE_RECORDING
@@ -94,11 +94,11 @@ public class AudioRecord
// Events:
// to keep in sync with frameworks/base/include/media/AudioRecord.h
/**
* Event id for when the recording head has reached a previously set marker.
* Event id denotes when record head has reached a previously set marker.
*/
private static final int NATIVE_EVENT_MARKER = 2;
/**
* Event id for when the previously set update period has passed during recording.
* Event id denotes when previously set update period has elapsed during recording.
*/
private static final int NATIVE_EVENT_NEW_POS = 3;
@@ -188,7 +188,7 @@ public class AudioRecord
*/
private int mNativeBufferSizeInBytes = 0;
//---------------------------------------------------------
// Constructor, Finalize
//--------------------
@@ -206,7 +206,9 @@ public class AudioRecord
* {@link AudioFormat#ENCODING_PCM_8BIT}
* @param 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.
* than this size. See {@link #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.
* @throws java.lang.IllegalArgumentException
*/
public AudioRecord(int audioSource, int sampleRateInHz, int channelConfig, int audioFormat,
@@ -319,11 +321,13 @@ public class AudioRecord
mNativeBufferSizeInBytes = audioBufferSize;
}
/**
* 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 void release() {
try {
@@ -334,7 +338,7 @@ public class AudioRecord
native_release();
mState = STATE_UNINITIALIZED;
}
@Override
protected void finalize() {
@@ -404,24 +408,27 @@ public class AudioRecord
public int getRecordingState() {
return mRecordingState;
}
/**
* @return marker position in frames
* Returns the notification marker position expressed in frames.
*/
public int getNotificationMarkerPosition() {
return native_get_marker_pos();
}
/**
* @return update period in frames
* Returns the notification update period expressed in frames.
*/
public int getPositionNotificationPeriod() {
return native_get_pos_update_period();
}
/**
* 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.
* @param sampleRateInHz the sample rate expressed in Hertz.
* @param channelConfig describes the configuration of the audio channels.
* See {@link AudioFormat#CHANNEL_CONFIGURATION_MONO} and
@@ -432,7 +439,7 @@ public class AudioRecord
* hardware, or an invalid parameter was passed,
* or {@link #ERROR} if the implementation was unable to query the hardware for its
* output properties,
* or the minimum buffer size expressed in of bytes.
* or the minimum buffer size expressed in bytes.
*/
static public int getMinBufferSize(int sampleRateInHz, int channelConfig, int audioFormat) {
int channelCount = 0;
@@ -516,7 +523,7 @@ public class AudioRecord
/**
* Reads audio data from the audio hardware for recording into a buffer.
* @param audioData the array to which the recorded audio data is written.
* @param offsetInBytes index in audioData from which the data is written.
* @param offsetInBytes index in audioData from which the data is written expressed in bytes.
* @param sizeInBytes the number of requested bytes.
* @return the number of bytes that were read or or {@link #ERROR_INVALID_OPERATION}
* if the object wasn't properly initialized, or {@link #ERROR_BAD_VALUE} if
@@ -540,9 +547,9 @@ public class AudioRecord
/**
* Reads audio data from the audio hardware for recording into a buffer.
* @param audioData the array to which the recorded audio data is written.
* @param offsetInShorts index in audioData from which the data is written.
* @param offsetInShorts index in audioData from which the data is written expressed in shorts.
* @param sizeInShorts the number of requested shorts.
* @return the number of bytes that were read or or {@link #ERROR_INVALID_OPERATION}
* @return the number of shorts that were read or or {@link #ERROR_INVALID_OPERATION}
* if the object wasn't properly initialized, or {@link #ERROR_BAD_VALUE} if
* the parameters don't resolve to valid data and indexes.
* The number of shorts will not exceed sizeInShorts.
@@ -595,8 +602,15 @@ public class AudioRecord
public void setRecordPositionUpdateListener(OnRecordPositionUpdateListener listener) {
setRecordPositionUpdateListener(listener, null);
}
/**
* 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.
* @param listener
* @param handler the Handler that will receive the event notification messages.
*/
public void setRecordPositionUpdateListener(OnRecordPositionUpdateListener listener,
Handler handler) {
synchronized (mPositionListenerLock) {
@@ -616,8 +630,8 @@ public class AudioRecord
}
}
/**
* Sets the marker position at which the listener is called, if set with
* {@link #setRecordPositionUpdateListener(OnRecordPositionUpdateListener)} or
@@ -629,8 +643,8 @@ public class AudioRecord
public int setNotificationMarkerPosition(int markerInFrames) {
return native_set_marker_pos(markerInFrames);
}
/**
* Sets the period at which the listener is called, if set with
* {@link #setRecordPositionUpdateListener(OnRecordPositionUpdateListener)} or
@@ -648,7 +662,9 @@ public class AudioRecord
//--------------------
/**
* Interface definition for a callback to be invoked when an AudioRecord has
* reached a notification marker set by setNotificationMarkerPosition().
* reached a notification marker set by {@link AudioRecord#setNotificationMarkerPosition(int)}
* or for periodic updates on the progress of the record head, as set by
* {@link AudioRecord#setPositionNotificationPeriod(int)}.
*/
public interface OnRecordPositionUpdateListener {
/**
@@ -663,10 +679,9 @@ public class AudioRecord
*/
void onPeriodicNotification(AudioRecord recorder);
}
//---------------------------------------------------------
// Inner classes
//--------------------
@@ -678,12 +693,12 @@ public class AudioRecord
private class NativeEventHandler extends Handler {
private final AudioRecord mAudioRecord;
NativeEventHandler(AudioRecord recorder, Looper looper) {
super(looper);
mAudioRecord = recorder;
}
@Override
public void handleMessage(Message msg) {
OnRecordPositionUpdateListener listener = null;
@@ -779,7 +794,3 @@ public class AudioRecord
}