SampleStream

Artifact: androidx.media3:media3-exoplayer

Kotlin |Java

@UnstableApi
public interface SampleStream

Known direct subclasses

ChunkSampleStream.EmbeddedSampleStream, ChunkSampleStream, EmptySampleStream, FakeSampleStream

`ChunkSampleStream.EmbeddedSampleStream`	A `SampleStream` embedded in a `ChunkSampleStream`.
`ChunkSampleStream`	A `SampleStream` that loads media in `Chunk`s, obtained from a `ChunkSource`.
`EmptySampleStream`	An empty `SampleStream`.
`FakeSampleStream`	Fake `SampleStream` that outputs a given `Format` and any amount of `items`.

A stream of media samples (and associated format information).

Summary

Nested types
`@Documented @Retention(value = RetentionPolicy.SOURCE) @Target(value = ElementType.TYPE_USE) @IntDef(value = [C.RESULT_NOTHING_READ, C.RESULT_FORMAT_READ, C.RESULT_BUFFER_READ]) public annotation SampleStream.ReadDataResult` Return values of `readData`.
`@Documented @Retention(value = RetentionPolicy.SOURCE) @Target(value = ElementType.TYPE_USE) @IntDef(flag = true, value = ) public annotation SampleStream.ReadFlags` Flags that can be specified when calling `readData`.

Constants
`default static final int`	`FLAG_OMIT_SAMPLE_DATA = 4` Specifies that `data`, `supplementalData` and `cryptoInfo` should not be populated when reading a sample buffer.
`default static final int`	`FLAG_PEEK = 1` Specifies that the read position should not be advanced if a sample buffer is read.
`default 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 methods
`abstract boolean`	`isReady()` Returns whether data is available to be read.
`abstract void`	`maybeThrowError()` Throws an error that's preventing data from being read.
`abstract int`	`@SampleStream.ReadDataResult readData( FormatHolder formatHolder, DecoderInputBuffer buffer, @SampleStream.ReadFlags int readFlags )` Attempts to read from the stream.
`abstract 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.

Constants

FLAG_OMIT_SAMPLE_DATA

default static final int FLAG_OMIT_SAMPLE_DATA = 4

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

This flag is useful for efficiently reading or (when combined with FLAG_PEEK) peeking sample metadata. It can also be used for efficiency by a caller wishing to skip a sample buffer.

FLAG_PEEK

default static final int FLAG_PEEK = 1

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

FLAG_REQUIRE_FORMAT

default 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. In detail, the effect of this flag is as follows:

If a sample buffer would be read were the flag not set, then the stream format will be read instead.
If nothing would be read were the flag not set, then the stream format will be read if it's known. If the stream format is not known then behavior is unchanged.
If an end of stream buffer would be read were the flag not set, then behavior is unchanged.

Public methods

isReady

abstract 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

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

readData

@SampleStream.ReadDataResult
abstract 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.

skipData

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

SampleStream

Summary

Nested types

Constants

Public methods

Constants

FLAG_OMIT_SAMPLE_DATA

FLAG_PEEK

FLAG_REQUIRE_FORMAT

Public methods

isReady

maybeThrowError

readData

skipData