Package com.google.android.exoplayer2.source.chunk

## Class ChunkSampleStream<T extends ChunkSource>

- java.lang.Object
- - com.google.android.exoplayer2.source.chunk.ChunkSampleStream<T>

- All Implemented Interfaces:
    `SampleStream`, `SequenceableLoader`, `Loader.Callback<Chunk>`, `Loader.ReleaseCallback`

      public class ChunkSampleStream<T extends ChunkSource>
      extends Object
      implements SampleStream, SequenceableLoader, Loader.Callback<Chunk>, Loader.ReleaseCallback

  A `SampleStream` that loads media in `Chunk`s, obtained from a `ChunkSource`. May also be configured to expose additional embedded `SampleStream`s.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `class` | `ChunkSampleStream.EmbeddedSampleStream` | A `SampleStream` embedded in a `ChunkSampleStream`.
    `static interface` | `ChunkSampleStream.ReleaseCallback<T extends ChunkSource>` | A callback to be notified when a sample stream has finished being released.

    - ### Nested classes/interfaces inherited from interface com.google.android.exoplayer2.source.SampleStream

      `SampleStream.ReadDataResult, SampleStream.ReadFlags`

    - ### Nested classes/interfaces inherited from interface com.google.android.exoplayer2.source.SequenceableLoader

      `SequenceableLoader.Callback<T extends SequenceableLoader>`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `@com.google.android.exoplayer2.C.TrackType int` | `primaryTrackType` |

    - ### Fields inherited from interface com.google.android.exoplayer2.source.SampleStream

      `FLAG_OMIT_SAMPLE_DATA, FLAG_PEEK, FLAG_REQUIRE_FORMAT`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ChunkSampleStream​(@com.google.android.exoplayer2.C.TrackType int primaryTrackType, int[] embeddedTrackTypes, Format[] embeddedTrackFormats, T chunkSource, SequenceableLoader.Callback<ChunkSampleStream<T>> callback, Allocator allocator, long positionUs, DrmSessionManager drmSessionManager, DrmSessionEventListener.EventDispatcher drmEventDispatcher, LoadErrorHandlingPolicy loadErrorHandlingPolicy, MediaSourceEventListener.EventDispatcher mediaSourceEventDispatcher)` | Constructs an instance.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `continueLoading​(long positionUs)` | Attempts to continue loading.
    `void` | `discardBuffer​(long positionUs, boolean toKeyframe)` | Discards buffered media up to the specified position.
    `long` | `getAdjustedSeekPositionUs​(long positionUs, SeekParameters seekParameters)` | Adjusts a seek position given the specified `SeekParameters`.
    `long` | `getBufferedPositionUs()` | Returns an estimate of the position up to which data is buffered.
    `T` | `getChunkSource()` | Returns the `ChunkSource` used by this stream.
    `long` | `getNextLoadPositionUs()` | Returns the next load time, or `C.TIME_END_OF_SOURCE` if loading has finished.
    `boolean` | `isLoading()` | Returns whether the loader is currently loading.
    `boolean` | `isReady()` | Returns whether data is available to be read.
    `void` | `maybeThrowError()` | Throws an error that's preventing data from being read.
    `void` | `onLoadCanceled​(Chunk loadable, long elapsedRealtimeMs, long loadDurationMs, boolean released)` | Called when a load has been canceled.
    `void` | `onLoadCompleted​(Chunk loadable, long elapsedRealtimeMs, long loadDurationMs)` | Called when a load has completed.
    `void` | `onLoaderReleased()` | Called when the `Loader` has finished being released.
    `Loader.LoadErrorAction` | `onLoadError​(Chunk loadable, long elapsedRealtimeMs, long loadDurationMs, IOException error, int errorCount)` | Called when a load encounters an error.
    `int` | `readData​(FormatHolder formatHolder, DecoderInputBuffer buffer, @com.google.android.exoplayer2.source.SampleStream.ReadFlags int readFlags)` | Attempts to read from the stream.
    `void` | `reevaluateBuffer​(long positionUs)` | Re-evaluates the buffer given the playback position.
    `void` | `release()` | Releases the stream.
    `void` | `release​(ChunkSampleStream.ReleaseCallback<T> callback)` | Releases the stream.
    `void` | `seekToUs​(long positionUs)` | Seeks to the specified position in microseconds.
    `ChunkSampleStream.EmbeddedSampleStream` | `selectEmbeddedTrack​(long positionUs, int trackType)` | Selects the embedded track, returning a new `ChunkSampleStream.EmbeddedSampleStream` from which the track's samples can be consumed.
    `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.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### primaryTrackType

          public final @com.google.android.exoplayer2.C.TrackType int primaryTrackType

  - ### Constructor Detail

    - #### ChunkSampleStream

          public ChunkSampleStream​(@com.google.android.exoplayer2.C.TrackType int primaryTrackType,
                                   @Nullable
                                   int[] embeddedTrackTypes,
                                   @Nullable
                                   Format[] embeddedTrackFormats,
                                   T chunkSource,
                                   SequenceableLoader.Callback<ChunkSampleStream<T>> callback,
                                   Allocator allocator,
                                   long positionUs,
                                   DrmSessionManager drmSessionManager,
                                   DrmSessionEventListener.EventDispatcher drmEventDispatcher,
                                   LoadErrorHandlingPolicy loadErrorHandlingPolicy,
                                   MediaSourceEventListener.EventDispatcher mediaSourceEventDispatcher)

      Constructs an instance.
      Parameters:
        `primaryTrackType` - The `type` of the primary track.
        `embeddedTrackTypes` - The types of any embedded tracks, or null.
        `embeddedTrackFormats` - The formats of the embedded tracks, or null.
        `chunkSource` - A `ChunkSource` from which chunks to load are obtained.
        `callback` - An `SequenceableLoader.Callback` for the stream.
        `allocator` - An `Allocator` from which allocations can be obtained.
        `positionUs` - The position from which to start loading media.
        `drmSessionManager` - The `DrmSessionManager` to obtain `DrmSessions` from.
        `drmEventDispatcher` - A dispatcher to notify of `DrmSessionEventListener` events.
        `loadErrorHandlingPolicy` - The `LoadErrorHandlingPolicy`.
        `mediaSourceEventDispatcher` - A dispatcher to notify of `MediaSourceEventListener` events.

  - ### Method Detail

    - #### discardBuffer

          public void discardBuffer​(long positionUs,
                                    boolean toKeyframe)

      Discards buffered media up to the specified position.
      Parameters:
        `positionUs` - The position to discard up to, in microseconds.
        `toKeyframe` - If true then for each track discards samples up to the keyframe before or at the specified position, rather than any sample before or at that position.

    - #### selectEmbeddedTrack

          public ChunkSampleStream.EmbeddedSampleStream selectEmbeddedTrack​(long positionUs,
                                                                            int trackType)

      Selects the embedded track, returning a new `ChunkSampleStream.EmbeddedSampleStream` from which the track's samples can be consumed. `ChunkSampleStream.EmbeddedSampleStream.release()` must be called on the returned stream when the track is no longer required, and before calling this method again to obtain another stream for the same track.
      Parameters:
        `positionUs` - The current playback position in microseconds.
        `trackType` - The type of the embedded track to enable.
      Returns:
        The `ChunkSampleStream.EmbeddedSampleStream` for the embedded track.

    - #### getChunkSource

          public T getChunkSource()

      Returns the `ChunkSource` used by this stream.

    - #### getBufferedPositionUs

          public long getBufferedPositionUs()

      Returns an estimate of the position up to which data is buffered.
      Specified by:
        `getBufferedPositionUs` in interface `SequenceableLoader`
      Returns:
        An estimate of the absolute position in microseconds up to which data is buffered, or `C.TIME_END_OF_SOURCE` if the track is fully buffered.

    - #### getAdjustedSeekPositionUs

          public long getAdjustedSeekPositionUs​(long positionUs,
                                                SeekParameters seekParameters)

      Adjusts a seek position given the specified `SeekParameters`. Chunk boundaries are used as sync points.
      Parameters:
        `positionUs` - The seek position in microseconds.
        `seekParameters` - Parameters that control how the seek is performed.
      Returns:
        The adjusted seek position, in microseconds.

    - #### seekToUs

          public void seekToUs​(long positionUs)

      Seeks to the specified position in microseconds.
      Parameters:
        `positionUs` - The seek position in microseconds.

    - #### release

          public void release()

      Releases the stream.

      This method should be called when the stream is no longer required. Either this method or `release(ReleaseCallback)` can be used to release this stream.

    - #### release

          public void release​(@Nullable
                              ChunkSampleStream.ReleaseCallback<T> callback)

      Releases the stream.

      This method should be called when the stream is no longer required. Either this method or `release()` can be used to release this stream.

      Parameters:
        `callback` - An optional callback to be called on the loading thread once the loader has been released.

    - #### onLoaderReleased

          public void onLoaderReleased()

      Description copied from interface: `Loader.ReleaseCallback`
      Called when the `Loader` has finished being released.
      Specified by:
        `onLoaderReleased` in interface `Loader.ReleaseCallback`

    - #### isReady

          public boolean isReady()

      Description copied from interface: `SampleStream`
      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 `SampleStream.readData(com.google.android.exoplayer2.FormatHolder, com.google.android.exoplayer2.decoder.DecoderInputBuffer, @com.google.android.exoplayer2.source.SampleStream.ReadFlags int)`. Hence an ended stream is always ready.

      Specified by:
        `isReady` in interface `SampleStream`
      Returns:
        Whether data is available to be read.

    - #### maybeThrowError

          public void maybeThrowError()
                               throws IOException

      Description copied from interface: `SampleStream`
      Throws an error that's preventing data from being read. Does nothing if no such error exists.
      Specified by:
        `maybeThrowError` in interface `SampleStream`
      Throws:
        `IOException` - The underlying error.

    - #### readData

          public int readData​(FormatHolder formatHolder,
                              DecoderInputBuffer buffer,
                              @com.google.android.exoplayer2.source.SampleStream.ReadFlags int readFlags)

      Description copied from interface: `SampleStream`
      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.

      Specified by:
        `readData` in interface `SampleStream`
      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.

    - #### skipData

          public int skipData​(long positionUs)

      Description copied from interface: `SampleStream`
      Attempts to skip to the keyframe before the specified position, or to the end of the stream if `positionUs` is beyond it.
      Specified by:
        `skipData` in interface `SampleStream`
      Parameters:
        `positionUs` - The specified time.
      Returns:
        The number of samples that were skipped.

    - #### onLoadCompleted

          public void onLoadCompleted​(Chunk loadable,
                                      long elapsedRealtimeMs,
                                      long loadDurationMs)

      Description copied from interface: `Loader.Callback`
      Called when a load has completed.

      Note: There is guaranteed to be a memory barrier between `Loader.Loadable.load()` exiting and this callback being called.

      Specified by:
        `onLoadCompleted` in interface `Loader.Callback<T extends ChunkSource>`
      Parameters:
        `loadable` - The loadable whose load has completed.
        `elapsedRealtimeMs` - `SystemClock.elapsedRealtime()` when the load ended.
        `loadDurationMs` - The duration in milliseconds of the load since `Loader.startLoading(T, com.google.android.exoplayer2.upstream.Loader.Callback<T>, int)` was called.

    - #### onLoadCanceled

          public void onLoadCanceled​(Chunk loadable,
                                     long elapsedRealtimeMs,
                                     long loadDurationMs,
                                     boolean released)

      Description copied from interface: `Loader.Callback`
      Called when a load has been canceled.

      Note: If the `Loader` has not been released then there is guaranteed to be a memory barrier between `Loader.Loadable.load()` exiting and this callback being called. If the `Loader` has been released then this callback may be called before `Loader.Loadable.load()` exits.

      Specified by:
        `onLoadCanceled` in interface `Loader.Callback<T extends ChunkSource>`
      Parameters:
        `loadable` - The loadable whose load has been canceled.
        `elapsedRealtimeMs` - `SystemClock.elapsedRealtime()` when the load was canceled.
        `loadDurationMs` - The duration in milliseconds of the load since `Loader.startLoading(T, com.google.android.exoplayer2.upstream.Loader.Callback<T>, int)` was called up to the point at which it was canceled.
        `released` - True if the load was canceled because the `Loader` was released. False otherwise.

    - #### onLoadError

          public Loader.LoadErrorAction onLoadError​(Chunk loadable,
                                                    long elapsedRealtimeMs,
                                                    long loadDurationMs,
                                                    IOException error,
                                                    int errorCount)

      Description copied from interface: `Loader.Callback`
      Called when a load encounters an error.

      Note: There is guaranteed to be a memory barrier between `Loader.Loadable.load()` exiting and this callback being called.

      Specified by:
        `onLoadError` in interface `Loader.Callback<T extends ChunkSource>`
      Parameters:
        `loadable` - The loadable whose load has encountered an error.
        `elapsedRealtimeMs` - `SystemClock.elapsedRealtime()` when the error occurred.
        `loadDurationMs` - The duration in milliseconds of the load since `Loader.startLoading(T, com.google.android.exoplayer2.upstream.Loader.Callback<T>, int)` was called up to the point at which the error occurred.
        `error` - The load error.
        `errorCount` - The number of errors this load has encountered, including this one.
      Returns:
        The desired error handling action. One of `Loader.RETRY`, `Loader.RETRY_RESET_ERROR_COUNT`, `Loader.DONT_RETRY`, `Loader.DONT_RETRY_FATAL` or a retry action created by `Loader.createRetryAction(boolean, long)`.

    - #### continueLoading

          public boolean continueLoading​(long positionUs)

      Description copied from interface: `SequenceableLoader`
      Attempts to continue loading.
      Specified by:
        `continueLoading` in interface `SequenceableLoader`
      Parameters:
        `positionUs` - The current playback position in microseconds. If playback of the period to which this loader belongs has not yet started, the value will be the starting position in the period minus the duration of any media in previous periods still to be played.
      Returns:
        True if progress was made, meaning that `SequenceableLoader.getNextLoadPositionUs()` will return a different value than prior to the call. False otherwise.

    - #### isLoading

          public boolean isLoading()

      Description copied from interface: `SequenceableLoader`
      Returns whether the loader is currently loading.
      Specified by:
        `isLoading` in interface `SequenceableLoader`

    - #### getNextLoadPositionUs

          public long getNextLoadPositionUs()

      Description copied from interface: `SequenceableLoader`
      Returns the next load time, or `C.TIME_END_OF_SOURCE` if loading has finished.
      Specified by:
        `getNextLoadPositionUs` in interface `SequenceableLoader`

    - #### reevaluateBuffer

          public void reevaluateBuffer​(long positionUs)

      Description copied from interface: `SequenceableLoader`
      Re-evaluates the buffer given the playback position.

      Re-evaluation may discard buffered media or cancel ongoing loads so that media can be re-buffered in a different quality.

      Specified by:
        `reevaluateBuffer` in interface `SequenceableLoader`
      Parameters:
        `positionUs` - The current playback position in microseconds. If playback of this period has not yet started, the value will be the starting position in this period minus the duration of any media in previous periods still to be played.