ClippingMediaPeriod

@UnstableApi
public final class ClippingMediaPeriod implements MediaPeriod, MediaPeriod.Callback


Wraps a MediaPeriod and clips its SampleStreams to provide a subsequence of their samples.

Summary

Public fields

final MediaPeriod

The MediaPeriod wrapped by this clipping media period.

Public constructors

ClippingMediaPeriod(
    MediaPeriod mediaPeriod,
    boolean enableInitialDiscontinuity,
    long startUs,
    long endUs
)

Creates a new clipping media period that provides a clipped view of the specified 's sample streams.

Public methods

boolean

Attempts to continue loading.

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

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

long

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

List<StreamKey>

Returns a list of StreamKeys which allow to filter the media in this period to load only the parts needed to play the provided TrackSelections.

TrackGroupArray

Returns the TrackGroups exposed by the period.

boolean

Returns whether the media period is currently loading.

void

Throws an error that's preventing the period from becoming prepared.

void

Called by the loader to indicate that it wishes for its continueLoading 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 positionUs)

Prepares this media period asynchronously.

long

Attempts to read a discontinuity.

void
reevaluateBuffer(long positionUs)

Re-evaluates the buffer given the playback position.

long
seekToUs(long positionUs)

Attempts to seek to the specified position in microseconds.

long
selectTracks(
    @NullableType ExoTrackSelection[] selections,
    boolean[] mayRetainStreamFlags,
    @NullableType SampleStream[] streams,
    boolean[] streamResetFlags,
    long positionUs
)

Performs a track selection.

void

Sets a clipping error detected by the media source so that it can be thrown as a period error at the next opportunity.

void
updateClipping(long startUs, long endUs)

Updates the clipping start/end times for this period, in microseconds.

Public fields

mediaPeriod

public final MediaPeriod mediaPeriod

The MediaPeriod wrapped by this clipping media period.

Public constructors

ClippingMediaPeriod

public ClippingMediaPeriod(
    MediaPeriod mediaPeriod,
    boolean enableInitialDiscontinuity,
    long startUs,
    long endUs
)

Creates a new clipping media period that provides a clipped view of the specified 's sample streams.

If the start point is guaranteed to be a key frame, pass false to enableInitialPositionDiscontinuity to suppress an initial discontinuity when the period is first read from.

Parameters
MediaPeriod mediaPeriod

The media period to clip.

boolean enableInitialDiscontinuity

Whether the initial discontinuity should be enabled.

long startUs

The clipping start time, in microseconds.

long endUs

The clipping end time, in microseconds, or TIME_END_OF_SOURCE to indicate the end of the period.

Public methods

continueLoading

public boolean continueLoading(LoadingInfo loadingInfo)

Attempts to continue loading.

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

A period may call onContinueLoadingRequested on the Callback passed to prepare 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.

Parameters
LoadingInfo loadingInfo

The LoadingInfo when attempting to continue loading.

Returns
boolean

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

discardBuffer

public void discardBuffer(long positionUs, boolean toKeyframe)

Discards buffered media up to the specified position.

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

Parameters
long positionUs

The position in microseconds.

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

getAdjustedSeekPositionUs

public long getAdjustedSeekPositionUs(
    long positionUs,
    SeekParameters seekParameters
)

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.

Parameters
long positionUs

The seek position in microseconds.

SeekParameters seekParameters

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

Returns
long

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

getBufferedPositionUs

public long getBufferedPositionUs()

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.

Returns
long

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

getNextLoadPositionUs

public long getNextLoadPositionUs()

Returns the next load time, or 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.

getStreamKeys

public List<StreamKeygetStreamKeys(List<ExoTrackSelection> trackSelections)

Returns a list of StreamKeys which allow to filter the media in this period to load only the parts needed to play the provided TrackSelections.

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

Parameters
List<ExoTrackSelection> trackSelections

The TrackSelections describing the tracks for which stream keys are requested.

Returns
List<StreamKey>

The corresponding StreamKeys for the selected tracks, or an empty list if filtering is not possible and the entire media needs to be loaded to play the selected tracks.

getTrackGroups

public TrackGroupArray getTrackGroups()

Returns the TrackGroups exposed by the period.

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

Returns
TrackGroupArray

The TrackGroups.

isLoading

public boolean isLoading()

Returns whether the media period is currently loading.

maybeThrowPrepareError

public void maybeThrowPrepareError()

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.

Throws
java.io.IOException

The underlying error.

onContinueLoadingRequested

public void onContinueLoadingRequested(MediaPeriod source)

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

onPrepared

public void onPrepared(MediaPeriod mediaPeriod)

Called when preparation completes.

Called on the playback thread. After invoking this method, the MediaPeriod can expect for selectTracks to be called with the initial track selection.

Parameters
MediaPeriod mediaPeriod

The prepared MediaPeriod.

prepare

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

Prepares this media period asynchronously.

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

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

Parameters
MediaPeriod.Callback callback

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

long positionUs

The expected starting position, in microseconds.

readDiscontinuity

public long readDiscontinuity()

Attempts to read a discontinuity.

A discontinuity implies that the provided SampleStreams will start from a new playback position and any output pipelines need to be reset. This happens for example if the streams provide decode-only samples before the intended playback start position that need to be dropped.

After this method has returned a value other than 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.

Returns
long

The playback position after the discontinuity, in microseconds, or TIME_UNSET if there is no discontinuity.

reevaluateBuffer

public void reevaluateBuffer(long positionUs)

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 or cancel ongoing loads so that media can be re-buffered in a different quality.

Parameters
long 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.

seekToUs

public long seekToUs(long positionUs)

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.

Parameters
long positionUs

The seek position in microseconds.

Returns
long

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

selectTracks

public long selectTracks(
    @NullableType ExoTrackSelection[] selections,
    boolean[] mayRetainStreamFlags,
    @NullableType SampleStream[] streams,
    boolean[] streamResetFlags,
    long positionUs
)

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.

Note that previously passed TrackSelections are no longer valid, and any references to them must be updated to point to the new selections.

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

Parameters
@NullableType ExoTrackSelection[] selections

The renderer track selections.

boolean[] mayRetainStreamFlags

Flags indicating whether the existing sample stream can be retained for each track selection. A true value indicates that the selection is equivalent to the one that was previously passed, and that the caller does not require that the sample stream be recreated. If a retained sample stream holds any references to the track selection then they must be updated to point to the new selection.

@NullableType SampleStream[] streams

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

boolean[] 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.

long positionUs

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

Returns
long

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

setClippingError

public void setClippingError(
    ClippingMediaSource.IllegalClippingException clippingError
)

Sets a clipping error detected by the media source so that it can be thrown as a period error at the next opportunity.

Parameters
ClippingMediaSource.IllegalClippingException clippingError

The clipping error.

updateClipping

public void updateClipping(long startUs, long endUs)

Updates the clipping start/end times for this period, in microseconds.

Parameters
long startUs

The clipping start time, in microseconds.

long endUs

The clipping end time, in microseconds, or TIME_END_OF_SOURCE to indicate the end of the period.