ExoPlayer 2 - MediaSource composition

MediaSource composition is a powerful concept in ExoPlayer 2, enabling functionality such as side-loaded subtitles, looping and playback of sequences of videos.

To play a piece of media in ExoPlayer 2, an application must first create a corresponding MediaSource object to provide to the player. For example to play an MP4, an application must create an ExtractorMediaSource:

ExtractorMediaSource is suitable for regular media files (mp4, webm, mkv etc). The ExoPlayer library also provides MediaSource implementations for DASH (DashMediaSource), SmoothStreaming (SsMediaSource) and HLS (HlsMediaSource).


In addition to the MediaSource implementations described above, the ExoPlayer library also provides MergingMediaSource, LoopingMediaSource and ConcatenatingMediaSource. These are examples MediaSource implementations that enable more complex playback functionality through composition. We describe a number of common use cases below. Note that although the following examples are described in the context of video playback, they apply equally to audio only playback too, and indeed to the playback of any supported media type(s).

Side-loading a subtitle file

Given a video file and a separate subtitle file, MergingMediaSource can be used to merge them into a single source for playback.

Seamlessly looping a video

A video can be seamlessly looped using a LoopingMediaSource. The following example loops a video indefinitely. It’s also possible to specify a finite loop count when creating a LoopingMediaSource.

Seamlessly playing a sequence of videos

ConcatenatingMediaSource enables sequential playback of two or more individual MediaSources. The following example plays two videos in sequence. Transitions between sources are seamless. There is no requirement that the sources being concatenated are of the same format (e.g. it’s fine to concatenate a video file containing 480p H264 with one that contains 720p VP9). The sources may even be of different types (e.g. it’s fine to concatenate a video with an audio only stream).

Advanced composition

It’s possible to further combine composite MediaSources for more unusual use cases. Given two videos A and B, the following example shows how LoopingMediaSource and ConcatenatingMediaSource can be used together to loop the sequence (A,A,B) indefinitely.

The following example is equivalent, demonstrating that there can be more than one way of achieving the same result.

Important note: It is important to avoid using the same MediaSource instance multiple times in a composition, unless explicitly allowed according to the documentation. The use of firstSource twice in the example above is one such case, since the Javadoc for ConcatenatingMediaSource explicitly states that duplicate entries are allowed. In general, however, the graph of objects formed by a composition should be a tree. Using multiple equivalent MediaSource instances in a composition is allowed.


In conclusion, MediaSource composition is a powerful concept in ExoPlayer 2, enabling functionality such as side-loaded subtitles, looping and playback of sequences of videos. It is important to avoid using the same MediaSource instance multiple times in a composition, unless explicitly allowed according to the documentation.