DefaultHlsPlaylistTracker


@UnstableApi
class DefaultHlsPlaylistTracker : HlsPlaylistTracker, Loader.Callback


Default implementation for HlsPlaylistTracker.

Summary

Constants

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

const HlsPlaylistTracker.Factory!

Factory for DefaultHlsPlaylistTracker instances.

Public constructors

DefaultHlsPlaylistTracker(
    dataSourceFactory: HlsDataSourceFactory!,
    loadErrorHandlingPolicy: LoadErrorHandlingPolicy!,
    playlistParserFactory: HlsPlaylistParserFactory!
)

Creates an instance.

DefaultHlsPlaylistTracker(
    dataSourceFactory: HlsDataSourceFactory!,
    loadErrorHandlingPolicy: LoadErrorHandlingPolicy!,
    playlistParserFactory: HlsPlaylistParserFactory!,
    playlistStuckTargetDurationCoefficient: Double
)

Creates an instance.

Public functions

Unit

Registers a listener to receive events from the playlist tracker.

Unit

Deactivate the playlist for playback.

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

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

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

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

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
onLoadCanceled(
    loadable: ParsingLoadable<HlsPlaylist!>!,
    elapsedRealtimeMs: Long,
    loadDurationMs: Long,
    released: Boolean
)

Called when a load has been canceled.

Unit
onLoadCompleted(
    loadable: ParsingLoadable<HlsPlaylist!>!,
    elapsedRealtimeMs: Long,
    loadDurationMs: Long
)

Called when a load has completed.

Loader.LoadErrorAction!
onLoadError(
    loadable: ParsingLoadable<HlsPlaylist!>!,
    elapsedRealtimeMs: Long,
    loadDurationMs: Long,
    error: IOException!,
    errorCount: Int
)

Called when a load encounters an 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.

Inherited functions

From androidx.media3.exoplayer.upstream.Loader.Callback
Unit
onLoadStarted(
    loadable: T!,
    elapsedRealtimeMs: Long,
    loadDurationMs: Long,
    retryCount: Int
)

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

Constants

DEFAULT_PLAYLIST_STUCK_TARGET_DURATION_COEFFICIENT

const val DEFAULT_PLAYLIST_STUCK_TARGET_DURATION_COEFFICIENT = 3.5: 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.

FACTORY

const val FACTORYHlsPlaylistTracker.Factory!

Factory for DefaultHlsPlaylistTracker instances.

Public constructors

DefaultHlsPlaylistTracker

DefaultHlsPlaylistTracker(
    dataSourceFactory: HlsDataSourceFactory!,
    loadErrorHandlingPolicy: LoadErrorHandlingPolicy!,
    playlistParserFactory: HlsPlaylistParserFactory!
)

Creates an instance.

Parameters
dataSourceFactory: HlsDataSourceFactory!

A factory for DataSource instances.

loadErrorHandlingPolicy: LoadErrorHandlingPolicy!

The LoadErrorHandlingPolicy.

playlistParserFactory: HlsPlaylistParserFactory!

An HlsPlaylistParserFactory.

DefaultHlsPlaylistTracker

DefaultHlsPlaylistTracker(
    dataSourceFactory: HlsDataSourceFactory!,
    loadErrorHandlingPolicy: LoadErrorHandlingPolicy!,
    playlistParserFactory: HlsPlaylistParserFactory!,
    playlistStuckTargetDurationCoefficient: Double
)

Creates an instance.

Parameters
dataSourceFactory: HlsDataSourceFactory!

A factory for DataSource instances.

loadErrorHandlingPolicy: LoadErrorHandlingPolicy!

The LoadErrorHandlingPolicy.

playlistParserFactory: HlsPlaylistParserFactory!

An HlsPlaylistParserFactory.

playlistStuckTargetDurationCoefficient: Double

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 functions

addListener

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

Registers a listener to receive events from the playlist tracker.

Parameters
listener: HlsPlaylistTracker.PlaylistEventListener!

The listener.

deactivatePlaylistForPlayback

fun deactivatePlaylistForPlayback(url: Uri!): Unit

Deactivate the playlist for playback.

The default implementation is a no-op.

Parameters
url: Uri!

The Uri of the playlist to deactivate for playback.

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.

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.

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.

onLoadCanceled

fun onLoadCanceled(
    loadable: ParsingLoadable<HlsPlaylist!>!,
    elapsedRealtimeMs: Long,
    loadDurationMs: Long,
    released: Boolean
): Unit

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
loadable: ParsingLoadable<HlsPlaylist!>!

The loadable whose load has been canceled.

elapsedRealtimeMs: Long

elapsedRealtime when the load was canceled.

loadDurationMs: Long

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

released: Boolean

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

onLoadCompleted

fun onLoadCompleted(
    loadable: ParsingLoadable<HlsPlaylist!>!,
    elapsedRealtimeMs: Long,
    loadDurationMs: Long
): Unit

Called when a load has completed.

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

Parameters
loadable: ParsingLoadable<HlsPlaylist!>!

The loadable whose load has completed.

elapsedRealtimeMs: Long

elapsedRealtime when the load ended.

loadDurationMs: Long

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

onLoadError

fun onLoadError(
    loadable: ParsingLoadable<HlsPlaylist!>!,
    elapsedRealtimeMs: Long,
    loadDurationMs: Long,
    error: IOException!,
    errorCount: Int
): Loader.LoadErrorAction!

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
loadable: ParsingLoadable<HlsPlaylist!>!

The loadable whose load has encountered an error.

elapsedRealtimeMs: Long

elapsedRealtime when the error occurred.

loadDurationMs: Long

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

error: IOException!

The load error.

errorCount: Int

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

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.

Public properties

initialStartTimeUs

val initialStartTimeUsLong

isLive

val isLiveBoolean

multivariantPlaylist

val multivariantPlaylistHlsMultivariantPlaylist?