ChunkSampleStream


@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

A SampleStream embedded in a ChunkSampleStream.

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,
    downloadExecutor: ReleasableExecutor?
)

Constructs an instance.

Public functions

Boolean

Consumes a pending initial discontinuity.

Boolean

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

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

Long

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

Boolean

Returns whether the loader is currently loading.

Boolean

Returns whether data is available to be read.

Unit

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

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

Releases the stream.

Unit

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.

Inherited Constants

From androidx.media3.exoplayer.source.SampleStream
const Int

Specifies that data, supplementalData and cryptoInfo should not be populated when reading a sample buffer.

const Int

Specifies that the read position should not be advanced if a sample buffer is read.

const Int

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,
    downloadExecutor: ReleasableExecutor?
)

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.

downloadExecutor: ReleasableExecutor?

An optional externally provided ReleasableExecutor for loading and extracting media.

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 primaryTrackTypeInt