ConcatenatingMediaSource


@UnstableApi
public final class ConcatenatingMediaSource extends CompositeMediaSource


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

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

Appends multiple MediaSources to the playlist.

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

Adds multiple MediaSources to the playlist.

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

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

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

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

synchronized void

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

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

Returns the MediaItem whose media is provided by the source.

synchronized MediaSource
getMediaSource(int index)

Returns the MediaSource at a specified index.

synchronized int

Returns the number of media sources in the playlist.

boolean

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

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 MediaSources 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 MediaSources from the playlist, by specifying an initial index (included) and a final index (excluded), and executes a custom action on completion.

synchronized void

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

Disables the source, see disable.

void

Enables the source, see enable.

synchronized void

Starts source preparation and enables the source, see prepareSource.

synchronized void

Releases the source, see releaseSource.

Inherited methods

From androidx.media3.exoplayer.source.BaseMediaSource
final void
@UnstableApi
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
@UnstableApi
addEventListener(
    Handler handler,
    MediaSourceEventListener eventListener
)

Adds a MediaSourceEventListener to the list of listeners which are notified of media source events.

final DrmSessionEventListener.EventDispatcher

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

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

Disables the source for the creation of MediaPeriods.

final void

Enables the source for the creation of MediaPeriods.

final PlayerId

Returns the PlayerId of the player using this media source.

final boolean

Returns whether the source is enabled.

final void
@UnstableApi
prepareSource(
    MediaSource.MediaSourceCaller caller,
    @Nullable TransferListener mediaTransferListener
)

This method is deprecated.

Implement prepareSource instead.

final void
@UnstableApi
prepareSource(
    MediaSource.MediaSourceCaller caller,
    @Nullable TransferListener mediaTransferListener,
    PlayerId playerId
)

Registers a MediaSourceCaller.

final boolean

Returns whether the source has prepareSource called.

final void

Updates timeline and manifest and notifies all listeners of the update.

final void

Unregisters a caller, and disables and releases the source if no longer required.

final void

Removes a DrmSessionEventListener from the list of listeners which are notified of DRM events for this media source.

final void

Removes a MediaSourceEventListener from the list of listeners which are notified of media source events.

final void

Sets the PlayerId of the player using this media source.

From androidx.media3.exoplayer.source.CompositeMediaSource
final void

Disables a child source.

final void

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

Throws any pending error encountered while loading or refreshing source information.

final void

Prepares a child source.

final void

Releases a child source.

From androidx.media3.exoplayer.source.MediaSource
boolean

Returns whether the MediaItem for this source can be updated with the provided item.

void

Updates the MediaItem for this source.

Public constructors

ConcatenatingMediaSource

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

The MediaSources 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 MediaSources 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 MediaSources 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 MediaSources 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 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.

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.