com.google.android.exoplayer2.audio

Class SimpleDecoderAudioRenderer

java.lang.Object

com.google.android.exoplayer2.BaseRenderer

com.google.android.exoplayer2.audio.SimpleDecoderAudioRenderer

All Implemented Interfaces:

PlayerMessage.Target, Renderer, RendererCapabilities, MediaClock

public abstract class SimpleDecoderAudioRenderer
extends BaseRenderer
implements MediaClock

Decodes and renders audio using a SimpleDecoder.

This renderer accepts the following messages sent via ExoPlayer#createMessage(Target) on the playback thread:

• Message with type C.MSG_SET_VOLUME to set the volume. The message payload should be a Float with 0 being silence and 1 being unity gain.
• Message with type C.MSG_SET_AUDIO_ATTRIBUTES to set the audio attributes. The message payload should be an AudioAttributes instance that will configure the underlying audio track.
• Message with type C.MSG_SET_AUX_EFFECT_INFO to set the auxiliary effect. The message payload should be an AuxEffectInfo instance that will configure the underlying audio track.

Nested Class Summary

Nested classes/interfaces inherited from interface com.google.android.exoplayer2.Renderer

Renderer.State

Field Summary

Fields inherited from interface com.google.android.exoplayer2.Renderer

STATE_DISABLED, STATE_ENABLED, STATE_STARTED

Fields inherited from interface com.google.android.exoplayer2.RendererCapabilities

ADAPTIVE_NOT_SEAMLESS, ADAPTIVE_NOT_SUPPORTED, ADAPTIVE_SEAMLESS, ADAPTIVE_SUPPORT_MASK, FORMAT_EXCEEDS_CAPABILITIES, FORMAT_HANDLED, FORMAT_SUPPORT_MASK, FORMAT_UNSUPPORTED_DRM, FORMAT_UNSUPPORTED_SUBTYPE, FORMAT_UNSUPPORTED_TYPE, TUNNELING_NOT_SUPPORTED, TUNNELING_SUPPORT_MASK, TUNNELING_SUPPORTED

Constructor Summary

Constructors

Constructor and Description
SimpleDecoderAudioRenderer()
SimpleDecoderAudioRenderer(android.os.Handler eventHandler, AudioRendererEventListener eventListener, AudioCapabilities audioCapabilities)
SimpleDecoderAudioRenderer(android.os.Handler eventHandler, AudioRendererEventListener eventListener, AudioCapabilities audioCapabilities, DrmSessionManager<ExoMediaCrypto> drmSessionManager, boolean playClearSamplesWithoutKeys, AudioProcessor... audioProcessors)
SimpleDecoderAudioRenderer(android.os.Handler eventHandler, AudioRendererEventListener eventListener, AudioProcessor... audioProcessors)
SimpleDecoderAudioRenderer(android.os.Handler eventHandler, AudioRendererEventListener eventListener, DrmSessionManager<ExoMediaCrypto> drmSessionManager, boolean playClearSamplesWithoutKeys, AudioSink audioSink)

Method Summary

Modifier and Type	Method and Description
protected abstract SimpleDecoder<DecoderInputBuffer,? extends SimpleOutputBuffer,? extends AudioDecoderException>	createDecoder(Format format, ExoMediaCrypto mediaCrypto) Creates a decoder for the given format.
MediaClock	getMediaClock() If the renderer advances its own playback position then this method returns a corresponding MediaClock.
protected Format	getOutputFormat() Returns the format of audio buffers output by the decoder.
PlaybackParameters	getPlaybackParameters() Returns the active playback parameters.
long	getPositionUs() Returns the current media position in microseconds.
void	handleMessage(int messageType, java.lang.Object message) Handles a message delivered to the target.
boolean	isEnded() Whether the renderer is ready for the ExoPlayer instance to transition to Player.STATE_ENDED.
boolean	isReady() Whether the renderer is able to immediately render media from the current position.
protected void	onAudioSessionId(int audioSessionId) Called when the audio session id becomes known.
protected void	onAudioTrackPositionDiscontinuity()
protected void	onAudioTrackUnderrun(int bufferSize, long bufferSizeMs, long elapsedSinceLastFeedMs)
protected void	onDisabled() Called when the renderer is disabled.
protected void	onEnabled(boolean joining) Called when the renderer is enabled.
protected void	onPositionReset(long positionUs, boolean joining) Called when the position is reset.
protected void	onStarted() Called when the renderer is started.
protected void	onStopped() Called when the renderer is stopped.
void	render(long positionUs, long elapsedRealtimeUs) Incrementally renders the SampleStream.
PlaybackParameters	setPlaybackParameters(PlaybackParameters playbackParameters) Attempts to set the playback parameters and returns the active playback parameters, which may differ from those passed in.
int	supportsFormat(Format format) Returns the extent to which the Renderer supports a given format.
protected abstract int	supportsFormatInternal(DrmSessionManager<ExoMediaCrypto> drmSessionManager, Format format) Returns the RendererCapabilities.FORMAT_SUPPORT_MASK component of the return value for supportsFormat(Format).
protected boolean	supportsOutput(int channelCount, int encoding) Returns whether the sink supports the audio format.

Methods inherited from class com.google.android.exoplayer2.BaseRenderer

disable, enable, getCapabilities, getConfiguration, getIndex, getState, getStream, getStreamFormats, getTrackType, hasReadStreamToEnd, isCurrentStreamFinal, isSourceReady, maybeThrowStreamError, onStreamChanged, readSource, replaceStream, resetPosition, setCurrentStreamFinal, setIndex, skipSource, start, stop, supportsFormatDrm, supportsMixedMimeTypeAdaptation

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.google.android.exoplayer2.Renderer

setOperatingRate

Constructor Detail

SimpleDecoderAudioRenderer

public SimpleDecoderAudioRenderer()

SimpleDecoderAudioRenderer

public SimpleDecoderAudioRenderer(@Nullable
                                  android.os.Handler eventHandler,
                                  @Nullable
                                  AudioRendererEventListener eventListener,
                                  AudioProcessor... audioProcessors)

Parameters:

eventHandler - A handler to use when delivering events to eventListener. May be null if delivery of events is not required.

eventListener - A listener of events. May be null if delivery of events is not required.

audioProcessors - Optional AudioProcessors that will process audio before output.

SimpleDecoderAudioRenderer

public SimpleDecoderAudioRenderer(@Nullable
                                  android.os.Handler eventHandler,
                                  @Nullable
                                  AudioRendererEventListener eventListener,
                                  @Nullable
                                  AudioCapabilities audioCapabilities)

Parameters:

eventHandler - A handler to use when delivering events to eventListener. May be null if delivery of events is not required.

eventListener - A listener of events. May be null if delivery of events is not required.

audioCapabilities - The audio capabilities for playback on this device. May be null if the default capabilities (no encoded audio passthrough support) should be assumed.

SimpleDecoderAudioRenderer

public SimpleDecoderAudioRenderer(@Nullable
                                  android.os.Handler eventHandler,
                                  @Nullable
                                  AudioRendererEventListener eventListener,
                                  @Nullable
                                  AudioCapabilities audioCapabilities,
                                  @Nullable
                                  DrmSessionManager<ExoMediaCrypto> drmSessionManager,
                                  boolean playClearSamplesWithoutKeys,
                                  AudioProcessor... audioProcessors)

Parameters:

eventHandler - A handler to use when delivering events to eventListener. May be null if delivery of events is not required.

eventListener - A listener of events. May be null if delivery of events is not required.

audioCapabilities - The audio capabilities for playback on this device. May be null if the default capabilities (no encoded audio passthrough support) should be assumed.

drmSessionManager - For use with encrypted media. May be null if support for encrypted media is not required.

playClearSamplesWithoutKeys - Encrypted media may contain clear (un-encrypted) regions. For example a media file may start with a short clear region so as to allow playback to begin in parallel with key acquisition. This parameter specifies whether the renderer is permitted to play clear regions of encrypted media files before drmSessionManager has obtained the keys necessary to decrypt encrypted regions of the media.

audioProcessors - Optional AudioProcessors that will process audio before output.

SimpleDecoderAudioRenderer

public SimpleDecoderAudioRenderer(@Nullable
                                  android.os.Handler eventHandler,
                                  @Nullable
                                  AudioRendererEventListener eventListener,
                                  @Nullable
                                  DrmSessionManager<ExoMediaCrypto> drmSessionManager,
                                  boolean playClearSamplesWithoutKeys,
                                  AudioSink audioSink)

Parameters:

eventHandler - A handler to use when delivering events to eventListener. May be null if delivery of events is not required.

eventListener - A listener of events. May be null if delivery of events is not required.

drmSessionManager - For use with encrypted media. May be null if support for encrypted media is not required.

playClearSamplesWithoutKeys - Encrypted media may contain clear (un-encrypted) regions. For example a media file may start with a short clear region so as to allow playback to begin in parallel with key acquisition. This parameter specifies whether the renderer is permitted to play clear regions of encrypted media files before drmSessionManager has obtained the keys necessary to decrypt encrypted regions of the media.

audioSink - The sink to which audio will be output.

Method Detail

getMediaClock

public MediaClock getMediaClock()

Description copied from interface: Renderer

If the renderer advances its own playback position then this method returns a corresponding MediaClock. If provided, the player will use the returned MediaClock as its source of time during playback. A player may have at most one renderer that returns a MediaClock from this method.

Specified by:

getMediaClock in interface Renderer

Overrides:

getMediaClock in class BaseRenderer

Returns:

The MediaClock tracking the playback position of the renderer, or null.

supportsFormat

public final int supportsFormat(Format format)

Description copied from interface: RendererCapabilities

Returns the extent to which the Renderer supports a given format. The returned value is the bitwise OR of three properties:

• The level of support for the format itself. One of RendererCapabilities.FORMAT_HANDLED, RendererCapabilities.FORMAT_EXCEEDS_CAPABILITIES, RendererCapabilities.FORMAT_UNSUPPORTED_DRM, RendererCapabilities.FORMAT_UNSUPPORTED_SUBTYPE and RendererCapabilities.FORMAT_UNSUPPORTED_TYPE.
• The level of support for adapting from the format to another format of the same mime type. One of RendererCapabilities.ADAPTIVE_SEAMLESS, RendererCapabilities.ADAPTIVE_NOT_SEAMLESS and RendererCapabilities.ADAPTIVE_NOT_SUPPORTED. Only set if the level of support for the format itself is RendererCapabilities.FORMAT_HANDLED or RendererCapabilities.FORMAT_EXCEEDS_CAPABILITIES.
• The level of support for tunneling. One of RendererCapabilities.TUNNELING_SUPPORTED and RendererCapabilities.TUNNELING_NOT_SUPPORTED. Only set if the level of support for the format itself is RendererCapabilities.FORMAT_HANDLED or RendererCapabilities.FORMAT_EXCEEDS_CAPABILITIES.

The individual properties can be retrieved by performing a bitwise AND with RendererCapabilities.FORMAT_SUPPORT_MASK, RendererCapabilities.ADAPTIVE_SUPPORT_MASK and RendererCapabilities.TUNNELING_SUPPORT_MASK respectively.

Specified by:

supportsFormat in interface RendererCapabilities

Parameters:

format - The format.

Returns:

The extent to which the renderer is capable of supporting the given format.

supportsFormatInternal

protected abstract int supportsFormatInternal(DrmSessionManager<ExoMediaCrypto> drmSessionManager,
                                              Format format)

Returns the RendererCapabilities.FORMAT_SUPPORT_MASK component of the return value for supportsFormat(Format).

Parameters:

drmSessionManager - The renderer's DrmSessionManager.

format - The format, which has an audio Format.sampleMimeType.

Returns:

The extent to which the renderer supports the format itself.

supportsOutput

protected final boolean supportsOutput(int channelCount,
                                       @C.Encoding
                                       int encoding)

Returns whether the sink supports the audio format.

See Also:

AudioSink.supportsOutput(int, int)

render

public void render(long positionUs,
                   long elapsedRealtimeUs)
            throws ExoPlaybackException

Description copied from interface: Renderer

Incrementally renders the SampleStream.

If the renderer is in the Renderer.STATE_ENABLED state then each call to this method will do work toward being ready to render the SampleStream when the renderer is started. It may also render the very start of the media, for example the first frame of a video stream. If the renderer is in the Renderer.STATE_STARTED state then calls to this method will render the SampleStream in sync with the specified media positions.

This method should return quickly, and should not block if the renderer is unable to make useful progress.

This method may be called when the renderer is in the following states: Renderer.STATE_ENABLED, Renderer.STATE_STARTED.

Specified by:

render in interface Renderer

Parameters:

positionUs - The current media time in microseconds, measured at the start of the current iteration of the rendering loop.

elapsedRealtimeUs - SystemClock.elapsedRealtime() in microseconds, measured at the start of the current iteration of the rendering loop.

Throws:

ExoPlaybackException - If an error occurs.

onAudioSessionId

protected void onAudioSessionId(int audioSessionId)

Called when the audio session id becomes known. The default implementation is a no-op. One reason for overriding this method would be to instantiate and enable a Virtualizer in order to spatialize the audio channels. For this use case, any Virtualizer instances should be released in onDisabled() (if not before).

See Also:

AudioSink.Listener.onAudioSessionId(int)

onAudioTrackPositionDiscontinuity

protected void onAudioTrackPositionDiscontinuity()

See Also:

AudioSink.Listener.onPositionDiscontinuity()

onAudioTrackUnderrun

protected void onAudioTrackUnderrun(int bufferSize,
                                    long bufferSizeMs,
                                    long elapsedSinceLastFeedMs)

See Also:

AudioSink.Listener.onUnderrun(int, long, long)

createDecoder

protected abstract SimpleDecoder<DecoderInputBuffer,? extends SimpleOutputBuffer,? extends AudioDecoderException> createDecoder(Format format,
                                                                                                                                ExoMediaCrypto mediaCrypto)
                                                                                                                         throws AudioDecoderException

Creates a decoder for the given format.

Parameters:

format - The format for which a decoder is required.

mediaCrypto - The ExoMediaCrypto object required for decoding encrypted content. Maybe null and can be ignored if decoder does not handle encrypted content.

Returns:

The decoder.

Throws:

AudioDecoderException - If an error occurred creating a suitable decoder.

getOutputFormat

protected Format getOutputFormat()

Returns the format of audio buffers output by the decoder. Will not be called until the first output buffer has been dequeued, so the decoder may use input data to determine the format.

The default implementation returns a 16-bit PCM format with the same channel count and sample rate as the input.

isEnded

public boolean isEnded()

Description copied from interface: Renderer

Whether the renderer is ready for the ExoPlayer instance to transition to Player.STATE_ENDED. The player will make this transition as soon as true is returned by all of its Renderers.

This method may be called when the renderer is in the following states: Renderer.STATE_ENABLED, Renderer.STATE_STARTED.

Specified by:

isEnded in interface Renderer

Returns:

Whether the renderer is ready for the player to transition to the ended state.

isReady

public boolean isReady()

Description copied from interface: Renderer

Whether the renderer is able to immediately render media from the current position.

If the renderer is in the Renderer.STATE_STARTED state then returning true indicates that the renderer has everything that it needs to continue playback. Returning false indicates that the player should pause until the renderer is ready.

If the renderer is in the Renderer.STATE_ENABLED state then returning true indicates that the renderer is ready for playback to be started. Returning false indicates that it is not.

This method may be called when the renderer is in the following states: Renderer.STATE_ENABLED, Renderer.STATE_STARTED.

Specified by:

isReady in interface Renderer

Returns:

Whether the renderer is ready to render media.

getPositionUs

public long getPositionUs()

Description copied from interface: MediaClock

Returns the current media position in microseconds.

Specified by:

getPositionUs in interface MediaClock

setPlaybackParameters

public PlaybackParameters setPlaybackParameters(PlaybackParameters playbackParameters)

Description copied from interface: MediaClock

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

Specified by:

setPlaybackParameters in interface MediaClock

Parameters:

playbackParameters - The playback parameters.

Returns:

The active playback parameters.

getPlaybackParameters

public PlaybackParameters getPlaybackParameters()

Description copied from interface: MediaClock

Returns the active playback parameters.

Specified by:

getPlaybackParameters in interface MediaClock

onEnabled

protected void onEnabled(boolean joining)
                  throws ExoPlaybackException

Description copied from class: BaseRenderer

Called when the renderer is enabled.

The default implementation is a no-op.

Overrides:

onEnabled in class BaseRenderer

Parameters:

joining - Whether this renderer is being enabled to join an ongoing playback.

Throws:

ExoPlaybackException - If an error occurs.

onPositionReset

protected void onPositionReset(long positionUs,
                               boolean joining)
                        throws ExoPlaybackException

Description copied from class: BaseRenderer

Called when the position is reset. This occurs when the renderer is enabled after BaseRenderer.onStreamChanged(Format[], long) has been called, and also when a position discontinuity is encountered.

After a position reset, the renderer's SampleStream is guaranteed to provide samples starting from a key frame.

The default implementation is a no-op.

Overrides:

onPositionReset in class BaseRenderer

Parameters:

positionUs - The new playback position in microseconds.

joining - Whether this renderer is being enabled to join an ongoing playback.

Throws:

ExoPlaybackException - If an error occurs.

onStarted

protected void onStarted()

Description copied from class: BaseRenderer

Called when the renderer is started.

The default implementation is a no-op.

Overrides:

onStarted in class BaseRenderer

onStopped

protected void onStopped()

Description copied from class: BaseRenderer

Called when the renderer is stopped.

The default implementation is a no-op.

Overrides:

onStopped in class BaseRenderer

onDisabled

protected void onDisabled()

Description copied from class: BaseRenderer

Called when the renderer is disabled.

The default implementation is a no-op.

Overrides:

onDisabled in class BaseRenderer

handleMessage

public void handleMessage(int messageType,
                          @Nullable
                          java.lang.Object message)
                   throws ExoPlaybackException

Description copied from interface: PlayerMessage.Target

Handles a message delivered to the target.

Specified by:

handleMessage in interface PlayerMessage.Target

Overrides:

handleMessage in class BaseRenderer

Parameters:

messageType - The message type.

message - The message payload.

Throws:

ExoPlaybackException - If an error occurred whilst handling the message. Should only be thrown by targets that handle messages on the playback thread.