com.google.android.exoplayer2.source

Class DeferredMediaPeriod

java.lang.Object

com.google.android.exoplayer2.source.DeferredMediaPeriod

All Implemented Interfaces:

MediaPeriod, MediaPeriod.Callback, SequenceableLoader, SequenceableLoader.Callback<MediaPeriod>

public final class DeferredMediaPeriod
extends java.lang.Object
implements MediaPeriod, MediaPeriod.Callback

Media period that wraps a media source and defers calling its MediaSource.createPeriod(MediaPeriodId, Allocator) method until #createPeriod(MediaPeriodId) has been called. This is useful if you need to return a media period immediately but the media source that should create it is not yet prepared.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	DeferredMediaPeriod.PrepareErrorListener Listener for preparation errors.

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

MediaPeriod.Callback

Field Summary

Fields

Modifier and Type	Field and Description
MediaSource.MediaPeriodId	id The MediaSource.MediaPeriodId used to create the deferred media period.
MediaSource	mediaSource The MediaSource which will create the actual media period.

Constructor Summary

Constructors

Constructor and Description
DeferredMediaPeriod(MediaSource mediaSource, MediaSource.MediaPeriodId id, Allocator allocator) Creates a new deferred media period.

Method Summary

Modifier and Type	Method and Description
boolean	continueLoading(long positionUs) Attempts to continue loading.
void	createPeriod(MediaSource.MediaPeriodId id) Calls MediaSource.createPeriod(MediaPeriodId, Allocator) on the wrapped source then prepares it if MediaPeriod.prepare(Callback, long) has been called.
void	discardBuffer(long positionUs, boolean toKeyframe) Discards buffered media up to the specified position.
long	getAdjustedSeekPositionUs(long positionUs, SeekParameters seekParameters) Returns the position to which a seek will be performed, given the specified seek position and SeekParameters.
long	getBufferedPositionUs() Returns an estimate of the position up to which data is buffered for the enabled tracks.
long	getNextLoadPositionUs() Returns the next load time, or C.TIME_END_OF_SOURCE if loading has finished.
TrackGroupArray	getTrackGroups() Returns the TrackGroups exposed by the period.
void	maybeThrowPrepareError() Throws an error that's preventing the period from becoming prepared.
void	onContinueLoadingRequested(MediaPeriod source) Called by the loader to indicate that it wishes for its SequenceableLoader.continueLoading(long) method to be called when it can continue to load data.
void	onPrepared(MediaPeriod mediaPeriod) Called when preparation completes.
void	prepare(MediaPeriod.Callback callback, long preparePositionUs) Prepares this media period asynchronously.
long	readDiscontinuity() Attempts to read a discontinuity.
void	reevaluateBuffer(long positionUs) Re-evaluates the buffer given the playback position.
void	releasePeriod() Releases the period.
long	seekToUs(long positionUs) Attempts to seek to the specified position in microseconds.
long	selectTracks(TrackSelection[] selections, boolean[] mayRetainStreamFlags, SampleStream[] streams, boolean[] streamResetFlags, long positionUs) Performs a track selection.
void	setDefaultPreparePositionUs(long defaultPreparePositionUs) Sets the default prepare position at which to prepare the media period.
void	setPrepareErrorListener(DeferredMediaPeriod.PrepareErrorListener listener) Sets a listener for preparation errors.

Methods inherited from class java.lang.Object

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

Field Detail

mediaSource

public final MediaSource mediaSource

The MediaSource which will create the actual media period.

id

public final MediaSource.MediaPeriodId id

The MediaSource.MediaPeriodId used to create the deferred media period.

Constructor Detail

DeferredMediaPeriod

public DeferredMediaPeriod(MediaSource mediaSource,
                           MediaSource.MediaPeriodId id,
                           Allocator allocator)

Creates a new deferred media period.

Parameters:

mediaSource - The media source to wrap.

id - The identifier used to create the deferred media period.

allocator - The allocator used to create the media period.

Method Detail

setPrepareErrorListener

public void setPrepareErrorListener(DeferredMediaPeriod.PrepareErrorListener listener)

Sets a listener for preparation errors.

Parameters:

listener - An listener to be notified of media period preparation errors. If a listener is set, maybeThrowPrepareError() will not throw but will instead pass the first preparation error (if any) to the listener.

setDefaultPreparePositionUs

public void setDefaultPreparePositionUs(long defaultPreparePositionUs)

Sets the default prepare position at which to prepare the media period. This value is only used if the call to MediaPeriod.prepare(Callback, long) is being deferred and the call was made with a (presumably default) prepare position of 0.

Note that this will override an intentional seek to zero in the corresponding non-seekable timeline window. This is unlikely to be a problem as a non-zero default position usually only occurs for live playbacks and seeking to zero in a live window would cause BehindLiveWindowExceptions anyway.

Parameters:

defaultPreparePositionUs - The actual default prepare position, in microseconds.

createPeriod

public void createPeriod(MediaSource.MediaPeriodId id)

Calls MediaSource.createPeriod(MediaPeriodId, Allocator) on the wrapped source then prepares it if MediaPeriod.prepare(Callback, long) has been called. Call releasePeriod() to release the period.

Parameters:

id - The identifier that should be used to create the media period from the media source.

releasePeriod

public void releasePeriod()

Releases the period.

prepare

public void prepare(MediaPeriod.Callback callback,
                    long preparePositionUs)

Description copied from interface: MediaPeriod

Prepares this media period asynchronously.

callback.onPrepared is called when preparation completes. If preparation fails, MediaPeriod.maybeThrowPrepareError() will throw an IOException.

If preparation succeeds and results in a source timeline change (e.g. the period duration becoming known), MediaSource.SourceInfoRefreshListener.onSourceInfoRefreshed(MediaSource, Timeline, Object) will be called before callback.onPrepared.

Specified by:

prepare in interface MediaPeriod

Parameters:

callback - Callback to receive updates from this period, including being notified when preparation completes.

preparePositionUs - The expected starting position, in microseconds.

maybeThrowPrepareError

public void maybeThrowPrepareError()
                            throws java.io.IOException

Description copied from interface: MediaPeriod

Throws an error that's preventing the period from becoming prepared. Does nothing if no such error exists.

This method is only called before the period has completed preparation.

Specified by:

maybeThrowPrepareError in interface MediaPeriod

Throws:

java.io.IOException - The underlying error.

getTrackGroups

public TrackGroupArray getTrackGroups()

Description copied from interface: MediaPeriod

Returns the TrackGroups exposed by the period.

This method is only called after the period has been prepared.

Specified by:

getTrackGroups in interface MediaPeriod

Returns:

The TrackGroups.

selectTracks

public long selectTracks(TrackSelection[] selections,
                         boolean[] mayRetainStreamFlags,
                         SampleStream[] streams,
                         boolean[] streamResetFlags,
                         long positionUs)

Description copied from interface: MediaPeriod

Performs a track selection.

The call receives track selections for each renderer, mayRetainStreamFlags indicating whether the existing SampleStream can be retained for each selection, and the existing streams themselves. The call will update streams to reflect the provided selections, clearing, setting and replacing entries as required. If an existing sample stream is retained but with the requirement that the consuming renderer be reset, then the corresponding flag in streamResetFlags will be set to true. This flag will also be set if a new sample stream is created.

This method is only called after the period has been prepared.

Specified by:

selectTracks in interface MediaPeriod

Parameters:

selections - The renderer track selections.

mayRetainStreamFlags - Flags indicating whether the existing sample stream can be retained for each selection. A true value indicates that the selection is unchanged, and that the caller does not require that the sample stream be recreated.

streams - The existing sample streams, which will be updated to reflect the provided selections.

streamResetFlags - Will be updated to indicate new sample streams, and sample streams that have been retained but with the requirement that the consuming renderer be reset.

positionUs - The current playback position in microseconds. If playback of this period has not yet started, the value will be the starting position.

Returns:

The actual position at which the tracks were enabled, in microseconds.

discardBuffer

public void discardBuffer(long positionUs,
                          boolean toKeyframe)

Description copied from interface: MediaPeriod

Discards buffered media up to the specified position.

This method is only called after the period has been prepared.

Specified by:

discardBuffer in interface MediaPeriod

Parameters:

positionUs - The position in microseconds.

toKeyframe - If true then for each track discards samples up to the keyframe before or at the specified position, rather than any sample before or at that position.

readDiscontinuity

public long readDiscontinuity()

Description copied from interface: MediaPeriod

Attempts to read a discontinuity.

After this method has returned a value other than C.TIME_UNSET, all SampleStreams provided by the period are guaranteed to start from a key frame.

This method is only called after the period has been prepared and before reading from any SampleStreams provided by the period.

Specified by:

readDiscontinuity in interface MediaPeriod

Returns:

If a discontinuity was read then the playback position in microseconds after the discontinuity. Else C.TIME_UNSET.

getBufferedPositionUs

public long getBufferedPositionUs()

Description copied from interface: MediaPeriod

Returns an estimate of the position up to which data is buffered for the enabled tracks.

This method is only called when at least one track is selected.

Specified by:

getBufferedPositionUs in interface MediaPeriod

Specified by:

getBufferedPositionUs in interface SequenceableLoader

Returns:

An estimate of the absolute position in microseconds up to which data is buffered, or C.TIME_END_OF_SOURCE if the track is fully buffered.

seekToUs

public long seekToUs(long positionUs)

Description copied from interface: MediaPeriod

Attempts to seek to the specified position in microseconds.

After this method has been called, all SampleStreams provided by the period are guaranteed to start from a key frame.

This method is only called when at least one track is selected.

Specified by:

seekToUs in interface MediaPeriod

Parameters:

positionUs - The seek position in microseconds.

Returns:

The actual position to which the period was seeked, in microseconds.

getAdjustedSeekPositionUs

public long getAdjustedSeekPositionUs(long positionUs,
                                      SeekParameters seekParameters)

Description copied from interface: MediaPeriod

Returns the position to which a seek will be performed, given the specified seek position and SeekParameters.

This method is only called after the period has been prepared.

Specified by:

getAdjustedSeekPositionUs in interface MediaPeriod

Parameters:

positionUs - The seek position in microseconds.

seekParameters - Parameters that control how the seek is performed. Implementations may apply seek parameters on a best effort basis.

Returns:

The actual position to which a seek will be performed, in microseconds.

getNextLoadPositionUs

public long getNextLoadPositionUs()

Description copied from interface: MediaPeriod

Returns the next load time, or C.TIME_END_OF_SOURCE if loading has finished.

This method is only called after the period has been prepared. It may be called when no tracks are selected.

Specified by:

getNextLoadPositionUs in interface MediaPeriod

Specified by:

getNextLoadPositionUs in interface SequenceableLoader

reevaluateBuffer

public void reevaluateBuffer(long positionUs)

Description copied from interface: MediaPeriod

Re-evaluates the buffer given the playback position.

This method is only called after the period has been prepared.

A period may choose to discard buffered media so that it can be re-buffered in a different quality.

Specified by:

reevaluateBuffer in interface MediaPeriod

Specified by:

reevaluateBuffer in interface SequenceableLoader

Parameters:

positionUs - The current playback position in microseconds. If playback of this period has not yet started, the value will be the starting position in this period minus the duration of any media in previous periods still to be played.

continueLoading

public boolean continueLoading(long positionUs)

Description copied from interface: MediaPeriod

Attempts to continue loading.

This method may be called both during and after the period has been prepared.

A period may call SequenceableLoader.Callback.onContinueLoadingRequested(SequenceableLoader) on the MediaPeriod.Callback passed to MediaPeriod.prepare(Callback, long) to request that this method be called when the period is permitted to continue loading data. A period may do this both during and after preparation.

Specified by:

continueLoading in interface MediaPeriod

Specified by:

continueLoading in interface SequenceableLoader

Parameters:

positionUs - The current playback position in microseconds. If playback of this period has not yet started, the value will be the starting position in this period minus the duration of any media in previous periods still to be played.

Returns:

True if progress was made, meaning that MediaPeriod.getNextLoadPositionUs() will return a different value than prior to the call. False otherwise.

onContinueLoadingRequested

public void onContinueLoadingRequested(MediaPeriod source)

Description copied from interface: SequenceableLoader.Callback

Called by the loader to indicate that it wishes for its SequenceableLoader.continueLoading(long) method to be called when it can continue to load data. Called on the playback thread.

Specified by:

onContinueLoadingRequested in interface SequenceableLoader.Callback<MediaPeriod>

onPrepared

public void onPrepared(MediaPeriod mediaPeriod)

Description copied from interface: MediaPeriod.Callback

Called when preparation completes.

Called on the playback thread. After invoking this method, the MediaPeriod can expect for MediaPeriod.selectTracks(TrackSelection[], boolean[], SampleStream[], boolean[], long) to be called with the initial track selection.

Specified by:

onPrepared in interface MediaPeriod.Callback

Parameters:

mediaPeriod - The prepared MediaPeriod.