MediaPeriod

Artifact: androidx.media3:media3-exoplayer

Kotlin |Java

@UnstableApi
public interface MediaPeriod extends SequenceableLoader

Known direct subclasses

ClippingMediaPeriod, FakeAdaptiveMediaPeriod, FakeMediaPeriod, MaskingMediaPeriod

`ClippingMediaPeriod`	Wraps a `MediaPeriod` and clips its `SampleStream`s to provide a subsequence of their samples.
`FakeAdaptiveMediaPeriod`	Fake `MediaPeriod` that provides tracks from the given `TrackGroupArray`.
`FakeMediaPeriod`	Fake `MediaPeriod` that provides tracks from the given `TrackGroupArray`.
`MaskingMediaPeriod`	Media period that defers calling `createPeriod` on a given source until `createPeriod` has been called.

Loads media corresponding to a Timeline.Period, and allows that media to be read. All methods are called on the player's internal playback thread, as described in the ExoPlayer Javadoc.

A MediaPeriod may only able to provide one SampleStream corresponding to a group at any given time, however this SampleStream may adapt between multiple tracks within the group.

Summary

Nested types
`public interface MediaPeriod.Callback extends SequenceableLoader.Callback` A callback to be notified of `MediaPeriod` events.

Public methods
`abstract boolean`	`continueLoading(LoadingInfo loadingInfo)` Attempts to continue loading.
`abstract void`	`discardBuffer(long positionUs, boolean toKeyframe)` Discards buffered media up to the specified position.
`abstract long`	`getAdjustedSeekPositionUs( long positionUs, SeekParameters seekParameters )` Returns the position to which a seek will be performed, given the specified seek position and `SeekParameters`.
`abstract long`	`getBufferedPositionUs()` Returns an estimate of the position up to which data is buffered for the enabled tracks.
`abstract long`	`getNextLoadPositionUs()` Returns the next load time, or `TIME_END_OF_SOURCE` if loading has finished.
`default List<StreamKey>`	`getStreamKeys(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`.
`abstract TrackGroupArray`	`getTrackGroups()` Returns the `TrackGroup`s exposed by the period.
`abstract boolean`	`isLoading()` Returns whether the media period is currently loading.
`abstract void`	`maybeThrowPrepareError()` Throws an error that's preventing the period from becoming prepared.
`abstract void`	`prepare(MediaPeriod.Callback callback, long positionUs)` Prepares this media period asynchronously.
`abstract long`	`readDiscontinuity()` Attempts to read a discontinuity.
`abstract void`	`reevaluateBuffer(long positionUs)` Re-evaluates the buffer given the playback position.
`abstract long`	`seekToUs(long positionUs)` Attempts to seek to the specified position in microseconds.
`abstract long`	`selectTracks( @NullableType ExoTrackSelection[] selections, boolean[] mayRetainStreamFlags, @NullableType SampleStream[] streams, boolean[] streamResetFlags, long positionUs )` Performs a track selection.
`default long`	`setEndPositionUs(long endPositionUs)` Sets the end position at which the period stops loading and providing samples.
`default void`	`@ExperimentalApi setUsesStreamPrerollFlags()` Notifies the media period that the player will use `getFlags` to check if streams contain initial discontinuities at the start of the period rather than using `readDiscontinuity`.

Public methods

continueLoading

abstract 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

abstract 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

abstract 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

abstract 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

abstract 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

default List<StreamKey> getStreamKeys(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

abstract TrackGroupArray getTrackGroups()

Returns the TrackGroups exposed by the period.

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

Returns
`TrackGroupArray`	The `TrackGroup`s.

isLoading

abstract boolean isLoading()

Returns whether the media period is currently loading.

maybeThrowPrepareError

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

prepare

abstract 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

abstract 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

abstract 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

abstract 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

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

setEndPositionUs

default long setEndPositionUs(long endPositionUs)

Sets the end position at which the period stops loading and providing samples.

This method may be called at any time.

If a value other than TIME_END_OF_SOURCE is returned, the implementation must stop returning samples from the created SampleStream instances beyond the specified end position and mark further reads with BUFFER_FLAG_END_OF_STREAM. The stream may return additional out of order samples required for decoding.

Parameters
`long endPositionUs`	The requested end position, in microseconds, or `TIME_END_OF_SOURCE` to not set an end position.

Returns
`long`	Returns the actual position, in microseconds, at which the source stops loading and providing samples, or `TIME_END_OF_SOURCE` if setting the end position is not supported and all samples until then end of the source will be provided.

setUsesStreamPrerollFlags

@ExperimentalApi
default void setUsesStreamPrerollFlags()

Notifies the media period that the player will use getFlags to check if streams contain initial discontinuities at the start of the period rather than using readDiscontinuity.

If invoked then readDiscontinuity should only report discontinuities that occur during playback, not any initial discontinuities at the start of the period.

MediaPeriod

Summary

Nested types

Public methods

Public methods

continueLoading

discardBuffer

getAdjustedSeekPositionUs

getBufferedPositionUs

getNextLoadPositionUs

getStreamKeys

getTrackGroups

isLoading

maybeThrowPrepareError

prepare

readDiscontinuity

reevaluateBuffer

seekToUs

selectTracks

setEndPositionUs

setUsesStreamPrerollFlags