1044cfe82a
Using chunkless preparation greatly improves start up time if the master playlist declares CODECS for the renditions. Hence, we turn this on by default as it benefits most well-defined HLS master playlists. The only known reason why developers may want to turn this feature off is when the renditions contain muxed closed-caption tracks that are not declared in the master playlist. So this change also updates the documentation and RELEASENOTES to point out this caveat. PiperOrigin-RevId: 413950036
136 lines
4.9 KiB
Markdown
136 lines
4.9 KiB
Markdown
---
|
|
title: HLS
|
|
---
|
|
|
|
{% include_relative _page_fragments/supported-formats-hls.md %}
|
|
|
|
## Using MediaItem ##
|
|
|
|
To play an HLS stream, you need to depend on the HLS module.
|
|
|
|
~~~
|
|
implementation 'com.google.android.exoplayer:exoplayer-hls:2.X.X'
|
|
~~~
|
|
{: .language-gradle}
|
|
|
|
You can then create a `MediaItem` for an HLS playlist URI and pass it to the
|
|
player.
|
|
|
|
~~~
|
|
// 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();
|
|
~~~
|
|
{: .language-java}
|
|
|
|
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 master
|
|
playlist. If the URI points to a master 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.
|
|
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 media source to be played.
|
|
player.setMediaSource(hlsMediaSource);
|
|
// Prepare the player.
|
|
player.prepare();
|
|
~~~
|
|
{: .language-java}
|
|
|
|
## 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 a on-demand content, and
|
|
possibly many times for live content. The code snippet below shows how an app
|
|
can do something whenever the manifest is loaded.
|
|
|
|
~~~
|
|
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.
|
|
}
|
|
}
|
|
});
|
|
~~~
|
|
{: .language-java}
|
|
|
|
## 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 master 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 master 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 master playlist instead.
|
|
~~~
|
|
HlsMediaSource hlsMediaSource =
|
|
new HlsMediaSource.Factory(dataSourceFactory)
|
|
.setAllowChunklessPreparation(false)
|
|
.createMediaSource(MediaItem.fromUri(hlsUri));
|
|
~~~
|
|
{: .language-java}
|
|
|
|
## 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 Master 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.
|
|
|
|
[HlsMediaSource]: {{ site.exo_sdk }}/source/hls/HlsMediaSource.html
|
|
[HTTP Live Streaming]: https://tools.ietf.org/html/rfc8216
|
|
[PlayerView]: {{ site.exo_sdk }}/ui/PlayerView.html
|
|
[UI components]: {{ site.baseurl }}/ui-components.html
|
|
[Customization page]: {{ site.baseurl }}/customization.html
|
|
[Medium post about HLS playback in ExoPlayer]: https://medium.com/google-exoplayer/hls-playback-in-exoplayer-a33959a47be7
|