ChunkSampleStream

Artifact: androidx.media3:media3-exoplayer

Kotlin |Java

@UnstableApi
public class ChunkSampleStream<T extends ChunkSource> implements SampleStream, SequenceableLoader, Loader.Callback, Loader.ReleaseCallback

A SampleStream that loads media in Chunks, obtained from a ChunkSource. May also be configured to expose additional embedded SampleStreams.

Summary

Nested types
`public final inner class ChunkSampleStream.EmbeddedSampleStream implements SampleStream` A `SampleStream` embedded in a `ChunkSampleStream`.
`public interface ChunkSampleStream.ReleaseCallback<T extends ChunkSource>` A callback to be notified when a sample stream has finished being released.

Public fields
`final T`	`chunkSource`
`final int`	`@C.TrackType primaryTrackType`

Public constructors
ChunkSampleStream( @C.TrackType int primaryTrackType, @Nullable int[] embeddedTrackTypes, @Nullable Format[] embeddedTrackFormats, T chunkSource, SequenceableLoader.Callback<ChunkSampleStream<T>> callback, Allocator allocator, long positionUs, DrmSessionManager drmSessionManager, DrmSessionEventListener.EventDispatcher drmEventDispatcher, LoadErrorHandlingPolicy loadErrorHandlingPolicy, MediaSourceEventListener.EventDispatcher mediaSourceEventDispatcher, boolean canReportInitialDiscontinuity, @Nullable ReleasableExecutor downloadExecutor ) Constructs an instance.

Public constructors

ChunkSampleStream(
    @C.TrackType int primaryTrackType,
    @Nullable int[] embeddedTrackTypes,
    @Nullable Format[] embeddedTrackFormats,
    T chunkSource,
    SequenceableLoader.Callback<ChunkSampleStream<T>> callback,
    Allocator allocator,
    long positionUs,
    DrmSessionManager drmSessionManager,
    DrmSessionEventListener.EventDispatcher drmEventDispatcher,
    LoadErrorHandlingPolicy loadErrorHandlingPolicy,
    MediaSourceEventListener.EventDispatcher mediaSourceEventDispatcher,
    boolean canReportInitialDiscontinuity,
    @Nullable ReleasableExecutor downloadExecutor
)

Constructs an instance.

Public methods
`boolean`	`consumeInitialDiscontinuity()` Consumes a pending initial discontinuity.
`boolean`	`continueLoading(LoadingInfo loadingInfo)` Attempts to continue loading.
`void`	`discardBuffer(long positionUs, boolean toKeyframe)` Discards buffered media up to the specified position.
`void`	`discardUpstreamSamplesForClippedDuration(long clippedDurationUs)` Discards upstream samples that exceed the given clipped duration of the stream.
`long`	`getAdjustedSeekPositionUs( long positionUs, SeekParameters seekParameters )` Adjusts a seek position given the specified `SeekParameters`.
`long`	`getBufferedPositionUs()` Returns an estimate of the position up to which data is buffered.
`T`	`getChunkSource()` Returns the `ChunkSource` used by this stream.
`long`	`getNextLoadPositionUs()` Returns the next load time, or `TIME_END_OF_SOURCE` if loading has finished.
`boolean`	`isLoading()` Returns whether the loader is currently loading.
`boolean`	`isReady()` Returns whether data is available to be read.
`void`	`maybeThrowError()` Throws an error that's preventing data from being read.
`void`	`onLoadCanceled( Chunk loadable, long elapsedRealtimeMs, long loadDurationMs, boolean released )` Called when a load has been canceled.
`void`	`onLoadCompleted( Chunk loadable, long elapsedRealtimeMs, long loadDurationMs )` Called when a load has completed.
`Loader.LoadErrorAction`	`onLoadError( Chunk loadable, long elapsedRealtimeMs, long loadDurationMs, IOException error, int errorCount )` Called when a load encounters an error.
`void`	`onLoadStarted( Chunk loadable, long elapsedRealtimeMs, long loadDurationMs, int retryCount )` Called when a load has started for the first time or through a retry.
`void`	`onLoaderReleased()` Called when the `Loader` has finished being released.
`int`	`readData( FormatHolder formatHolder, DecoderInputBuffer buffer, @SampleStream.ReadFlags int readFlags )` Attempts to read from the stream.
`void`	`reevaluateBuffer(long positionUs)` Re-evaluates the buffer given the playback position.
`void`	`release()` Releases the stream.
`void`	`release(@Nullable ChunkSampleStream.ReleaseCallback<T> callback)` Releases the stream.
`void`	`seekToUs(long positionUs)` Seeks to the specified position in microseconds.
`ChunkSampleStream.EmbeddedSampleStream`	`selectEmbeddedTrack(long positionUs, int trackType)` Selects the embedded track, returning a new `EmbeddedSampleStream` from which the track's samples can be consumed.
`int`	`skipData(long positionUs)` Attempts to skip to the keyframe before the specified position, or to the end of the stream if `positionUs` is beyond it.

Inherited Constants

From androidx.media3.exoplayer.source.SampleStream

`static final int`	`FLAG_OMIT_SAMPLE_DATA = 4` Specifies that `data`, `supplementalData` and `cryptoInfo` should not be populated when reading a sample buffer.
`static final int`	`FLAG_PEEK = 1` Specifies that the read position should not be advanced if a sample buffer is read.
`static final int`	`FLAG_REQUIRE_FORMAT = 2` Specifies that if a sample buffer would normally be read next, the format of the stream should be read instead.

Public fields

chunkSource

public final T chunkSource

primaryTrackType

@C.TrackType
public final int primaryTrackType

Public constructors

ChunkSampleStream

public ChunkSampleStream(
    @C.TrackType int primaryTrackType,
    @Nullable int[] embeddedTrackTypes,
    @Nullable Format[] embeddedTrackFormats,
    T chunkSource,
    SequenceableLoader.Callback<ChunkSampleStream<T>> callback,
    Allocator allocator,
    long positionUs,
    DrmSessionManager drmSessionManager,
    DrmSessionEventListener.EventDispatcher drmEventDispatcher,
    LoadErrorHandlingPolicy loadErrorHandlingPolicy,
    MediaSourceEventListener.EventDispatcher mediaSourceEventDispatcher,
    boolean canReportInitialDiscontinuity,
    @Nullable ReleasableExecutor downloadExecutor
)

Constructs an instance.

Parameters
`@C.TrackType int primaryTrackType`	The `type` of the primary track.
`@Nullable int[] embeddedTrackTypes`	The types of any embedded tracks, or null.
`@Nullable Format[] embeddedTrackFormats`	The formats of the embedded tracks, or null.
`T chunkSource`	A `ChunkSource` from which chunks to load are obtained.
`SequenceableLoader.Callback<ChunkSampleStream<T>> callback`	An `Callback` for the stream.
`Allocator allocator`	An `Allocator` from which allocations can be obtained.
`long positionUs`	The position from which to start loading media.
`DrmSessionManager drmSessionManager`	The `DrmSessionManager` to obtain `DrmSessions` from.
`DrmSessionEventListener.EventDispatcher drmEventDispatcher`	A dispatcher to notify of `DrmSessionEventListener` events.
`LoadErrorHandlingPolicy loadErrorHandlingPolicy`	The `LoadErrorHandlingPolicy`.
`MediaSourceEventListener.EventDispatcher mediaSourceEventDispatcher`	A dispatcher to notify of `MediaSourceEventListener` events.
`boolean canReportInitialDiscontinuity`	Whether the stream can report an initial discontinuity if the first chunk can't start at the beginning and needs to preroll data.
`@Nullable ReleasableExecutor downloadExecutor`	An optional externally provided `ReleasableExecutor` for loading and extracting media.

Public methods

consumeInitialDiscontinuity

public boolean consumeInitialDiscontinuity()

Consumes a pending initial discontinuity.

Returns
`boolean`	Whether the stream had an initial discontinuity.

continueLoading

public boolean continueLoading(LoadingInfo loadingInfo)

Attempts to continue loading.

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.

Parameters
`long positionUs`	The position to discard up to, 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.

discardUpstreamSamplesForClippedDuration

public void discardUpstreamSamplesForClippedDuration(long clippedDurationUs)

Discards upstream samples that exceed the given clipped duration of the stream.

Parameters
`long clippedDurationUs`	The clipped duration of the stream in microseconds, or `TIME_UNSET` if not known.

getAdjustedSeekPositionUs

public long getAdjustedSeekPositionUs(
    long positionUs,
    SeekParameters seekParameters
)

Adjusts a seek position given the specified SeekParameters. Chunk boundaries are used as sync points.

Parameters
`long positionUs`	The seek position in microseconds.
`SeekParameters seekParameters`	Parameters that control how the seek is performed.

Returns
`long`	The adjusted seek position, in microseconds.

getBufferedPositionUs

public long getBufferedPositionUs()

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

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.

getChunkSource

public T getChunkSource()

Returns the ChunkSource used by this stream.

getNextLoadPositionUs

public long getNextLoadPositionUs()

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

isLoading

public boolean isLoading()

Returns whether the loader is currently loading.

isReady

public boolean isReady()

Returns whether data is available to be read.

Note: If the stream has ended then a buffer with the end of stream flag can always be read from readData. Hence an ended stream is always ready.

Returns
`boolean`	Whether data is available to be read.

maybeThrowError

public void maybeThrowError()

Throws an error that's preventing data from being read. Does nothing if no such error exists.

Throws
`java.io.IOException`	The underlying error.

onLoadCanceled

public void onLoadCanceled(
    Chunk loadable,
    long elapsedRealtimeMs,
    long loadDurationMs,
    boolean released
)

Called when a load has been canceled.

Note: If the Loader has not been released then there is guaranteed to be a memory barrier between load exiting and this callback being called. If the Loader has been released then this callback may be called before load exits.

Parameters
`Chunk loadable`	The loadable whose load has been canceled.
`long elapsedRealtimeMs`	`elapsedRealtime` when the load was canceled.
`long loadDurationMs`	The duration in milliseconds of the load since `startLoading` was called up to the point at which it was canceled.
`boolean released`	True if the load was canceled because the `Loader` was released. False otherwise.

onLoadCompleted

public void onLoadCompleted(
    Chunk loadable,
    long elapsedRealtimeMs,
    long loadDurationMs
)

Called when a load has completed.

Note: There is guaranteed to be a memory barrier between load exiting and this callback being called.

Parameters
`Chunk loadable`	The loadable whose load has completed.
`long elapsedRealtimeMs`	`elapsedRealtime` when the load ended.
`long loadDurationMs`	The duration in milliseconds of the load since `startLoading` was called.

onLoadError

public Loader.LoadErrorAction onLoadError(
    Chunk loadable,
    long elapsedRealtimeMs,
    long loadDurationMs,
    IOException error,
    int errorCount
)

Called when a load encounters an error.

Note: There is guaranteed to be a memory barrier between load exiting and this callback being called.

Parameters
`Chunk loadable`	The loadable whose load has encountered an error.
`long elapsedRealtimeMs`	`elapsedRealtime` when the error occurred.
`long loadDurationMs`	The duration in milliseconds of the load since `startLoading` was called up to the point at which the error occurred.
`IOException error`	The load error.
`int errorCount`	The number of errors this load has encountered, including this one.

Returns
`Loader.LoadErrorAction`	The desired error handling action. One of `RETRY`, `RETRY_RESET_ERROR_COUNT`, `DONT_RETRY`, `DONT_RETRY_FATAL` or a retry action created by `createRetryAction`.

onLoadStarted

public void onLoadStarted(
    Chunk loadable,
    long elapsedRealtimeMs,
    long loadDurationMs,
    int retryCount
)

Called when a load has started for the first time or through a retry.

This is called for the first time with retryCount == 0 just before the load is started.

Parameters
`Chunk loadable`	The loadable whose load has started.
`long elapsedRealtimeMs`	`elapsedRealtime` when the load attempts to start.
`long loadDurationMs`	The duration in milliseconds of the load since `startLoading` was called.
`int retryCount`	The number of failed attempts since `startLoading` was called (this is zero for the first load attempt).

onLoaderReleased

public void onLoaderReleased()

Called when the Loader has finished being released.

readData

public int readData(
    FormatHolder formatHolder,
    DecoderInputBuffer buffer,
    @SampleStream.ReadFlags int readFlags
)

Attempts to read from the stream.

If the stream has ended then BUFFER_FLAG_END_OF_STREAM flag is set on buffer and RESULT_BUFFER_READ is returned. Else if no data is available then RESULT_NOTHING_READ is returned. Else if the format of the media is changing or if formatRequired is set then formatHolder is populated and RESULT_FORMAT_READ is returned. Else buffer is populated and RESULT_BUFFER_READ is returned.

Parameters
`FormatHolder formatHolder`	A `FormatHolder` to populate in the case of reading a format.
`DecoderInputBuffer buffer`	A `DecoderInputBuffer` to populate in the case of reading a sample or the end of the stream. If the end of the stream has been reached, the `BUFFER_FLAG_END_OF_STREAM` flag will be set on the buffer.
`@SampleStream.ReadFlags int readFlags`	Flags controlling the behavior of this read operation.

Returns
`int`	The `result` of the read operation.

Throws
`androidx.media3.decoder.DecoderInputBuffer.InsufficientCapacityException`	If the `buffer` has insufficient capacity to hold the data of a sample being read. The buffer `timestamp` and flags are populated if this exception is thrown, but the read position is not advanced.

reevaluateBuffer

public void reevaluateBuffer(long positionUs)

Re-evaluates the buffer given the playback position.

Re-evaluation may 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.

release

public void release()

Releases the stream.

This method should be called when the stream is no longer required. Either this method or release can be used to release this stream.

release

public void release(@Nullable ChunkSampleStream.ReleaseCallback<T> callback)

Releases the stream.

This method should be called when the stream is no longer required. Either this method or release can be used to release this stream.

Parameters
`@Nullable ChunkSampleStream.ReleaseCallback<T> callback`	An optional callback to be called on the loading thread once the loader has been released.

seekToUs

public void seekToUs(long positionUs)

Seeks to the specified position in microseconds.

Parameters
`long positionUs`	The seek position in microseconds.

selectEmbeddedTrack

public ChunkSampleStream.EmbeddedSampleStream selectEmbeddedTrack(long positionUs, int trackType)

Selects the embedded track, returning a new EmbeddedSampleStream from which the track's samples can be consumed. release must be called on the returned stream when the track is no longer required, and before calling this method again to obtain another stream for the same track.

Parameters
`long positionUs`	The current playback position in microseconds.
`int trackType`	The type of the embedded track to enable.

Returns
`ChunkSampleStream.EmbeddedSampleStream`	The `EmbeddedSampleStream` for the embedded track.

skipData

public int skipData(long positionUs)

Attempts to skip to the keyframe before the specified position, or to the end of the stream if positionUs is beyond it.

Parameters
`long positionUs`	The specified time.

Returns
`int`	The number of samples that were skipped.

ChunkSampleStream

Summary

Nested types

Public fields

Public constructors

Public methods

Inherited Constants

Public fields

chunkSource

primaryTrackType

Public constructors

ChunkSampleStream

Public methods

consumeInitialDiscontinuity

continueLoading

discardBuffer

discardUpstreamSamplesForClippedDuration

getAdjustedSeekPositionUs

getBufferedPositionUs

getChunkSource

getNextLoadPositionUs

isLoading

isReady

maybeThrowError

onLoadCanceled

onLoadCompleted

onLoadError

onLoadStarted

onLoaderReleased

readData

reevaluateBuffer

release

release

seekToUs

selectEmbeddedTrack

skipData