Package com.google.android.exoplayer2.source

## Class WrappingMediaSource

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

- All Implemented Interfaces:
    `MediaSource`
  Direct Known Subclasses:
    `ClippingMediaSource`, `LoopingMediaSource`, `MaskingMediaSource`

      public abstract class WrappingMediaSource
      extends CompositeMediaSource<Void>

  An abstract `MediaSource` wrapping a single child `MediaSource`.

  The implementation may want to override the following methods as needed:

  - `getMediaItem()`: Amend the `MediaItem` for this media source. This is only used before the child source is prepared.
  - `onChildSourceInfoRefreshed(Timeline)`: Called whenever the child source's `Timeline` changed. 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)`.
  - `createPeriod(com.google.android.exoplayer2.source.MediaSource.MediaPeriodId, com.google.android.exoplayer2.upstream.Allocator, long)`/`releasePeriod(com.google.android.exoplayer2.source.MediaPeriod)`: These methods create and release `MediaPeriod` instances. They typically forward to the wrapped media source and optionally wrap the returned `MediaPeriod`.

  Other methods like `prepareSourceInternal(com.google.android.exoplayer2.upstream.TransferListener)`, `CompositeMediaSource.enableInternal()`, `CompositeMediaSource.disableInternal()` or `CompositeMediaSource.releaseSourceInternal()` only need to be overwritten if required for resource management.

- - ### Nested Class Summary

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

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

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected MediaSource` | `mediaSource` | The wrapped child `MediaSource`.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `WrappingMediaSource​(MediaSource mediaSource)` | Creates the wrapping `MediaSource`.

  - ### 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`.
    `protected void` | `disableChildSource()` | Disables the child source.
    `protected void` | `enableChildSource()` | Enables the child source.
    `Timeline` | `getInitialTimeline()` | Returns the initial placeholder timeline that is returned immediately when the real timeline is not yet known, or null to let the player create an initial timeline.
    `MediaItem` | `getMediaItem()` | Returns the `MediaItem` for this media source.
    `protected MediaSource.MediaPeriodId` | `getMediaPeriodIdForChildMediaPeriodId​(MediaSource.MediaPeriodId mediaPeriodId)` | Returns the `MediaSource.MediaPeriodId` in the wrapping source corresponding to the specified `MediaSource.MediaPeriodId` in a child source.
    `protected MediaSource.MediaPeriodId` | `getMediaPeriodIdForChildMediaPeriodId​(Void childSourceId, MediaSource.MediaPeriodId mediaPeriodId)` | Returns the `MediaSource.MediaPeriodId` in the composite source corresponding to the specified `MediaSource.MediaPeriodId` in a child source.
    `protected long` | `getMediaTimeForChildMediaTime​(long mediaTimeMs)` | Returns the media time in the `MediaPeriod` of the wrapping source corresponding to the specified media time in the `MediaPeriod` of the child source.
    `protected long` | `getMediaTimeForChildMediaTime​(Void childSourceId, long mediaTimeMs)` | Returns the media time in the `MediaPeriod` of the composite source corresponding to the specified media time in the `MediaPeriod` of the child source.
    `protected int` | `getWindowIndexForChildWindowIndex​(int windowIndex)` | Returns the window index in the wrapping source corresponding to the specified window index in a child source.
    `protected int` | `getWindowIndexForChildWindowIndex​(Void childSourceId, int windowIndex)` | Returns the window index in the composite source corresponding to the specified window index in a child source.
    `boolean` | `isSingleWindow()` | Returns true if the media source is guaranteed to never have zero or more than one window.
    `protected void` | `onChildSourceInfoRefreshed​(Timeline newTimeline)` | Called when the child source info has been refreshed.
    `protected void` | `onChildSourceInfoRefreshed​(Void childSourceId, MediaSource mediaSource, Timeline newTimeline)` | Called when the source info of a child source has been refreshed.
    `protected void` | `prepareChildSource()` | Prepares the wrapped child source.
    `protected void` | `prepareSourceInternal()` | Starts source preparation and enables the source, see `BaseMediaSource.prepareSource(MediaSourceCaller, TransferListener, PlayerId)`.
    `protected void` | `prepareSourceInternal​(TransferListener mediaTransferListener)` | Starts source preparation and enables the source, see `BaseMediaSource.prepareSource(MediaSourceCaller, TransferListener, PlayerId)`.
    `protected void` | `releaseChildSource()` | Releases the child source.
    `void` | `releasePeriod​(MediaPeriod mediaPeriod)` | Releases a `MediaPeriod`.

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

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

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

- - ### Field Detail

    - #### mediaSource

          protected final MediaSource mediaSource

      The wrapped child `MediaSource`.

  - ### Constructor Detail

    - #### WrappingMediaSource

          protected WrappingMediaSource​(MediaSource mediaSource)

      Creates the wrapping `MediaSource`.
      Parameters:
        `mediaSource` - The wrapped child `MediaSource`.

  - ### Method Detail

    - #### prepareSourceInternal

          protected final void prepareSourceInternal​(@Nullable
                                                     TransferListener mediaTransferListener)

      Description copied from class: `BaseMediaSource`
      Starts source preparation and enables the source, see `BaseMediaSource.prepareSource(MediaSourceCaller, TransferListener, PlayerId)`. 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.

    - #### prepareSourceInternal

          protected void prepareSourceInternal()

      Starts source preparation and enables the source, see `BaseMediaSource.prepareSource(MediaSourceCaller, TransferListener, PlayerId)`. This method is called at most once until the next call to `CompositeMediaSource.releaseSourceInternal()`.

    - #### getInitialTimeline

          @Nullable
          public Timeline getInitialTimeline()

      Description copied from interface: `MediaSource`
      Returns the initial placeholder timeline that is returned immediately when the real timeline is not yet known, or null to let the player create an initial timeline.

      The initial timeline must use the same uids for windows and periods that the real timeline will use. It also must provide windows which are marked as dynamic to indicate that the window is expected to change when the real timeline arrives.

      Any media source which has multiple windows should typically provide such an initial timeline to make sure the player reports the correct number of windows immediately.

    - #### isSingleWindow

          public boolean isSingleWindow()

      Description copied from interface: `MediaSource`
      Returns true if the media source is guaranteed to never have zero or more than one window.

      The default implementation returns `true`.

      Returns:
        true if the source has exactly one window.

    - #### getMediaItem

          public MediaItem getMediaItem()

      Returns the `MediaItem` for this media source.

      This method can be overridden to amend the `MediaItem` of the child source. It is only used before the child source is prepared.

      See Also:
        `MediaSource.getMediaItem()`

    - #### createPeriod

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

      Creates the requested `MediaPeriod`.

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

      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)

      Releases a `MediaPeriod`.

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

      Parameters:
        `mediaPeriod` - The period to release.
      See Also:
        `MediaSource.releasePeriod(MediaPeriod)`

    - #### onChildSourceInfoRefreshed

          protected final void onChildSourceInfoRefreshed​(Void childSourceId,
                                                          MediaSource mediaSource,
                                                          Timeline newTimeline)

      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:
        `childSourceId` - The unique id used to prepare the child source.
        `mediaSource` - The child source whose source info has been refreshed.
        `newTimeline` - The timeline of the child source.

    - #### onChildSourceInfoRefreshed

          protected void onChildSourceInfoRefreshed​(Timeline newTimeline)

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

      Parameters:
        `newTimeline` - The timeline of the child source.

    - #### getWindowIndexForChildWindowIndex

          protected final int getWindowIndexForChildWindowIndex​(Void childSourceId,
                                                                int windowIndex)

      Description copied from class: `CompositeMediaSource`
      Returns the window index in the composite source corresponding to the specified window index in a child source. The default implementation does not change the window index.
      Overrides:
        `getWindowIndexForChildWindowIndex` in class `CompositeMediaSource<Void>`
      Parameters:
        `childSourceId` - The unique id used to prepare the child source.
        `windowIndex` - A window index of the child source.
      Returns:
        The corresponding window index in the composite source.

    - #### getWindowIndexForChildWindowIndex

          protected int getWindowIndexForChildWindowIndex​(int windowIndex)

      Returns the window index in the wrapping source corresponding to the specified window index in a child source. The default implementation does not change the window index.
      Parameters:
        `windowIndex` - A window index of the child source.
      Returns:
        The corresponding window index in the wrapping source.

    - #### getMediaPeriodIdForChildMediaPeriodId

          @Nullable
          protected final MediaSource.MediaPeriodId getMediaPeriodIdForChildMediaPeriodId​(Void childSourceId,
                                                                                          MediaSource.MediaPeriodId mediaPeriodId)

      Description copied from class: `CompositeMediaSource`
      Returns the `MediaSource.MediaPeriodId` in the composite source corresponding to the specified `MediaSource.MediaPeriodId` in a child source. The default implementation does not change the media period id.
      Overrides:
        `getMediaPeriodIdForChildMediaPeriodId` in class `CompositeMediaSource<Void>`
      Parameters:
        `childSourceId` - The unique id used to prepare the child source.
        `mediaPeriodId` - A `MediaSource.MediaPeriodId` of the child source.
      Returns:
        The corresponding `MediaSource.MediaPeriodId` in the composite source. Null if no corresponding media period id can be determined.

    - #### getMediaPeriodIdForChildMediaPeriodId

          @Nullable
          protected MediaSource.MediaPeriodId getMediaPeriodIdForChildMediaPeriodId​(MediaSource.MediaPeriodId mediaPeriodId)

      Returns the `MediaSource.MediaPeriodId` in the wrapping source corresponding to the specified `MediaSource.MediaPeriodId` in a child source. The default implementation does not change the media period id.
      Parameters:
        `mediaPeriodId` - A `MediaSource.MediaPeriodId` of the child source.
      Returns:
        The corresponding `MediaSource.MediaPeriodId` in the wrapping source. Null if no corresponding media period id can be determined.

    - #### getMediaTimeForChildMediaTime

          protected final long getMediaTimeForChildMediaTime​(Void childSourceId,
                                                             long mediaTimeMs)

      Description copied from class: `CompositeMediaSource`
      Returns the media time in the `MediaPeriod` of the composite source corresponding to the specified media time in the `MediaPeriod` of the child source. The default implementation does not change the media time.
      Overrides:
        `getMediaTimeForChildMediaTime` in class `CompositeMediaSource<Void>`
      Parameters:
        `childSourceId` - The unique id used to prepare the child source.
        `mediaTimeMs` - A media time in the `MediaPeriod` of the child source, in milliseconds.
      Returns:
        The corresponding media time in the `MediaPeriod` of the composite source, in milliseconds.

    - #### getMediaTimeForChildMediaTime

          protected long getMediaTimeForChildMediaTime​(long mediaTimeMs)

      Returns the media time in the `MediaPeriod` of the wrapping source corresponding to the specified media time in the `MediaPeriod` of the child source. The default implementation does not change the media time.
      Parameters:
        `mediaTimeMs` - A media time in the `MediaPeriod` of the child source, in milliseconds.
      Returns:
        The corresponding media time in the `MediaPeriod` of the wrapping source, in milliseconds.

    - #### prepareChildSource

          protected final void prepareChildSource()

      Prepares the wrapped child source.

      `onChildSourceInfoRefreshed(Timeline)` will be called when the child source updates its timeline.

      If sources aren't explicitly released with `releaseChildSource()` they will be released in `CompositeMediaSource.releaseSourceInternal()`.

    - #### enableChildSource

          protected final void enableChildSource()

      Enables the child source.

    - #### disableChildSource

          protected final void disableChildSource()

      Disables the child source.

    - #### releaseChildSource

          protected final void releaseChildSource()

      Releases the child source.