Package com.google.android.exoplayer2.source

## Class SampleQueue

- java.lang.Object
- - com.google.android.exoplayer2.source.SampleQueue

- All Implemented Interfaces:
    `TrackOutput`

      public class SampleQueue
      extends Object
      implements TrackOutput

  A queue of media samples.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `SampleQueue.UpstreamFormatChangedListener` | A listener for changes to the upstream format.

    - ### Nested classes/interfaces inherited from interface com.google.android.exoplayer2.extractor.TrackOutput

      `TrackOutput.CryptoData, TrackOutput.SampleDataPart`

  - ### Field Summary

    - ### Fields inherited from interface com.google.android.exoplayer2.extractor.TrackOutput

      `SAMPLE_DATA_PART_ENCRYPTION, SAMPLE_DATA_PART_MAIN, SAMPLE_DATA_PART_SUPPLEMENTAL`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `SampleQueue​(Allocator allocator, Looper playbackLooper, DrmSessionManager drmSessionManager, DrmSessionEventListener.EventDispatcher drmEventDispatcher)` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static SampleQueue` | `createWithDrm​(Allocator allocator, Looper playbackLooper, DrmSessionManager drmSessionManager, DrmSessionEventListener.EventDispatcher drmEventDispatcher)` | Creates a sample queue with DRM resource management.
    `static SampleQueue` | `createWithoutDrm​(Allocator allocator)` | Creates a sample queue without DRM resource management.
    `long` | `discardSampleMetadataToRead()` |
    `void` | `discardTo​(long timeUs, boolean toKeyframe, boolean stopAtReadPosition)` | Discards up to but not including the sample immediately before or at the specified time.
    `void` | `discardToEnd()` | Discards all samples in the queue and advances the read position.
    `void` | `discardToRead()` | Discards up to but not including the read position.
    `void` | `discardUpstreamFrom​(long timeUs)` | Discards samples from the write side of the queue.
    `void` | `discardUpstreamSamples​(int discardFromIndex)` | Discards samples from the write side of the queue.
    `void` | `format​(Format unadjustedUpstreamFormat)` | Called when the `Format` of the track has been extracted from the stream.
    `protected Format` | `getAdjustedUpstreamFormat​(Format format)` | Adjusts the upstream `Format` (i.e., the `Format` that was most recently passed to `format(Format)`).
    `int` | `getFirstIndex()` | Returns the current absolute start index.
    `long` | `getFirstTimestampUs()` | Returns the timestamp of the first sample, or `Long.MIN_VALUE` if the queue is empty.
    `long` | `getLargestQueuedTimestampUs()` | Returns the largest sample timestamp that has been queued since the last `reset()`.
    `long` | `getLargestReadTimestampUs()` | Returns the largest sample timestamp that has been read since the last `reset()`.
    `int` | `getReadIndex()` | Returns the current absolute read index.
    `int` | `getSkipCount​(long timeUs, boolean allowEndOfQueue)` | Returns the number of samples that need to be `skipped` to advance the read position to the keyframe before or at the specified time.
    `Format` | `getUpstreamFormat()` | Returns the upstream `Format` in which samples are being queued.
    `int` | `getWriteIndex()` | Returns the current absolute write index.
    `protected void` | `invalidateUpstreamFormatAdjustment()` | Invalidates the last upstream format adjustment.
    `boolean` | `isLastSampleQueued()` | Returns whether the last sample of the stream has knowingly been queued.
    `boolean` | `isReady​(boolean loadingFinished)` | Returns whether there is data available for reading.
    `void` | `maybeThrowError()` | Throws an error that's preventing data from being read.
    `int` | `peekSourceId()` | Peeks the source id of the next sample to be read, or the current upstream source id if the queue is empty or if the read position is at the end of the queue.
    `void` | `preRelease()` | Calls `discardToEnd()` and releases any resources owned by the queue.
    `int` | `read​(FormatHolder formatHolder, DecoderInputBuffer buffer, int readFlags, boolean loadingFinished)` | Attempts to read from the queue.
    `void` | `release()` | Calls `reset(true)` and releases any resources owned by the queue.
    `void` | `reset()` | Convenience method for `reset(false)`.
    `void` | `reset​(boolean resetUpstreamFormat)` | Clears all samples from the queue.
    `int` | `sampleData​(DataReader input, int length, boolean allowEndOfInput, int sampleDataPart)` | Called to write sample data to the output.
    `void` | `sampleData​(ParsableByteArray buffer, int length, int sampleDataPart)` | Called to write sample data to the output.
    `void` | `sampleMetadata​(long timeUs, int flags, int size, int offset, TrackOutput.CryptoData cryptoData)` | Called when metadata associated with a sample has been extracted from the stream.
    `boolean` | `seekTo​(int sampleIndex)` | Attempts to seek the read position to the specified sample index.
    `boolean` | `seekTo​(long timeUs, boolean allowTimeBeyondBuffer)` | Attempts to seek the read position to the keyframe before or at the specified time.
    `void` | `setSampleOffsetUs​(long sampleOffsetUs)` | Sets an offset that will be added to the timestamps (and sub-sample timestamps) of samples that are subsequently queued.
    `void` | `setStartTimeUs​(long startTimeUs)` | Sets the start time for the queue.
    `void` | `setUpstreamFormatChangeListener​(SampleQueue.UpstreamFormatChangedListener listener)` | Sets a listener to be notified of changes to the upstream format.
    `void` | `skip​(int count)` | Advances the read position by the specified number of samples.
    `void` | `sourceId​(int sourceId)` | Sets a source identifier for subsequent samples.
    `void` | `splice()` | Indicates samples that are subsequently queued should be spliced into those already queued.

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

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

    - ### Methods inherited from interface com.google.android.exoplayer2.extractor.TrackOutput

      `sampleData, sampleData`

- - ### Constructor Detail

    - #### SampleQueue

          protected SampleQueue​(Allocator allocator,
                                @Nullable
                                Looper playbackLooper,
                                @Nullable
                                DrmSessionManager drmSessionManager,
                                @Nullable
                                DrmSessionEventListener.EventDispatcher drmEventDispatcher)

  - ### Method Detail

    - #### createWithoutDrm

          public static SampleQueue createWithoutDrm​(Allocator allocator)

      Creates a sample queue without DRM resource management.
      Parameters:
        `allocator` - An `Allocator` from which allocations for sample data can be obtained.

    - #### createWithDrm

          public static SampleQueue createWithDrm​(Allocator allocator,
                                                  Looper playbackLooper,
                                                  DrmSessionManager drmSessionManager,
                                                  DrmSessionEventListener.EventDispatcher drmEventDispatcher)

      Creates a sample queue with DRM resource management.

      For each sample added to the queue, a `DrmSession` will be attached containing the keys needed to decrypt it.

      Parameters:
        `allocator` - An `Allocator` from which allocations for sample data can be obtained.
        `playbackLooper` - The looper associated with the media playback thread.
        `drmSessionManager` - The `DrmSessionManager` to obtain `DrmSessions` from. The created instance does not take ownership of this `DrmSessionManager`.
        `drmEventDispatcher` - A `DrmSessionEventListener.EventDispatcher` to notify of events related to this SampleQueue.

    - #### release

          @CallSuper
          public void release()

      Calls `reset(true)` and releases any resources owned by the queue.

    - #### reset

          public final void reset()

      Convenience method for `reset(false)`.

    - #### reset

          @CallSuper
          public void reset​(boolean resetUpstreamFormat)

      Clears all samples from the queue.
      Parameters:
        `resetUpstreamFormat` - Whether the upstream format should be cleared. If set to false, samples queued after the reset (and before a subsequent call to `format(Format)`) are assumed to have the current upstream format. If set to true, `format(Format)` must be called after the reset before any more samples can be queued.

    - #### setStartTimeUs

          public final void setStartTimeUs​(long startTimeUs)

      Sets the start time for the queue. Samples with earlier timestamps will be discarded or have the `C.BUFFER_FLAG_DECODE_ONLY` flag set when read.
      Parameters:
        `startTimeUs` - The start time, in microseconds.

    - #### sourceId

          public final void sourceId​(int sourceId)

      Sets a source identifier for subsequent samples.
      Parameters:
        `sourceId` - The source identifier.

    - #### splice

          public final void splice()

      Indicates samples that are subsequently queued should be spliced into those already queued.

    - #### getWriteIndex

          public final int getWriteIndex()

      Returns the current absolute write index.

    - #### discardUpstreamSamples

          public final void discardUpstreamSamples​(int discardFromIndex)

      Discards samples from the write side of the queue.
      Parameters:
        `discardFromIndex` - The absolute index of the first sample to be discarded. Must be in the range [`getReadIndex()`, `getWriteIndex()`].

    - #### discardUpstreamFrom

          public final void discardUpstreamFrom​(long timeUs)

      Discards samples from the write side of the queue.
      Parameters:
        `timeUs` - Samples will be discarded from the write end of the queue until a sample with a timestamp smaller than timeUs is encountered (this sample is not discarded). Must be larger than `getLargestReadTimestampUs()`.

    - #### preRelease

          @CallSuper
          public void preRelease()

      Calls `discardToEnd()` and releases any resources owned by the queue.

    - #### maybeThrowError

          @CallSuper
          public 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.

    - #### getFirstIndex

          public final int getFirstIndex()

      Returns the current absolute start index.

    - #### getReadIndex

          public final int getReadIndex()

      Returns the current absolute read index.

    - #### peekSourceId

          public final int peekSourceId()

      Peeks the source id of the next sample to be read, or the current upstream source id if the queue is empty or if the read position is at the end of the queue.
      Returns:
        The source id.

    - #### getUpstreamFormat

          @Nullable
          public final Format getUpstreamFormat()

      Returns the upstream `Format` in which samples are being queued.

    - #### getLargestQueuedTimestampUs

          public final long getLargestQueuedTimestampUs()

      Returns the largest sample timestamp that has been queued since the last `reset()`.

      Samples that were discarded by calling `discardUpstreamSamples(int)` are not considered as having been queued. Samples that were dequeued from the front of the queue are considered as having been queued.

      Returns:
        The largest sample timestamp that has been queued, or `Long.MIN_VALUE` if no samples have been queued.

    - #### getLargestReadTimestampUs

          public final long getLargestReadTimestampUs()

      Returns the largest sample timestamp that has been read since the last `reset()`.
      Returns:
        The largest sample timestamp that has been read, or `Long.MIN_VALUE` if no samples have been read.

    - #### isLastSampleQueued

          public final boolean isLastSampleQueued()

      Returns whether the last sample of the stream has knowingly been queued. A return value of `false` means that the last sample had not been queued or that it's unknown whether the last sample has been queued.

      Samples that were discarded by calling `discardUpstreamSamples(int)` are not considered as having been queued. Samples that were dequeued from the front of the queue are considered as having been queued.

    - #### getFirstTimestampUs

          public final long getFirstTimestampUs()

      Returns the timestamp of the first sample, or `Long.MIN_VALUE` if the queue is empty.

    - #### isReady

          @CallSuper
          public boolean isReady​(boolean loadingFinished)

      Returns whether there is data available for reading.

      Note: If the stream has ended then a buffer with the end of stream flag can always be read from `read(com.google.android.exoplayer2.FormatHolder, com.google.android.exoplayer2.decoder.DecoderInputBuffer, int, boolean)`. Hence an ended stream is always ready.

      Parameters:
        `loadingFinished` - Whether no more samples will be written to the sample queue. When true, this method returns true if the sample queue is empty, because an empty sample queue means the end of stream has been reached. When false, this method returns false if the sample queue is empty.

    - #### read

          @CallSuper
          public int read​(FormatHolder formatHolder,
                          DecoderInputBuffer buffer,
                          @ReadFlags
                          int readFlags,
                          boolean loadingFinished)

      Attempts to read from the queue.

      `Formats` read from this method may be associated to a `DrmSession` through `FormatHolder.drmSession`.

      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.
        `loadingFinished` - True if an empty queue should be considered the end of the stream.
      Returns:
        The result, which can be `C.RESULT_NOTHING_READ`, `C.RESULT_FORMAT_READ` or `C.RESULT_BUFFER_READ`.
      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.

    - #### seekTo

          public final boolean seekTo​(int sampleIndex)

      Attempts to seek the read position to the specified sample index.
      Parameters:
        `sampleIndex` - The sample index.
      Returns:
        Whether the seek was successful.

    - #### seekTo

          public final boolean seekTo​(long timeUs,
                                      boolean allowTimeBeyondBuffer)

      Attempts to seek the read position to the keyframe before or at the specified time.
      Parameters:
        `timeUs` - The time to seek to.
        `allowTimeBeyondBuffer` - Whether the operation can succeed if `timeUs` is beyond the end of the queue, by seeking to the last sample (or keyframe).
      Returns:
        Whether the seek was successful.

    - #### getSkipCount

          public final int getSkipCount​(long timeUs,
                                        boolean allowEndOfQueue)

      Returns the number of samples that need to be `skipped` to advance the read position to the keyframe before or at the specified time.
      Parameters:
        `timeUs` - The time to advance to.
        `allowEndOfQueue` - Whether the end of the queue is considered a keyframe when `timeUs` is larger than the largest queued timestamp.
      Returns:
        The number of samples that need to be skipped, which may be equal to 0.

    - #### skip

          public final void skip​(int count)

      Advances the read position by the specified number of samples.
      Parameters:
        `count` - The number of samples to advance the read position by. Must be at least 0 and at most `getWriteIndex()` - `getReadIndex()`.

    - #### discardTo

          public final void discardTo​(long timeUs,
                                      boolean toKeyframe,
                                      boolean stopAtReadPosition)

      Discards up to but not including the sample immediately before or at the specified time.
      Parameters:
        `timeUs` - The time to discard up to.
        `toKeyframe` - If true then discards samples up to the keyframe before or at the specified time, rather than any sample before or at that time.
        `stopAtReadPosition` - If true then samples are only discarded if they're before the read position. If false then samples at and beyond the read position may be discarded, in which case the read position is advanced to the first remaining sample.

    - #### discardToRead

          public final void discardToRead()

      Discards up to but not including the read position.

    - #### discardToEnd

          public final void discardToEnd()

      Discards all samples in the queue and advances the read position.

    - #### setSampleOffsetUs

          public final void setSampleOffsetUs​(long sampleOffsetUs)

      Sets an offset that will be added to the timestamps (and sub-sample timestamps) of samples that are subsequently queued.
      Parameters:
        `sampleOffsetUs` - The timestamp offset in microseconds.

    - #### setUpstreamFormatChangeListener

          public final void setUpstreamFormatChangeListener​(@Nullable
                                                            SampleQueue.UpstreamFormatChangedListener listener)

      Sets a listener to be notified of changes to the upstream format.
      Parameters:
        `listener` - The listener.

    - #### format

          public final void format​(Format unadjustedUpstreamFormat)

      Description copied from interface: `TrackOutput`
      Called when the `Format` of the track has been extracted from the stream.
      Specified by:
        `format` in interface `TrackOutput`
      Parameters:
        `unadjustedUpstreamFormat` - The extracted `Format`.

    - #### sampleData

          public final int sampleData​(DataReader input,
                                      int length,
                                      boolean allowEndOfInput,
                                      @SampleDataPart
                                      int sampleDataPart)
                               throws IOException

      Description copied from interface: `TrackOutput`
      Called to write sample data to the output.
      Specified by:
        `sampleData` in interface `TrackOutput`
      Parameters:
        `input` - A `DataReader` from which to read the sample data.
        `length` - The maximum length to read from the input.
        `allowEndOfInput` - True if encountering the end of the input having read no data is allowed, and should result in `C.RESULT_END_OF_INPUT` being returned. False if it should be considered an error, causing an `EOFException` to be thrown.
        `sampleDataPart` - The part of the sample data to which this call corresponds.
      Returns:
        The number of bytes appended.
      Throws:
        `IOException` - If an error occurred reading from the input.

    - #### sampleData

          public final void sampleData​(ParsableByteArray buffer,
                                       int length,
                                       @SampleDataPart
                                       int sampleDataPart)

      Description copied from interface: `TrackOutput`
      Called to write sample data to the output.
      Specified by:
        `sampleData` in interface `TrackOutput`
      Parameters:
        `buffer` - A `ParsableByteArray` from which to read the sample data.
        `length` - The number of bytes to read, starting from `data.getPosition()`.
        `sampleDataPart` - The part of the sample data to which this call corresponds.

    - #### sampleMetadata

          public void sampleMetadata​(long timeUs,
                                     @BufferFlags
                                     int flags,
                                     int size,
                                     int offset,
                                     @Nullable
                                     TrackOutput.CryptoData cryptoData)

      Description copied from interface: `TrackOutput`
      Called when metadata associated with a sample has been extracted from the stream.

      The corresponding sample data will have already been passed to the output via calls to `TrackOutput.sampleData(DataReader, int, boolean)` or `TrackOutput.sampleData(ParsableByteArray, int)`.

      Specified by:
        `sampleMetadata` in interface `TrackOutput`
      Parameters:
        `timeUs` - The media timestamp associated with the sample, in microseconds.
        `flags` - Flags associated with the sample. See `C.BUFFER_FLAG_*`.
        `size` - The size of the sample data, in bytes.
        `offset` - The number of bytes that have been passed to `TrackOutput.sampleData(DataReader, int, boolean)` or `TrackOutput.sampleData(ParsableByteArray, int)` since the last byte belonging to the sample whose metadata is being passed.
        `cryptoData` - The encryption data required to decrypt the sample. May be null.

    - #### invalidateUpstreamFormatAdjustment

          protected final void invalidateUpstreamFormatAdjustment()

      Invalidates the last upstream format adjustment. `getAdjustedUpstreamFormat(Format)` will be called to adjust the upstream `Format` again before the next sample is queued.

    - #### getAdjustedUpstreamFormat

          @CallSuper
          protected Format getAdjustedUpstreamFormat​(Format format)

      Adjusts the upstream `Format` (i.e., the `Format` that was most recently passed to `format(Format)`).

      The default implementation incorporates the sample offset passed to `setSampleOffsetUs(long)` into `Format.subsampleOffsetUs`.

      Parameters:
        `format` - The `Format` to adjust.
      Returns:
        The adjusted `Format`.

    - #### discardSampleMetadataToRead

          public long discardSampleMetadataToRead()