AI 146941: am: CL 146938 am: CL 146937 Finalize AudioRecord javadoc. (954bbe9f) · Commits · e / os / android_frameworks_base

media/java/android/media/AudioRecord.java

+46 −35

Original line number	Original line	Diff line number	Diff line
	@@ -40,7 +40,7 @@ import android.util.Log;
	* <p>Upon creation, an AudioRecord object initializes its associated audio buffer that it will		* <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,		* 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		* 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.		* the total recording buffer size.
	*/		*/
	public class AudioRecord		public class AudioRecord
	@@ -49,20 +49,20 @@ public class AudioRecord
	// Constants		// 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;		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;		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		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		public static final int RECORDSTATE_RECORDING = 3;// matches SL_RECORDSTATE_RECORDING

	@@ -94,11 +94,11 @@ public class AudioRecord
	// Events:		// Events:
	// to keep in sync with frameworks/base/include/media/AudioRecord.h		// 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;		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 static final int NATIVE_EVENT_NEW_POS = 3;

	@@ -206,7 +206,9 @@ public class AudioRecord
	* {@link AudioFormat#ENCODING_PCM_8BIT}		* {@link AudioFormat#ENCODING_PCM_8BIT}
	* @param bufferSizeInBytes the total size (in bytes) of the buffer where audio data is written		* @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		* 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		* @throws java.lang.IllegalArgumentException
	*/		*/
	public AudioRecord(int audioSource, int sampleRateInHz, int channelConfig, int audioFormat,		public AudioRecord(int audioSource, int sampleRateInHz, int channelConfig, int audioFormat,
	@@ -324,6 +326,8 @@ public class AudioRecord

	/**		/**
	* Releases the native AudioRecord resources.		* 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() {		public void release() {
	try {		try {
	@@ -406,14 +410,14 @@ public class AudioRecord
	}		}

	/**		/**
	* @return marker position in frames		* Returns the notification marker position expressed in frames.
	*/		*/
	public int getNotificationMarkerPosition() {		public int getNotificationMarkerPosition() {
	return native_get_marker_pos();		return native_get_marker_pos();
	}		}

	/**		/**
	* @return update period in frames		* Returns the notification update period expressed in frames.
	*/		*/
	public int getPositionNotificationPeriod() {		public int getPositionNotificationPeriod() {
	return native_get_pos_update_period();		return native_get_pos_update_period();
	@@ -422,6 +426,9 @@ public class AudioRecord
	/**		/**
	* Returns the minimum buffer size required for the successful creation of an AudioRecord		* Returns the minimum buffer size required for the successful creation of an AudioRecord
	* object.		* 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 sampleRateInHz the sample rate expressed in Hertz.
	* @param channelConfig describes the configuration of the audio channels.		* @param channelConfig describes the configuration of the audio channels.
	* See {@link AudioFormat#CHANNEL_CONFIGURATION_MONO} and		* See {@link AudioFormat#CHANNEL_CONFIGURATION_MONO} and
	@@ -432,7 +439,7 @@ public class AudioRecord
	* hardware, or an invalid parameter was passed,		* hardware, or an invalid parameter was passed,
	* or {@link #ERROR} if the implementation was unable to query the hardware for its		* or {@link #ERROR} if the implementation was unable to query the hardware for its
	* output properties,		* 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) {		static public int getMinBufferSize(int sampleRateInHz, int channelConfig, int audioFormat) {
	int channelCount = 0;		int channelCount = 0;
	@@ -516,7 +523,7 @@ public class AudioRecord
	/**		/**
	* Reads audio data from the audio hardware for recording into a buffer.		* 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 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.		* @param sizeInBytes the number of requested bytes.
	* @return the number of bytes that were read or or {@link #ERROR_INVALID_OPERATION}		* @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		* 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.		* 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 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.		* @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		* if the object wasn't properly initialized, or {@link #ERROR_BAD_VALUE} if
	* the parameters don't resolve to valid data and indexes.		* the parameters don't resolve to valid data and indexes.
	* The number of shorts will not exceed sizeInShorts.		* The number of shorts will not exceed sizeInShorts.
	@@ -596,7 +603,14 @@ public class AudioRecord
	setRecordPositionUpdateListener(listener, null);		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,		public void setRecordPositionUpdateListener(OnRecordPositionUpdateListener listener,
	Handler handler) {		Handler handler) {
	synchronized (mPositionListenerLock) {		synchronized (mPositionListenerLock) {
	@@ -648,7 +662,9 @@ public class AudioRecord
	//--------------------		//--------------------
	/**		/**
	* Interface definition for a callback to be invoked when an AudioRecord has		* 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 {		public interface OnRecordPositionUpdateListener {
	/**		/**
	@@ -666,7 +682,6 @@ public class AudioRecord




	//---------------------------------------------------------		//---------------------------------------------------------
	// Inner classes		// Inner classes
	//--------------------		//--------------------
	@@ -779,7 +794,3 @@ public class AudioRecord

	}		}