* If track's creation mode is {@link #MODE_STATIC}, you must have called one of - * the {@link #write(byte[], int, int)}, {@link #write(short[], int, int)}, - * or {@link #write(float[], int, int, int)} methods. - * If the mode is {@link #MODE_STREAM}, you can optionally prime the - * output buffer by writing up to bufferSizeInBytes (from constructor) before starting. - * This priming will avoid an immediate underrun, but is not required. + * the write methods ({@link #write(byte[], int, int)}, {@link #write(byte[], int, int, int)}, + * {@link #write(short[], int, int)}, {@link #write(short[], int, int, int)}, + * {@link #write(float[], int, int, int)}, or {@link #write(ByteBuffer, int, int)}) prior to + * play(). + *
+ * If the mode is {@link #MODE_STREAM}, you can optionally prime the data path prior to
+ * calling play(), by writing up to bufferSizeInBytes (from constructor).
+ * If you don’t call write() first, or if you call write() but with an insufficient amount of
+ * data, then the track will be in underrun state at play(). In this case,
+ * playback will not actually start playing until the data path is filled to a
+ * device-specific minimum level. This requirement for the path to be filled
+ * to a minimum level is also true when resuming audio playback after calling stop().
+ * Similarly the buffer will need to be filled up again after
+ * the track underruns due to failure to call write() in a timely manner with sufficient data.
+ * For portability, an application should prime the data path to the maximum allowed
+ * by writing data until the write() method returns a short transfer count.
+ * This allows play() to start immediately, and reduces the chance of underrun.
*
- * @throws IllegalStateException
+ * @throws IllegalStateException if the track isn't properly initialized
*/
public void play()
throws IllegalStateException {
@@ -1567,21 +1587,30 @@ public class AudioTrack
* or copies audio data for later playback (static buffer mode).
* The format specified in the AudioTrack constructor should be
* {@link AudioFormat#ENCODING_PCM_8BIT} to correspond to the data in the array.
- * In streaming mode, will block until all data has been written to the audio sink.
+ *
+ * In streaming mode, the write will normally block until all the data has been enqueued for + * playback, and will return a full transfer count. However, if the track is stopped or paused + * on entry, or another thread interrupts the write by calling stop or pause, or an I/O error + * occurs during the write, then the write may return a short transfer count. + *
* In static buffer mode, copies the data to the buffer starting at offset 0.
- * Note that the actual playback of this data might occur after this function
- * returns. This function is thread safe with respect to {@link #stop} calls,
- * in which case all of the specified data might not be written to the audio sink.
+ * Note that the actual playback of this data might occur after this function returns.
*
* @param audioData the array that holds the data to play.
* @param offsetInBytes the offset expressed in bytes in audioData where the data to play
* starts.
* @param sizeInBytes the number of bytes to read in audioData after the offset.
- * @return the number of bytes that were written or {@link #ERROR_INVALID_OPERATION}
- * if the object wasn't properly initialized, or {@link #ERROR_BAD_VALUE} if
+ * @return zero or the positive number of bytes that were written, or
+ * {@link #ERROR_INVALID_OPERATION}
+ * if the track isn't properly initialized, or {@link #ERROR_BAD_VALUE} if
* the parameters don't resolve to valid data and indexes, or
* {@link AudioManager#ERROR_DEAD_OBJECT} if the AudioTrack is not valid anymore and
* needs to be recreated.
+ * The dead object error code is not returned if some data was successfully transferred.
+ * In this case, the error is returned at the next write().
+ *
+ * This is equivalent to {@link #write(byte[], int, int, int)} with writeMode
+ * set to {@link #WRITE_BLOCKING}.
*/
public int write(@NonNull byte[] audioData, int offsetInBytes, int sizeInBytes) {
return write(audioData, offsetInBytes, sizeInBytes, WRITE_BLOCKING);
@@ -1592,11 +1621,17 @@ public class AudioTrack
* or copies audio data for later playback (static buffer mode).
* The format specified in the AudioTrack constructor should be
* {@link AudioFormat#ENCODING_PCM_8BIT} to correspond to the data in the array.
- * In streaming mode, will block until all data has been written to the audio sink.
- * In static buffer mode, copies the data to the buffer starting at offset 0.
- * Note that the actual playback of this data might occur after this function
- * returns. This function is thread safe with respect to {@link #stop} calls,
- * in which case all of the specified data might not be written to the audio sink.
+ *
+ * In streaming mode, the blocking behavior depends on the write mode. If the write mode is + * {@link #WRITE_BLOCKING}, the write will normally block until all the data has been enqueued + * for playback, and will return a full transfer count. However, if the write mode is + * {@link #WRITE_NON_BLOCKING}, or the track is stopped or paused on entry, or another thread + * interrupts the write by calling stop or pause, or an I/O error + * occurs during the write, then the write may return a short transfer count. + *
+ * In static buffer mode, copies the data to the buffer starting at offset 0,
+ * and the write mode is ignored.
+ * Note that the actual playback of this data might occur after this function returns.
*
* @param audioData the array that holds the data to play.
* @param offsetInBytes the offset expressed in bytes in audioData where the data to play
@@ -1608,11 +1643,14 @@ public class AudioTrack
* to the audio sink.
*
With {@link #WRITE_NON_BLOCKING}, the write will return immediately after
* queuing as much audio data for playback as possible without blocking.
- * @return the number of bytes that were written or {@link #ERROR_INVALID_OPERATION}
- * if the object wasn't properly initialized, or {@link #ERROR_BAD_VALUE} if
+ * @return zero or the positive number of bytes that were written, or
+ * {@link #ERROR_INVALID_OPERATION}
+ * if the track isn't properly initialized, or {@link #ERROR_BAD_VALUE} if
* the parameters don't resolve to valid data and indexes, or
* {@link AudioManager#ERROR_DEAD_OBJECT} if the AudioTrack is not valid anymore and
* needs to be recreated.
+ * The dead object error code is not returned if some data was successfully transferred.
+ * In this case, the error is returned at the next write().
*/
public int write(@NonNull byte[] audioData, int offsetInBytes, int sizeInBytes,
@WriteMode int writeMode) {
@@ -1650,21 +1688,30 @@ public class AudioTrack
* or copies audio data for later playback (static buffer mode).
* The format specified in the AudioTrack constructor should be
* {@link AudioFormat#ENCODING_PCM_16BIT} to correspond to the data in the array.
- * In streaming mode, will block until all data has been written to the audio sink.
+ *
+ * In streaming mode, the write will normally block until all the data has been enqueued for + * playback, and will return a full transfer count. However, if the track is stopped or paused + * on entry, or another thread interrupts the write by calling stop or pause, or an I/O error + * occurs during the write, then the write may return a short transfer count. + *
* In static buffer mode, copies the data to the buffer starting at offset 0.
- * Note that the actual playback of this data might occur after this function
- * returns. This function is thread safe with respect to {@link #stop} calls,
- * in which case all of the specified data might not be written to the audio sink.
+ * Note that the actual playback of this data might occur after this function returns.
*
* @param audioData the array that holds the data to play.
* @param offsetInShorts the offset expressed in shorts in audioData where the data to play
* starts.
* @param sizeInShorts the number of shorts to read in audioData after the offset.
- * @return the number of shorts that were written or {@link #ERROR_INVALID_OPERATION}
- * if the object wasn't properly initialized, or {@link #ERROR_BAD_VALUE} if
+ * @return zero or the positive number of shorts that were written, or
+ * {@link #ERROR_INVALID_OPERATION}
+ * if the track isn't properly initialized, or {@link #ERROR_BAD_VALUE} if
* the parameters don't resolve to valid data and indexes, or
* {@link AudioManager#ERROR_DEAD_OBJECT} if the AudioTrack is not valid anymore and
* needs to be recreated.
+ * The dead object error code is not returned if some data was successfully transferred.
+ * In this case, the error is returned at the next write().
+ *
+ * This is equivalent to {@link #write(short[], int, int, int)} with writeMode
+ * set to {@link #WRITE_BLOCKING}.
*/
public int write(@NonNull short[] audioData, int offsetInShorts, int sizeInShorts) {
return write(audioData, offsetInShorts, sizeInShorts, WRITE_BLOCKING);
@@ -1675,11 +1722,16 @@ public class AudioTrack
* or copies audio data for later playback (static buffer mode).
* The format specified in the AudioTrack constructor should be
* {@link AudioFormat#ENCODING_PCM_16BIT} to correspond to the data in the array.
- * In streaming mode, will block until all data has been written to the audio sink.
+ *
+ * In streaming mode, the blocking behavior depends on the write mode. If the write mode is + * {@link #WRITE_BLOCKING}, the write will normally block until all the data has been enqueued + * for playback, and will return a full transfer count. However, if the write mode is + * {@link #WRITE_NON_BLOCKING}, or the track is stopped or paused on entry, or another thread + * interrupts the write by calling stop or pause, or an I/O error + * occurs during the write, then the write may return a short transfer count. + *
* In static buffer mode, copies the data to the buffer starting at offset 0.
- * Note that the actual playback of this data might occur after this function
- * returns. This function is thread safe with respect to {@link #stop} calls,
- * in which case all of the specified data might not be written to the audio sink.
+ * Note that the actual playback of this data might occur after this function returns.
*
* @param audioData the array that holds the data to play.
* @param offsetInShorts the offset expressed in shorts in audioData where the data to play
@@ -1691,11 +1743,14 @@ public class AudioTrack
* to the audio sink.
*
With {@link #WRITE_NON_BLOCKING}, the write will return immediately after
* queuing as much audio data for playback as possible without blocking.
- * @return the number of shorts that were written or {@link #ERROR_INVALID_OPERATION}
- * if the object wasn't properly initialized, or {@link #ERROR_BAD_VALUE} if
+ * @return zero or the positive number of shorts that were written, or
+ * {@link #ERROR_INVALID_OPERATION}
+ * if the track isn't properly initialized, or {@link #ERROR_BAD_VALUE} if
* the parameters don't resolve to valid data and indexes, or
* {@link AudioManager#ERROR_DEAD_OBJECT} if the AudioTrack is not valid anymore and
* needs to be recreated.
+ * The dead object error code is not returned if some data was successfully transferred.
+ * In this case, the error is returned at the next write().
*/
public int write(@NonNull short[] audioData, int offsetInShorts, int sizeInShorts,
@WriteMode int writeMode) {
@@ -1733,14 +1788,18 @@ public class AudioTrack
* or copies audio data for later playback (static buffer mode).
* The format specified in the AudioTrack constructor should be
* {@link AudioFormat#ENCODING_PCM_FLOAT} to correspond to the data in the array.
+ *
+ * In streaming mode, the blocking behavior depends on the write mode. If the write mode is + * {@link #WRITE_BLOCKING}, the write will normally block until all the data has been enqueued + * for playback, and will return a full transfer count. However, if the write mode is + * {@link #WRITE_NON_BLOCKING}, or the track is stopped or paused on entry, or another thread + * interrupts the write by calling stop or pause, or an I/O error + * occurs during the write, then the write may return a short transfer count. + *
* In static buffer mode, copies the data to the buffer starting at offset 0, * and the write mode is ignored. - * In streaming mode, the blocking behavior will depend on the write mode. - *
- * Note that the actual playback of this data might occur after this function - * returns. This function is thread safe with respect to {@link #stop} calls, - * in which case all of the specified data might not be written to the audio sink. - *
+ * Note that the actual playback of this data might occur after this function returns.
+ *
* @param audioData the array that holds the data to play.
* The implementation does not clip for sample values within the nominal range
* [-1.0f, 1.0f], provided that all gains in the audio pipeline are
@@ -1760,11 +1819,14 @@ public class AudioTrack
* to the audio sink.
*
With {@link #WRITE_NON_BLOCKING}, the write will return immediately after
* queuing as much audio data for playback as possible without blocking.
- * @return the number of floats that were written, or {@link #ERROR_INVALID_OPERATION}
- * if the object wasn't properly initialized, or {@link #ERROR_BAD_VALUE} if
+ * @return zero or the positive number of floats that were written, or
+ * {@link #ERROR_INVALID_OPERATION}
+ * if the track isn't properly initialized, or {@link #ERROR_BAD_VALUE} if
* the parameters don't resolve to valid data and indexes, or
* {@link AudioManager#ERROR_DEAD_OBJECT} if the AudioTrack is not valid anymore and
* needs to be recreated.
+ * The dead object error code is not returned if some data was successfully transferred.
+ * In this case, the error is returned at the next write().
*/
public int write(@NonNull float[] audioData, int offsetInFloats, int sizeInFloats,
@WriteMode int writeMode) {
@@ -1808,9 +1870,19 @@ public class AudioTrack
/**
* Writes the audio data to the audio sink for playback (streaming mode),
* or copies audio data for later playback (static buffer mode).
- * In static buffer mode, copies the data to the buffer starting at its 0 offset, and the write
- * mode is ignored.
- * In streaming mode, the blocking behavior will depend on the write mode.
+ * The audioData in ByteBuffer should match the format specified in the AudioTrack constructor.
+ *
+ * In streaming mode, the blocking behavior depends on the write mode. If the write mode is + * {@link #WRITE_BLOCKING}, the write will normally block until all the data has been enqueued + * for playback, and will return a full transfer count. However, if the write mode is + * {@link #WRITE_NON_BLOCKING}, or the track is stopped or paused on entry, or another thread + * interrupts the write by calling stop or pause, or an I/O error + * occurs during the write, then the write may return a short transfer count. + *
+ * In static buffer mode, copies the data to the buffer starting at offset 0,
+ * and the write mode is ignored.
+ * Note that the actual playback of this data might occur after this function returns.
+ *
* @param audioData the buffer that holds the data to play, starting at the position reported
* by audioData.position().
*
Note that upon return, the buffer position (audioData.position()) will
@@ -1824,10 +1896,12 @@ public class AudioTrack
* to the audio sink.
*
With {@link #WRITE_NON_BLOCKING}, the write will return immediately after
* queuing as much audio data for playback as possible without blocking.
- * @return 0 or a positive number of bytes that were written, or
+ * @return zero or the positive number of bytes that were written, or
* {@link #ERROR_BAD_VALUE}, {@link #ERROR_INVALID_OPERATION}, or
* {@link AudioManager#ERROR_DEAD_OBJECT} if the AudioTrack is not valid anymore and
* needs to be recreated.
+ * The dead object error code is not returned if some data was successfully transferred.
+ * In this case, the error is returned at the next write().
*/
public int write(@NonNull ByteBuffer audioData, int sizeInBytes,
@WriteMode int writeMode) {
@@ -1874,8 +1948,8 @@ public class AudioTrack
}
/**
- * Writes the audio data to the audio sink for playback (streaming mode) on a HW_AV_SYNC track.
- * In streaming mode, the blocking behavior will depend on the write mode.
+ * Writes the audio data to the audio sink for playback in streaming mode on a HW_AV_SYNC track.
+ * The blocking behavior will depend on the write mode.
* @param audioData the buffer that holds the data to play, starting at the position reported
* by audioData.position().
*
Note that upon return, the buffer position (audioData.position()) will
@@ -1889,10 +1963,12 @@ public class AudioTrack
*
With {@link #WRITE_NON_BLOCKING}, the write will return immediately after
* queuing as much audio data for playback as possible without blocking.
* @param timestamp The timestamp of the first decodable audio frame in the provided audioData.
- * @return 0 or a positive number of bytes that were written, or
+ * @return zero or a positive number of bytes that were written, or
* {@link #ERROR_BAD_VALUE}, {@link #ERROR_INVALID_OPERATION}, or
* {@link AudioManager#ERROR_DEAD_OBJECT} if the AudioTrack is not valid anymore and
* needs to be recreated.
+ * The dead object error code is not returned if some data was successfully transferred.
+ * In this case, the error is returned at the next write().
*/
public int write(ByteBuffer audioData, int sizeInBytes,
@WriteMode int writeMode, long timestamp) {