ConcatenatingMediaSource

Artifact: androidx.media3:media3-exoplayer

Kotlin |Java

@UnstableApi
public final class ConcatenatingMediaSource extends CompositeMediaSource

java.lang.Object
↳	androidx.media3.exoplayer.source.BaseMediaSource
	↳	androidx.media3.exoplayer.source.CompositeMediaSource
		↳	androidx.media3.exoplayer.source.ConcatenatingMediaSource

Concatenates multiple MediaSource instances. The list of MediaSource instances 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.

Summary

Public constructors
`ConcatenatingMediaSource(MediaSource[] mediaSources)`
`ConcatenatingMediaSource(boolean isAtomic, MediaSource[] mediaSources)`
`ConcatenatingMediaSource( boolean isAtomic, ShuffleOrder shuffleOrder, MediaSource[] mediaSources )`
`ConcatenatingMediaSource( boolean isAtomic, boolean useLazyPreparation, ShuffleOrder shuffleOrder, MediaSource[] mediaSources )`

Public methods
`synchronized void`	`addMediaSource(MediaSource mediaSource)` Appends a `MediaSource` to the playlist.
`synchronized void`	`addMediaSource(int index, MediaSource mediaSource)` Adds a `MediaSource` to the playlist.
`synchronized void`	`addMediaSource( MediaSource mediaSource, Handler handler, Runnable onCompletionAction )` Appends a `MediaSource` to the playlist and executes a custom action on completion.
`synchronized void`	`addMediaSource( int index, MediaSource mediaSource, Handler handler, Runnable onCompletionAction )` Adds a `MediaSource` to the playlist and executes a custom action on completion.
`synchronized void`	`addMediaSources(Collection<MediaSource> mediaSources)` Appends multiple `MediaSource`s to the playlist.
`synchronized void`	`addMediaSources(int index, Collection<MediaSource> mediaSources)` Adds multiple `MediaSource`s to the playlist.
`synchronized void`	`addMediaSources( Collection<MediaSource> mediaSources, Handler handler, Runnable onCompletionAction )` Appends multiple `MediaSource`s to the playlist and executes a custom action on completion.
`synchronized 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.
`synchronized void`	`clear()` Clears the playlist.
`synchronized 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`.
`synchronized 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.
`synchronized MediaSource`	`getMediaSource(int index)` Returns the `MediaSource` at a specified index.
`synchronized int`	`getSize()` Returns the number of media sources in the playlist.
`boolean`	`isSingleWindow()` Returns true if the media source is guaranteed to never have zero or more than one window.
`synchronized void`	`moveMediaSource(int currentIndex, int newIndex)` Moves an existing `MediaSource` within the playlist.
`synchronized void`	`moveMediaSource( int currentIndex, int newIndex, Handler handler, Runnable onCompletionAction )` Moves an existing `MediaSource` within the playlist and executes a custom action on completion.
`void`	`releasePeriod(MediaPeriod mediaPeriod)` Releases the period.
`synchronized MediaSource`	`removeMediaSource(int index)` Removes a `MediaSource` from the playlist.
`synchronized MediaSource`	`removeMediaSource( int index, Handler handler, Runnable onCompletionAction )` Removes a `MediaSource` from the playlist and executes a custom action on completion.
`synchronized 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).
`synchronized 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.
`synchronized void`	`setShuffleOrder(ShuffleOrder shuffleOrder)` Sets a new shuffle order to use when shuffling the child media sources.
`synchronized void`	`setShuffleOrder( ShuffleOrder shuffleOrder, Handler handler, Runnable onCompletionAction )` Sets a new shuffle order to use when shuffling the child media sources.

Protected methods
`void`	`disableInternal()` Disables the source, see `disable`.
`void`	`enableInternal()` Enables the source, see `enable`.
`synchronized void`	`prepareSourceInternal(@Nullable TransferListener mediaTransferListener)` Starts source preparation and enables the source, see `prepareSource`.
`synchronized void`	`releaseSourceInternal()` Releases the source, see `releaseSource`.

Inherited fields

From androidx.media3.exoplayer.source.BaseMediaSource

@Nullable PlayerId

playerId

Inherited methods

From androidx.media3.exoplayer.source.BaseMediaSource

`final void`	`addDrmEventListener( Handler handler, DrmSessionEventListener eventListener )` Adds a `DrmSessionEventListener` to the list of listeners which are notified of DRM events for this media source.
`final void`	`addEventListener( Handler handler, MediaSourceEventListener eventListener )` Adds a `MediaSourceEventListener` to the list of listeners which are notified of media source events.
`final DrmSessionEventListener.EventDispatcher`	`createDrmEventDispatcher( @Nullable MediaSource.MediaPeriodId mediaPeriodId )` Returns a `DrmSessionEventListener.EventDispatcher` which dispatches all events to the registered listeners with the specified `MediaPeriodId`
`final DrmSessionEventListener.EventDispatcher`	`createDrmEventDispatcher( int windowIndex, @Nullable MediaSource.MediaPeriodId mediaPeriodId )` Returns a `DrmSessionEventListener.EventDispatcher` which dispatches all events to the registered listeners with the specified window index and `MediaPeriodId`.
`final MediaSourceEventListener.EventDispatcher`	`createEventDispatcher(@Nullable MediaSource.MediaPeriodId mediaPeriodId)` Returns a `MediaSourceEventListener.EventDispatcher` which dispatches all events to the registered listeners with the specified `MediaPeriodId`.
`final MediaSourceEventListener.EventDispatcher`	`createEventDispatcher( MediaSource.MediaPeriodId mediaPeriodId, long mediaTimeOffsetMs )` This method is deprecated. Use `createEventDispatcher` instead.
`final MediaSourceEventListener.EventDispatcher`	`createEventDispatcher( int windowIndex, @Nullable MediaSource.MediaPeriodId mediaPeriodId )` Returns a `MediaSourceEventListener.EventDispatcher` which dispatches all events to the registered listeners with the specified window index and `MediaPeriodId`.
`final MediaSourceEventListener.EventDispatcher`	`createEventDispatcher( int windowIndex, @Nullable MediaSource.MediaPeriodId mediaPeriodId, long mediaTimeOffsetMs )` This method is deprecated. Use `createEventDispatcher` instead.
`final void`	`disable(MediaSource.MediaSourceCaller caller)` Disables the source for the creation of `MediaPeriods`.
`final void`	`enable(MediaSource.MediaSourceCaller caller)` Enables the source for the creation of `MediaPeriods`.
`final PlayerId`	`getPlayerId()` Returns the `PlayerId` of the player using this media source.
`final boolean`	`isEnabled()` Returns whether the source is enabled.
`final void`	`prepareSource( MediaSource.MediaSourceCaller caller, @Nullable TransferListener mediaTransferListener )` This method is deprecated. Implement `prepareSource` instead.
`final void`	`prepareSource( MediaSource.MediaSourceCaller caller, @Nullable TransferListener mediaTransferListener, PlayerId playerId )` Registers a `MediaSourceCaller`.
`final boolean`	`prepareSourceCalled()` Returns whether the source has `prepareSource` called.
`final void`	`refreshSourceInfo(Timeline timeline)` Updates timeline and manifest and notifies all listeners of the update.
`final void`	`releaseSource(MediaSource.MediaSourceCaller caller)` Unregisters a caller, and disables and releases the source if no longer required.
`final void`	`removeDrmEventListener(DrmSessionEventListener eventListener)` Removes a `DrmSessionEventListener` from the list of listeners which are notified of DRM events for this media source.
`final void`	`removeEventListener(MediaSourceEventListener eventListener)` Removes a `MediaSourceEventListener` from the list of listeners which are notified of media source events.
`final void`	`setPlayerId(PlayerId playerId)` Sets the `PlayerId` of the player using this media source.

From androidx.media3.exoplayer.source.CompositeMediaSource

`final void`	`disableChildSource(@UnknownNull T id)` Disables a child source.
`final void`	`enableChildSource(@UnknownNull T id)` Enables a child source.
`long`	`getMediaTimeForChildMediaTime( @UnknownNull T childSourceId, long mediaTimeMs, @Nullable MediaSource.MediaPeriodId mediaPeriodId )` Returns the media time in the `MediaPeriod` of the composite source corresponding to the specified media time in the `MediaPeriod` of the child source.
`void`	`@CallSuper maybeThrowSourceInfoRefreshError()` Throws any pending error encountered while loading or refreshing source information.
`final void`	`prepareChildSource(@UnknownNull T id, MediaSource mediaSource)` Prepares a child source.
`final void`	`releaseChildSource(@UnknownNull T id)` Releases a child source.

From androidx.media3.exoplayer.source.MediaSource

`boolean`	`@UnstableApi canUpdateMediaItem(MediaItem mediaItem)` Returns whether the `MediaItem` for this source can be updated with the provided item.
`void`	`@UnstableApi updateMediaItem(MediaItem mediaItem)` Updates the `MediaItem` for this source.

Public constructors

ConcatenatingMediaSource

public ConcatenatingMediaSource(MediaSource[] mediaSources)

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

ConcatenatingMediaSource

public ConcatenatingMediaSource(boolean isAtomic, MediaSource[] mediaSources)

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

ConcatenatingMediaSource

public ConcatenatingMediaSource(
    boolean isAtomic,
    ShuffleOrder shuffleOrder,
    MediaSource[] mediaSources
)

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

ConcatenatingMediaSource

public ConcatenatingMediaSource(
    boolean isAtomic,
    boolean useLazyPreparation,
    ShuffleOrder shuffleOrder,
    MediaSource[] mediaSources
)

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

Public methods

addMediaSource

synchronized public void addMediaSource(MediaSource mediaSource)

Appends a MediaSource to the playlist.

Parameters
`MediaSource mediaSource`	The `MediaSource` to be added to the list.

addMediaSource

synchronized public void addMediaSource(int index, MediaSource mediaSource)

Adds a MediaSource to the playlist.

Parameters
`int index`	The index at which the new `MediaSource` will be inserted. This index must be in the range of 0 <= index <= `getSize`.
`MediaSource mediaSource`	The `MediaSource` to be added to the list.

addMediaSource

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

Appends a MediaSource to the playlist and executes a custom action on completion.

Parameters
`MediaSource mediaSource`	The `MediaSource` to be added to the list.
`Handler handler`	The `Handler` to run `onCompletionAction`.
`Runnable onCompletionAction`	A `Runnable` which is executed immediately after the media source has been added to the playlist.

addMediaSource

synchronized 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
`int index`	The index at which the new `MediaSource` will be inserted. This index must be in the range of 0 <= index <= `getSize`.
`MediaSource mediaSource`	The `MediaSource` to be added to the list.
`Handler handler`	The `Handler` to run `onCompletionAction`.
`Runnable onCompletionAction`	A `Runnable` which is executed immediately after the media source has been added to the playlist.

addMediaSources

synchronized public void addMediaSources(Collection<MediaSource> mediaSources)

Appends multiple MediaSources to the playlist.

Parameters
`Collection<MediaSource> 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

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

Adds multiple MediaSources to the playlist.

Parameters
`int index`	The index at which the new `MediaSource`s will be inserted. This index must be in the range of 0 <= index <= `getSize`.
`Collection<MediaSource> 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

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

Appends multiple MediaSources to the playlist and executes a custom action on completion.

Parameters
`Collection<MediaSource> 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 handler`	The `Handler` to run `onCompletionAction`.
`Runnable onCompletionAction`	A `Runnable` which is executed immediately after the media sources have been added to the playlist.

addMediaSources

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

Adds multiple MediaSources to the playlist and executes a custom action on completion.

Parameters
`int index`	The index at which the new `MediaSource`s will be inserted. This index must be in the range of 0 <= index <= `getSize`.
`Collection<MediaSource> 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 handler`	The `Handler` to run `onCompletionAction`.
`Runnable onCompletionAction`	A `Runnable` which is executed immediately after the media sources have been added to the playlist.

clear

synchronized public void clear()

Clears the playlist.

clear

synchronized public void clear(Handler handler, Runnable onCompletionAction)

Clears the playlist and executes a custom action on completion.

Parameters
`Handler handler`	The `Handler` to run `onCompletionAction`.
`Runnable onCompletionAction`	A `Runnable` which is executed immediately after the playlist has been cleared.

createPeriod

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

Returns a new MediaPeriod identified by periodId.

Should not be called directly from application code.

This method must be called on the playback thread and only if the source is enabled.

Parameters
`MediaSource.MediaPeriodId id`	The identifier of the period.
`Allocator allocator`	An `Allocator` from which to obtain media buffer allocations.
`long startPositionUs`	The expected start position, in microseconds.

Returns
`MediaPeriod`	A new `MediaPeriod`.

getInitialTimeline

synchronized public 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.

Should not be called directly from application code.

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.

This method must be called on the application thread.

getMediaItem

public MediaItem getMediaItem()

Returns the MediaItem whose media is provided by the source.

Should not be called directly from application code.

This method must be called on the application thread.

getMediaSource

synchronized public MediaSource getMediaSource(int index)

Returns the MediaSource at a specified index.

Parameters
`int index`	An index in the range of 0 <= index <= `getSize`.

Returns
`MediaSource`	The `MediaSource` at this index.

getSize

synchronized public int getSize()

Returns the number of media sources in the playlist.

isSingleWindow

public boolean isSingleWindow()

Returns true if the media source is guaranteed to never have zero or more than one window.

Should not be called directly from application code.

The default implementation returns true.

This method must be called on the application thread.

Returns
`boolean`	true if the source has exactly one window.

moveMediaSource

synchronized public void moveMediaSource(int currentIndex, int newIndex)

Moves an existing MediaSource within the playlist.

Parameters
`int currentIndex`	The current index of the media source in the playlist. This index must be in the range of 0 <= index <`getSize`.
`int newIndex`	The target index of the media source in the playlist. This index must be in the range of 0 <= index <`getSize`.

moveMediaSource

synchronized 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
`int currentIndex`	The current index of the media source in the playlist. This index must be in the range of 0 <= index <`getSize`.
`int newIndex`	The target index of the media source in the playlist. This index must be in the range of 0 <= index <`getSize`.
`Handler handler`	The `Handler` to run `onCompletionAction`.
`Runnable onCompletionAction`	A `Runnable` which is executed immediately after the media source has been moved.

releasePeriod

public void releasePeriod(MediaPeriod mediaPeriod)

Releases the period.

Should not be called directly from application code.

This method must be called on the playback thread.

Parameters
`MediaPeriod mediaPeriod`	The period to release.

removeMediaSource

synchronized 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 instead.

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

Parameters
`int index`	The index at which the media source will be removed. This index must be in the range of 0 <= index <`getSize`.

Returns
`MediaSource`	The removed `MediaSource`.

removeMediaSource

synchronized 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 instead.

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

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

Returns
`MediaSource`	The removed `MediaSource`.

removeMediaSourceRange

synchronized public void removeMediaSourceRange(int fromIndex, int toIndex)

Removes a range of MediaSources 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
`int 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`.
`int 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
`java.lang.IndexOutOfBoundsException`	When the range is malformed, i.e. `fromIndex`<0, `toIndex`>`getSize`, `fromIndex`>`toIndex`

removeMediaSourceRange

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

Removes a range of MediaSources 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
`int 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`.
`int 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 handler`	The `Handler` to run `onCompletionAction`.
`Runnable onCompletionAction`	A `Runnable` which is executed immediately after the media source range has been removed from the playlist.

Throws
`java.lang.IllegalArgumentException`	When the range is malformed, i.e. `fromIndex`<0, `toIndex`>`getSize`, `fromIndex`>`toIndex`

setShuffleOrder

synchronized public void setShuffleOrder(ShuffleOrder shuffleOrder)

Sets a new shuffle order to use when shuffling the child media sources.

Parameters
`ShuffleOrder shuffleOrder`	A `ShuffleOrder`.

setShuffleOrder

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

Sets a new shuffle order to use when shuffling the child media sources.

Parameters
`ShuffleOrder shuffleOrder`	A `ShuffleOrder`.
`Handler handler`	The `Handler` to run `onCompletionAction`.
`Runnable onCompletionAction`	A `Runnable` which is executed immediately after the shuffle order has been changed.

Protected methods

disableInternal

protected void disableInternal()

Disables the source, see disable.

enableInternal

protected void enableInternal()

Enables the source, see enable.

prepareSourceInternal

synchronized protected void prepareSourceInternal(@Nullable TransferListener mediaTransferListener)

Starts source preparation and enables the source, see prepareSource. This method is called at most once until the next call to releaseSourceInternal.

Parameters
`@Nullable TransferListener 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.

releaseSourceInternal

synchronized protected void releaseSourceInternal()

Releases the source, see releaseSource. This method is called exactly once after each call to prepareSourceInternal.