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.ClippingMediaSource

- All Implemented Interfaces:
    `MediaSource`

      public final class ClippingMediaSource
      extends CompositeMediaSource<Void>

  `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.MediaPeriodId, MediaSource.MediaSourceCaller`

  - ### 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)` | Returns a new `MediaPeriod` identified by `periodId`.
    `MediaItem` | `getMediaItem()` | Returns the `MediaItem` whose media is provided by the source.
    `void` | `maybeThrowSourceInfoRefreshError()` | Throws any pending error encountered while loading or refreshing source information.
    `protected void` | `onChildSourceInfoRefreshed​(Void id, MediaSource mediaSource, Timeline timeline)` | Called when the source info of a child source has been refreshed.
    `protected void` | `prepareSourceInternal​(TransferListener mediaTransferListener)` | Starts source preparation and enables the source, see `BaseMediaSource.prepareSource(MediaSourceCaller, TransferListener)`.
    `void` | `releasePeriod​(MediaPeriod mediaPeriod)` | Releases the period.
    `protected void` | `releaseSourceInternal()` | Releases the source, see `BaseMediaSource.releaseSource(MediaSourceCaller)`.

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

      `disableChildSource, disableInternal, enableChildSource, enableInternal, getMediaPeriodIdForChildMediaPeriodId, getMediaTimeForChildMediaTime, getWindowIndexForChildWindowIndex, prepareChildSource, releaseChildSource`

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

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

    - ### 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.MediaSource

      `getInitialTimeline, isSingleWindow`

- - ### 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

    - #### getMediaItem

          public MediaItem getMediaItem()

      Description copied from interface: `MediaSource`
      Returns the `MediaItem` whose media is provided by the source.

    - #### prepareSourceInternal

          protected void prepareSourceInternal​(@Nullable
                                               TransferListener mediaTransferListener)

      Description copied from class: `BaseMediaSource`
      Starts source preparation and enables the source, see `BaseMediaSource.prepareSource(MediaSourceCaller, TransferListener)`. This method is called at most once until the next call to `BaseMediaSource.releaseSourceInternal()`.
      Overrides:
        `prepareSourceInternal` in class `CompositeMediaSource<Void>`
      Parameters:
        `mediaTransferListener` - The transfer listener which should be informed of any media data transfers. May be null if no listener is available. Note that this listener should usually be only informed of transfers related to the media loads and not of auxiliary loads for manifests and other data.

    - #### 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)`.

      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 interface: `MediaSource`
      Returns a new `MediaPeriod` identified by `periodId`.

      Should not be called directly from application code.

      Must only be called if the source is enabled.

      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`.

    - #### releasePeriod

          public void releasePeriod​(MediaPeriod mediaPeriod)

      Description copied from interface: `MediaSource`
      Releases the period.

      Should not be called directly from application code.

      Parameters:
        `mediaPeriod` - The period to release.

    - #### 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​(Void id,
                                                    MediaSource mediaSource,
                                                    Timeline timeline)

      Description copied from class: `CompositeMediaSource`
      Called when the source info of a child source has been refreshed.
      Specified by:
        `onChildSourceInfoRefreshed` in class `CompositeMediaSource<Void>`
      Parameters:
        `id` - The unique id used to prepare the child source.
        `mediaSource` - The child source whose source info has been refreshed.
        `timeline` - The timeline of the child source.