Package com.google.android.exoplayer2.source

## Class ClippingMediaSource

- java.lang.Object
- - com.google.android.exoplayer2.source.BaseMediaSource
  - - com.google.android.exoplayer2.source.CompositeMediaSource<Void>
    - - com.google.android.exoplayer2.source.WrappingMediaSource
      - - com.google.android.exoplayer2.source.ClippingMediaSource

- All Implemented Interfaces:
    `MediaSource`

      public final class ClippingMediaSource
      extends WrappingMediaSource

  `MediaSource` that wraps a source and clips its timeline based on specified start/end positions. The wrapped source must consist of a single period.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `ClippingMediaSource.IllegalClippingException` | Thrown when a `ClippingMediaSource` cannot clip its wrapped source.

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

      `MediaSource.Factory, MediaSource.MediaPeriodId, MediaSource.MediaSourceCaller`

  - ### Field Summary

    - ### Fields inherited from class com.google.android.exoplayer2.source.WrappingMediaSource

      `mediaSource`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ClippingMediaSource​(MediaSource mediaSource, long durationUs)` | Creates a new clipping source that wraps the specified source and provides samples from the default position for the specified duration.
    `ClippingMediaSource​(MediaSource mediaSource, long startPositionUs, long endPositionUs)` | Creates a new clipping source that wraps the specified source and provides samples between the specified start and end position.
    `ClippingMediaSource​(MediaSource mediaSource, long startPositionUs, long endPositionUs, boolean enableInitialDiscontinuity, boolean allowDynamicClippingUpdates, boolean relativeToDefaultPosition)` | Creates a new clipping source that wraps the specified source.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `MediaPeriod` | `createPeriod​(MediaSource.MediaPeriodId id, Allocator allocator, long startPositionUs)` | Creates the requested `MediaPeriod`.
    `void` | `maybeThrowSourceInfoRefreshError()` | Throws any pending error encountered while loading or refreshing source information.
    `protected void` | `onChildSourceInfoRefreshed​(Timeline newTimeline)` | Called when the child source info has been refreshed.
    `void` | `releasePeriod​(MediaPeriod mediaPeriod)` | Releases a `MediaPeriod`.
    `protected void` | `releaseSourceInternal()` | Releases the source, see `BaseMediaSource.releaseSource(MediaSourceCaller)`.

    - ### Methods inherited from class com.google.android.exoplayer2.source.WrappingMediaSource

      `disableChildSource, enableChildSource, getInitialTimeline, getMediaItem, getMediaPeriodIdForChildMediaPeriodId, getMediaPeriodIdForChildMediaPeriodId, getMediaTimeForChildMediaTime, getMediaTimeForChildMediaTime, getWindowIndexForChildWindowIndex, getWindowIndexForChildWindowIndex, isSingleWindow, onChildSourceInfoRefreshed, prepareChildSource, prepareSourceInternal, prepareSourceInternal, releaseChildSource`

    - ### Methods inherited from class com.google.android.exoplayer2.source.CompositeMediaSource

      `disableChildSource, disableInternal, enableChildSource, enableInternal, prepareChildSource, releaseChildSource`

    - ### Methods inherited from class com.google.android.exoplayer2.source.BaseMediaSource

      `addDrmEventListener, addEventListener, createDrmEventDispatcher, createDrmEventDispatcher, createEventDispatcher, createEventDispatcher, createEventDispatcher, disable, enable, getPlayerId, isEnabled, prepareSource, prepareSource, refreshSourceInfo, releaseSource, removeDrmEventListener, removeEventListener`

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

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

- - ### Constructor Detail

    - #### ClippingMediaSource

          public ClippingMediaSource​(MediaSource mediaSource,
                                     long startPositionUs,
                                     long endPositionUs)

      Creates a new clipping source that wraps the specified source and provides samples between the specified start and end position.
      Parameters:
        `mediaSource` - The single-period source to wrap.
        `startPositionUs` - The start position within `mediaSource`'s window at which to start providing samples, in microseconds.
        `endPositionUs` - The end position within `mediaSource`'s window at which to stop providing samples, in microseconds. Specify `C.TIME_END_OF_SOURCE` to provide samples from the specified start point up to the end of the source. Specifying a position that exceeds the `mediaSource`'s duration will also result in the end of the source not being clipped.

    - #### ClippingMediaSource

          public ClippingMediaSource​(MediaSource mediaSource,
                                     long durationUs)

      Creates a new clipping source that wraps the specified source and provides samples from the default position for the specified duration.
      Parameters:
        `mediaSource` - The single-period source to wrap.
        `durationUs` - The duration from the default position in the window in `mediaSource`'s timeline at which to stop providing samples. Specifying a duration that exceeds the `mediaSource`'s duration will result in the end of the source not being clipped.

    - #### ClippingMediaSource

          public ClippingMediaSource​(MediaSource mediaSource,
                                     long startPositionUs,
                                     long endPositionUs,
                                     boolean enableInitialDiscontinuity,
                                     boolean allowDynamicClippingUpdates,
                                     boolean relativeToDefaultPosition)

      Creates a new clipping source that wraps the specified source.

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

      For live streams, if the clipping positions should move with the live window, pass `true` to `allowDynamicClippingUpdates`. Otherwise, the live stream ends when the playback reaches `endPositionUs` in the last reported live window at the time a media period was created.

      Parameters:
        `mediaSource` - The single-period source to wrap.
        `startPositionUs` - The start position at which to start providing samples, in microseconds. If `relativeToDefaultPosition` is `false`, this position is relative to the start of the window in `mediaSource`'s timeline. If `relativeToDefaultPosition` is `true`, this position is relative to the default position in the window in `mediaSource`'s timeline.
        `endPositionUs` - The end position at which to stop providing samples, in microseconds. Specify `C.TIME_END_OF_SOURCE` to provide samples from the specified start point up to the end of the source. Specifying a position that exceeds the `mediaSource`'s duration will also result in the end of the source not being clipped. If `relativeToDefaultPosition` is `false`, the specified position is relative to the start of the window in `mediaSource`'s timeline. If `relativeToDefaultPosition` is `true`, this position is relative to the default position in the window in `mediaSource`'s timeline.
        `enableInitialDiscontinuity` - Whether the initial discontinuity should be enabled.
        `allowDynamicClippingUpdates` - Whether the clipping of active media periods moves with a live window. If `false`, playback ends when it reaches `endPositionUs` in the last reported live window at the time a media period was created.
        `relativeToDefaultPosition` - Whether `startPositionUs` and `endPositionUs` are relative to the default position in the window in `mediaSource`'s timeline.

  - ### Method Detail

    - #### maybeThrowSourceInfoRefreshError

          public void maybeThrowSourceInfoRefreshError()
                                                throws IOException

      Description copied from interface: `MediaSource`
      Throws any pending error encountered while loading or refreshing source information.

      Should not be called directly from application code.

      Must only be called after `MediaSource.prepareSource(MediaSourceCaller, TransferListener, PlayerId)`.

      Specified by:
        `maybeThrowSourceInfoRefreshError` in interface `MediaSource`
      Overrides:
        `maybeThrowSourceInfoRefreshError` in class `CompositeMediaSource<Void>`
      Throws:
        `IOException`

    - #### createPeriod

          public MediaPeriod createPeriod​(MediaSource.MediaPeriodId id,
                                          Allocator allocator,
                                          long startPositionUs)

      Description copied from class: `WrappingMediaSource`
      Creates the requested `MediaPeriod`.

      This method typically forwards to the wrapped media source and optionally wraps the returned `MediaPeriod`.

      Specified by:
        `createPeriod` in interface `MediaSource`
      Overrides:
        `createPeriod` in class `WrappingMediaSource`
      Parameters:
        `id` - The identifier of the period.
        `allocator` - An `Allocator` from which to obtain media buffer allocations.
        `startPositionUs` - The expected start position, in microseconds.
      Returns:
        A new `MediaPeriod`.
      See Also:
        `MediaSource.createPeriod(MediaPeriodId, Allocator, long)`

    - #### releasePeriod

          public void releasePeriod​(MediaPeriod mediaPeriod)

      Description copied from class: `WrappingMediaSource`
      Releases a `MediaPeriod`.

      This method typically forwards to the wrapped media source and optionally unwraps the provided `MediaPeriod`.

      Specified by:
        `releasePeriod` in interface `MediaSource`
      Overrides:
        `releasePeriod` in class `WrappingMediaSource`
      Parameters:
        `mediaPeriod` - The period to release.
      See Also:
        `MediaSource.releasePeriod(MediaPeriod)`

    - #### releaseSourceInternal

          protected void releaseSourceInternal()

      Description copied from class: `BaseMediaSource`
      Releases the source, see `BaseMediaSource.releaseSource(MediaSourceCaller)`. This method is called exactly once after each call to `BaseMediaSource.prepareSourceInternal(TransferListener)`.
      Overrides:
        `releaseSourceInternal` in class `CompositeMediaSource<Void>`

    - #### onChildSourceInfoRefreshed

          protected void onChildSourceInfoRefreshed​(Timeline newTimeline)

      Description copied from class: `WrappingMediaSource`
      Called when the child source info has been refreshed.

      This `Timeline` can be amended if needed, for example using `ForwardingTimeline`. The `Timeline` for the wrapping source needs to be published with `BaseMediaSource.refreshSourceInfo(Timeline)`.

      Overrides:
        `onChildSourceInfoRefreshed` in class `WrappingMediaSource`
      Parameters:
        `newTimeline` - The timeline of the child source.