com.google.android.exoplayer2.audio

Interface AudioSink

All Known Implementing Classes:

DefaultAudioSink

public interface AudioSink

A sink that consumes audio data.

Before starting playback, specify the input audio format by calling configure(int, int, int, int, int[], int, int).

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(int, int, int, int, int[], int, int) whenever the input format changes. The sink will be reinitialized on the next call to handleBuffer(ByteBuffer, long).

Call reset() to prepare the sink to receive audio data from a new playback position.

Call playToEndOfStream() repeatedly to play out all data when no more input buffers will be provided via handleBuffer(ByteBuffer, long) until the next reset(). Call release() when the instance is no longer required.

The implementation may be backed by a platform AudioTrack. In this case, setAudioSessionId(int), setAudioAttributes(AudioAttributes), enableTunnelingV21(int) and/or disableTunneling() may be called before writing data to the sink. These methods may also be called after writing data to the sink, in which case it will be reinitialized as required. For implementations that are not based on platform AudioTracks, calling methods relating to audio sessions, audio attributes, and tunneling may have no effect.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	AudioSink.ConfigurationException Thrown when a failure occurs configuring the sink.
static class	AudioSink.InitializationException Thrown when a failure occurs initializing the sink.
static interface	AudioSink.Listener Listener for audio sink events.
static class	AudioSink.WriteException Thrown when a failure occurs writing to the sink.

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.

Method Summary

Modifier and Type	Method and Description
void	configure(int inputEncoding, int inputChannelCount, int inputSampleRate, int specifiedBufferSize, int[] outputChannels, int trimStartFrames, int trimEndFrames) Configures (or reconfigures) the sink.
void	disableTunneling() Disables tunneling.
void	enableTunnelingV21(int tunnelingAudioSessionId) Enables tunneling, if possible.
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.
PlaybackParameters	getPlaybackParameters() Gets the active PlaybackParameters.
boolean	handleBuffer(java.nio.ByteBuffer buffer, long presentationTimeUs) Attempts to process data from a ByteBuffer, starting from its current position and ending at its limit (exclusive).
void	handleDiscontinuity() Signals to the sink that the next buffer may be discontinuous with the previous buffer.
boolean	hasPendingData() Returns whether the sink has data pending that has not been consumed yet.
boolean	isEncodingSupported(int encoding) Returns whether it's possible to play audio in the specified encoding.
boolean	isEnded() Returns whether playToEndOfStream() has been called and all buffers have been processed.
void	pause() Pauses playback.
void	play() Starts or resumes consuming audio if initialized.
void	playToEndOfStream() Processes any remaining data.
void	release() Releases any resources associated with this instance.
void	reset() Resets the sink, after which it is ready to receive buffers from a new playback position.
void	setAudioAttributes(AudioAttributes audioAttributes) Sets attributes for audio playback.
void	setAudioSessionId(int audioSessionId) Sets the audio session id.
void	setAuxEffectInfo(AuxEffectInfo auxEffectInfo) Sets the auxiliary effect.
void	setListener(AudioSink.Listener listener) Sets the listener for sink events, which should be the audio renderer.
PlaybackParameters	setPlaybackParameters(PlaybackParameters playbackParameters) Attempts to set the playback parameters and returns the active playback parameters, which may differ from those passed in.
void	setVolume(float volume) Sets the playback volume.

Field Detail

CURRENT_POSITION_NOT_SET

static final long CURRENT_POSITION_NOT_SET

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

See Also:

Constant Field Values

Method Detail

setListener

void setListener(AudioSink.Listener listener)

Sets the listener for sink events, which should be the audio renderer.

Parameters:

listener - The listener for sink events, which should be the audio renderer.

isEncodingSupported

boolean isEncodingSupported(@C.Encoding
                            int encoding)

Returns whether it's possible to play audio in the specified encoding.

Parameters:

encoding - The audio encoding.

Returns:

Whether it's possible to play audio in the specified encoding.

getCurrentPositionUs

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.

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

void configure(@C.Encoding
               int inputEncoding,
               int inputChannelCount,
               int inputSampleRate,
               int specifiedBufferSize,
               @Nullable
               int[] outputChannels,
               int trimStartFrames,
               int trimEndFrames)
        throws AudioSink.ConfigurationException

Configures (or reconfigures) the sink.

Parameters:

inputEncoding - The encoding of audio data provided in the input buffers.

inputChannelCount - The number of channels.

inputSampleRate - The sample rate in Hz.

specifiedBufferSize - A specific size for the playback buffer in bytes, or 0 to infer a suitable buffer size.

outputChannels - A mapping from input to output channels that is applied to this sink's input as a preprocessing step, if handling PCM input. Specify null to leave the input unchanged. Otherwise, the element at index i specifies index of the input channel to map to output channel i when preprocessing input buffers. After the map is applied the audio data will have outputChannels.length channels.

trimStartFrames - The number of audio frames to trim from the start of data written to the sink after this call.

trimEndFrames - The number of audio frames to trim from data written to the sink immediately preceding the next call to reset() or this method.

Throws:

AudioSink.ConfigurationException - If an error occurs configuring the sink.

play

void play()

Starts or resumes consuming audio if initialized.

handleDiscontinuity

void handleDiscontinuity()

Signals to the sink that the next buffer may be discontinuous with the previous buffer.

handleBuffer

boolean handleBuffer(java.nio.ByteBuffer buffer,
                     long presentationTimeUs)
              throws AudioSink.InitializationException,
                     AudioSink.WriteException

Attempts to process data from a ByteBuffer, 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 handled. AudioSink.Listener.onPositionDiscontinuity() will be called if presentationTimeUs is discontinuous with the last buffer handled since the last reset.

Returns whether the data was handled in full. If the data was not handled in full then the same ByteBuffer must be provided to subsequent calls until it has been fully consumed, except in the case of an intervening call to reset() (or to configure(int, int, int, int, int[], int, int) that causes the sink to be reset).

Parameters:

buffer - The buffer containing audio data.

presentationTimeUs - The presentation timestamp of the buffer in microseconds.

Returns:

Whether the buffer was handled fully.

Throws:

AudioSink.InitializationException - If an error occurs initializing the sink.

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

playToEndOfStream

void playToEndOfStream()
                throws AudioSink.WriteException

Processes any remaining data. isEnded() will return true when no data remains.

Throws:

AudioSink.WriteException - If an error occurs draining data to the sink.

isEnded

boolean isEnded()

Returns whether playToEndOfStream() has been called and all buffers have been processed.

hasPendingData

boolean hasPendingData()

Returns whether the sink has data pending that has not been consumed yet.

setPlaybackParameters

PlaybackParameters setPlaybackParameters(PlaybackParameters playbackParameters)

Attempts to set the playback parameters and returns the active playback parameters, which may differ from those passed in.

Parameters:

playbackParameters - The new playback parameters to attempt to set.

Returns:

The active playback parameters.

getPlaybackParameters

PlaybackParameters getPlaybackParameters()

Gets the active PlaybackParameters.

setAudioAttributes

void setAudioAttributes(AudioAttributes audioAttributes)

Sets attributes for audio playback. If the attributes have changed and if the sink is not configured for use with tunneling, then it is reset and the audio session id is cleared.

If the sink is configured for use with tunneling then the audio attributes are ignored. The sink is not reset and the audio session id is not cleared. The passed attributes will be used if the sink is later re-configured into non-tunneled mode.

Parameters:

audioAttributes - The attributes for audio playback.

setAudioSessionId

void setAudioSessionId(int audioSessionId)

Sets the audio session id.

setAuxEffectInfo

void setAuxEffectInfo(AuxEffectInfo auxEffectInfo)

Sets the auxiliary effect.

enableTunnelingV21

void enableTunnelingV21(int tunnelingAudioSessionId)

Enables tunneling, if possible. The sink is reset if tunneling was previously disabled or if the audio session id has changed. Enabling tunneling is only possible if the sink is based on a platform AudioTrack, and requires platform API version 21 onwards.

Parameters:

tunnelingAudioSessionId - The audio session id to use.

Throws:

java.lang.IllegalStateException - Thrown if enabling tunneling on platform API version < 21.

disableTunneling

void disableTunneling()

Disables tunneling. If tunneling was previously enabled then the sink is reset and any audio session id is cleared.

setVolume

void setVolume(float volume)

Sets the playback volume.

Parameters:

volume - A volume in the range [0.0, 1.0].

pause

void pause()

Pauses playback.

reset

void reset()

Resets the sink, after which it is ready to receive buffers from a new playback position.

The audio session may remain active until release() is called.

release

void release()

Releases any resources associated with this instance.