Package com.google.android.exoplayer2.source

## Class ConcatenatingMediaSource

- java.lang.Object
- - com.google.android.exoplayer2.source.BaseMediaSource
  - - com.google.android.exoplayer2.source.CompositeMediaSource<com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder>
    - - com.google.android.exoplayer2.source.ConcatenatingMediaSource

- All Implemented Interfaces:
    `MediaSource`

      public final class ConcatenatingMediaSource
      extends CompositeMediaSource<com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder>

  Concatenates multiple `MediaSource`s. The list of `MediaSource`s can be modified during playback. It is valid for the same `MediaSource` instance to be present more than once in the concatenation. Access to this class is thread-safe.

- - ### Nested Class Summary

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

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

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ConcatenatingMediaSource​(boolean isAtomic, boolean useLazyPreparation, ShuffleOrder shuffleOrder, MediaSource... mediaSources)` |
    `ConcatenatingMediaSource​(boolean isAtomic, MediaSource... mediaSources)` |
    `ConcatenatingMediaSource​(boolean isAtomic, ShuffleOrder shuffleOrder, MediaSource... mediaSources)` |
    `ConcatenatingMediaSource​(MediaSource... mediaSources)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addMediaSource​(int index, MediaSource mediaSource)` | Adds a `MediaSource` to the playlist.
    `void` | `addMediaSource​(int index, MediaSource mediaSource, Handler handler, Runnable onCompletionAction)` | Adds a `MediaSource` to the playlist and executes a custom action on completion.
    `void` | `addMediaSource​(MediaSource mediaSource)` | Appends a `MediaSource` to the playlist.
    `void` | `addMediaSource​(MediaSource mediaSource, Handler handler, Runnable onCompletionAction)` | Appends a `MediaSource` to the playlist and executes a custom action on completion.
    `void` | `addMediaSources​(int index, Collection<MediaSource> mediaSources)` | Adds multiple `MediaSource`s to the playlist.
    `void` | `addMediaSources​(int index, Collection<MediaSource> mediaSources, Handler handler, Runnable onCompletionAction)` | Adds multiple `MediaSource`s to the playlist and executes a custom action on completion.
    `void` | `addMediaSources​(Collection<MediaSource> mediaSources)` | Appends multiple `MediaSource`s to the playlist.
    `void` | `addMediaSources​(Collection<MediaSource> mediaSources, Handler handler, Runnable onCompletionAction)` | Appends multiple `MediaSource`s to the playlist and executes a custom action on completion.
    `void` | `clear()` | Clears the playlist.
    `void` | `clear​(Handler handler, Runnable onCompletionAction)` | Clears the playlist and executes a custom action on completion.
    `MediaPeriod` | `createPeriod​(MediaSource.MediaPeriodId id, Allocator allocator, long startPositionUs)` | Returns a new `MediaPeriod` identified by `periodId`.
    `protected void` | `disableInternal()` | Disables the source, see `BaseMediaSource.disable(MediaSourceCaller)`.
    `protected void` | `enableInternal()` | Enables the source, see `BaseMediaSource.enable(MediaSourceCaller)`.
    `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` whose media is provided by the source.
    `protected MediaSource.MediaPeriodId` | `getMediaPeriodIdForChildMediaPeriodId​(com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder mediaSourceHolder, MediaSource.MediaPeriodId mediaPeriodId)` | Returns the `MediaSource.MediaPeriodId` in the composite source corresponding to the specified `MediaSource.MediaPeriodId` in a child source.
    `MediaSource` | `getMediaSource​(int index)` | Returns the `MediaSource` at a specified index.
    `int` | `getSize()` | Returns the number of media sources in the playlist.
    `protected int` | `getWindowIndexForChildWindowIndex​(com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder mediaSourceHolder, 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.
    `void` | `moveMediaSource​(int currentIndex, int newIndex)` | Moves an existing `MediaSource` within the playlist.
    `void` | `moveMediaSource​(int currentIndex, int newIndex, Handler handler, Runnable onCompletionAction)` | Moves an existing `MediaSource` within the playlist and executes a custom action on completion.
    `protected void` | `onChildSourceInfoRefreshed​(com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder mediaSourceHolder, 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, PlayerId)`.
    `void` | `releasePeriod​(MediaPeriod mediaPeriod)` | Releases the period.
    `protected void` | `releaseSourceInternal()` | Releases the source, see `BaseMediaSource.releaseSource(MediaSourceCaller)`.
    `MediaSource` | `removeMediaSource​(int index)` | Removes a `MediaSource` from the playlist.
    `MediaSource` | `removeMediaSource​(int index, Handler handler, Runnable onCompletionAction)` | Removes a `MediaSource` from the playlist and executes a custom action on completion.
    `void` | `removeMediaSourceRange​(int fromIndex, int toIndex)` | Removes a range of `MediaSource`s from the playlist, by specifying an initial index (included) and a final index (excluded).
    `void` | `removeMediaSourceRange​(int fromIndex, int toIndex, Handler handler, Runnable onCompletionAction)` | Removes a range of `MediaSource`s from the playlist, by specifying an initial index (included) and a final index (excluded), and executes a custom action on completion.
    `void` | `setShuffleOrder​(ShuffleOrder shuffleOrder)` | Sets a new shuffle order to use when shuffling the child media sources.
    `void` | `setShuffleOrder​(ShuffleOrder shuffleOrder, Handler handler, Runnable onCompletionAction)` | Sets a new shuffle order to use when shuffling the child media sources.

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

      `disableChildSource, enableChildSource, getMediaTimeForChildMediaTime, maybeThrowSourceInfoRefreshError, 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

    - #### ConcatenatingMediaSource

          public ConcatenatingMediaSource​(MediaSource... mediaSources)

      Parameters:
        `mediaSources` - The `MediaSource`s to concatenate. It is valid for the same `MediaSource` instance to be present more than once in the array.

    - #### ConcatenatingMediaSource

          public ConcatenatingMediaSource​(boolean isAtomic,
                                          MediaSource... mediaSources)

      Parameters:
        `isAtomic` - Whether the concatenating media source will be treated as atomic, i.e., treated as a single item for repeating and shuffling.
        `mediaSources` - The `MediaSource`s to concatenate. It is valid for the same `MediaSource` instance to be present more than once in the array.

    - #### ConcatenatingMediaSource

          public ConcatenatingMediaSource​(boolean isAtomic,
                                          ShuffleOrder shuffleOrder,
                                          MediaSource... mediaSources)

      Parameters:
        `isAtomic` - Whether the concatenating media source will be treated as atomic, i.e., treated as a single item for repeating and shuffling.
        `shuffleOrder` - The `ShuffleOrder` to use when shuffling the child media sources.
        `mediaSources` - The `MediaSource`s to concatenate. It is valid for the same `MediaSource` instance to be present more than once in the array.

    - #### ConcatenatingMediaSource

          public ConcatenatingMediaSource​(boolean isAtomic,
                                          boolean useLazyPreparation,
                                          ShuffleOrder shuffleOrder,
                                          MediaSource... mediaSources)

      Parameters:
        `isAtomic` - Whether the concatenating media source will be treated as atomic, i.e., treated as a single item for repeating and shuffling.
        `useLazyPreparation` - Whether playlist items are prepared lazily. If false, all manifest loads and other initial preparation steps happen immediately. If true, these initial preparations are triggered only when the player starts buffering the media.
        `shuffleOrder` - The `ShuffleOrder` to use when shuffling the child media sources.
        `mediaSources` - The `MediaSource`s to concatenate. It is valid for the same `MediaSource` instance to be present more than once in the array.

  - ### Method Detail

    - #### getInitialTimeline

          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.

    - #### addMediaSource

          public void addMediaSource​(MediaSource mediaSource)

      Appends a `MediaSource` to the playlist.
      Parameters:
        `mediaSource` - The `MediaSource` to be added to the list.

    - #### addMediaSource

          public void addMediaSource​(MediaSource mediaSource,
                                     Handler handler,
                                     Runnable onCompletionAction)

      Appends a `MediaSource` to the playlist and executes a custom action on completion.
      Parameters:
        `mediaSource` - The `MediaSource` to be added to the list.
        `handler` - The `Handler` to run `onCompletionAction`.
        `onCompletionAction` - A `Runnable` which is executed immediately after the media source has been added to the playlist.

    - #### addMediaSource

          public void addMediaSource​(int index,
                                     MediaSource mediaSource)

      Adds a `MediaSource` to the playlist.
      Parameters:
        `index` - The index at which the new `MediaSource` will be inserted. This index must be in the range of 0 <= index <= `getSize()`.
        `mediaSource` - The `MediaSource` to be added to the list.

    - #### addMediaSource

          public void addMediaSource​(int index,
                                     MediaSource mediaSource,
                                     Handler handler,
                                     Runnable onCompletionAction)

      Adds a `MediaSource` to the playlist and executes a custom action on completion.
      Parameters:
        `index` - The index at which the new `MediaSource` will be inserted. This index must be in the range of 0 <= index <= `getSize()`.
        `mediaSource` - The `MediaSource` to be added to the list.
        `handler` - The `Handler` to run `onCompletionAction`.
        `onCompletionAction` - A `Runnable` which is executed immediately after the media source has been added to the playlist.

    - #### addMediaSources

          public void addMediaSources​(Collection<MediaSource> mediaSources)

      Appends multiple `MediaSource`s to the playlist.
      Parameters:
        `mediaSources` - A collection of `MediaSource`s to be added to the list. The media sources are added in the order in which they appear in this collection.

    - #### addMediaSources

          public void addMediaSources​(Collection<MediaSource> mediaSources,
                                      Handler handler,
                                      Runnable onCompletionAction)

      Appends multiple `MediaSource`s to the playlist and executes a custom action on completion.
      Parameters:
        `mediaSources` - A collection of `MediaSource`s to be added to the list. The media sources are added in the order in which they appear in this collection.
        `handler` - The `Handler` to run `onCompletionAction`.
        `onCompletionAction` - A `Runnable` which is executed immediately after the media sources have been added to the playlist.

    - #### addMediaSources

          public void addMediaSources​(int index,
                                      Collection<MediaSource> mediaSources)

      Adds multiple `MediaSource`s to the playlist.
      Parameters:
        `index` - The index at which the new `MediaSource`s will be inserted. This index must be in the range of 0 <= index <= `getSize()`.
        `mediaSources` - A collection of `MediaSource`s to be added to the list. The media sources are added in the order in which they appear in this collection.

    - #### addMediaSources

          public void addMediaSources​(int index,
                                      Collection<MediaSource> mediaSources,
                                      Handler handler,
                                      Runnable onCompletionAction)

      Adds multiple `MediaSource`s to the playlist and executes a custom action on completion.
      Parameters:
        `index` - The index at which the new `MediaSource`s will be inserted. This index must be in the range of 0 <= index <= `getSize()`.
        `mediaSources` - A collection of `MediaSource`s to be added to the list. The media sources are added in the order in which they appear in this collection.
        `handler` - The `Handler` to run `onCompletionAction`.
        `onCompletionAction` - A `Runnable` which is executed immediately after the media sources have been added to the playlist.

    - #### removeMediaSource

          public MediaSource removeMediaSource​(int index)

      Removes a `MediaSource` from the playlist.

      Note: If you want to move the instance, it's preferable to use `moveMediaSource(int, int)` instead.

      Note: If you want to remove a set of contiguous sources, it's preferable to use `removeMediaSourceRange(int, int)` instead.

      Parameters:
        `index` - The index at which the media source will be removed. This index must be in the range of 0 <= index < `getSize()`.
      Returns:
        The removed `MediaSource`.

    - #### removeMediaSource

          public MediaSource removeMediaSource​(int index,
                                               Handler handler,
                                               Runnable onCompletionAction)

      Removes a `MediaSource` from the playlist and executes a custom action on completion.

      Note: If you want to move the instance, it's preferable to use `moveMediaSource(int, int, Handler, Runnable)` instead.

      Note: If you want to remove a set of contiguous sources, it's preferable to use `removeMediaSourceRange(int, int, Handler, Runnable)` instead.

      Parameters:
        `index` - The index at which the media source will be removed. This index must be in the range of 0 <= index < `getSize()`.
        `handler` - The `Handler` to run `onCompletionAction`.
        `onCompletionAction` - A `Runnable` which is executed immediately after the media source has been removed from the playlist.
      Returns:
        The removed `MediaSource`.

    - #### removeMediaSourceRange

          public void removeMediaSourceRange​(int fromIndex,
                                             int toIndex)

      Removes a range of `MediaSource`s from the playlist, by specifying an initial index (included) and a final index (excluded).

      Note: when specified range is empty, no actual media source is removed and no exception is thrown.

      Parameters:
        `fromIndex` - The initial range index, pointing to the first media source that will be removed. This index must be in the range of 0 <= index <= `getSize()`.
        `toIndex` - The final range index, pointing to the first media source that will be left untouched. This index must be in the range of 0 <= index <= `getSize()`.
      Throws:
        `IndexOutOfBoundsException` - When the range is malformed, i.e. `fromIndex` < 0, `toIndex` > `getSize()`, `fromIndex` > `toIndex`

    - #### removeMediaSourceRange

          public void removeMediaSourceRange​(int fromIndex,
                                             int toIndex,
                                             Handler handler,
                                             Runnable onCompletionAction)

      Removes a range of `MediaSource`s from the playlist, by specifying an initial index (included) and a final index (excluded), and executes a custom action on completion.

      Note: when specified range is empty, no actual media source is removed and no exception is thrown.

      Parameters:
        `fromIndex` - The initial range index, pointing to the first media source that will be removed. This index must be in the range of 0 <= index <= `getSize()`.
        `toIndex` - The final range index, pointing to the first media source that will be left untouched. This index must be in the range of 0 <= index <= `getSize()`.
        `handler` - The `Handler` to run `onCompletionAction`.
        `onCompletionAction` - A `Runnable` which is executed immediately after the media source range has been removed from the playlist.
      Throws:
        `IllegalArgumentException` - When the range is malformed, i.e. `fromIndex` < 0, `toIndex` > `getSize()`, `fromIndex` > `toIndex`

    - #### moveMediaSource

          public void moveMediaSource​(int currentIndex,
                                      int newIndex)

      Moves an existing `MediaSource` within the playlist.
      Parameters:
        `currentIndex` - The current index of the media source in the playlist. This index must be in the range of 0 <= index < `getSize()`.
        `newIndex` - The target index of the media source in the playlist. This index must be in the range of 0 <= index < `getSize()`.

    - #### moveMediaSource

          public void moveMediaSource​(int currentIndex,
                                      int newIndex,
                                      Handler handler,
                                      Runnable onCompletionAction)

      Moves an existing `MediaSource` within the playlist and executes a custom action on completion.
      Parameters:
        `currentIndex` - The current index of the media source in the playlist. This index must be in the range of 0 <= index < `getSize()`.
        `newIndex` - The target index of the media source in the playlist. This index must be in the range of 0 <= index < `getSize()`.
        `handler` - The `Handler` to run `onCompletionAction`.
        `onCompletionAction` - A `Runnable` which is executed immediately after the media source has been moved.

    - #### clear

          public void clear()

      Clears the playlist.

    - #### clear

          public void clear​(Handler handler,
                            Runnable onCompletionAction)

      Clears the playlist and executes a custom action on completion.
      Parameters:
        `handler` - The `Handler` to run `onCompletionAction`.
        `onCompletionAction` - A `Runnable` which is executed immediately after the playlist has been cleared.

    - #### getSize

          public int getSize()

      Returns the number of media sources in the playlist.

    - #### getMediaSource

          public MediaSource getMediaSource​(int index)

      Returns the `MediaSource` at a specified index.
      Parameters:
        `index` - An index in the range of 0 <= index <= `getSize()`.
      Returns:
        The `MediaSource` at this index.

    - #### setShuffleOrder

          public void setShuffleOrder​(ShuffleOrder shuffleOrder)

      Sets a new shuffle order to use when shuffling the child media sources.
      Parameters:
        `shuffleOrder` - A `ShuffleOrder`.

    - #### setShuffleOrder

          public void setShuffleOrder​(ShuffleOrder shuffleOrder,
                                      Handler handler,
                                      Runnable onCompletionAction)

      Sets a new shuffle order to use when shuffling the child media sources.
      Parameters:
        `shuffleOrder` - A `ShuffleOrder`.
        `handler` - The `Handler` to run `onCompletionAction`.
        `onCompletionAction` - A `Runnable` which is executed immediately after the shuffle order has been changed.

    - #### 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, PlayerId)`. This method is called at most once until the next call to `BaseMediaSource.releaseSourceInternal()`.
      Overrides:
        `prepareSourceInternal` in class `CompositeMediaSource<com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder>`
      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.

    - #### enableInternal

          protected void enableInternal()

      Description copied from class: `BaseMediaSource`
      Enables the source, see `BaseMediaSource.enable(MediaSourceCaller)`.
      Overrides:
        `enableInternal` in class `CompositeMediaSource<com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder>`

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

    - #### disableInternal

          protected void disableInternal()

      Description copied from class: `BaseMediaSource`
      Disables the source, see `BaseMediaSource.disable(MediaSourceCaller)`.
      Overrides:
        `disableInternal` in class `CompositeMediaSource<com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder>`

    - #### 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<com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder>`

    - #### onChildSourceInfoRefreshed

          protected void onChildSourceInfoRefreshed​(com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder mediaSourceHolder,
                                                    MediaSource mediaSource,
                                                    Timeline timeline)

      Called when the source info of a child source has been refreshed.
      Specified by:
        `onChildSourceInfoRefreshed` in class `CompositeMediaSource<com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder>`
      Parameters:
        `mediaSourceHolder` - 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.

    - #### getMediaPeriodIdForChildMediaPeriodId

          @Nullable
          protected MediaSource.MediaPeriodId getMediaPeriodIdForChildMediaPeriodId​(com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder mediaSourceHolder,
                                                                                    MediaSource.MediaPeriodId mediaPeriodId)

      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<com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder>`
      Parameters:
        `mediaSourceHolder` - 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.

    - #### getWindowIndexForChildWindowIndex

          protected int getWindowIndexForChildWindowIndex​(com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder mediaSourceHolder,
                                                          int windowIndex)

      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<com.google.android.exoplayer2.source.ConcatenatingMediaSource.MediaSourceHolder>`
      Parameters:
        `mediaSourceHolder` - 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.