public final class AudioTrack extends Object
AudioTrack
and handles
playback position smoothing, non-blocking writes and reconfiguration.
Before starting playback, specify the input format by calling
configure(String, int, int, int, int)
. Next call initialize(int)
, optionally
specifying an audio session.
Call handleBuffer(ByteBuffer, long)
to write data, and handleDiscontinuity()
when the data being fed is discontinuous. Call play()
to start playing the written data.
Call configure(String, int, int, int, int)
whenever the input format changes. If
isInitialized()
returns false
after the call, it is necessary to call
initialize(int)
before writing more data.
The underlying AudioTrack
is created by initialize(int)
and
released by reset()
(and configure(String, int, int, int, int)
unless the input
format is unchanged). It is safe to call initialize(int)
after calling reset()
without reconfiguration.
Call release()
when the instance is no longer required.
Modifier and Type | Class and Description |
---|---|
static class |
AudioTrack.InitializationException
Thrown when a failure occurs initializing an
AudioTrack . |
static class |
AudioTrack.InvalidAudioTrackTimestampException
Thrown when
AudioTrack.getTimestamp(android.media.AudioTimestamp) returns a spurious timestamp, if
AudioTrack#failOnSpuriousAudioTimestamp is set. |
static class |
AudioTrack.WriteException
Thrown when a failure occurs writing to an
AudioTrack . |
Modifier and Type | Field and Description |
---|---|
static long |
CURRENT_POSITION_NOT_SET
Returned by
getCurrentPositionUs(boolean) when the position is not set. |
static boolean |
enablePreV21AudioSessionWorkaround
Whether to enable a workaround for an issue where an audio effect does not keep its session
active across releasing/initializing a new audio track, on platform builds where
Util.SDK_INT < 21. |
static boolean |
failOnSpuriousAudioTimestamp
Whether to throw an
AudioTrack.InvalidAudioTrackTimestampException when a spurious timestamp is
reported from AudioTrack.getTimestamp(android.media.AudioTimestamp) . |
static int |
RESULT_BUFFER_CONSUMED
Returned in the result of
handleBuffer(java.nio.ByteBuffer, long) if the buffer can be released. |
static int |
RESULT_POSITION_DISCONTINUITY
Returned in the result of
handleBuffer(java.nio.ByteBuffer, long) if the buffer was discontinuous. |
static int |
SESSION_ID_NOT_SET
Represents an unset
AudioTrack session identifier. |
Constructor and Description |
---|
AudioTrack(AudioCapabilities audioCapabilities,
int streamType) |
Modifier and Type | Method and Description |
---|---|
void |
configure(String mimeType,
int channelCount,
int sampleRate,
int pcmEncoding,
int specifiedBufferSize)
Configures (or reconfigures) the audio track.
|
int |
getBufferSize()
Returns the size of this
AudioTrack 's buffer in bytes. |
long |
getBufferSizeUs()
Returns the size of the buffer in microseconds for PCM
AudioTrack s, or
C.TIME_UNSET for passthrough AudioTrack s. |
long |
getCurrentPositionUs(boolean sourceEnded)
Returns the playback position in the stream starting at zero, in microseconds, or
CURRENT_POSITION_NOT_SET if it is not yet available. |
int |
handleBuffer(ByteBuffer buffer,
long presentationTimeUs)
Attempts to write data from a
ByteBuffer to the audio track, starting from its current
position and ending at its limit (exclusive). |
void |
handleDiscontinuity()
Signals to the audio track that the next buffer is discontinuous with the previous buffer.
|
void |
handleEndOfStream()
Ensures that the last data passed to
handleBuffer(ByteBuffer, long) is played in full. |
boolean |
hasPendingData()
Returns whether the audio track has more data pending that will be played back.
|
int |
initialize(int sessionId)
Initializes the audio track for writing new buffers using
handleBuffer(java.nio.ByteBuffer, long) . |
boolean |
isInitialized()
Returns whether the audio track has been successfully initialized via
initialize(int) and
not yet reset() . |
boolean |
isPassthroughSupported(String mimeType)
Returns whether it's possible to play audio in the specified format using encoded passthrough.
|
void |
pause()
Pauses playback.
|
void |
play()
Starts or resumes playing audio if the audio track has been initialized.
|
void |
release()
Releases all resources associated with this instance.
|
void |
reset()
Releases the underlying audio track asynchronously.
|
void |
setPlaybackParams(PlaybackParams playbackParams)
Sets the playback parameters.
|
void |
setVolume(float volume)
Sets the playback volume.
|
public static final int RESULT_POSITION_DISCONTINUITY
handleBuffer(java.nio.ByteBuffer, long)
if the buffer was discontinuous.public static final int RESULT_BUFFER_CONSUMED
handleBuffer(java.nio.ByteBuffer, long)
if the buffer can be released.public static final int SESSION_ID_NOT_SET
AudioTrack
session identifier.public static final long CURRENT_POSITION_NOT_SET
getCurrentPositionUs(boolean)
when the position is not set.public static boolean enablePreV21AudioSessionWorkaround
Util.SDK_INT
< 21.
The flag must be set before creating a player.
public static boolean failOnSpuriousAudioTimestamp
AudioTrack.InvalidAudioTrackTimestampException
when a spurious timestamp is
reported from AudioTrack.getTimestamp(android.media.AudioTimestamp)
.
The flag must be set before creating a player. Should be set to true
for testing and
debugging purposes only.
public AudioTrack(AudioCapabilities audioCapabilities, int streamType)
audioCapabilities
- The current audio capabilities.streamType
- The type of audio stream for the underlying AudioTrack
.public boolean isPassthroughSupported(String mimeType)
mimeType
- The format mime type.public boolean isInitialized()
initialize(int)
and
not yet reset()
.public long getCurrentPositionUs(boolean sourceEnded)
CURRENT_POSITION_NOT_SET
if it is not yet available.
If the device supports it, the method uses the playback timestamp from
AudioTrack.getTimestamp(android.media.AudioTimestamp)
. Otherwise, it derives a smoothed position by
sampling the AudioTrack
's frame position.
sourceEnded
- Specify true
if no more input buffers will be provided.public void configure(String mimeType, int channelCount, int sampleRate, int pcmEncoding, int specifiedBufferSize)
mimeType
- The mime type.channelCount
- The number of channels.sampleRate
- The sample rate in Hz.pcmEncoding
- For PCM formats, the encoding used. One of C.ENCODING_PCM_16BIT
,
C.ENCODING_PCM_16BIT
, C.ENCODING_PCM_24BIT
and
C.ENCODING_PCM_32BIT
.specifiedBufferSize
- A specific size for the playback buffer in bytes, or 0 to infer a
suitable buffer size automatically.public int initialize(int sessionId) throws AudioTrack.InitializationException
handleBuffer(java.nio.ByteBuffer, long)
.sessionId
- Audio track session identifier to re-use, or SESSION_ID_NOT_SET
to
create a new one.AudioTrack.InitializationException
public int getBufferSize()
AudioTrack
's buffer in bytes.
The value returned from this method may change as a result of calling one of the
configure(java.lang.String, int, int, int, int)
methods.
public long getBufferSizeUs()
AudioTrack
s, or
C.TIME_UNSET
for passthrough AudioTrack
s.
The value returned from this method may change as a result of calling one of the
configure(java.lang.String, int, int, int, int)
methods.
AudioTrack
s, or
C.TIME_UNSET
for passthrough AudioTrack
s.public void play()
public void handleDiscontinuity()
public int handleBuffer(ByteBuffer buffer, long presentationTimeUs) throws AudioTrack.WriteException
ByteBuffer
to the audio track, starting from its current
position and ending at its limit (exclusive). The position of the ByteBuffer
is
advanced by the number of bytes that were successfully written.
Returns a bit field containing RESULT_BUFFER_CONSUMED
if the data was written in full,
and RESULT_POSITION_DISCONTINUITY
if the buffer was discontinuous with previously
written data.
If the data was not written in full then the same ByteBuffer
must be provided to
subsequent calls until it has been fully consumed, except in the case of an interleaving call
to configure(java.lang.String, int, int, int, int)
or reset()
.
buffer
- The buffer containing audio data to play back.presentationTimeUs
- Presentation timestamp of the next buffer in microseconds.RESULT_BUFFER_CONSUMED
if the buffer can be released, and
RESULT_POSITION_DISCONTINUITY
if the buffer was not contiguous with previously
written data.AudioTrack.WriteException
- If an error occurs writing the audio data.public void handleEndOfStream()
handleBuffer(ByteBuffer, long)
is played in full.public boolean hasPendingData()
public void setPlaybackParams(PlaybackParams playbackParams)
Util.SDK_INT
>= 23playbackParams
- The playback parameters to be used by the
AudioTrack
.UnsupportedOperationException
- if the Playback Parameters are not supported. That is,
Util.SDK_INT
< 23.public void setVolume(float volume)
volume
- A volume in the range [0.0, 1.0].public void pause()
public void reset()
Calling initialize(int)
will block until the audio track has been released, so it is
safe to initialize immediately after a reset. The audio session may remain active until
release()
is called.
public void release()