DefaultHlsPlaylistTracker

Artifact: androidx.media3:media3-exoplayer-hls

Kotlin |Java

@UnstableApi
class DefaultHlsPlaylistTracker : HlsPlaylistTracker, Loader.Callback

Default implementation for HlsPlaylistTracker.

Summary

Constants
`const 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.
`const HlsPlaylistTracker.Factory!`	`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`	`addListener(listener: HlsPlaylistTracker.PlaylistEventListener!)` Registers a listener to receive events from the playlist tracker.
`Unit`	`deactivatePlaylistForPlayback(url: Uri!)` 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`	`isSnapshotValid(url: Uri!)` 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`	`maybeThrowPlaylistRefreshError(url: Uri!)` If the playlist is having trouble refreshing the playlist referenced by the given `Uri`, this method throws the underlying error.
`Unit`	`maybeThrowPrimaryPlaylistRefreshError()` 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`	`refreshPlaylist(url: Uri!)` Requests a playlist refresh and removes it from the exclusion list.
`Unit`	`removeListener(listener: HlsPlaylistTracker.PlaylistEventListener!)` Unregisters a listener.
`Unit`	`start( initialPlaylistUri: Uri!, eventDispatcher: MediaSourceEventListener.EventDispatcher!, primaryPlaylistListener: HlsPlaylistTracker.PrimaryPlaylistListener! )` Starts the playlist tracker.
`Unit`	`stop()` Stops the playlist tracker and releases any acquired resources.

Public properties
`Long`	`initialStartTimeUs`
`Boolean`	`isLive`
`HlsMultivariantPlaylist?`	`multivariantPlaylist`

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 FACTORY: HlsPlaylistTracker.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 initialStartTimeUs: Long

isLive

val isLive: Boolean

multivariantPlaylist

val multivariantPlaylist: HlsMultivariantPlaylist?