DefaultHlsPlaylistTracker


@UnstableApi
public final class DefaultHlsPlaylistTracker implements HlsPlaylistTracker, Loader.Callback


Default implementation for HlsPlaylistTracker.

Summary

Constants

static final double

Default coefficient applied on the target duration of a playlist to determine the amount of time after which an unchanging playlist is considered stuck.

static final HlsPlaylistTracker.Factory

Factory for DefaultHlsPlaylistTracker instances.

Public constructors

DefaultHlsPlaylistTracker(
    HlsDataSourceFactory dataSourceFactory,
    LoadErrorHandlingPolicy loadErrorHandlingPolicy,
    HlsPlaylistParserFactory playlistParserFactory
)

Creates an instance.

DefaultHlsPlaylistTracker(
    HlsDataSourceFactory dataSourceFactory,
    LoadErrorHandlingPolicy loadErrorHandlingPolicy,
    HlsPlaylistParserFactory playlistParserFactory,
    double playlistStuckTargetDurationCoefficient
)

Creates an instance.

Public methods

void

Registers a listener to receive events from the playlist tracker.

void

Deactivate the playlist for playback.

boolean
excludeMediaPlaylist(Uri playlistUrl, long exclusionDurationMs)

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.

@Nullable HlsMultivariantPlaylist

Returns the multivariant playlist.

@Nullable HlsMediaPlaylist
getPlaylistSnapshot(Uri url, boolean isForPlayback)

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.

void

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

void

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

void
onLoadCanceled(
    ParsingLoadable<HlsPlaylist> loadable,
    long elapsedRealtimeMs,
    long loadDurationMs,
    boolean released
)

Called when a load has been canceled.

void
onLoadCompleted(
    ParsingLoadable<HlsPlaylist> loadable,
    long elapsedRealtimeMs,
    long loadDurationMs
)

Called when a load has completed.

Loader.LoadErrorAction
onLoadError(
    ParsingLoadable<HlsPlaylist> loadable,
    long elapsedRealtimeMs,
    long loadDurationMs,
    IOException error,
    int errorCount
)

Called when a load encounters an error.

void

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

void

Unregisters a listener.

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

Starts the playlist tracker.

void

Stops the playlist tracker and releases any acquired resources.

Inherited methods

From androidx.media3.exoplayer.upstream.Loader.Callback
void
onLoadStarted(
    T loadable,
    long elapsedRealtimeMs,
    long loadDurationMs,
    int retryCount
)

Called when a load has started for the first time or through a retry.

Constants

DEFAULT_PLAYLIST_STUCK_TARGET_DURATION_COEFFICIENT

public static final double DEFAULT_PLAYLIST_STUCK_TARGET_DURATION_COEFFICIENT = 3.5

Default coefficient applied on the target duration of a playlist to determine the amount of time after which an unchanging playlist is considered stuck.

FACTORY

public static final HlsPlaylistTracker.Factory FACTORY

Factory for DefaultHlsPlaylistTracker instances.

Public fields

initialStartTimeUs

public long initialStartTimeUs

isLive

public boolean isLive

multivariantPlaylist

public @Nullable HlsMultivariantPlaylist multivariantPlaylist

Public constructors

DefaultHlsPlaylistTracker

public DefaultHlsPlaylistTracker(
    HlsDataSourceFactory dataSourceFactory,
    LoadErrorHandlingPolicy loadErrorHandlingPolicy,
    HlsPlaylistParserFactory playlistParserFactory
)

Creates an instance.

Parameters
HlsDataSourceFactory dataSourceFactory

A factory for DataSource instances.

LoadErrorHandlingPolicy loadErrorHandlingPolicy

The LoadErrorHandlingPolicy.

HlsPlaylistParserFactory playlistParserFactory

An HlsPlaylistParserFactory.

DefaultHlsPlaylistTracker

public DefaultHlsPlaylistTracker(
    HlsDataSourceFactory dataSourceFactory,
    LoadErrorHandlingPolicy loadErrorHandlingPolicy,
    HlsPlaylistParserFactory playlistParserFactory,
    double playlistStuckTargetDurationCoefficient
)

Creates an instance.

Parameters
HlsDataSourceFactory dataSourceFactory

A factory for DataSource instances.

LoadErrorHandlingPolicy loadErrorHandlingPolicy

The LoadErrorHandlingPolicy.

HlsPlaylistParserFactory playlistParserFactory

An HlsPlaylistParserFactory.

double playlistStuckTargetDurationCoefficient

A coefficient to apply to the target duration of media playlists in order to determine that a non-changing playlist is stuck. Once a playlist is deemed stuck, a PlaylistStuckException is thrown via maybeThrowPlaylistRefreshError.

Public methods

addListener

public void addListener(HlsPlaylistTracker.PlaylistEventListener listener)

Registers a listener to receive events from the playlist tracker.

Parameters
HlsPlaylistTracker.PlaylistEventListener listener

The listener.

deactivatePlaylistForPlayback

public 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

public 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

public long getInitialStartTimeUs()

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

getMultivariantPlaylist

public @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

public @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

public boolean isLive()

Returns whether the tracked playlists describe a live stream.

Returns
boolean

True if the content is live. False otherwise.

isSnapshotValid

public 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

public 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

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

onLoadCanceled

public void onLoadCanceled(
    ParsingLoadable<HlsPlaylist> loadable,
    long elapsedRealtimeMs,
    long loadDurationMs,
    boolean released
)

Called when a load has been canceled.

Note: If the Loader has not been released then there is guaranteed to be a memory barrier between load exiting and this callback being called. If the has been released then this callback may be called before load exits.

Parameters
ParsingLoadable<HlsPlaylist> loadable

The loadable whose load has been canceled.

long elapsedRealtimeMs

elapsedRealtime when the load was canceled.

long loadDurationMs

The duration in milliseconds of the load since startLoading was called up to the point at which it was canceled.

boolean released

True if the load was canceled because the Loader was released. False otherwise.

onLoadCompleted

public void onLoadCompleted(
    ParsingLoadable<HlsPlaylist> loadable,
    long elapsedRealtimeMs,
    long loadDurationMs
)

Called when a load has completed.

Note: There is guaranteed to be a memory barrier between load exiting and this callback being called.

Parameters
ParsingLoadable<HlsPlaylist> loadable

The loadable whose load has completed.

long elapsedRealtimeMs

elapsedRealtime when the load ended.

long loadDurationMs

The duration in milliseconds of the load since startLoading was called.

onLoadError

public Loader.LoadErrorAction onLoadError(
    ParsingLoadable<HlsPlaylist> loadable,
    long elapsedRealtimeMs,
    long loadDurationMs,
    IOException error,
    int errorCount
)

Called when a load encounters an error.

Note: There is guaranteed to be a memory barrier between load exiting and this callback being called.

Parameters
ParsingLoadable<HlsPlaylist> loadable

The loadable whose load has encountered an error.

long elapsedRealtimeMs

elapsedRealtime when the error occurred.

long loadDurationMs

The duration in milliseconds of the load since startLoading was called up to the point at which the error occurred.

IOException error

The load error.

int errorCount

The number of errors this load has encountered, including this one.

Returns
Loader.LoadErrorAction

The desired error handling action. One of RETRY, RETRY_RESET_ERROR_COUNT, DONT_RETRY, DONT_RETRY_FATAL or a retry action created by createRetryAction.

refreshPlaylist

public 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

public void removeListener(HlsPlaylistTracker.PlaylistEventListener listener)

Unregisters a listener.

Parameters
HlsPlaylistTracker.PlaylistEventListener listener

The listener to unregister.

start

public 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

public void stop()

Stops the playlist tracker and releases any acquired resources.

Must be called once per start call.