* <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
// 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
// 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;
*/
private int mNativeBufferSizeInBytes = 0;
-
+
//---------------------------------------------------------
// Constructor, Finalize
//--------------------
* {@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,
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 {
native_release();
mState = STATE_UNINITIALIZED;
}
-
+
@Override
protected void finalize() {
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
* 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;
/**
* 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
/**
* 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.
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) {
}
}
-
-
+
+
/**
* Sets the marker position at which the listener is called, if set with
* {@link #setRecordPositionUpdateListener(OnRecordPositionUpdateListener)} or
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
//--------------------
/**
* 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 {
/**
*/
void onPeriodicNotification(AudioRecord recorder);
}
-
-
-
+
+
//---------------------------------------------------------
// Inner classes
//--------------------
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;
}
-
-
-
-
OSDN Git Service
