HlsPlaylistTracker

@UnstableApi
interface HlsPlaylistTracker

Known direct subclasses
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

Factory for HlsPlaylistTracker instances.

Called on playlist loading events.

Thrown when the media sequence of a new snapshot indicates the server has reset.

Thrown when a playlist is considered to be stuck due to a server side error.

Listener for primary playlist changes.

Public functions
Unit

Registers a listener to receive events from the playlist tracker.
Boolean
excludeMediaPlaylist(playlistUrl: Uri!, exclusionDurationMs: Long)

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

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

Returns the multivariant playlist.
HlsMediaPlaylist?
getPlaylistSnapshot(url: Uri!, isForPlayback: Boolean)

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

Returns whether the tracked playlists describe a live stream.
Boolean

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.
Unit

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

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

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

Unregisters a listener.
Unit
start(
    initialPlaylistUri: Uri!,
    eventDispatcher: MediaSourceEventListener.EventDispatcher!,
    primaryPlaylistListener: HlsPlaylistTracker.PrimaryPlaylistListener!
)

Starts the playlist tracker.
Unit

Stops the playlist tracker and releases any acquired resources.

Public functions

addListener

fun addListener(listener: HlsPlaylistTracker.PlaylistEventListener!): Unit

Registers a listener to receive events from the playlist tracker.

Parameters
listener: HlsPlaylistTracker.PlaylistEventListener!

The listener.

excludeMediaPlaylist

fun excludeMediaPlaylist(playlistUrl: Uri!, exclusionDurationMs: Long): Boolean

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

Parameters
playlistUrl: Uri!

The URL of the media playlist.
exclusionDurationMs: Long

The duration for which to exclude the playlist.
Returns
Boolean

Whether exclusion was successful.

getInitialStartTimeUs

fun getInitialStartTimeUs(): Long

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

getMultivariantPlaylist

fun getMultivariantPlaylist(): HlsMultivariantPlaylist?

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
HlsMultivariantPlaylist?

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

getPlaylistSnapshot

fun getPlaylistSnapshot(url: Uri!, isForPlayback: Boolean): HlsMediaPlaylist?

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

Parameters
url: Uri!

The Uri corresponding to the requested media playlist.
isForPlayback: Boolean

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
HlsMediaPlaylist?

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

isLive

fun isLive(): Boolean

Returns whether the tracked playlists describe a live stream.

Returns
Boolean

True if the content is live. False otherwise.

isSnapshotValid

fun isSnapshotValid(url: Uri!): Boolean

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
url: Uri!

The Uri.
Returns
Boolean

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

maybeThrowPlaylistRefreshError

fun maybeThrowPlaylistRefreshError(url: Uri!): Unit

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

Parameters
url: Uri!

The Uri.
Throws
java.io.IOException

The underyling error.

maybeThrowPrimaryPlaylistRefreshError

fun maybeThrowPrimaryPlaylistRefreshError(): Unit

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

fun refreshPlaylist(url: Uri!): Unit

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
url: Uri!

The Uri of the playlist to be refreshed.

removeListener

fun removeListener(listener: HlsPlaylistTracker.PlaylistEventListener!): Unit

Unregisters a listener.

Parameters
listener: HlsPlaylistTracker.PlaylistEventListener!

The listener to unregister.

start

fun start(
    initialPlaylistUri: Uri!,
    eventDispatcher: MediaSourceEventListener.EventDispatcher!,
    primaryPlaylistListener: HlsPlaylistTracker.PrimaryPlaylistListener!
): Unit

Starts the playlist tracker.

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

Parameters
initialPlaylistUri: Uri!

Uri of the HLS stream. Can point to a media playlist or a multivariant playlist.
eventDispatcher: MediaSourceEventListener.EventDispatcher!

A dispatcher to notify of events.
primaryPlaylistListener: HlsPlaylistTracker.PrimaryPlaylistListener!

A callback for the primary playlist change events.

stop

fun stop(): Unit

Stops the playlist tracker and releases any acquired resources.

Must be called once per start call.