@UnstableApi
public class SampleQueue implements TrackOutput

A queue of media samples.

Summary

Nested types

A listener for changes to the upstream format.

Public fields
boolean
long
@Nullable Format

Protected constructors
SampleQueue(
    Allocator allocator,
    @Nullable DrmSessionManager drmSessionManager,
    @Nullable DrmSessionEventListener.EventDispatcher drmEventDispatcher
)

Public methods
static SampleQueue
createWithDrm(
    Allocator allocator,
    DrmSessionManager drmSessionManager,
    DrmSessionEventListener.EventDispatcher drmEventDispatcher
)

Creates a sample queue with DRM resource management.
static SampleQueue
createWithDrm(
    Allocator allocator,
    Looper playbackLooper,
    DrmSessionManager drmSessionManager,
    DrmSessionEventListener.EventDispatcher drmEventDispatcher
)

This method is deprecated.

Use createWithDrm instead.
static SampleQueue

Creates a sample queue without DRM resource management.
synchronized long
final void
discardTo(long timeUs, boolean toKeyframe, boolean stopAtReadPosition)

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

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

Discards up to but not including the read position.
final void
discardUpstreamFrom(long timeUs)

Discards samples from the write side of the queue.
final void
discardUpstreamSamples(int discardFromIndex)

Discards samples from the write side of the queue.
final void
format(Format format)

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

Returns the current absolute start index.
synchronized final long

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

Returns the largest sample timestamp that has been queued since the last reset.
synchronized final long

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

Returns the current absolute read index.
synchronized final int
getSkipCount(long timeUs, boolean allowEndOfQueue)

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

Returns the upstream Format in which samples are being queued.
final int

Returns the current absolute write index.
synchronized final boolean

Returns whether the last sample of the stream has knowingly been queued.
synchronized boolean
@CallSuper
isReady(boolean loadingFinished)

Returns whether there is data available for reading.
void

Throws an error that's preventing data from being read.
synchronized final 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.
void

Calls discardToEnd and releases any resources owned by the queue.
int
@CallSuper
read(
    FormatHolder formatHolder,
    DecoderInputBuffer buffer,
    @SampleStream.ReadFlags int readFlags,
    boolean loadingFinished
)

Attempts to read from the queue.
void

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

Convenience method for reset(false).
void
@CallSuper
reset(boolean resetUpstreamFormat)

Clears all samples from the queue.
final void
sampleData(
    ParsableByteArray data,
    int length,
    @TrackOutput.SampleDataPart int sampleDataPart
)

Called to write sample data to the output.
final int
sampleData(
    DataReader input,
    int length,
    boolean allowEndOfInput,
    @TrackOutput.SampleDataPart int sampleDataPart
)

Called to write sample data to the output.
void
sampleMetadata(
    long timeUs,
    @C.BufferFlags int flags,
    int size,
    int offset,
    @Nullable TrackOutput.CryptoData cryptoData
)

Called when metadata associated with a sample has been extracted from the stream.
synchronized final boolean
seekTo(int sampleIndex)

Attempts to seek the read position to the specified sample index.
synchronized final boolean
seekTo(long timeUs, boolean allowTimeBeyondBuffer)

Attempts to seek the read position to the keyframe before or at the specified time.
final void
setSampleOffsetUs(long sampleOffsetUs)

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

Sets the start time for the queue.
final void

Sets a listener to be notified of changes to the upstream format.
synchronized final void
skip(int count)

Advances the read position by the specified number of samples.
final void
sourceId(long sourceId)

Sets a source identifier for subsequent samples.
final void

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

Protected methods
Format

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

Invalidates the last upstream format adjustment.

Inherited Constants
From androidx.media3.extractor.TrackOutput
static final int

Sample encryption data.
static final int

Main media sample data.
static final int

Sample supplemental data.

Inherited methods
From androidx.media3.extractor.TrackOutput
void
sampleData(ParsableByteArray data, int length)

Equivalent to sampleData sampleData(data, length, SAMPLE_DATA_PART_MAIN)}.
int
sampleData(DataReader input, int length, boolean allowEndOfInput)

Equivalent to sampleData(input, length, allowEndOfInput, SAMPLE_DATA_PART_MAIN).

Public fields

isLastSampleQueued

public boolean isLastSampleQueued

largestQueuedTimestampUs

public long largestQueuedTimestampUs

upstreamFormat

public @Nullable Format upstreamFormat

Protected constructors

SampleQueue

protected SampleQueue(
    Allocator allocator,
    @Nullable DrmSessionManager drmSessionManager,
    @Nullable DrmSessionEventListener.EventDispatcher drmEventDispatcher
)

Public methods

createWithDrm

public static SampleQueue createWithDrm(
    Allocator allocator,
    DrmSessionManager drmSessionManager,
    DrmSessionEventListener.EventDispatcher drmEventDispatcher
)

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.
DrmSessionEventListener.EventDispatcher drmEventDispatcher

A DrmSessionEventListener.EventDispatcher to notify of events related to this SampleQueue.

createWithDrm

public static SampleQueue createWithDrm(
    Allocator allocator,
    Looper playbackLooper,
    DrmSessionManager drmSessionManager,
    DrmSessionEventListener.EventDispatcher drmEventDispatcher
)

createWithoutDrm

public static SampleQueue createWithoutDrm(Allocator allocator)

Creates a sample queue without DRM resource management.

Parameters
Allocator allocator

An Allocator from which allocations for sample data can be obtained.

discardSampleMetadataToRead

synchronized public long discardSampleMetadataToRead()

discardTo

public final void discardTo(long timeUs, boolean toKeyframe, boolean stopAtReadPosition)

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

Parameters
long timeUs

The time to discard up to.
boolean toKeyframe

If true then discards samples up to the keyframe before or at the specified time, rather than any sample before or at that time.
boolean stopAtReadPosition

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

public final void discardToEnd()

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

discardToRead

public final void discardToRead()

Discards up to but not including the read position.

discardUpstreamFrom

public final void discardUpstreamFrom(long timeUs)

Discards samples from the write side of the queue.

Parameters
long timeUs

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

public final void discardUpstreamSamples(int discardFromIndex)

Discards samples from the write side of the queue.

Parameters
int discardFromIndex

The absolute index of the first sample to be discarded. Must be in the range [getReadIndex, getWriteIndex].

format

public final void format(Format format)

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

Parameters
Format format

The extracted Format.

getFirstIndex

public final int getFirstIndex()

Returns the current absolute start index.

getFirstTimestampUs

synchronized public final long getFirstTimestampUs()

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

getLargestQueuedTimestampUs

synchronized public final long getLargestQueuedTimestampUs()

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

Samples that were discarded by calling discardUpstreamSamples are not considered as having been queued. Samples that were dequeued from the front of the queue are considered as having been queued.

Returns
long

The largest sample timestamp that has been queued, or MIN_VALUE if no samples have been queued.

getLargestReadTimestampUs

synchronized public final long getLargestReadTimestampUs()

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

public final int getReadIndex()

Returns the current absolute read index.

getSkipCount

synchronized public final int getSkipCount(long timeUs, boolean allowEndOfQueue)

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
long timeUs

The time to advance to.
boolean allowEndOfQueue

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.

getUpstreamFormat

synchronized public final @Nullable Format getUpstreamFormat()

Returns the upstream Format in which samples are being queued.

getWriteIndex

public final int getWriteIndex()

Returns the current absolute write index.

isLastSampleQueued

synchronized public final boolean isLastSampleQueued()

Returns whether the last sample of the stream has knowingly been queued. A return value of false means that the last sample had not been queued or that it's unknown whether the last sample has been queued.

Samples that were discarded by calling discardUpstreamSamples are not considered as having been queued. Samples that were dequeued from the front of the queue are considered as having been queued.

isReady

@CallSuper
synchronized public boolean isReady(boolean loadingFinished)

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
boolean loadingFinished

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

peekSourceId

synchronized public final 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.

Returns
long

The source id.

preRelease

@CallSuper
public void preRelease()

Calls discardToEnd and releases any resources owned by the queue.

read

@CallSuper
public int read(
    FormatHolder formatHolder,
    DecoderInputBuffer buffer,
    @SampleStream.ReadFlags int readFlags,
    boolean loadingFinished
)

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.
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.
boolean loadingFinished

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
public void release()

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

reset

public final void reset()

Convenience method for reset(false).

reset

@CallSuper
public void reset(boolean resetUpstreamFormat)

Clears all samples from the queue.

Parameters
boolean resetUpstreamFormat

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

public final void sampleData(
    ParsableByteArray data,
    int length,
    @TrackOutput.SampleDataPart int sampleDataPart
)

Called to write sample data to the output.

Parameters
ParsableByteArray data

A ParsableByteArray from which to read the sample data.
int length

The number of bytes to read, starting from data.getPosition().
@TrackOutput.SampleDataPart int sampleDataPart

The part of the sample data to which this call corresponds.

sampleData

public final int sampleData(
    DataReader input,
    int length,
    boolean allowEndOfInput,
    @TrackOutput.SampleDataPart int sampleDataPart
)

Called to write sample data to the output.

Parameters
DataReader input

A DataReader from which to read the sample data.
int length

The maximum length to read from the input.
boolean allowEndOfInput

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 int sampleDataPart

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

public void sampleMetadata(
    long timeUs,
    @C.BufferFlags int flags,
    int size,
    int offset,
    @Nullable TrackOutput.CryptoData cryptoData
)

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
long timeUs

The media timestamp associated with the sample, in microseconds.
@C.BufferFlags int flags

Flags associated with the sample. See C.BUFFER_FLAG_*.
int size

The size of the sample data, in bytes.
int offset

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.
@Nullable TrackOutput.CryptoData cryptoData

The encryption data required to decrypt the sample. May be null.

seekTo

synchronized public final boolean seekTo(int sampleIndex)

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

Parameters
int sampleIndex

The sample index.
Returns
boolean

Whether the seek was successful.

seekTo

synchronized public final boolean seekTo(long timeUs, boolean allowTimeBeyondBuffer)

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
long timeUs

The time to seek to.
boolean allowTimeBeyondBuffer

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

public final void setSampleOffsetUs(long sampleOffsetUs)

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

Parameters
long sampleOffsetUs

The timestamp offset in microseconds.

setStartTimeUs

public final void setStartTimeUs(long startTimeUs)

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
long startTimeUs

The start time, in microseconds.

setUpstreamFormatChangeListener

public final void setUpstreamFormatChangeListener(
    @Nullable SampleQueue.UpstreamFormatChangedListener listener
)

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

Parameters
@Nullable SampleQueue.UpstreamFormatChangedListener listener

The listener.

skip

synchronized public final void skip(int count)

Advances the read position by the specified number of samples.

Parameters
int count

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

sourceId

public final void sourceId(long sourceId)

Sets a source identifier for subsequent samples.

Parameters
long sourceId

The source identifier.

splice

public final void splice()

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

Protected methods

getAdjustedUpstreamFormat

@CallSuper
protected Format getAdjustedUpstreamFormat(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 final void invalidateUpstreamFormatAdjustment()

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