com.google.android.exoplayer

Class TrackRenderer

java.lang.Object

com.google.android.exoplayer.TrackRenderer

All Implemented Interfaces:

ExoPlayer.ExoPlayerComponent

Direct Known Subclasses:

DummyTrackRenderer, SampleSourceTrackRenderer

public abstract class TrackRenderer
extends Object
implements ExoPlayer.ExoPlayerComponent

Renders a single component of media.

Internally, a renderer's lifecycle is managed by the owning ExoPlayer. The player will transition its renderers through various states as the overall playback state changes. The valid state transitions are shown below, annotated with the methods that are invoked during each transition.

Field Summary

Fields

Modifier and Type	Field and Description
static long	END_OF_TRACK_US Represents the time of the end of the track.
static long	MATCH_LONGEST_US Represents a time or duration that should match the duration of the longest track whose duration is known.
protected static int	STATE_ENABLED The renderer is enabled.
protected static int	STATE_PREPARED The renderer has completed necessary preparation.
protected static int	STATE_RELEASED The renderer has been released and should not be used.
protected static int	STATE_STARTED The renderer is started.
protected static int	STATE_UNPREPARED The renderer has not yet been prepared.
static long	UNKNOWN_TIME_US Represents an unknown time or duration.

Constructor Summary

Constructors

Constructor and Description
TrackRenderer()

Method Summary

Modifier and Type	Method and Description
protected abstract boolean	doPrepare(long positionUs) Invoked to make progress when the renderer is in the STATE_UNPREPARED state.
protected abstract void	doSomeWork(long positionUs, long elapsedRealtimeUs) Invoked to make progress when the renderer is in the STATE_ENABLED or STATE_STARTED states.
protected abstract long	getBufferedPositionUs() Returns an estimate of the absolute position in microseconds up to which data is buffered.
protected abstract long	getDurationUs() Returns the duration of the media being rendered.
protected abstract MediaFormat	getFormat(int track) Returns the format of the specified track.
protected MediaClock	getMediaClock() If the renderer advances its own playback position then this method returns a corresponding MediaClock.
protected int	getState() Returns the current state of the renderer.
protected abstract int	getTrackCount() Returns the number of tracks exposed by the renderer.
void	handleMessage(int what, Object object) Handles a message delivered to the component.
protected abstract boolean	isEnded() Whether the renderer is ready for the ExoPlayer instance to transition to ExoPlayer.STATE_ENDED.
protected abstract boolean	isReady() Whether the renderer is able to immediately render media from the current position.
protected abstract void	maybeThrowError() Throws an error that's preventing the renderer from making progress or buffering more data at this point in time.
protected void	onDisabled() Called when the renderer is disabled.
protected void	onEnabled(int track, long positionUs, boolean joining) Called when the renderer is enabled.
protected void	onReleased() Called when the renderer is released.
protected void	onStarted() Called when the renderer is started.
protected void	onStopped() Called when the renderer is stopped.
protected abstract void	seekTo(long positionUs) Seeks to a specified time in the track.

Methods inherited from class java.lang.Object

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

Field Detail

UNKNOWN_TIME_US

public static final long UNKNOWN_TIME_US

Represents an unknown time or duration. Equal to C.UNKNOWN_TIME_US.

See Also:

Constant Field Values

MATCH_LONGEST_US

public static final long MATCH_LONGEST_US

Represents a time or duration that should match the duration of the longest track whose duration is known. Equal to C.MATCH_LONGEST_US.

See Also:

Constant Field Values

END_OF_TRACK_US

public static final long END_OF_TRACK_US

Represents the time of the end of the track.

See Also:

Constant Field Values

STATE_RELEASED

protected static final int STATE_RELEASED

The renderer has been released and should not be used.

See Also:

Constant Field Values

STATE_UNPREPARED

protected static final int STATE_UNPREPARED

The renderer has not yet been prepared.

See Also:

Constant Field Values

STATE_PREPARED

protected static final int STATE_PREPARED

The renderer has completed necessary preparation. Preparation may include, for example, reading the header of a media file to determine the track format and duration.

The renderer should not hold scarce or expensive system resources (e.g. media decoders) and should not be actively buffering media data when in this state.

See Also:

Constant Field Values

STATE_ENABLED

protected static final int STATE_ENABLED

The renderer is enabled. It should either be ready to be started, or be actively working towards this state (e.g. a renderer in this state will typically hold any resources that it requires, such as media decoders, and will have buffered or be buffering any media data that is required to start playback).

See Also:

Constant Field Values

STATE_STARTED

protected static final int STATE_STARTED

The renderer is started. Calls to doSomeWork(long, long) should cause the media to be rendered.

See Also:

Constant Field Values

Constructor Detail

TrackRenderer

public TrackRenderer()

Method Detail

getMediaClock

protected MediaClock getMediaClock()

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.

Returns:

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

getState

protected final int getState()

Returns the current state of the renderer.

Returns:

The current state (one of the STATE_* constants).

doPrepare

protected abstract boolean doPrepare(long positionUs)
                              throws ExoPlaybackException

Invoked to make progress when the renderer is in the STATE_UNPREPARED state. This method will be called repeatedly until true is returned.

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

Parameters:

positionUs - The player's current playback position.

Returns:

True if the renderer is now prepared. False otherwise.

Throws:

ExoPlaybackException - If an error occurs.

getTrackCount

protected abstract int getTrackCount()

Returns the number of tracks exposed by the renderer.

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

Returns:

The number of tracks.

getFormat

protected abstract MediaFormat getFormat(int track)

Returns the format of the specified track.

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

Parameters:

track - The track index.

Returns:

The format of the specified track.

onEnabled

protected void onEnabled(int track,
                         long positionUs,
                         boolean joining)
                  throws ExoPlaybackException

Called when the renderer is enabled.

The default implementation is a no-op.

Parameters:

track - The track for which the renderer is being enabled.

positionUs - The player's current position.

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

Throws:

ExoPlaybackException - If an error occurs.

onStarted

protected void onStarted()
                  throws ExoPlaybackException

Called when the renderer is started.

The default implementation is a no-op.

Throws:

ExoPlaybackException - If an error occurs.

onStopped

protected void onStopped()
                  throws ExoPlaybackException

Called when the renderer is stopped.

The default implementation is a no-op.

Throws:

ExoPlaybackException - If an error occurs.

onDisabled

protected void onDisabled()
                   throws ExoPlaybackException

Called when the renderer is disabled.

The default implementation is a no-op.

Throws:

ExoPlaybackException - If an error occurs.

onReleased

protected void onReleased()
                   throws ExoPlaybackException

Called when the renderer is released.

The default implementation is a no-op.

Throws:

ExoPlaybackException - If an error occurs.

isEnded

protected abstract boolean isEnded()

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

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

Returns:

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

isReady

protected abstract boolean isReady()

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

If the renderer is in the 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 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: STATE_ENABLED, STATE_STARTED

Returns:

True if the renderer is ready to render media. False otherwise.

doSomeWork

protected abstract void doSomeWork(long positionUs,
                                   long elapsedRealtimeUs)
                            throws ExoPlaybackException

Invoked to make progress when the renderer is in the STATE_ENABLED or STATE_STARTED states.

If the renderer's state is STATE_STARTED, then repeated calls to this method should cause the media track to be rendered. If the state is STATE_ENABLED, then repeated calls should make progress towards getting the renderer into a position where it is ready to render the track.

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

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

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.

maybeThrowError

protected abstract void maybeThrowError()
                                 throws ExoPlaybackException

Throws an error that's preventing the renderer from making progress or buffering more data at this point in time.

Throws:

ExoPlaybackException - An error that's preventing the renderer from making progress or buffering more data.

getDurationUs

protected abstract long getDurationUs()

Returns the duration of the media being rendered.

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

Returns:

The duration of the track in microseconds, or MATCH_LONGEST_US if the track's duration should match that of the longest track whose duration is known, or or UNKNOWN_TIME_US if the duration is not known.

getBufferedPositionUs

protected abstract long getBufferedPositionUs()

Returns an estimate of the absolute position in microseconds up to which data is buffered.

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

Returns:

An estimate of the absolute position in microseconds up to which data is buffered, or END_OF_TRACK_US if the track is fully buffered, or UNKNOWN_TIME_US if no estimate is available.

seekTo

protected abstract void seekTo(long positionUs)
                        throws ExoPlaybackException

Seeks to a specified time in the track.

This method may be called when the renderer is in the following states: STATE_ENABLED

Parameters:

positionUs - The desired playback position in microseconds.

Throws:

ExoPlaybackException - If an error occurs.

handleMessage

public void handleMessage(int what,
                          Object object)
                   throws ExoPlaybackException

Description copied from interface: ExoPlayer.ExoPlayerComponent

Handles a message delivered to the component. Invoked on the playback thread.

Specified by:

handleMessage in interface ExoPlayer.ExoPlayerComponent

Parameters:

what - An integer identifying the type of message.

object - The message object.

Throws:

ExoPlaybackException - If an error occurred whilst handling the message.