Package com.google.android.exoplayer2.source

## Class ClippingMediaPeriod

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

- All Implemented Interfaces:
    `MediaPeriod`, `MediaPeriod.Callback`, `SequenceableLoader`, `SequenceableLoader.Callback<MediaPeriod>`

      public final class ClippingMediaPeriod
      extends Object
      implements MediaPeriod, MediaPeriod.Callback

  Wraps a `MediaPeriod` and clips its `SampleStream`s to provide a subsequence of their samples.

- - ### Nested Class Summary

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

      `MediaPeriod.Callback`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `MediaPeriod` | `mediaPeriod` | The `MediaPeriod` wrapped by this clipping media period.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ClippingMediaPeriod​(MediaPeriod mediaPeriod, boolean enableInitialDiscontinuity, long startUs, long endUs)` | Creates a new clipping media period that provides a clipped view of the specified `MediaPeriod`'s sample streams.

  - ### 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)` | Returns the position to which a seek will be performed, given the specified seek position and `SeekParameters`.
    `long` | `getBufferedPositionUs()` | Returns an estimate of the position up to which data is buffered for the enabled tracks.
    `long` | `getNextLoadPositionUs()` | Returns the next load time, or `C.TIME_END_OF_SOURCE` if loading has finished.
    `TrackGroupArray` | `getTrackGroups()` | Returns the `TrackGroup`s exposed by the period.
    `boolean` | `isLoading()` | Returns whether the media period is currently loading.
    `void` | `maybeThrowPrepareError()` | Throws an error that's preventing the period from becoming prepared.
    `void` | `onContinueLoadingRequested​(MediaPeriod source)` | Called by the loader to indicate that it wishes for its `SequenceableLoader.continueLoading(long)` method to be called when it can continue to load data.
    `void` | `onPrepared​(MediaPeriod mediaPeriod)` | Called when preparation completes.
    `void` | `prepare​(MediaPeriod.Callback callback, long positionUs)` | Prepares this media period asynchronously.
    `long` | `readDiscontinuity()` | Attempts to read a discontinuity.
    `void` | `reevaluateBuffer​(long positionUs)` | Re-evaluates the buffer given the playback position.
    `long` | `seekToUs​(long positionUs)` | Attempts to seek to the specified position in microseconds.
    `long` | `selectTracks​(@NullableType ExoTrackSelection[] selections, boolean[] mayRetainStreamFlags, @NullableType SampleStream[] streams, boolean[] streamResetFlags, long positionUs)` | Performs a track selection.
    `void` | `updateClipping​(long startUs, long endUs)` | Updates the clipping start/end times for this period, in microseconds.

    - ### 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.source.MediaPeriod

      `getStreamKeys`

- - ### Field Detail

    - #### mediaPeriod

          public final MediaPeriod mediaPeriod

      The `MediaPeriod` wrapped by this clipping media period.

  - ### Constructor Detail

    - #### ClippingMediaPeriod

          public ClippingMediaPeriod​(MediaPeriod mediaPeriod,
                                     boolean enableInitialDiscontinuity,
                                     long startUs,
                                     long endUs)

      Creates a new clipping media period that provides a clipped view of the specified `MediaPeriod`'s sample streams.

      If the start point is guaranteed to be a key frame, pass `false` to `enableInitialPositionDiscontinuity` to suppress an initial discontinuity when the period is first read from.

      Parameters:
        `mediaPeriod` - The media period to clip.
        `enableInitialDiscontinuity` - Whether the initial discontinuity should be enabled.
        `startUs` - The clipping start time, in microseconds.
        `endUs` - The clipping end time, in microseconds, or `C.TIME_END_OF_SOURCE` to indicate the end of the period.

  - ### Method Detail

    - #### updateClipping

          public void updateClipping​(long startUs,
                                     long endUs)

      Updates the clipping start/end times for this period, in microseconds.
      Parameters:
        `startUs` - The clipping start time, in microseconds.
        `endUs` - The clipping end time, in microseconds, or `C.TIME_END_OF_SOURCE` to indicate the end of the period.

    - #### prepare

          public void prepare​(MediaPeriod.Callback callback,
                              long positionUs)

      Description copied from interface: `MediaPeriod`
      Prepares this media period asynchronously.

      `callback.onPrepared` is called when preparation completes. If preparation fails, `MediaPeriod.maybeThrowPrepareError()` will throw an `IOException`.

      If preparation succeeds and results in a source timeline change (e.g. the period duration becoming known), `MediaSource.MediaSourceCaller.onSourceInfoRefreshed(MediaSource, Timeline)` will be called before `callback.onPrepared`.

      Specified by:
        `prepare` in interface `MediaPeriod`
      Parameters:
        `callback` - Callback to receive updates from this period, including being notified when preparation completes.
        `positionUs` - The expected starting position, in microseconds.

    - #### maybeThrowPrepareError

          public void maybeThrowPrepareError()
                                      throws IOException

      Description copied from interface: `MediaPeriod`
      Throws an error that's preventing the period from becoming prepared. Does nothing if no such error exists.

      This method is only called before the period has completed preparation.

      Specified by:
        `maybeThrowPrepareError` in interface `MediaPeriod`
      Throws:
        `IOException` - The underlying error.

    - #### getTrackGroups

          public TrackGroupArray getTrackGroups()

      Description copied from interface: `MediaPeriod`
      Returns the `TrackGroup`s exposed by the period.

      This method is only called after the period has been prepared.

      Specified by:
        `getTrackGroups` in interface `MediaPeriod`
      Returns:
        The `TrackGroup`s.

    - #### selectTracks

          public long selectTracks​(@NullableType ExoTrackSelection[] selections,
                                   boolean[] mayRetainStreamFlags,
                                   @NullableType SampleStream[] streams,
                                   boolean[] streamResetFlags,
                                   long positionUs)

      Description copied from interface: `MediaPeriod`
      Performs a track selection.

      The call receives track `selections` for each renderer, `mayRetainStreamFlags` indicating whether the existing `SampleStream` can be retained for each selection, and the existing `stream`s themselves. The call will update `streams` to reflect the provided selections, clearing, setting and replacing entries as required. If an existing sample stream is retained but with the requirement that the consuming renderer be reset, then the corresponding flag in `streamResetFlags` will be set to true. This flag will also be set if a new sample stream is created.

      Note that previously passed `TrackSelections` are no longer valid, and any references to them must be updated to point to the new selections.

      This method is only called after the period has been prepared.

      Specified by:
        `selectTracks` in interface `MediaPeriod`
      Parameters:
        `selections` - The renderer track selections.
        `mayRetainStreamFlags` - Flags indicating whether the existing sample stream can be retained for each track selection. A `true` value indicates that the selection is equivalent to the one that was previously passed, and that the caller does not require that the sample stream be recreated. If a retained sample stream holds any references to the track selection then they must be updated to point to the new selection.
        `streams` - The existing sample streams, which will be updated to reflect the provided selections.
        `streamResetFlags` - Will be updated to indicate new sample streams, and sample streams that have been retained but with the requirement that the consuming renderer be reset.
        `positionUs` - The current playback position in microseconds. If playback of this period has not yet started, the value will be the starting position.
      Returns:
        The actual position at which the tracks were enabled, in microseconds.

    - #### discardBuffer

          public void discardBuffer​(long positionUs,
                                    boolean toKeyframe)

      Description copied from interface: `MediaPeriod`
      Discards buffered media up to the specified position.

      This method is only called after the period has been prepared.

      Specified by:
        `discardBuffer` in interface `MediaPeriod`
      Parameters:
        `positionUs` - The position 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.

    - #### reevaluateBuffer

          public void reevaluateBuffer​(long positionUs)

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

      This method is only called after the period has been prepared.

      A period may choose to discard buffered media or cancel ongoing loads so that media can be re-buffered in a different quality.

      Specified by:
        `reevaluateBuffer` in interface `MediaPeriod`
      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.

    - #### readDiscontinuity

          public long readDiscontinuity()

      Description copied from interface: `MediaPeriod`
      Attempts to read a discontinuity.

      After this method has returned a value other than `C.TIME_UNSET`, all `SampleStream`s provided by the period are guaranteed to start from a key frame.

      This method is only called after the period has been prepared and before reading from any `SampleStream`s provided by the period.

      Specified by:
        `readDiscontinuity` in interface `MediaPeriod`
      Returns:
        If a discontinuity was read then the playback position in microseconds after the discontinuity. Else `C.TIME_UNSET`.

    - #### getBufferedPositionUs

          public long getBufferedPositionUs()

      Description copied from interface: `MediaPeriod`
      Returns an estimate of the position up to which data is buffered for the enabled tracks.

      This method is only called when at least one track is selected.

      Specified by:
        `getBufferedPositionUs` in interface `MediaPeriod`
      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.

    - #### seekToUs

          public long seekToUs​(long positionUs)

      Description copied from interface: `MediaPeriod`
      Attempts to seek to the specified position in microseconds.

      After this method has been called, all `SampleStream`s provided by the period are guaranteed to start from a key frame.

      This method is only called when at least one track is selected.

      Specified by:
        `seekToUs` in interface `MediaPeriod`
      Parameters:
        `positionUs` - The seek position in microseconds.
      Returns:
        The actual position to which the period was seeked, in microseconds.

    - #### getAdjustedSeekPositionUs

          public long getAdjustedSeekPositionUs​(long positionUs,
                                                SeekParameters seekParameters)

      Description copied from interface: `MediaPeriod`
      Returns the position to which a seek will be performed, given the specified seek position and `SeekParameters`.

      This method is only called after the period has been prepared.

      Specified by:
        `getAdjustedSeekPositionUs` in interface `MediaPeriod`
      Parameters:
        `positionUs` - The seek position in microseconds.
        `seekParameters` - Parameters that control how the seek is performed. Implementations may apply seek parameters on a best effort basis.
      Returns:
        The actual position to which a seek will be performed, in microseconds.

    - #### getNextLoadPositionUs

          public long getNextLoadPositionUs()

      Description copied from interface: `MediaPeriod`
      Returns the next load time, or `C.TIME_END_OF_SOURCE` if loading has finished.

      This method is only called after the period has been prepared. It may be called when no tracks are selected.

      Specified by:
        `getNextLoadPositionUs` in interface `MediaPeriod`
      Specified by:
        `getNextLoadPositionUs` in interface `SequenceableLoader`

    - #### continueLoading

          public boolean continueLoading​(long positionUs)

      Description copied from interface: `MediaPeriod`
      Attempts to continue loading.

      This method may be called both during and after the period has been prepared.

      A period may call `SequenceableLoader.Callback.onContinueLoadingRequested(SequenceableLoader)` on the `MediaPeriod.Callback` passed to `MediaPeriod.prepare(Callback, long)` to request that this method be called when the period is permitted to continue loading data. A period may do this both during and after preparation.

      Specified by:
        `continueLoading` in interface `MediaPeriod`
      Specified by:
        `continueLoading` 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.
      Returns:
        True if progress was made, meaning that `MediaPeriod.getNextLoadPositionUs()` will return a different value than prior to the call. False otherwise.

    - #### isLoading

          public boolean isLoading()

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

    - #### onPrepared

          public void onPrepared​(MediaPeriod mediaPeriod)

      Description copied from interface: `MediaPeriod.Callback`
      Called when preparation completes.

      Called on the playback thread. After invoking this method, the `MediaPeriod` can expect for `MediaPeriod.selectTracks(ExoTrackSelection[], boolean[], SampleStream[], boolean[], long)` to be called with the initial track selection.

      Specified by:
        `onPrepared` in interface `MediaPeriod.Callback`
      Parameters:
        `mediaPeriod` - The prepared `MediaPeriod`.

    - #### onContinueLoadingRequested

          public void onContinueLoadingRequested​(MediaPeriod source)

      Description copied from interface: `SequenceableLoader.Callback`
      Called by the loader to indicate that it wishes for its `SequenceableLoader.continueLoading(long)` method to be called when it can continue to load data. Called on the playback thread.
      Specified by:
        `onContinueLoadingRequested` in interface `SequenceableLoader.Callback<MediaPeriod>`