@UnstableApi
interface SampleStream

Known direct subclasses
ChunkSampleStream.EmbeddedSampleStream

A SampleStream embedded in a ChunkSampleStream.
ChunkSampleStream

A SampleStream that loads media in Chunks, 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(flag = true, value = )
annotation SampleStream.Flags

Flags that can be specified on the stream.

Return values of readData.
@Documented
@Retention(value = RetentionPolicy.SOURCE)
@Target(value = ElementType.TYPE_USE)
@IntDef(flag = true, value = )
annotation SampleStream.ReadFlags

Flags that can be specified when calling readData.

Constants
const Int

Specifies that the stream contains a preroll of decode-only samples.
const Int

Specifies that the stream may contain preroll samples.
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.
const Int

Specifies that playout of the stream should be stopped once the duration is reached.

Public functions
Int

Returns the Flags set on this stream.
Boolean

Returns whether data is available to be read.
Unit

Throws an error that's preventing data from being read.
Int
@SampleStream.ReadDataResult
readData(
    formatHolder: FormatHolder!,
    buffer: DecoderInputBuffer!,
    @SampleStream.ReadFlags readFlags: Int
)

Attempts to read from the stream.
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.

Constants

FLAG_HAS_PREROLL

const val FLAG_HAS_PREROLL = 4: Int

Specifies that the stream contains a preroll of decode-only samples.

FLAG_MAYBE_HAS_PREROLL

const val FLAG_MAYBE_HAS_PREROLL = 2: Int

Specifies that the stream may contain preroll samples.

A stream must resolve itself eventually to either not have this flag or have FLAG_HAS_PREROLL.

FLAG_OMIT_SAMPLE_DATA

const val FLAG_OMIT_SAMPLE_DATA = 4: Int

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

const val FLAG_PEEK = 1: Int

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

FLAG_REQUIRE_FORMAT

const val FLAG_REQUIRE_FORMAT = 2: Int

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.

FLAG_STRICT_DURATION

const val FLAG_STRICT_DURATION = 1: Int

Specifies that playout of the stream should be stopped once the duration is reached.

Public functions

getFlags

@SampleStream.Flags
fun getFlags(): Int

Returns the Flags set on this stream.

The value returned by this method is allowed to change during playback. Callers should check the flags when needed.

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.

readData

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

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.