com.kaltura.android.exoplayer.audio

Class AudioTrack

java.lang.Object

com.kaltura.android.exoplayer.audio.AudioTrack

public final class AudioTrack
extends java.lang.Object

Plays audio data. The implementation delegates to an AudioTrack and handles playback position smoothing, non-blocking writes and reconfiguration.

Before starting playback, specify the input audio format by calling one of the configure(java.lang.String, int, int, int) methods and initialize() the instance, optionally specifying an audio session.

Call handleBuffer(ByteBuffer, int, int, long) to write data to play back, and handleDiscontinuity() when a buffer is skipped. Call play() to start playing back written data.

Call configure(java.lang.String, int, int, int) again whenever the input format changes. If isInitialized() returns false after calling configure(java.lang.String, int, int, int), it is necessary to re-initialize() the instance before writing more data.

The underlying framework audio track is created by initialize() and released asynchronously by reset() (and configure(java.lang.String, int, int, int), unless the format is unchanged). Reinitialization blocks until releasing the old audio track completes. It is safe to re-initialize() the instance after calling reset(), without reconfiguration.

Call release() when the instance will no longer be used.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AudioTrack.InitializationException Thrown when a failure occurs instantiating 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.

Field Summary

Fields

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 API version < 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, int, int, long) if the buffer can be released.
static int	RESULT_POSITION_DISCONTINUITY Returned in the result of handleBuffer(java.nio.ByteBuffer, int, int, long) if the buffer was discontinuous.
static int	SESSION_ID_NOT_SET Represents an unset AudioTrack session identifier.

Constructor Summary

Constructors

Constructor and Description
AudioTrack() Creates an audio track with default audio capabilities (no encoded audio passthrough support).
AudioTrack(AudioCapabilities audioCapabilities, int streamType) Creates an audio track using the specified audio capabilities and stream type.

Method Summary

Modifier and Type	Method and Description
void	configure(java.lang.String mimeType, int channelCount, int sampleRate, int pcmEncoding) Configures (or reconfigures) the audio track, inferring a suitable buffer size automatically.
void	configure(java.lang.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 AudioTracks, or C.UNKNOWN_TIME_US for passthrough AudioTracks.
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(java.nio.ByteBuffer buffer, int offset, int size, long presentationTimeUs) Attempts to write size bytes from buffer at offset to the audio track.
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, int, int, long) is played out in full.
boolean	hasPendingData() Returns whether the audio track has more data pending that will be played back.
int	initialize() Initializes the audio track for writing new buffers using handleBuffer(java.nio.ByteBuffer, int, int, long).
int	initialize(int sessionId) Initializes the audio track for writing new buffers using handleBuffer(java.nio.ByteBuffer, int, int, long).
boolean	isInitialized() Returns whether the audio track has been successfully initialized via initialize() and not yet reset().
boolean	isPassthroughSupported(java.lang.String mimeType) Returns whether it is possible to play back input audio in the specified format using encoded audio 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(android.media.PlaybackParams playbackParams) Sets the playback parameters.
void	setVolume(float volume) Sets the playback volume.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RESULT_POSITION_DISCONTINUITY

public static final int RESULT_POSITION_DISCONTINUITY

Returned in the result of handleBuffer(java.nio.ByteBuffer, int, int, long) if the buffer was discontinuous.

See Also:

Constant Field Values

RESULT_BUFFER_CONSUMED

public static final int RESULT_BUFFER_CONSUMED

Returned in the result of handleBuffer(java.nio.ByteBuffer, int, int, long) if the buffer can be released.

See Also:

Constant Field Values

SESSION_ID_NOT_SET

public static final int SESSION_ID_NOT_SET

Represents an unset AudioTrack session identifier.

See Also:

Constant Field Values

CURRENT_POSITION_NOT_SET

public static final long CURRENT_POSITION_NOT_SET

Returned by getCurrentPositionUs(boolean) when the position is not set.

See Also:

Constant Field Values

enablePreV21AudioSessionWorkaround

public 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 API version < 21.

The flag must be set before creating a player.

failOnSpuriousAudioTimestamp

public static boolean failOnSpuriousAudioTimestamp

Whether to throw an 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.

Constructor Detail

AudioTrack

public AudioTrack()

Creates an audio track with default audio capabilities (no encoded audio passthrough support).

AudioTrack

public AudioTrack(AudioCapabilities audioCapabilities,
                  int streamType)

Creates an audio track using the specified audio capabilities and stream type.

Parameters:

audioCapabilities - The current audio playback capabilities.

streamType - The type of audio stream for the underlying AudioTrack.

Method Detail

isPassthroughSupported

public boolean isPassthroughSupported(java.lang.String mimeType)

Returns whether it is possible to play back input audio in the specified format using encoded audio passthrough.

isInitialized

public boolean isInitialized()

Returns whether the audio track has been successfully initialized via initialize() and not yet reset().

getCurrentPositionUs

public 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.

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.

Parameters:

sourceEnded - Specify true if no more input buffers will be provided.

Returns:

The playback position relative to the start of playback, in microseconds.

configure

public void configure(java.lang.String mimeType,
                      int channelCount,
                      int sampleRate,
                      int pcmEncoding)

Configures (or reconfigures) the audio track, inferring a suitable buffer size automatically.

Parameters:

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.

configure

public void configure(java.lang.String mimeType,
                      int channelCount,
                      int sampleRate,
                      int pcmEncoding,
                      int specifiedBufferSize)

Configures (or reconfigures) the audio track.

Parameters:

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.

initialize

public int initialize()
               throws AudioTrack.InitializationException

Initializes the audio track for writing new buffers using handleBuffer(java.nio.ByteBuffer, int, int, long).

Returns:

The audio track session identifier.

Throws:

AudioTrack.InitializationException

initialize

public int initialize(int sessionId)
               throws AudioTrack.InitializationException

Initializes the audio track for writing new buffers using handleBuffer(java.nio.ByteBuffer, int, int, long).

Parameters:

sessionId - Audio track session identifier to re-use, or SESSION_ID_NOT_SET to create a new one.

Returns:

The new (or re-used) session identifier.

Throws:

AudioTrack.InitializationException

getBufferSize

public int getBufferSize()

Returns the size of this 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) methods.

Returns:

The size of the buffer in bytes.

getBufferSizeUs

public long getBufferSizeUs()

Returns the size of the buffer in microseconds for PCM AudioTracks, or C.UNKNOWN_TIME_US for passthrough AudioTracks.

The value returned from this method may change as a result of calling one of the configure(java.lang.String, int, int, int) methods.

Returns:

The size of the buffer in microseconds for PCM AudioTracks, or C.UNKNOWN_TIME_US for passthrough AudioTracks.

play

public void play()

Starts or resumes playing audio if the audio track has been initialized.

handleDiscontinuity

public void handleDiscontinuity()

Signals to the audio track that the next buffer is discontinuous with the previous buffer.

handleBuffer

public int handleBuffer(java.nio.ByteBuffer buffer,
                        int offset,
                        int size,
                        long presentationTimeUs)
                 throws AudioTrack.WriteException

Attempts to write size bytes from buffer at offset to the audio track. Returns a bit field containing RESULT_BUFFER_CONSUMED if the buffer can be released (due to having been written), and RESULT_POSITION_DISCONTINUITY if the buffer was discontinuous with previously written data.

Parameters:

buffer - The buffer containing audio data to play back.

offset - The offset in the buffer from which to consume data.

size - The number of bytes to consume from buffer.

presentationTimeUs - Presentation timestamp of the next buffer in microseconds.

Returns:

A bit field with RESULT_BUFFER_CONSUMED if the buffer can be released, and RESULT_POSITION_DISCONTINUITY if the buffer was not contiguous with previously written data.

Throws:

AudioTrack.WriteException - If an error occurs writing the audio data.

handleEndOfStream

public void handleEndOfStream()

Ensures that the last data passed to handleBuffer(ByteBuffer, int, int, long) is played out in full.

hasPendingData

public boolean hasPendingData()

Returns whether the audio track has more data pending that will be played back.

setPlaybackParams

public void setPlaybackParams(android.media.PlaybackParams playbackParams)

Sets the playback parameters. Only available for SDK_INT >= 23

Throws:

java.lang.UnsupportedOperationException - if the Playback Parameters are not supported. That is, SDK_INT < 23.

setVolume

public void setVolume(float volume)

Sets the playback volume.

pause

public void pause()

Pauses playback.

reset

public void reset()

Releases the underlying audio track asynchronously. Calling initialize() will block until the audio track has been released, so it is safe to initialize immediately after resetting. The audio session may remain active until the instance is release()d.

release

public void release()

Releases all resources associated with this instance.