ChunkSampleStream

Artifact: androidx.media3:media3-exoplayer

Kotlin |Java

@UnstableApi
class ChunkSampleStream<T : ChunkSource?> : 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
`inner class ChunkSampleStream.EmbeddedSampleStream : SampleStream` A `SampleStream` embedded in a `ChunkSampleStream`.
`interface ChunkSampleStream.ReleaseCallback<T : ChunkSource?>` A callback to be notified when a sample stream has finished being released.

Public constructors
ChunkSampleStream( @C.TrackType primaryTrackType: Int, embeddedTrackTypes: IntArray?, embeddedTrackFormats: Array<Format!>?, chunkSource: T!, callback: SequenceableLoader.Callback<ChunkSampleStream<T!>!>!, allocator: Allocator!, positionUs: Long, drmSessionManager: DrmSessionManager!, drmEventDispatcher: DrmSessionEventListener.EventDispatcher!, loadErrorHandlingPolicy: LoadErrorHandlingPolicy!, mediaSourceEventDispatcher: MediaSourceEventListener.EventDispatcher!, canReportInitialDiscontinuity: Boolean ) Constructs an instance.

Public constructors

ChunkSampleStream(
    @C.TrackType primaryTrackType: Int,
    embeddedTrackTypes: IntArray?,
    embeddedTrackFormats: Array<Format!>?,
    chunkSource: T!,
    callback: SequenceableLoader.Callback<ChunkSampleStream<T!>!>!,
    allocator: Allocator!,
    positionUs: Long,
    drmSessionManager: DrmSessionManager!,
    drmEventDispatcher: DrmSessionEventListener.EventDispatcher!,
    loadErrorHandlingPolicy: LoadErrorHandlingPolicy!,
    mediaSourceEventDispatcher: MediaSourceEventListener.EventDispatcher!,
    canReportInitialDiscontinuity: Boolean
)

Constructs an instance.

Public functions
`Boolean`	`consumeInitialDiscontinuity()` Consumes a pending initial discontinuity.
`Boolean`	`continueLoading(loadingInfo: LoadingInfo!)` Attempts to continue loading.
`Unit`	`discardBuffer(positionUs: Long, toKeyframe: Boolean)` Discards buffered media up to the specified position.
`Long`	`getAdjustedSeekPositionUs( positionUs: Long, seekParameters: SeekParameters! )` Adjusts a seek position given the specified `SeekParameters`.
`Long`	`getBufferedPositionUs()` Returns an estimate of the position up to which data is buffered.
`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.
`Unit`	`maybeThrowError()` Throws an error that's preventing data from being read.
`Unit`	`onLoadCanceled( loadable: Chunk!, elapsedRealtimeMs: Long, loadDurationMs: Long, released: Boolean )` Called when a load has been canceled.
`Unit`	`onLoadCompleted( loadable: Chunk!, elapsedRealtimeMs: Long, loadDurationMs: Long )` Called when a load has completed.
`Loader.LoadErrorAction!`	`onLoadError( loadable: Chunk!, elapsedRealtimeMs: Long, loadDurationMs: Long, error: IOException!, errorCount: Int )` Called when a load encounters an error.
`Unit`	`onLoaderReleased()` Called when the `Loader` has finished being released.
`Int`	`readData( formatHolder: FormatHolder!, buffer: DecoderInputBuffer!, @SampleStream.ReadFlags readFlags: Int )` Attempts to read from the stream.
`Unit`	`reevaluateBuffer(positionUs: Long)` Re-evaluates the buffer given the playback position.
`Unit`	`release()` Releases the stream.
`Unit`	`release(callback: ChunkSampleStream.ReleaseCallback<T!>?)` Releases the stream.
`Unit`	`seekToUs(positionUs: Long)` Seeks to the specified position in microseconds.
`ChunkSampleStream.EmbeddedSampleStream!`	`selectEmbeddedTrack(positionUs: Long, trackType: Int)` Selects the embedded track, returning a new `EmbeddedSampleStream` from which the track's samples can be consumed.
`Int`	`skipData(positionUs: Long)` Attempts to skip to the keyframe before the specified position, or to the end of the stream if `positionUs` is beyond it.

Public properties
`T!`	`chunkSource`
`Int`	`@C.TrackType primaryTrackType`

Inherited Constants

From androidx.media3.exoplayer.source.SampleStream

`const Int`	`FLAG_OMIT_SAMPLE_DATA = 4` Specifies that `data`, `supplementalData` and `cryptoInfo` should not be populated when reading a sample buffer.
`const Int`	`FLAG_PEEK = 1` Specifies that the read position should not be advanced if a sample buffer is read.
`const 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.

Inherited functions

From androidx.media3.exoplayer.upstream.Loader.Callback

Unit

onLoadStarted(
    loadable: T!,
    elapsedRealtimeMs: Long,
    loadDurationMs: Long,
    retryCount: Int
)

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

Public constructors

ChunkSampleStream

ChunkSampleStream(
    @C.TrackType primaryTrackType: Int,
    embeddedTrackTypes: IntArray?,
    embeddedTrackFormats: Array<Format!>?,
    chunkSource: T!,
    callback: SequenceableLoader.Callback<ChunkSampleStream<T!>!>!,
    allocator: Allocator!,
    positionUs: Long,
    drmSessionManager: DrmSessionManager!,
    drmEventDispatcher: DrmSessionEventListener.EventDispatcher!,
    loadErrorHandlingPolicy: LoadErrorHandlingPolicy!,
    mediaSourceEventDispatcher: MediaSourceEventListener.EventDispatcher!,
    canReportInitialDiscontinuity: Boolean
)

Constructs an instance.

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

Public functions

consumeInitialDiscontinuity

fun consumeInitialDiscontinuity(): Boolean

Consumes a pending initial discontinuity.

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

continueLoading

fun continueLoading(loadingInfo: LoadingInfo!): Boolean

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

fun discardBuffer(positionUs: Long, toKeyframe: Boolean): Unit

Discards buffered media up to the specified position.

Parameters
`positionUs: Long`	The position to discard up to, in microseconds.
`toKeyframe: Boolean`	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

fun getAdjustedSeekPositionUs(
    positionUs: Long,
    seekParameters: SeekParameters!
): Long

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

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

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

getBufferedPositionUs

fun getBufferedPositionUs(): Long

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.

getNextLoadPositionUs

fun getNextLoadPositionUs(): Long

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

isLoading

fun isLoading(): Boolean

Returns whether the loader is currently loading.

isReady

fun isReady(): Boolean

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

fun maybeThrowError(): Unit

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

fun onLoadCanceled(
    loadable: Chunk!,
    elapsedRealtimeMs: Long,
    loadDurationMs: Long,
    released: Boolean
): Unit

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 has been released then this callback may be called before load exits.

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

onLoadCompleted

fun onLoadCompleted(
    loadable: Chunk!,
    elapsedRealtimeMs: Long,
    loadDurationMs: Long
): Unit

Called when a load has completed.

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

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

onLoadError

fun onLoadError(
    loadable: Chunk!,
    elapsedRealtimeMs: Long,
    loadDurationMs: Long,
    error: IOException!,
    errorCount: Int
): Loader.LoadErrorAction!

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
`loadable: Chunk!`	The loadable whose load has encountered an error.
`elapsedRealtimeMs: Long`	`elapsedRealtime` when the error occurred.
`loadDurationMs: Long`	The duration in milliseconds of the load since `startLoading` was called up to the point at which the error occurred.
`error: IOException!`	The load error.
`errorCount: Int`	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`.

onLoaderReleased

fun onLoaderReleased(): Unit

Called when the Loader has finished being released.

readData

fun readData(
    formatHolder: FormatHolder!,
    buffer: DecoderInputBuffer!,
    @SampleStream.ReadFlags readFlags: Int
): Int

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.
`buffer: DecoderInputBuffer!`	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 readFlags: Int`	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

fun reevaluateBuffer(positionUs: Long): Unit

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
`positionUs: Long`	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

fun release(): Unit

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

fun release(callback: ChunkSampleStream.ReleaseCallback<T!>?): Unit

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
`callback: ChunkSampleStream.ReleaseCallback<T!>?`	An optional callback to be called on the loading thread once the loader has been released.

seekToUs

fun seekToUs(positionUs: Long): Unit

Seeks to the specified position in microseconds.

Parameters
`positionUs: Long`	The seek position in microseconds.

selectEmbeddedTrack

fun selectEmbeddedTrack(positionUs: Long, trackType: Int): ChunkSampleStream.EmbeddedSampleStream!

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
`positionUs: Long`	The current playback position in microseconds.
`trackType: Int`	The type of the embedded track to enable.

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

skipData

fun skipData(positionUs: Long): Int

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

Parameters
`positionUs: Long`	The specified time.

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

Public properties

chunkSource

val chunkSource: T!

primaryTrackType

@C.TrackType
val primaryTrackType: Int

ChunkSampleStream

Summary

Nested types

Public constructors

Public functions

Public properties

Inherited Constants

Inherited functions

Public constructors

ChunkSampleStream

Public functions

consumeInitialDiscontinuity

continueLoading

discardBuffer

getAdjustedSeekPositionUs

getBufferedPositionUs

getNextLoadPositionUs

isLoading

isReady

maybeThrowError

onLoadCanceled

onLoadCompleted

onLoadError

onLoaderReleased

readData

reevaluateBuffer

release

release

seekToUs

selectEmbeddedTrack

skipData

Public properties

chunkSource

primaryTrackType