SampleQueue

Artifact: androidx.media3:media3-exoplayer

Kotlin |Java

@UnstableApi
class SampleQueue : TrackOutput

A queue of media samples.

Summary

Nested types
`interface SampleQueue.UpstreamFormatChangedListener` A listener for changes to the upstream format.

Protected constructors
`SampleQueue( allocator: Allocator!, drmSessionManager: DrmSessionManager?, drmEventDispatcher: DrmSessionEventListener.EventDispatcher? )`

Public functions
`java-static SampleQueue!`	`createWithDrm( allocator: Allocator!, drmSessionManager: DrmSessionManager!, drmEventDispatcher: DrmSessionEventListener.EventDispatcher! )` Creates a sample queue with DRM resource management.
`java-static SampleQueue!`	`createWithDrm( allocator: Allocator!, playbackLooper: Looper!, drmSessionManager: DrmSessionManager!, drmEventDispatcher: DrmSessionEventListener.EventDispatcher! )` This function is deprecated. Use `createWithDrm` instead.
`java-static SampleQueue!`	`createWithoutDrm(allocator: Allocator!)` Creates a sample queue without DRM resource management.
`synchronized Long`	`discardSampleMetadataToRead()`
`Unit`	`discardTo(timeUs: Long, toKeyframe: Boolean, stopAtReadPosition: Boolean)` Discards up to but not including the sample immediately before or at the specified time.
`Unit`	`discardToEnd()` Discards all samples in the queue and advances the read position.
`Unit`	`discardToRead()` Discards up to but not including the read position.
`Unit`	`discardUpstreamFrom(timeUs: Long)` Discards samples from the write side of the queue.
`Unit`	`discardUpstreamSamples(discardFromIndex: Int)` Discards samples from the write side of the queue.
`Unit`	`format(format: Format!)` Called when the `Format` of the track has been extracted from the stream.
`Int`	`getFirstIndex()` Returns the current absolute start index.
`synchronized Long`	`getFirstTimestampUs()` Returns the timestamp of the first sample, or `MIN_VALUE` if the queue is empty.
`synchronized Long`	`getLargestReadTimestampUs()` Returns the largest sample timestamp that has been read since the last reset.
`Int`	`getReadIndex()` Returns the current absolute read index.
`synchronized Int`	`getSkipCount(timeUs: Long, allowEndOfQueue: Boolean)` Returns the number of samples that need to be `skipped` to advance the read position to the keyframe before or at the specified time.
`Int`	`getWriteIndex()` Returns the current absolute write index.
`synchronized Boolean`	`@CallSuper isReady(loadingFinished: Boolean)` Returns whether there is data available for reading.
`Unit`	`@CallSuper maybeThrowError()` Throws an error that's preventing data from being read.
`synchronized Long`	`peekSourceId()` Peeks the source id of the next sample to be read, or the current upstream source id if the queue is empty or if the read position is at the end of the queue.
`Unit`	`@CallSuper preRelease()` Calls `discardToEnd` and releases any resources owned by the queue.
`Int`	`@CallSuper read( formatHolder: FormatHolder!, buffer: DecoderInputBuffer!, @SampleStream.ReadFlags readFlags: Int, loadingFinished: Boolean )` Attempts to read from the queue.
`Unit`	`@CallSuper release()` Calls `reset(true)` and releases any resources owned by the queue.
`Unit`	`reset()` Convenience method for `reset(false)`.
`Unit`	`@CallSuper reset(resetUpstreamFormat: Boolean)` Clears all samples from the queue.
`Unit`	`sampleData( data: ParsableByteArray!, length: Int, @TrackOutput.SampleDataPart sampleDataPart: Int )` Called to write sample data to the output.
`Int`	`sampleData( input: DataReader!, length: Int, allowEndOfInput: Boolean, @TrackOutput.SampleDataPart sampleDataPart: Int )` Called to write sample data to the output.
`Unit`	`sampleMetadata( timeUs: Long, @C.BufferFlags flags: Int, size: Int, offset: Int, cryptoData: TrackOutput.CryptoData? )` Called when metadata associated with a sample has been extracted from the stream.
`synchronized Boolean`	`seekTo(sampleIndex: Int)` Attempts to seek the read position to the specified sample index.
`synchronized Boolean`	`seekTo(timeUs: Long, allowTimeBeyondBuffer: Boolean)` Attempts to seek the read position to the keyframe before or at the specified time.
`Unit`	`setSampleOffsetUs(sampleOffsetUs: Long)` Sets an offset that will be added to the timestamps (and sub-sample timestamps) of samples that are subsequently queued.
`Unit`	`setStartTimeUs(startTimeUs: Long)` Sets the start time for the queue.
`Unit`	`setUpstreamFormatChangeListener( listener: SampleQueue.UpstreamFormatChangedListener? )` Sets a listener to be notified of changes to the upstream format.
`synchronized Unit`	`skip(count: Int)` Advances the read position by the specified number of samples.
`Unit`	`sourceId(sourceId: Long)` Sets a source identifier for subsequent samples.
`Unit`	`splice()` Indicates samples that are subsequently queued should be spliced into those already queued.

Protected functions
`Format!`	`@CallSuper getAdjustedUpstreamFormat(format: Format!)` Adjusts the upstream `Format` (i.e., the `Format` that was most recently passed to `format`).
`Unit`	`invalidateUpstreamFormatAdjustment()` Invalidates the last upstream format adjustment.

Public properties
`Boolean`	`isLastSampleQueued`
`Long`	`largestQueuedTimestampUs`
`Format?`	`upstreamFormat`

Inherited Constants

From androidx.media3.extractor.TrackOutput

`const Int`	`SAMPLE_DATA_PART_ENCRYPTION = 1` Sample encryption data.
`const Int`	`SAMPLE_DATA_PART_MAIN = 0` Main media sample data.
`const Int`	`SAMPLE_DATA_PART_SUPPLEMENTAL = 2` Sample supplemental data.

Inherited functions

From androidx.media3.extractor.TrackOutput

`Unit`	`durationUs(durationUs: Long)` Called to set the duration of the track in microseconds.
`Unit`	`sampleData(data: ParsableByteArray!, length: Int)` Equivalent to `sampleData` sampleData(data, length, SAMPLE_DATA_PART_MAIN)}.
`Int`	`sampleData(input: DataReader!, length: Int, allowEndOfInput: Boolean)` Equivalent to `sampleData(input, length, allowEndOfInput, SAMPLE_DATA_PART_MAIN)`.

Protected constructors

SampleQueue

protected SampleQueue(
    allocator: Allocator!,
    drmSessionManager: DrmSessionManager?,
    drmEventDispatcher: DrmSessionEventListener.EventDispatcher?
)

Public functions

createWithDrm

java-static fun createWithDrm(
    allocator: Allocator!,
    drmSessionManager: DrmSessionManager!,
    drmEventDispatcher: DrmSessionEventListener.EventDispatcher!
): SampleQueue!

Creates a sample queue with DRM resource management.

For each sample added to the queue, a DrmSession will be attached containing the keys needed to decrypt it.

Parameters
`allocator: Allocator!`	An `Allocator` from which allocations for sample data can be obtained.
`drmSessionManager: DrmSessionManager!`	The `DrmSessionManager` to obtain `DrmSessions` from. The created instance does not take ownership of this `DrmSessionManager`.
`drmEventDispatcher: DrmSessionEventListener.EventDispatcher!`	A `DrmSessionEventListener.EventDispatcher` to notify of events related to this SampleQueue.

createWithDrm

java-static fun createWithDrm(
    allocator: Allocator!,
    playbackLooper: Looper!,
    drmSessionManager: DrmSessionManager!,
    drmEventDispatcher: DrmSessionEventListener.EventDispatcher!
): SampleQueue!

createWithoutDrm

java-static fun createWithoutDrm(allocator: Allocator!): SampleQueue!

Creates a sample queue without DRM resource management.

Parameters
`allocator: Allocator!`	An `Allocator` from which allocations for sample data can be obtained.

discardSampleMetadataToRead

synchronized fun discardSampleMetadataToRead(): Long

discardTo

fun discardTo(timeUs: Long, toKeyframe: Boolean, stopAtReadPosition: Boolean): Unit

Discards up to but not including the sample immediately before or at the specified time.

Parameters
`timeUs: Long`	The time to discard up to.
`toKeyframe: Boolean`	If true then discards samples up to the keyframe before or at the specified time, rather than any sample before or at that time.
`stopAtReadPosition: Boolean`	If true then samples are only discarded if they're before the read position. If false then samples at and beyond the read position may be discarded, in which case the read position is advanced to the first remaining sample.

discardToEnd

fun discardToEnd(): Unit

Discards all samples in the queue and advances the read position.

discardToRead

fun discardToRead(): Unit

Discards up to but not including the read position.

discardUpstreamFrom

fun discardUpstreamFrom(timeUs: Long): Unit

Discards samples from the write side of the queue.

Parameters
`timeUs: Long`	Samples will be discarded from the write end of the queue until a sample with a timestamp smaller than timeUs is encountered (this sample is not discarded). Must be larger than `getLargestReadTimestampUs`.

discardUpstreamSamples

fun discardUpstreamSamples(discardFromIndex: Int): Unit

Discards samples from the write side of the queue.

Parameters
`discardFromIndex: Int`	The absolute index of the first sample to be discarded. Must be in the range [`getReadIndex`, `getWriteIndex`].

format

fun format(format: Format!): Unit

Called when the Format of the track has been extracted from the stream.

Parameters
`format: Format!`	The extracted `Format`.

getFirstIndex

fun getFirstIndex(): Int

Returns the current absolute start index.

getFirstTimestampUs

synchronized fun getFirstTimestampUs(): Long

Returns the timestamp of the first sample, or MIN_VALUE if the queue is empty.

getLargestReadTimestampUs

synchronized fun getLargestReadTimestampUs(): Long

Returns the largest sample timestamp that has been read since the last reset.

Returns
`Long`	The largest sample timestamp that has been read, or `MIN_VALUE` if no samples have been read.

getReadIndex

fun getReadIndex(): Int

Returns the current absolute read index.

getSkipCount

synchronized fun getSkipCount(timeUs: Long, allowEndOfQueue: Boolean): Int

Returns the number of samples that need to be skipped to advance the read position to the keyframe before or at the specified time.

Parameters
`timeUs: Long`	The time to advance to.
`allowEndOfQueue: Boolean`	Whether the end of the queue is considered a keyframe when `timeUs` is larger than the largest queued timestamp.

Returns
`Int`	The number of samples that need to be skipped, which may be equal to 0.

getWriteIndex

fun getWriteIndex(): Int

Returns the current absolute write index.

isReady

@CallSuper
synchronized fun isReady(loadingFinished: Boolean): Boolean

Returns whether there is data available for reading.

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

Parameters
`loadingFinished: Boolean`	Whether no more samples will be written to the sample queue. When true, this method returns true if the sample queue is empty, because an empty sample queue means the end of stream has been reached. When false, this method returns false if the sample queue is empty.

maybeThrowError

@CallSuper
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.

peekSourceId

synchronized fun peekSourceId(): Long

Peeks the source id of the next sample to be read, or the current upstream source id if the queue is empty or if the read position is at the end of the queue.

Returns
`Long`	The source id.

preRelease

@CallSuper
fun preRelease(): Unit

Calls discardToEnd and releases any resources owned by the queue.

read

@CallSuper
fun read(
    formatHolder: FormatHolder!,
    buffer: DecoderInputBuffer!,
    @SampleStream.ReadFlags readFlags: Int,
    loadingFinished: Boolean
): Int

Attempts to read from the queue.

Formats read from this method may be associated to a DrmSession through drmSession.

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.
`loadingFinished: Boolean`	True if an empty queue should be considered the end of the stream.

Returns
`Int`	The result, which can be `RESULT_NOTHING_READ`, `RESULT_FORMAT_READ` or `RESULT_BUFFER_READ`.

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.

release

@CallSuper
fun release(): Unit

Calls reset(true) and releases any resources owned by the queue.

reset

fun reset(): Unit

Convenience method for reset(false).

reset

@CallSuper
fun reset(resetUpstreamFormat: Boolean): Unit

Clears all samples from the queue.

Parameters
`resetUpstreamFormat: Boolean`	Whether the upstream format should be cleared. If set to false, samples queued after the reset (and before a subsequent call to `format`) are assumed to have the current upstream format. If set to true, `format` must be called after the reset before any more samples can be queued.

sampleData

fun sampleData(
    data: ParsableByteArray!,
    length: Int,
    @TrackOutput.SampleDataPart sampleDataPart: Int
): Unit

Called to write sample data to the output.

Parameters
`data: ParsableByteArray!`	A `ParsableByteArray` from which to read the sample data.
`length: Int`	The number of bytes to read, starting from `data.getPosition()`.
`@TrackOutput.SampleDataPart sampleDataPart: Int`	The part of the sample data to which this call corresponds.

sampleData

fun sampleData(
    input: DataReader!,
    length: Int,
    allowEndOfInput: Boolean,
    @TrackOutput.SampleDataPart sampleDataPart: Int
): Int

Called to write sample data to the output.

Parameters
`input: DataReader!`	A `DataReader` from which to read the sample data.
`length: Int`	The maximum length to read from the input.
`allowEndOfInput: Boolean`	True if encountering the end of the input having read no data is allowed, and should result in `RESULT_END_OF_INPUT` being returned. False if it should be considered an error, causing an `EOFException` to be thrown.
`@TrackOutput.SampleDataPart sampleDataPart: Int`	The part of the sample data to which this call corresponds.

Returns
`Int`	The number of bytes appended.

Throws
`java.io.IOException`	If an error occurred reading from the input.

sampleMetadata

fun sampleMetadata(
    timeUs: Long,
    @C.BufferFlags flags: Int,
    size: Int,
    offset: Int,
    cryptoData: TrackOutput.CryptoData?
): Unit

Called when metadata associated with a sample has been extracted from the stream.

The corresponding sample data will have already been passed to the output via calls to sampleData or sampleData.

Parameters
`timeUs: Long`	The media timestamp associated with the sample, in microseconds.
`@C.BufferFlags flags: Int`	Flags associated with the sample. See `C.BUFFER_FLAG_*`.
`size: Int`	The size of the sample data, in bytes.
`offset: Int`	The number of bytes that have been passed to `sampleData` or `sampleData` since the last byte belonging to the sample whose metadata is being passed.
`cryptoData: TrackOutput.CryptoData?`	The encryption data required to decrypt the sample. May be null.

seekTo

synchronized fun seekTo(sampleIndex: Int): Boolean

Attempts to seek the read position to the specified sample index.

Parameters
`sampleIndex: Int`	The sample index.

Returns
`Boolean`	Whether the seek was successful.

seekTo

synchronized fun seekTo(timeUs: Long, allowTimeBeyondBuffer: Boolean): Boolean

Attempts to seek the read position to the keyframe before or at the specified time.

For formats where all samples are sync samples, it seeks the read position to the first sample at or after the specified time.

Parameters
`timeUs: Long`	The time to seek to.
`allowTimeBeyondBuffer: Boolean`	Whether the operation can succeed if `timeUs` is beyond the end of the queue, by seeking to the last sample (or keyframe).

Returns
`Boolean`	Whether the seek was successful.

setSampleOffsetUs

fun setSampleOffsetUs(sampleOffsetUs: Long): Unit

Sets an offset that will be added to the timestamps (and sub-sample timestamps) of samples that are subsequently queued.

Parameters
`sampleOffsetUs: Long`	The timestamp offset in microseconds.

setStartTimeUs

fun setStartTimeUs(startTimeUs: Long): Unit

Sets the start time for the queue. Samples with earlier timestamps will be discarded if all samples are sync samples in the given input format.

Parameters
`startTimeUs: Long`	The start time, in microseconds.

setUpstreamFormatChangeListener

fun setUpstreamFormatChangeListener(
    listener: SampleQueue.UpstreamFormatChangedListener?
): Unit

Sets a listener to be notified of changes to the upstream format.

Parameters
`listener: SampleQueue.UpstreamFormatChangedListener?`	The listener.

skip

synchronized fun skip(count: Int): Unit

Advances the read position by the specified number of samples.

Parameters
`count: Int`	The number of samples to advance the read position by. Must be at least 0 and at most `getWriteIndex` - `getReadIndex`.

sourceId

fun sourceId(sourceId: Long): Unit

Sets a source identifier for subsequent samples.

Parameters
`sourceId: Long`	The source identifier.

splice

fun splice(): Unit

Indicates samples that are subsequently queued should be spliced into those already queued.

Protected functions

getAdjustedUpstreamFormat

@CallSuper
protected fun getAdjustedUpstreamFormat(format: Format!): Format!

Adjusts the upstream Format (i.e., the Format that was most recently passed to format).

The default implementation incorporates the sample offset passed to setSampleOffsetUs into subsampleOffsetUs.

Parameters
`format: Format!`	The `Format` to adjust.

Returns
`Format!`	The adjusted `Format`.

invalidateUpstreamFormatAdjustment

protected fun invalidateUpstreamFormatAdjustment(): Unit

Invalidates the last upstream format adjustment. getAdjustedUpstreamFormat will be called to adjust the upstream Format again before the next sample is queued.

Public properties

isLastSampleQueued

val isLastSampleQueued: Boolean

largestQueuedTimestampUs

val largestQueuedTimestampUs: Long

upstreamFormat

val upstreamFormat: Format?

SampleQueue

Summary

Nested types

Protected constructors

Public functions

Protected functions

Public properties

Inherited Constants

Inherited functions

Protected constructors

SampleQueue

Public functions

createWithDrm

createWithDrm

createWithoutDrm

discardSampleMetadataToRead

discardTo

discardToEnd

discardToRead

discardUpstreamFrom

discardUpstreamSamples

format

getFirstIndex

getFirstTimestampUs

getLargestReadTimestampUs

getReadIndex

getSkipCount

getWriteIndex

isReady

maybeThrowError

peekSourceId

preRelease

read

release

reset

reset

sampleData

sampleData

sampleMetadata

seekTo

seekTo

setSampleOffsetUs

setStartTimeUs

setUpstreamFormatChangeListener

skip

sourceId

splice

Protected functions

getAdjustedUpstreamFormat

invalidateUpstreamFormatAdjustment

Public properties

isLastSampleQueued

largestQueuedTimestampUs

upstreamFormat