# SampleStream

Artifact: [androidx.media3:media3-exoplayer](https://developer.android.com/jetpack/androidx/releases/media3) [View Source](https://cs.android.com/search?q=file:androidx/media3/exoplayer/source/SampleStream.java+class:androidx.media3.exoplayer.source.SampleStream)

*** ** * ** ***


```
@UnstableApi
public interface SampleStream
```

<br />

Known direct subclasses [ChunkSampleStream.EmbeddedSampleStream](https://developer.android.com/reference/androidx/media3/exoplayer/source/chunk/ChunkSampleStream.EmbeddedSampleStream), [ChunkSampleStream](https://developer.android.com/reference/androidx/media3/exoplayer/source/chunk/ChunkSampleStream), [EmptySampleStream](https://developer.android.com/reference/androidx/media3/exoplayer/source/EmptySampleStream), [FakeSampleStream](https://developer.android.com/reference/androidx/media3/test/utils/FakeSampleStream)

|---|---|
| `https://developer.android.com/reference/androidx/media3/exoplayer/source/chunk/ChunkSampleStream.EmbeddedSampleStream` | A `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream` embedded in a `https://developer.android.com/reference/androidx/media3/exoplayer/source/chunk/ChunkSampleStream`. |
| `https://developer.android.com/reference/androidx/media3/exoplayer/source/chunk/ChunkSampleStream` | A `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream` that loads media in `https://developer.android.com/reference/androidx/media3/exoplayer/source/chunk/Chunk`s, obtained from a `https://developer.android.com/reference/androidx/media3/exoplayer/source/chunk/ChunkSource`. |
| `https://developer.android.com/reference/androidx/media3/exoplayer/source/EmptySampleStream` | An empty `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream`. |
| `https://developer.android.com/reference/androidx/media3/test/utils/FakeSampleStream` | Fake `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream` that outputs a given `https://developer.android.com/reference/androidx/media3/common/Format` and any amount of `https://developer.android.com/reference/androidx/media3/test/utils/FakeSampleStream.FakeSampleStreamItem`. |

*** ** * ** ***

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

## Summary

| ### Nested types |
|---|
| `@https://developer.android.com/reference/java/lang/annotation/Documented.html @https://developer.android.com/reference/java/lang/annotation/Retention.html(value = https://developer.android.com/reference/java/lang/annotation/RetentionPolicy.html#SOURCE) @https://developer.android.com/reference/java/lang/annotation/Target.html(value = https://developer.android.com/reference/java/lang/annotation/ElementType.html#TYPE_USE) @https://developer.android.com/reference/androidx/annotation/IntDef(flag = true, value = ) public annotation https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream.Flags` Flags that can be specified on the stream. |
| `@https://developer.android.com/reference/java/lang/annotation/Documented.html @https://developer.android.com/reference/java/lang/annotation/Retention.html(value = https://developer.android.com/reference/java/lang/annotation/RetentionPolicy.html#SOURCE) @https://developer.android.com/reference/java/lang/annotation/Target.html(value = https://developer.android.com/reference/java/lang/annotation/ElementType.html#TYPE_USE) @https://developer.android.com/reference/androidx/annotation/IntDef(value = [https://developer.android.com/reference/androidx/media3/common/C.RESULT_NOTHING_READ, https://developer.android.com/reference/androidx/media3/common/C.RESULT_FORMAT_READ, https://developer.android.com/reference/androidx/media3/common/C.RESULT_BUFFER_READ]) public annotation https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream.ReadDataResult` Return values of `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#readData(androidx.media3.exoplayer.FormatHolder,androidx.media3.decoder.DecoderInputBuffer,int)`. |
| `@https://developer.android.com/reference/java/lang/annotation/Documented.html @https://developer.android.com/reference/java/lang/annotation/Retention.html(value = https://developer.android.com/reference/java/lang/annotation/RetentionPolicy.html#SOURCE) @https://developer.android.com/reference/java/lang/annotation/Target.html(value = https://developer.android.com/reference/java/lang/annotation/ElementType.html#TYPE_USE) @https://developer.android.com/reference/androidx/annotation/IntDef(flag = true, value = ) public annotation https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream.ReadFlags` Flags that can be specified when calling `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#readData(androidx.media3.exoplayer.FormatHolder,androidx.media3.decoder.DecoderInputBuffer,int)`. |

| ### Constants |
|---|---|
| `default static final int` | `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#FLAG_HAS_PREROLL() = 4` Specifies that the stream contains a preroll of decode-only samples. |
| `default static final int` | `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#FLAG_MAYBE_HAS_PREROLL() = 2` Specifies that the stream may contain preroll samples. |
| `default static final int` | `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#FLAG_OMIT_SAMPLE_DATA() = 4` Specifies that `https://developer.android.com/reference/androidx/media3/decoder/DecoderInputBuffer#data()`, `https://developer.android.com/reference/androidx/media3/decoder/DecoderInputBuffer#supplementalData()` and `https://developer.android.com/reference/androidx/media3/decoder/DecoderInputBuffer#cryptoInfo()` should not be populated when reading a sample buffer. |
| `default static final int` | `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#FLAG_PEEK() = 1` Specifies that the read position should not be advanced if a sample buffer is read. |
| `default static final int` | `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#FLAG_REQUIRE_FORMAT() = 2` Specifies that if a sample buffer would normally be read next, the format of the stream should be read instead. |
| `default static final int` | `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#FLAG_STRICT_DURATION() = 1` Specifies that playout of the stream should be stopped once the duration is reached. |

| ### Public methods |
|---|---|
| `default int` | `@https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream.Flags https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#getFlags()()` Returns the `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream.Flags` set on this stream. |
| `abstract boolean` | `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#isReady()()` Returns whether data is available to be read. |
| `abstract void` | `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#maybeThrowError()()` Throws an error that's preventing data from being read. |
| `abstract int` | `@https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream.ReadDataResult https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#readData(androidx.media3.exoplayer.FormatHolder,androidx.media3.decoder.DecoderInputBuffer,int)( https://developer.android.com/reference/androidx/media3/exoplayer/FormatHolder formatHolder, https://developer.android.com/reference/androidx/media3/decoder/DecoderInputBuffer buffer, @https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream.ReadFlags int readFlags )` Attempts to read from the stream. |
| `abstract int` | `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#skipData(long)(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_HAS_PREROLL

```
default static final int FLAG_HAS_PREROLL = 4
```

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

### FLAG_MAYBE_HAS_PREROLL

```
default static final int FLAG_MAYBE_HAS_PREROLL = 2
```

Specifies that the stream may contain preroll samples.

A stream must resolve itself eventually to either not have this flag or have `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#FLAG_HAS_PREROLL()`.

### FLAG_OMIT_SAMPLE_DATA

```
default static final int FLAG_OMIT_SAMPLE_DATA = 4
```

Specifies that `https://developer.android.com/reference/androidx/media3/decoder/DecoderInputBuffer#data()`, `https://developer.android.com/reference/androidx/media3/decoder/DecoderInputBuffer#supplementalData()` and `https://developer.android.com/reference/androidx/media3/decoder/DecoderInputBuffer#cryptoInfo()` should not be populated when reading a sample buffer.

This flag is useful for efficiently reading or (when combined with `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#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.

### FLAG_STRICT_DURATION

```
default static final int FLAG_STRICT_DURATION = 1
```

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

## Public methods

### getFlags

```
@SampleStream.Flags
default int getFlags()
```

Returns the `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream.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

```
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 `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream#readData(androidx.media3.exoplayer.FormatHolder,androidx.media3.decoder.DecoderInputBuffer,int)`. 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 |
|---|---|
| `https://developer.android.com/reference/java/io/IOException.html` | 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 `https://developer.android.com/reference/androidx/media3/common/C#BUFFER_FLAG_END_OF_STREAM()` flag is set on `
buffer` and `https://developer.android.com/reference/androidx/media3/common/C#RESULT_BUFFER_READ()` is returned. Else if no data is available then `https://developer.android.com/reference/androidx/media3/common/C#RESULT_NOTHING_READ()` is returned. Else if the format of the media is changing or if `
formatRequired` is set then `formatHolder` is populated and `https://developer.android.com/reference/androidx/media3/common/C#RESULT_FORMAT_READ()` is returned. Else `buffer` is populated and `https://developer.android.com/reference/androidx/media3/common/C#RESULT_BUFFER_READ()` is returned.

Value is one of the following:

- `C.RESULT_NOTHING_READ`
- `C.RESULT_FORMAT_READ`
- `C.RESULT_BUFFER_READ`

<br />

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/media3/exoplayer/FormatHolder formatHolder` | A `https://developer.android.com/reference/androidx/media3/exoplayer/FormatHolder` to populate in the case of reading a format. |
| `https://developer.android.com/reference/androidx/media3/decoder/DecoderInputBuffer buffer` | A `https://developer.android.com/reference/androidx/media3/decoder/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 `https://developer.android.com/reference/androidx/media3/common/C#BUFFER_FLAG_END_OF_STREAM()` flag will be set on the buffer. |
| `@https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream.ReadFlags int readFlags` | Flags controlling the behavior of this read operation. |

| Returns |
|---|---|
| `int` | The `https://developer.android.com/reference/androidx/media3/exoplayer/source/SampleStream.ReadDataResult` of the read operation. |

| Throws |
|---|---|
| `https://developer.android.com/reference/androidx/media3/decoder/DecoderInputBuffer.InsufficientCapacityException` | If the `buffer` has insufficient capacity to hold the data of a sample being read. The buffer `https://developer.android.com/reference/androidx/media3/decoder/DecoderInputBuffer#timeUs()` 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. |