HlsPlaylistTracker

Artifact: androidx.media3:media3-exoplayer-hls

View Source

---

Kotlin |Java

@UnstableApi
public interface HlsPlaylistTracker

Known direct subclasses

DefaultHlsPlaylistTracker

DefaultHlsPlaylistTracker

Default implementation for 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 multivariant playlist is an optional kind of playlist defined by the HLS specification (RFC 8216).

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

Summary

Nested types
public interface HlsPlaylistTracker.Factory Factory for HlsPlaylistTracker instances.
public interface HlsPlaylistTracker.PlaylistEventListener Called on playlist loading events.
public final class HlsPlaylistTracker.PlaylistResetException extends IOException Thrown when the media sequence of a new snapshot indicates the server has reset.
public final class HlsPlaylistTracker.PlaylistStuckException extends IOException Thrown when a playlist is considered to be stuck due to a server side error.
public interface HlsPlaylistTracker.PrimaryPlaylistListener Listener for primary playlist changes.

Public methods
abstract void	addListener(HlsPlaylistTracker.PlaylistEventListener listener) Registers a listener to receive events from the playlist tracker.
default void	deactivatePlaylistForPlayback(Uri url) Deactivate the playlist for playback.
abstract boolean	excludeMediaPlaylist(Uri playlistUrl, long exclusionDurationMs) Excludes the given media playlist for the given duration, in milliseconds.
abstract long	getInitialStartTimeUs() Returns the start time of the first loaded primary playlist, or TIME_UNSET if no media playlist has been loaded.
abstract @Nullable HlsMultivariantPlaylist	getMultivariantPlaylist() Returns the multivariant playlist.
abstract @Nullable HlsMediaPlaylist	getPlaylistSnapshot(Uri url, boolean isForPlayback) Returns the most recent snapshot available of the playlist referenced by the provided .
abstract boolean	isLive() Returns whether the tracked playlists describe a live stream.
abstract boolean	isSnapshotValid(Uri url) Returns whether the snapshot of the playlist referenced by the provided Uri is valid, meaning all the segments referenced by the playlist are expected to be available.
abstract void	maybeThrowPlaylistRefreshError(Uri url) If the playlist is having trouble refreshing the playlist referenced by the given Uri, this method throws the underlying error.
abstract void	maybeThrowPrimaryPlaylistRefreshError() If the tracker is having trouble refreshing the multivariant playlist or the primary playlist, this method throws the underlying error.
abstract void	refreshPlaylist(Uri url) Requests a playlist refresh and removes it from the exclusion list.
abstract void	removeListener(HlsPlaylistTracker.PlaylistEventListener listener) Unregisters a listener.
abstract void	start(     Uri initialPlaylistUri,     MediaSourceEventListener.EventDispatcher eventDispatcher,     HlsPlaylistTracker.PrimaryPlaylistListener primaryPlaylistListener ) Starts the playlist tracker.
abstract void	stop() Stops the playlist tracker and releases any acquired resources.

Public methods

addListener

abstract void addListener(HlsPlaylistTracker.PlaylistEventListener listener)

Registers a listener to receive events from the playlist tracker.

Parameters
HlsPlaylistTracker.PlaylistEventListener listener	The listener.

deactivatePlaylistForPlayback

default void deactivatePlaylistForPlayback(Uri url)

Deactivate the playlist for playback.

The default implementation is a no-op.

Parameters
Uri url	The Uri of the playlist to deactivate for playback.

excludeMediaPlaylist

abstract boolean excludeMediaPlaylist(Uri playlistUrl, long exclusionDurationMs)

Excludes the given media playlist for the given duration, in milliseconds.

Parameters
Uri playlistUrl	The URL of the media playlist.
long exclusionDurationMs	The duration for which to exclude the playlist.

Returns
boolean	Whether exclusion was successful.

getInitialStartTimeUs

abstract long getInitialStartTimeUs()

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

getMultivariantPlaylist

abstract @Nullable HlsMultivariantPlaylist getMultivariantPlaylist()

Returns the multivariant playlist.

If the uri passed to start points to a media playlist, an with a single variant for said media playlist is returned.

Returns
@Nullable HlsMultivariantPlaylist	The multivariant playlist. Null if the initial playlist has yet to be loaded.

getPlaylistSnapshot

abstract @Nullable HlsMediaPlaylist getPlaylistSnapshot(Uri url, boolean isForPlayback)

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

Parameters
Uri url	The Uri corresponding to the requested media playlist.
boolean isForPlayback	Whether the caller might use the snapshot to request media segments for playback. If true, the primary playlist may be updated to the one requested.

Returns
@Nullable HlsMediaPlaylist	The most recent snapshot of the playlist referenced by the provided Uri. May be null if no snapshot has been loaded yet.

isLive

abstract boolean isLive()

Returns whether the tracked playlists describe a live stream.

Returns
boolean	True if the content is live. False otherwise.

isSnapshotValid

abstract boolean isSnapshotValid(Uri url)

Returns whether the snapshot of the playlist referenced by the provided Uri 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
Uri url	The Uri.

Returns
boolean	Whether the snapshot of the playlist referenced by the provided Uri is valid.

maybeThrowPlaylistRefreshError

abstract void maybeThrowPlaylistRefreshError(Uri url)

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

Parameters
Uri url	The Uri.

Throws
java.io.IOException	The underyling error.

maybeThrowPrimaryPlaylistRefreshError

abstract void maybeThrowPrimaryPlaylistRefreshError()

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

Throws
java.io.IOException	The underlying error.

refreshPlaylist

abstract void refreshPlaylist(Uri url)

Requests a playlist refresh and removes it from the exclusion list.

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

Parameters
Uri url	The Uri of the playlist to be refreshed.

removeListener

abstract void removeListener(HlsPlaylistTracker.PlaylistEventListener listener)

Unregisters a listener.

Parameters
HlsPlaylistTracker.PlaylistEventListener listener	The listener to unregister.

start

abstract void start(
    Uri initialPlaylistUri,
    MediaSourceEventListener.EventDispatcher eventDispatcher,
    HlsPlaylistTracker.PrimaryPlaylistListener primaryPlaylistListener
)

Starts the playlist tracker.

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

Parameters
Uri initialPlaylistUri	Uri of the HLS stream. Can point to a media playlist or a multivariant playlist.
MediaSourceEventListener.EventDispatcher eventDispatcher	A dispatcher to notify of events.
HlsPlaylistTracker.PrimaryPlaylistListener primaryPlaylistListener	A callback for the primary playlist change events.

stop

abstract void stop()

Stops the playlist tracker and releases any acquired resources.

Must be called once per start call.