ConcatenatingMediaSource

@UnstableApi
public final class ConcatenatingMediaSource extends CompositeMediaSource<ConcatenatingMediaSource.MediaSourceHolder>

java.lang.Object
   ↳ androidx.media3.exoplayer.source.BaseMediaSource
     ↳ androidx.media3.exoplayer.source.CompositeMediaSource<ConcatenatingMediaSource.MediaSourceHolder>
       ↳ 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

Nested types

This class is deprecated. Deprecated in Java

Public constructors
ConcatenatingMediaSource(MediaSource[] mediaSources)

This method is deprecated. Deprecated in Java
ConcatenatingMediaSource(boolean isAtomic, MediaSource[] mediaSources)

This method is deprecated. Deprecated in Java
ConcatenatingMediaSource(
    boolean isAtomic,
    ShuffleOrder shuffleOrder,
    MediaSource[] mediaSources
)

This method is deprecated. Deprecated in Java
ConcatenatingMediaSource(
    boolean isAtomic,
    boolean useLazyPreparation,
    ShuffleOrder shuffleOrder,
    MediaSource[] mediaSources
)

This method is deprecated. Deprecated in Java

Public methods
synchronized void

This method is deprecated. Deprecated in Java
synchronized void
addMediaSource(int index, MediaSource mediaSource)

This method is deprecated. Deprecated in Java
synchronized void
addMediaSource(
    MediaSource mediaSource,
    Handler handler,
    Runnable onCompletionAction
)

This method is deprecated. Deprecated in Java
synchronized void
addMediaSource(
    int index,
    MediaSource mediaSource,
    Handler handler,
    Runnable onCompletionAction
)

This method is deprecated. Deprecated in Java
synchronized void

This method is deprecated. Deprecated in Java
synchronized void
addMediaSources(int index, Collection<MediaSource> mediaSources)

This method is deprecated. Deprecated in Java
synchronized void
addMediaSources(
    Collection<MediaSource> mediaSources,
    Handler handler,
    Runnable onCompletionAction
)

This method is deprecated. Deprecated in Java
synchronized void
addMediaSources(
    int index,
    Collection<MediaSource> mediaSources,
    Handler handler,
    Runnable onCompletionAction
)

This method is deprecated. Deprecated in Java
synchronized void

This method is deprecated. Deprecated in Java
synchronized void
clear(Handler handler, Runnable onCompletionAction)

This method is deprecated. Deprecated in Java
MediaPeriod
createPeriod(
    MediaSource.MediaPeriodId id,
    Allocator allocator,
    long startPositionUs
)

This method is deprecated. Deprecated in Java
synchronized Timeline

This method is deprecated. Deprecated in Java
MediaItem

This method is deprecated. Deprecated in Java
synchronized MediaSource
getMediaSource(int index)

This method is deprecated. Deprecated in Java
synchronized int

This method is deprecated. Deprecated in Java
boolean

This method is deprecated. Deprecated in Java
synchronized void
moveMediaSource(int currentIndex, int newIndex)

This method is deprecated. Deprecated in Java
synchronized void
moveMediaSource(
    int currentIndex,
    int newIndex,
    Handler handler,
    Runnable onCompletionAction
)

This method is deprecated. Deprecated in Java
void

This method is deprecated. Deprecated in Java
synchronized MediaSource
removeMediaSource(int index)

This method is deprecated. Deprecated in Java
synchronized MediaSource
removeMediaSource(
    int index,
    Handler handler,
    Runnable onCompletionAction
)

This method is deprecated. Deprecated in Java
synchronized void
removeMediaSourceRange(int fromIndex, int toIndex)

This method is deprecated. Deprecated in Java
synchronized void
removeMediaSourceRange(
    int fromIndex,
    int toIndex,
    Handler handler,
    Runnable onCompletionAction
)

This method is deprecated. Deprecated in Java
synchronized void

This method is deprecated. Deprecated in Java
synchronized void
setShuffleOrder(
    ShuffleOrder shuffleOrder,
    Handler handler,
    Runnable onCompletionAction
)

This method is deprecated. Deprecated in Java

Protected methods
void

This method is deprecated. Deprecated in Java
void

This method is deprecated. Deprecated in Java
@Nullable MediaSource.MediaPeriodId

This method is deprecated. Deprecated in Java
int
getWindowIndexForChildWindowIndex(
    ConcatenatingMediaSource.MediaSourceHolder childSourceId,
    int windowIndex
)

This method is deprecated. Deprecated in Java
void
onChildSourceInfoRefreshed(
    ConcatenatingMediaSource.MediaSourceHolder childSourceId,
    MediaSource mediaSource,
    Timeline newTimeline
)

This method is deprecated. Deprecated in Java
synchronized void

This method is deprecated. Deprecated in Java
synchronized void

This method is deprecated. Deprecated in Java

Inherited fields
From androidx.media3.exoplayer.source.BaseMediaSource
@Nullable BandwidthMeter

This field is deprecated. Deprecated in Java
@Nullable PlayerId

This field is deprecated. Deprecated in Java

Inherited methods
From androidx.media3.exoplayer.source.BaseMediaSource
final void
@UnstableApi
addDrmEventListener(
    Handler handler,
    DrmSessionEventListener eventListener
)

This method is deprecated. Deprecated in Java
final void
@UnstableApi
addEventListener(
    Handler handler,
    MediaSourceEventListener eventListener
)

This method is deprecated. Deprecated in Java
final DrmSessionEventListener.EventDispatcher

This method is deprecated. Deprecated in Java
final DrmSessionEventListener.EventDispatcher
createDrmEventDispatcher(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId
)

This method is deprecated. Deprecated in Java
final MediaSourceEventListener.EventDispatcher

This method is deprecated. Deprecated in Java
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
)

This method is deprecated. Deprecated in Java
final MediaSourceEventListener.EventDispatcher
createEventDispatcher(
    int windowIndex,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId,
    long mediaTimeOffsetMs
)

This method is deprecated.

Use createEventDispatcher instead.
final void

This method is deprecated. Deprecated in Java
final void

This method is deprecated. Deprecated in Java
final BandwidthMeter

This method is deprecated. Deprecated in Java
final PlayerId

This method is deprecated. Deprecated in Java
final boolean

This method is deprecated. Deprecated in Java
final void
@UnstableApi
prepareSource(
    MediaSource.MediaSourceCaller caller,
    PlayerId playerId,
    BandwidthMeter bandwidthMeter
)

This method is deprecated. Deprecated in Java
final boolean

This method is deprecated. Deprecated in Java
final void

This method is deprecated. Deprecated in Java
final void

This method is deprecated. Deprecated in Java
final void

This method is deprecated. Deprecated in Java
final void

This method is deprecated. Deprecated in Java
final void

This method is deprecated. Deprecated in Java
final void

This method is deprecated. Deprecated in Java
From androidx.media3.exoplayer.source.CompositeMediaSource
final void

This method is deprecated. Deprecated in Java
final void

This method is deprecated. Deprecated in Java
long
getMediaTimeForChildMediaTime(
    @UnknownNull T childSourceId,
    long mediaTimeMs,
    @Nullable MediaSource.MediaPeriodId mediaPeriodId
)

This method is deprecated. Deprecated in Java
void

This method is deprecated. Deprecated in Java
final void

This method is deprecated. Deprecated in Java
final void

This method is deprecated. Deprecated in Java
From androidx.media3.exoplayer.source.MediaSource
boolean

This method is deprecated. Deprecated in Java
void
@UnstableApi
prepareSource(
    MediaSource.MediaSourceCaller caller,
    @Nullable TransferListener mediaTransferListener,
    PlayerId playerId
)

This method is deprecated.

Use prepareSource instead.
void

This method is deprecated. Deprecated in Java

Public constructors

ConcatenatingMediaSource

public ConcatenatingMediaSource(MediaSource[] mediaSources)
Parameters
MediaSource[] mediaSources

The MediaSources 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
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 MediaSources 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
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 MediaSources 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
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 MediaSources to concatenate. It is valid for the same MediaSource 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 MediaSources 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 MediaSources will be inserted. This index must be in the range of 0 <= index <= getSize.
Collection<MediaSource> mediaSources

A collection of MediaSources 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 MediaSources 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 MediaSources will be inserted. This index must be in the range of 0 <= index <= getSize.
Collection<MediaSource> mediaSources

A collection of MediaSources 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.

getMediaPeriodIdForChildMediaPeriodId

protected @Nullable MediaSource.MediaPeriodId getMediaPeriodIdForChildMediaPeriodId(
    ConcatenatingMediaSource.MediaSourceHolder childSourceId,
    MediaSource.MediaPeriodId mediaPeriodId
)

Returns the MediaPeriodId in the composite source corresponding to the specified MediaPeriodId in a child source. The default implementation does not change the media period id.

Parameters
ConcatenatingMediaSource.MediaSourceHolder childSourceId

The unique id used to prepare the child source.
MediaSource.MediaPeriodId mediaPeriodId

A MediaPeriodId of the child source.
Returns
@Nullable MediaSource.MediaPeriodId

The corresponding MediaPeriodId in the composite source. Null if no corresponding media period id can be determined.

getWindowIndexForChildWindowIndex

protected int getWindowIndexForChildWindowIndex(
    ConcatenatingMediaSource.MediaSourceHolder childSourceId,
    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.

Parameters
ConcatenatingMediaSource.MediaSourceHolder childSourceId

The unique id used to prepare the child source.
int windowIndex

A window index of the child source.
Returns
int

The corresponding window index in the composite source.

onChildSourceInfoRefreshed

protected void onChildSourceInfoRefreshed(
    ConcatenatingMediaSource.MediaSourceHolder childSourceId,
    MediaSource mediaSource,
    Timeline newTimeline
)

Called when the source info of a child source has been refreshed.

Parameters
ConcatenatingMediaSource.MediaSourceHolder childSourceId

The unique id used to prepare the child source.
MediaSource mediaSource

The child source whose source info has been refreshed.
Timeline newTimeline

The timeline of the child source.

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.

This method is called on the playback thread.

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.

This method is called on the playback thread.