Package com.google.android.exoplayer2.source

## Interface SampleStream

- All Known Implementing Classes:
    `ChunkSampleStream`, `ChunkSampleStream.EmbeddedSampleStream`, `EmptySampleStream`, `FakeSampleStream`

      public interface SampleStream

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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static interface` | `SampleStream.ReadDataResult` | Return values of `readData(com.google.android.exoplayer2.FormatHolder, com.google.android.exoplayer2.decoder.DecoderInputBuffer, int)`.
    `static interface` | `SampleStream.ReadFlags` | Flags that can be specified when calling `readData(com.google.android.exoplayer2.FormatHolder, com.google.android.exoplayer2.decoder.DecoderInputBuffer, int)`.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `FLAG_OMIT_SAMPLE_DATA` | Specifies that `DecoderInputBuffer.data`, `DecoderInputBuffer.supplementalData` and `DecoderInputBuffer.cryptoInfo` should not be populated when reading a sample buffer.
    `static int` | `FLAG_PEEK` | Specifies that the read position should not be advanced if a sample buffer is read.
    `static int` | `FLAG_REQUIRE_FORMAT` | Specifies that if a sample buffer would normally be read next, the format of the stream should be read instead.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `isReady()` | Returns whether data is available to be read.
    `void` | `maybeThrowError()` | Throws an error that's preventing data from being read.
    `int` | `readData​(FormatHolder formatHolder, DecoderInputBuffer buffer, int readFlags)` | Attempts to read from the stream.
    `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.

- - ### Field Detail

    - #### FLAG_PEEK

          static final int FLAG_PEEK

      Specifies that the read position should not be advanced if a sample buffer is read.
      See Also:
        Constant Field Values

    - #### FLAG_REQUIRE_FORMAT

          static final int FLAG_REQUIRE_FORMAT

      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.
      See Also:
        Constant Field Values

    - #### FLAG_OMIT_SAMPLE_DATA

          static final int FLAG_OMIT_SAMPLE_DATA

      Specifies that `DecoderInputBuffer.data`, `DecoderInputBuffer.supplementalData` and `DecoderInputBuffer.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.

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### isReady

          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(com.google.android.exoplayer2.FormatHolder, com.google.android.exoplayer2.decoder.DecoderInputBuffer, int)`. Hence an ended stream is always ready.

      Returns:
        Whether data is available to be read.

    - #### maybeThrowError

          void maybeThrowError()
                        throws IOException

      Throws an error that's preventing data from being read. Does nothing if no such error exists.
      Throws:
        `IOException` - The underlying error.

    - #### readData

          @ReadDataResult
          int readData​(FormatHolder formatHolder,
                       DecoderInputBuffer buffer,
                       @ReadFlags
                       int readFlags)

      Attempts to read from the stream.

      If the stream has ended then `C.BUFFER_FLAG_END_OF_STREAM` flag is set on `buffer` and `C.RESULT_BUFFER_READ` is returned. Else if no data is available then `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 `C.RESULT_FORMAT_READ` is returned. Else `buffer` is populated and `C.RESULT_BUFFER_READ` is returned.

      Parameters:
        `formatHolder` - A `FormatHolder` to populate in the case of reading a format.
        `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 `C.BUFFER_FLAG_END_OF_STREAM` flag will be set on the buffer.
        `readFlags` - Flags controlling the behavior of this read operation.
      Returns:
        The `result` of the read operation.
      Throws:
        `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

          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:
        `positionUs` - The specified time.
      Returns:
        The number of samples that were skipped.