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

## Interface ChunkSource

- All Known Subinterfaces:
    `DashChunkSource`, `SsChunkSource`
  All Known Implementing Classes:
    `DefaultDashChunkSource`, `DefaultSsChunkSource`, `FakeChunkSource`

      public interface ChunkSource

  A provider of `Chunk`s for a `ChunkSampleStream` to load.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `long` | `getAdjustedSeekPositionUs​(long positionUs, SeekParameters seekParameters)` | Adjusts a seek position given the specified `SeekParameters`.
    `void` | `getNextChunk​(long playbackPositionUs, long loadPositionUs, List<? extends MediaChunk> queue, ChunkHolder out)` | Returns the next chunk to load.
    `int` | `getPreferredQueueSize​(long playbackPositionUs, List<? extends MediaChunk> queue)` | Evaluates whether `MediaChunk`s should be removed from the back of the queue.
    `void` | `maybeThrowError()` | If the source is currently having difficulty providing chunks, then this method throws the underlying error.
    `void` | `onChunkLoadCompleted​(Chunk chunk)` | Called when the `ChunkSampleStream` has finished loading a chunk obtained from this source.
    `boolean` | `onChunkLoadError​(Chunk chunk, boolean cancelable, LoadErrorHandlingPolicy.LoadErrorInfo loadErrorInfo, LoadErrorHandlingPolicy loadErrorHandlingPolicy)` | Called when the `ChunkSampleStream` encounters an error loading a chunk obtained from this source.
    `void` | `release()` | Releases any held resources.
    `boolean` | `shouldCancelLoad​(long playbackPositionUs, Chunk loadingChunk, List<? extends MediaChunk> queue)` | Returns whether an ongoing load of a chunk should be canceled.

- - ### Method Detail

    - #### getAdjustedSeekPositionUs

          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.

    - #### maybeThrowError

          void maybeThrowError()
                        throws IOException

      If the source is currently having difficulty providing chunks, then this method throws the underlying error. Otherwise does nothing.
      Throws:
        `IOException` - The underlying error.

    - #### getPreferredQueueSize

          int getPreferredQueueSize​(long playbackPositionUs,
                                    List<? extends MediaChunk> queue)

      Evaluates whether `MediaChunk`s should be removed from the back of the queue.

      Removing `MediaChunk`s from the back of the queue can be useful if they could be replaced with chunks of a significantly higher quality (e.g. because the available bandwidth has substantially increased).

      Will only be called if no `MediaChunk` in the queue is currently loading.

      Parameters:
        `playbackPositionUs` - The current playback position, in microseconds.
        `queue` - The queue of buffered `MediaChunk`s.
      Returns:
        The preferred queue size.

    - #### shouldCancelLoad

          boolean shouldCancelLoad​(long playbackPositionUs,
                                   Chunk loadingChunk,
                                   List<? extends MediaChunk> queue)

      Returns whether an ongoing load of a chunk should be canceled.
      Parameters:
        `playbackPositionUs` - The current playback position, in microseconds.
        `loadingChunk` - The currently loading `Chunk`.
        `queue` - The queue of buffered `MediaChunks`.
      Returns:
        Whether the ongoing load of `loadingChunk` should be canceled.

    - #### getNextChunk

          void getNextChunk​(long playbackPositionUs,
                            long loadPositionUs,
                            List<? extends MediaChunk> queue,
                            ChunkHolder out)

      Returns the next chunk to load.

      If a chunk is available then `ChunkHolder.chunk` is set. If the end of the stream has been reached then `ChunkHolder.endOfStream` is set. If a chunk is not available but the end of the stream has not been reached, the `ChunkHolder` is not modified.

      Parameters:
        `playbackPositionUs` - The current playback position in microseconds. If playback of the period to which this chunk source 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.
        `loadPositionUs` - The current load position in microseconds. If `queue` is empty, this is the starting position from which chunks should be provided. Else it's equal to `Chunk.endTimeUs` of the last chunk in the `queue`.
        `queue` - The queue of buffered `MediaChunk`s.
        `out` - A holder to populate.

    - #### onChunkLoadCompleted

          void onChunkLoadCompleted​(Chunk chunk)

      Called when the `ChunkSampleStream` has finished loading a chunk obtained from this source.
      Parameters:
        `chunk` - The chunk whose load has been completed.

    - #### onChunkLoadError

          boolean onChunkLoadError​(Chunk chunk,
                                   boolean cancelable,
                                   LoadErrorHandlingPolicy.LoadErrorInfo loadErrorInfo,
                                   LoadErrorHandlingPolicy loadErrorHandlingPolicy)

      Called when the `ChunkSampleStream` encounters an error loading a chunk obtained from this source.
      Parameters:
        `chunk` - The chunk whose load encountered the error.
        `cancelable` - Whether the load can be canceled.
        `loadErrorInfo` - The load error info.
        `loadErrorHandlingPolicy` - The load error handling policy to customize the behaviour of handling the load error.
      Returns:
        Whether the load should be canceled so that a replacement chunk can be loaded instead. Must be `false` if `cancelable` is `false`. If `true`, `getNextChunk(long, long, List, ChunkHolder)` will be called to obtain the replacement chunk.

    - #### release

          void release()

      Releases any held resources.