ExoPlayer supports HLS with multiple container formats. The contained audio and video sample formats must also be supported (see the sample formats section for details). We strongly encourage HLS content producers to generate high quality HLS streams, as described in this blog post.
Feature | Supported | Comments |
---|---|---|
Containers | ||
MPEG-TS | YES | |
FMP4/CMAF | YES | |
ADTS (AAC) | YES | |
MP3 | YES | |
Closed captions / subtitles | ||
CEA-608 | YES | |
CEA-708 | YES | |
WebVTT | YES | |
Metadata | ||
ID3 | YES | |
SCTE-35 | NO | |
Content protection | ||
AES-128 | YES | |
Sample AES-128 | NO | |
Widevine | YES | API 19+ ("cenc" scheme) and 25+ ("cbcs" scheme) |
PlayReady SL2000 | YES | Android TV only |
Server control | ||
Delta updates | YES | |
Blocking playlist reload | YES | |
Blocking load of preload hints | YES | Except for byteranges with undefined lengths |
Ad insertion | ||
Server-guided ad insertion (Interstitials) | Partially | Only VOD with X-ASSET-URI .
Live streams and
X-ASSET-LIST will be added
later. |
IMA server-side and client-side ads | YES | Ad insertion guide |
Live playback | ||
Regular live playback | YES | |
Low-latency HLS (Apple) | YES | |
Low-latency HLS (Community) | NO | |
Common Media Client Data CMCD | YES | CMCD integration guide |
Using MediaItem
To play an HLS stream, you need to depend on the HLS module.
implementation("androidx.media3:media3-exoplayer-hls:1.6.0")
implementation "androidx.media3:media3-exoplayer-hls:1.6.0"
You can then create a MediaItem
for an HLS playlist URI and pass it to the
player.
// Create a player instance.
val player = ExoPlayer.Builder(context).build()
// Set the media item to be played.
player.setMediaItem(MediaItem.fromUri(hlsUri))
// Prepare the player.
player.prepare()
// Create a player instance.
ExoPlayer player = new ExoPlayer.Builder(context).build();
// Set the media item to be played.
player.setMediaItem(MediaItem.fromUri(hlsUri));
// Prepare the player.
player.prepare();
If your URI doesn't end with .m3u8
, you can pass MimeTypes.APPLICATION_M3U8
to setMimeType
of MediaItem.Builder
to explicitly indicate the type of the
content.
The URI of the media item may point to either a media playlist or a multivariant
playlist. If the URI points to a multivariant playlist that declares multiple
#EXT-X-STREAM-INF
tags, then ExoPlayer will automatically adapt between
variants, taking into account both available bandwidth and device capabilities.
Using HlsMediaSource
For more customization options, you can create a HlsMediaSource
and pass it
directly to the player instead of a MediaItem
.
// Create a data source factory.
val dataSourceFactory: DataSource.Factory = DefaultHttpDataSource.Factory()
// Create a HLS media source pointing to a playlist uri.
val hlsMediaSource =
HlsMediaSource.Factory(dataSourceFactory).createMediaSource(MediaItem.fromUri(hlsUri))
// Create a player instance.
val player = ExoPlayer.Builder(context).build()
// Set the HLS media source as the playlist with a single media item.
player.setMediaSource(hlsMediaSource)
// Prepare the player.
player.prepare()
// Create a data source factory.
DataSource.Factory dataSourceFactory = new DefaultHttpDataSource.Factory();
// Create a HLS media source pointing to a playlist uri.
HlsMediaSource hlsMediaSource =
new HlsMediaSource.Factory(dataSourceFactory).createMediaSource(MediaItem.fromUri(hlsUri));
// Create a player instance.
ExoPlayer player = new ExoPlayer.Builder(context).build();
// Set the HLS media source as the playlist with a single media item.
player.setMediaSource(hlsMediaSource);
// Prepare the player.
player.prepare();
Accessing the manifest
You can retrieve the current manifest by calling Player.getCurrentManifest
.
For HLS, you should cast the returned object to HlsManifest
. The
onTimelineChanged
callback of Player.Listener
is also called whenever
the manifest is loaded. This will happen once for on-demand content and
possibly many times for live content. The following code snippet shows how an app
can do something whenever the manifest is loaded.
player.addListener(
object : Player.Listener {
override fun onTimelineChanged(timeline: Timeline, @TimelineChangeReason reason: Int) {
val manifest = player.currentManifest
if (manifest is HlsManifest) {
// Do something with the manifest.
}
}
}
)
player.addListener(
new Player.Listener() {
@Override
public void onTimelineChanged(
Timeline timeline, @Player.TimelineChangeReason int reason) {
Object manifest = player.getCurrentManifest();
if (manifest != null) {
HlsManifest hlsManifest = (HlsManifest) manifest;
// Do something with the manifest.
}
}
});
Play HLS streams with interstitials
The HLS specification defines HLS interstitials which can be used to include
interstitial information in a media playlist. ExoPlayer by default ignores these
interstitials. Support can be added by using HlsInterstitialsAdsLoader
. We
don't support all features of the spec from the start. If you miss support for
your stream, let us know by filing an issue on GitHub and send us your
stream URI, so we can add support for your stream.
Use a MediaItem
with the playlist API
The most convenient way to play HLS streams with interstitials is building an
ExoPlayer instance with a HlsInterstitialsAdsLoader.AdsMediaSourceFactory
.
This allows to use the MediaItem
based playlist API of the Player
interface to play HLS interstitials.
The MediaSource.Factory
of ExoPlayer
can be injected into the builder when
building the player instance:
hlsInterstitialsAdsLoader = HlsInterstitialsAdsLoader(context)
// Create a MediaSource.Factory for HLS streams with interstitials.
var hlsMediaSourceFactory =
HlsInterstitialsAdsLoader.AdsMediaSourceFactory(
hlsInterstitialsAdsLoader,
playerView,
DefaultMediaSourceFactory(context),
)
// Build player with interstitials media source factory
player =
ExoPlayer.Builder(context)
.setMediaSourceFactory(hlsMediaSourceFactory)
.build()
// Set the player on the ads loader.
hlsInterstitialsAdsLoader.setPlayer(player)
playerView.setPlayer(player)
hlsInterstitialsAdsLoader = new HlsInterstitialsAdsLoader(context);
// Create a MediaSource.Factory for HLS streams with interstitials.
MediaSource.Factory hlsMediaSourceFactory =
new HlsInterstitialsAdsLoader.AdsMediaSourceFactory(
hlsInterstitialsAdsLoader, playerView, new DefaultMediaSourceFactory(context));
// Build player with interstitials media source factory
player =
new ExoPlayer.Builder(context)
.setMediaSourceFactory(hlsMediaSourceFactory)
.build();
// Set the player on the ads loader.
hlsInterstitialsAdsLoader.setPlayer(player);
playerView.setPlayer(player);
With such a player setup, playing HLS interstitials is just about setting a
media item with an AdsConfiguration
on the player:
player.setMediaItem(
MediaItem.Builder()
.setUri("https://www.example.com/media.m3u8")
.setAdsConfiguration(
AdsConfiguration.Builder(Uri.parse("hls://interstitials"))
.setAdsId("ad-tag-0") // must be unique within playlist
.build())
.build())
player.prepare();
player.play();
player.setMediaItem(
new MediaItem.Builder()
.setUri("https://www.example.com/media.m3u8")
.setAdsConfiguration(
new AdsConfiguration.Builder(Uri.parse("hls://interstitials"))
.setAdsId("ad-tag-0") // must be unique within playlist
.build())
.build());
player.prepare();
player.play();
Use the media source based API
Alternatively, the ExoPlayer instance can be built without overriding the
default media source factory. To support interstitials, an app can then
use HlsInterstitialsAdsLoader.AdsMediaSourceFactory
directly to create a
MediaSource
and provide it to ExoPlayer using the media source based playlist
API:
hlsInterstitialsAdsLoader = HlsInterstitialsAdsLoader(context)
// Create a MediaSource.Factory for HLS streams with interstitials.
var hlsMediaSourceFactory =
HlsInterstitialsAdsLoader.AdsMediaSourceFactory(hlsInterstitialsAdsLoader, playerView, context)
// Build player with default media source factory.
player = new ExoPlayer.Builder(context).build();
// Create an media source from an HLS media item with ads configuration.
val mediaSource =
hlsMediaSourceFactory.createMediaSource(
MediaItem.Builder()
.setUri("https://www.example.com/media.m3u8")
.setAdsConfiguration(
MediaItem.AdsConfiguration.Builder(Uri.parse("hls://interstitials"))
.setAdsId("ad-tag-0")
.build()
)
.build()
)
// Set the media source on the player.
player.setMediaSource(mediaSource)
player.prepare()
player.play()
HlsInterstitialsAdsLoader hlsInterstitialsAdsLoader = new HlsInterstitialsAdsLoader(context);
// Create a MediaSource.Factory for HLS streams with interstitials.
MediaSource.Factory hlsMediaSourceFactory =
new HlsInterstitialsAdsLoader.AdsMediaSourceFactory(
hlsInterstitialsAdsLoader, playerView, context);
// Build player with default media source factory.
player = new ExoPlayer.Builder(context).build();
// Create an media source from an HLS media item with ads configuration.
MediaSource mediaSource =
hlsMediaSourceFactory.createMediaSource(
new MediaItem.Builder()
.setUri("https://www.example.com/media.m3u8")
.setAdsConfiguration(
new MediaItem.AdsConfiguration.Builder(Uri.parse("hls://interstitials"))
.setAdsId("ad-tag-0")
.build())
.build());
// Set the media source on the player.
exoPlayer.setMediaSource(mediaSource);
exoPlayer.prepare();
exoPlayer.play();
Listen to ad events
A Listener
can be added to HlsInterstitialsAdsLoader
to monitor events
regarding status changes concerning HLS interstitials playback. This allows an
app or SDK to track ads played, asset lists being loaded, ad media sources being
prepared or detect asset list load and ad preparation errors. Further, metadata
emitted by ad media sources can be received for fine-grained ad playback
verification or to track ad playback progress.
class AdsLoaderListener : HlsInterstitialsAdsLoader.Listener {
override fun onStart(mediaItem: MediaItem, adsId: Any, adViewProvider: AdViewProvider) {
// Do something when HLS media item with interstitials is started.
}
override fun onMetadata(
mediaItem: MediaItem,
adsId: Any,
adGroupIndex: Int,
adIndexInAdGroup: Int,
metadata: Metadata,
) {
// Do something with metadata that is emitted by the ad media source of the given ad.
}
override fun onAdCompleted(
mediaItem: MediaItem,
adsId: Any,
adGroupIndex: Int,
adIndexInAdGroup: Int,
) {
// Do something when ad completed playback.
}
// ... See JavaDoc for further callbacks of HlsInterstitialsAdsLoader.Listener.
override fun onStop(mediaItem: MediaItem, adsId: Any, adPlaybackState: AdPlaybackState) {
// Do something with the resulting ad playback state when stopped.
}
}
private class AdsLoaderListener
implements HlsInterstitialsAdsLoader.Listener {
// implement HlsInterstitialsAdsLoader.Listener
@Override
public void onStart(MediaItem mediaItem, Object adsId, AdViewProvider adViewProvider) {
// Do something when HLS media item with interstitials is started.
}
@Override
public void onMetadata(
MediaItem mediaItem,
Object adsId,
int adGroupIndex,
int adIndexInAdGroup,
Metadata metadata) {
// Do something with metadata that is emitted by the ad media source of the given ad.
}
@Override
public void onAdCompleted(
MediaItem mediaItem, Object adsId, int adGroupIndex, int adIndexInAdGroup) {
// Do something when ad completed playback.
}
// ... See JavaDoc for further callbacks of HlsInterstitialsAdsLoader.Listener.
@Override
public void onStop(MediaItem mediaItem, Object adsId, AdPlaybackState adPlaybackState) {
// Do something with the resulting ad playback state when stopped.
}
}
The listener can then be added to the ads loader:
var listener = AdsLoaderListener();
// Add the listener to the ads loader to receive ad loader events.
hlsInterstitialsAdsLoader.addListener(listener);
AdsLoaderListener listener = new AdsLoaderListener();
// Add the listener to the ads loader to receive ad loader events.
hlsInterstitialsAdsLoader.addListener(listener);
HlsInterstitialsAdsLoader
lifecycle
An instance of HlsInterstitialsAdsLoader
or
HlsInterstitialsAdsLoader.AdsMediaSourceFactory
can be reused for multiple
player instances that create multiple media sources for which ads have to be
loaded.
An instance can be created for example in the onCreate
method of an Activity
and then be re-used for multiple player instances. This works as long as it is
in use by a single player instance at the same time. This is useful for the
common use case when the app is taken into the background, the player instance
is destroyed and then a new instance is created when the app is foregrounded
again.
// Create the ads loader instance (for example onCreate).
hlsInterstitialsAdsLoader = HlsInterstitialsAdsLoader(context);
// Build a player and set it on the ads loader (for example onStart).
player = ExoPlayer.Builder(context).build();
hlsInterstitialsAdsLoader.setPlayer(player);
// Release the player and unset it on the ads loader (for example onStop).
player.release();
hlsInterstitialsAdsLoader.setPlayer(null);
// Build another player and set it on the ads loader (for example onStart).
player = ExoPlayer.Builder(context).build();
hlsInterstitialsAdsLoader.setPlayer(player);
// Release the player and unset it on the ads loader (for example onStop).
player.release();
hlsInterstitialsAdsLoader.setPlayer(null);
// Release the ads loader when not used anymore (for example onDestroy).
hlsInterstitialsAdsLoader.release();
// Create the ads loader instance (for example onCreate).
hlsInterstitialsAdsLoader = new HlsInterstitialsAdsLoader(context);
// Build a player and set it on the ads loader (for example onStart).
player = new ExoPlayer.Builder(context).build();
hlsInterstitialsAdsLoader.setPlayer(player);
// Release the player and unset it on the ads loader (for example onStop).
player.release();
hlsInterstitialsAdsLoader.setPlayer(null);
// Build another player and set it on the ads loader (for example onStart).
player = new ExoPlayer.Builder(context).build();
hlsInterstitialsAdsLoader.setPlayer(player);
// Release the player and unset it on the ads loader (for example onStop).
player.release();
hlsInterstitialsAdsLoader.setPlayer(null);
// Release the ads loader when not used anymore (for example onDestroy).
hlsInterstitialsAdsLoader.release();
Generally, make sure to release the old player instance before setting the next player instance on the ads loader. Once the ads loader itself is released, the ads loader can't be used anymore.
Customizing playback
ExoPlayer provides multiple ways for you to tailor playback experience to your app's needs. See the Customization page for examples.
Disabling chunkless preparation
By default, ExoPlayer will use chunkless preparation. This means that ExoPlayer
will only use the information in the multivariant playlist to prepare the
stream, which works if the #EXT-X-STREAM-INF
tags contain the CODECS
attribute.
You may need to disable this feature if your media segments contain muxed
closed-caption tracks that are not declared in the multivariant playlist with a
#EXT-X-MEDIA:TYPE=CLOSED-CAPTIONS
tag. Otherwise, these closed-caption tracks
won't be detected and played. You can disable chunkless preparation in the
HlsMediaSource.Factory
as shown in the following snippet. Note that this
will increase start up time as ExoPlayer needs to download a media segment to
discover these additional tracks and it is preferable to declare the
closed-caption tracks in the multivariant playlist instead.
val hlsMediaSource =
HlsMediaSource.Factory(dataSourceFactory)
.setAllowChunklessPreparation(false)
.createMediaSource(MediaItem.fromUri(hlsUri))
HlsMediaSource hlsMediaSource =
new HlsMediaSource.Factory(dataSourceFactory)
.setAllowChunklessPreparation(false)
.createMediaSource(MediaItem.fromUri(hlsUri));
Creating high quality HLS content
In order to get the most out of ExoPlayer, there are certain guidelines you can follow to improve your HLS content. Read our Medium post about HLS playback in ExoPlayer for a full explanation. The main points are:
- Use precise segment durations.
- Use a continuous media stream; avoid changes in the media structure across segments.
- Use the
#EXT-X-INDEPENDENT-SEGMENTS
tag. - Prefer demuxed streams, as opposed to files that include both video and audio.
- Include all information you can in the Multivariant Playlist.
The following guidelines apply specifically for live streams:
- Use the
#EXT-X-PROGRAM-DATE-TIME
tag. - Use the
#EXT-X-DISCONTINUITY-SEQUENCE
tag. - Provide a long live window. One minute or more is great.