com.google.android.exoplayer2.source.hls.playlist

Interface HlsPlaylistTracker

All Known Implementing Classes:

DefaultHlsPlaylistTracker

public interface HlsPlaylistTracker

Tracks playlists associated to an HLS stream and provides snapshots.

The playlist tracker is responsible for exposing the seeking window, which is defined by the segments that one of the playlists exposes. This playlist is called primary and needs to be periodically refreshed in the case of live streams. Note that the primary playlist is one of the media playlists while the master playlist is an optional kind of playlist defined by the HLS specification (RFC 8216).

Playlist loads might encounter errors. The tracker may choose to blacklist them to ensure a primary playlist is always available.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	HlsPlaylistTracker.PlaylistEventListener Called on playlist loading events.
static class	HlsPlaylistTracker.PlaylistResetException Thrown when the media sequence of a new snapshot indicates the server has reset.
static class	HlsPlaylistTracker.PlaylistStuckException Thrown when a playlist is considered to be stuck due to a server side error.
static interface	HlsPlaylistTracker.PrimaryPlaylistListener Listener for primary playlist changes.

Method Summary

Modifier and Type	Method and Description
void	addListener(HlsPlaylistTracker.PlaylistEventListener listener) Registers a listener to receive events from the playlist tracker.
long	getInitialStartTimeUs() Returns the start time of the first loaded primary playlist, or C.TIME_UNSET if no media playlist has been loaded.
HlsMasterPlaylist	getMasterPlaylist() Returns the master playlist.
HlsMediaPlaylist	getPlaylistSnapshot(HlsMasterPlaylist.HlsUrl url) Returns the most recent snapshot available of the playlist referenced by the provided HlsMasterPlaylist.HlsUrl.
boolean	isLive() Returns whether the tracked playlists describe a live stream.
boolean	isSnapshotValid(HlsMasterPlaylist.HlsUrl url) Returns whether the snapshot of the playlist referenced by the provided HlsMasterPlaylist.HlsUrl is valid, meaning all the segments referenced by the playlist are expected to be available.
void	maybeThrowPlaylistRefreshError(HlsMasterPlaylist.HlsUrl url) If the playlist is having trouble refreshing the playlist referenced by the given HlsMasterPlaylist.HlsUrl, this method throws the underlying error.
void	maybeThrowPrimaryPlaylistRefreshError() If the tracker is having trouble refreshing the master playlist or the primary playlist, this method throws the underlying error.
void	refreshPlaylist(HlsMasterPlaylist.HlsUrl url) Requests a playlist refresh and whitelists it.
void	removeListener(HlsPlaylistTracker.PlaylistEventListener listener) Unregisters a listener.
void	start(android.net.Uri initialPlaylistUri, com.google.android.exoplayer2.source.MediaSourceEventListener.EventDispatcher eventDispatcher, HlsPlaylistTracker.PrimaryPlaylistListener listener) Starts the playlist tracker.
void	stop() Stops the playlist tracker and releases any acquired resources.

Method Detail

start

void start(android.net.Uri initialPlaylistUri,
           com.google.android.exoplayer2.source.MediaSourceEventListener.EventDispatcher eventDispatcher,
           HlsPlaylistTracker.PrimaryPlaylistListener listener)

Starts the playlist tracker.

Must be called from the playback thread. A tracker may be restarted after a stop() call.

Parameters:

initialPlaylistUri - Uri of the HLS stream. Can point to a media playlist or a master playlist.

eventDispatcher - A dispatcher to notify of events.

listener - A callback for the primary playlist change events.

stop

void stop()

Stops the playlist tracker and releases any acquired resources.

Must be called once per start(android.net.Uri, com.google.android.exoplayer2.source.MediaSourceEventListener.EventDispatcher, com.google.android.exoplayer2.source.hls.playlist.HlsPlaylistTracker.PrimaryPlaylistListener) call.

addListener

void addListener(HlsPlaylistTracker.PlaylistEventListener listener)

Registers a listener to receive events from the playlist tracker.

Parameters:

listener - The listener.

removeListener

void removeListener(HlsPlaylistTracker.PlaylistEventListener listener)

Unregisters a listener.

Parameters:

listener - The listener to unregister.

getMasterPlaylist

@Nullable
HlsMasterPlaylist getMasterPlaylist()

Returns the master playlist.

If the uri passed to start(android.net.Uri, com.google.android.exoplayer2.source.MediaSourceEventListener.EventDispatcher, com.google.android.exoplayer2.source.hls.playlist.HlsPlaylistTracker.PrimaryPlaylistListener) points to a media playlist, an HlsMasterPlaylist with a single variant for said media playlist is returned.

Returns:

The master playlist. Null if the initial playlist has yet to be loaded.

getPlaylistSnapshot

@Nullable
HlsMediaPlaylist getPlaylistSnapshot(HlsMasterPlaylist.HlsUrl url)

Returns the most recent snapshot available of the playlist referenced by the provided HlsMasterPlaylist.HlsUrl.

Parameters:

url - The HlsMasterPlaylist.HlsUrl corresponding to the requested media playlist.

Returns:

The most recent snapshot of the playlist referenced by the provided HlsMasterPlaylist.HlsUrl. May be null if no snapshot has been loaded yet.

getInitialStartTimeUs

long getInitialStartTimeUs()

Returns the start time of the first loaded primary playlist, or C.TIME_UNSET if no media playlist has been loaded.

isSnapshotValid

boolean isSnapshotValid(HlsMasterPlaylist.HlsUrl url)

Returns whether the snapshot of the playlist referenced by the provided HlsMasterPlaylist.HlsUrl is valid, meaning all the segments referenced by the playlist are expected to be available. If the playlist is not valid then some of the segments may no longer be available.

Parameters:

url - The HlsMasterPlaylist.HlsUrl.

Returns:

Whether the snapshot of the playlist referenced by the provided HlsMasterPlaylist.HlsUrl is valid.

maybeThrowPrimaryPlaylistRefreshError

void maybeThrowPrimaryPlaylistRefreshError()
                                    throws java.io.IOException

If the tracker is having trouble refreshing the master playlist or the primary playlist, this method throws the underlying error. Otherwise, does nothing.

Throws:

java.io.IOException - The underlying error.

maybeThrowPlaylistRefreshError

void maybeThrowPlaylistRefreshError(HlsMasterPlaylist.HlsUrl url)
                             throws java.io.IOException

If the playlist is having trouble refreshing the playlist referenced by the given HlsMasterPlaylist.HlsUrl, this method throws the underlying error.

Parameters:

url - The HlsMasterPlaylist.HlsUrl.

Throws:

java.io.IOException - The underyling error.

refreshPlaylist

void refreshPlaylist(HlsMasterPlaylist.HlsUrl url)

Requests a playlist refresh and whitelists it.

The playlist tracker may choose the delay the playlist refresh. The request is discarded if a refresh was already pending.

Parameters:

url - The HlsMasterPlaylist.HlsUrl of the playlist to be refreshed.

isLive

boolean isLive()

Returns whether the tracked playlists describe a live stream.

Returns:

True if the content is live. False otherwise.