Package com.google.android.exoplayer2.source.hls.playlist

## Class DefaultHlsPlaylistTracker

- java.lang.Object
- - com.google.android.exoplayer2.source.hls.playlist.DefaultHlsPlaylistTracker

- All Implemented Interfaces:
    `HlsPlaylistTracker`, `Loader.Callback<ParsingLoadable<HlsPlaylist>>`

      public final class DefaultHlsPlaylistTracker
      extends Object
      implements HlsPlaylistTracker, Loader.Callback<ParsingLoadable<HlsPlaylist>>

  Default implementation for `HlsPlaylistTracker`.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface com.google.android.exoplayer2.source.hls.playlist.HlsPlaylistTracker

      `HlsPlaylistTracker.Factory, HlsPlaylistTracker.PlaylistEventListener, HlsPlaylistTracker.PlaylistResetException, HlsPlaylistTracker.PlaylistStuckException, HlsPlaylistTracker.PrimaryPlaylistListener`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static double` | `DEFAULT_PLAYLIST_STUCK_TARGET_DURATION_COEFFICIENT` | 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 HlsPlaylistTracker.Factory` | `FACTORY` | Factory for `DefaultHlsPlaylistTracker` instances.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DefaultHlsPlaylistTracker​(HlsDataSourceFactory dataSourceFactory, LoadErrorHandlingPolicy loadErrorHandlingPolicy, HlsPlaylistParserFactory playlistParserFactory)` | Creates an instance.
    `DefaultHlsPlaylistTracker​(HlsDataSourceFactory dataSourceFactory, LoadErrorHandlingPolicy loadErrorHandlingPolicy, HlsPlaylistParserFactory playlistParserFactory, double playlistStuckTargetDurationCoefficient)` | Creates an instance.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addListener​(HlsPlaylistTracker.PlaylistEventListener listener)` | Registers a listener to receive events from the playlist tracker.
    `boolean` | `excludeMediaPlaylist​(Uri playlistUrl, long exclusionDurationMs)` | Excludes the given media playlist for the given duration, in milliseconds.
    `long` | `getInitialStartTimeUs()` | Returns the start time of the first loaded primary playlist, or `C.TIME_UNSET` if no media playlist has been loaded.
    `HlsMasterPlaylist` | `getMasterPlaylist()` | Returns the master playlist.
    `HlsMediaPlaylist` | `getPlaylistSnapshot​(Uri url, boolean isForPlayback)` | Returns the most recent snapshot available of the playlist referenced by the provided `Uri`.
    `boolean` | `isLive()` | Returns whether the tracked playlists describe a live stream.
    `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.
    `void` | `maybeThrowPlaylistRefreshError​(Uri url)` | If the playlist is having trouble refreshing the playlist referenced by the given `Uri`, this method throws the underlying error.
    `void` | `maybeThrowPrimaryPlaylistRefreshError()` | If the tracker is having trouble refreshing the master 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` | `refreshPlaylist​(Uri url)` | Requests a playlist refresh and removes it from the exclusion list.
    `void` | `removeListener​(HlsPlaylistTracker.PlaylistEventListener listener)` | Unregisters a listener.
    `void` | `start​(Uri initialPlaylistUri, MediaSourceEventListener.EventDispatcher eventDispatcher, HlsPlaylistTracker.PrimaryPlaylistListener primaryPlaylistListener)` | Starts the playlist tracker.
    `void` | `stop()` | Stops the playlist tracker and releases any acquired resources.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### FACTORY

          public static final HlsPlaylistTracker.Factory FACTORY

      Factory for `DefaultHlsPlaylistTracker` instances.

    - #### DEFAULT_PLAYLIST_STUCK_TARGET_DURATION_COEFFICIENT

          public static final double DEFAULT_PLAYLIST_STUCK_TARGET_DURATION_COEFFICIENT

      Default coefficient applied on the target duration of a playlist to determine the amount of time after which an unchanging playlist is considered stuck.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DefaultHlsPlaylistTracker

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

      Creates an instance.
      Parameters:
        `dataSourceFactory` - A factory for `DataSource` instances.
        `loadErrorHandlingPolicy` - The `LoadErrorHandlingPolicy`.
        `playlistParserFactory` - An `HlsPlaylistParserFactory`.

    - #### DefaultHlsPlaylistTracker

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

      Creates an instance.
      Parameters:
        `dataSourceFactory` - A factory for `DataSource` instances.
        `loadErrorHandlingPolicy` - The `LoadErrorHandlingPolicy`.
        `playlistParserFactory` - An `HlsPlaylistParserFactory`.
        `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 `HlsPlaylistTracker.PlaylistStuckException` is thrown via `maybeThrowPlaylistRefreshError(Uri)`.

  - ### Method Detail

    - #### start

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

      Description copied from interface: `HlsPlaylistTracker`
      Starts the playlist tracker.

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

      Specified by:
        `start` in interface `HlsPlaylistTracker`
      Parameters:
        `initialPlaylistUri` - Uri of the HLS stream. Can point to a media playlist or a master playlist.
        `eventDispatcher` - A dispatcher to notify of events.
        `primaryPlaylistListener` - A callback for the primary playlist change events.

    - #### stop

          public void stop()

      Description copied from interface: `HlsPlaylistTracker`
      Stops the playlist tracker and releases any acquired resources.

      Must be called once per `HlsPlaylistTracker.start(android.net.Uri, com.google.android.exoplayer2.source.MediaSourceEventListener.EventDispatcher, com.google.android.exoplayer2.source.hls.playlist.HlsPlaylistTracker.PrimaryPlaylistListener)` call.

      Specified by:
        `stop` in interface `HlsPlaylistTracker`

    - #### addListener

          public void addListener​(HlsPlaylistTracker.PlaylistEventListener listener)

      Description copied from interface: `HlsPlaylistTracker`
      Registers a listener to receive events from the playlist tracker.
      Specified by:
        `addListener` in interface `HlsPlaylistTracker`
      Parameters:
        `listener` - The listener.

    - #### removeListener

          public void removeListener​(HlsPlaylistTracker.PlaylistEventListener listener)

      Description copied from interface: `HlsPlaylistTracker`
      Unregisters a listener.
      Specified by:
        `removeListener` in interface `HlsPlaylistTracker`
      Parameters:
        `listener` - The listener to unregister.

    - #### getMasterPlaylist

          @Nullable
          public HlsMasterPlaylist getMasterPlaylist()

      Description copied from interface: `HlsPlaylistTracker`
      Returns the master playlist.

      If the uri passed to `HlsPlaylistTracker.start(android.net.Uri, com.google.android.exoplayer2.source.MediaSourceEventListener.EventDispatcher, com.google.android.exoplayer2.source.hls.playlist.HlsPlaylistTracker.PrimaryPlaylistListener)` points to a media playlist, an `HlsMasterPlaylist` with a single variant for said media playlist is returned.

      Specified by:
        `getMasterPlaylist` in interface `HlsPlaylistTracker`
      Returns:
        The master playlist. Null if the initial playlist has yet to be loaded.

    - #### getPlaylistSnapshot

          @Nullable
          public HlsMediaPlaylist getPlaylistSnapshot​(Uri url,
                                                      boolean isForPlayback)

      Description copied from interface: `HlsPlaylistTracker`
      Returns the most recent snapshot available of the playlist referenced by the provided `Uri`.
      Specified by:
        `getPlaylistSnapshot` in interface `HlsPlaylistTracker`
      Parameters:
        `url` - The `Uri` corresponding to the requested media playlist.
        `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:
        The most recent snapshot of the playlist referenced by the provided `Uri`. May be null if no snapshot has been loaded yet.

    - #### getInitialStartTimeUs

          public long getInitialStartTimeUs()

      Description copied from interface: `HlsPlaylistTracker`
      Returns the start time of the first loaded primary playlist, or `C.TIME_UNSET` if no media playlist has been loaded.
      Specified by:
        `getInitialStartTimeUs` in interface `HlsPlaylistTracker`

    - #### isSnapshotValid

          public boolean isSnapshotValid​(Uri url)

      Description copied from interface: `HlsPlaylistTracker`
      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.
      Specified by:
        `isSnapshotValid` in interface `HlsPlaylistTracker`
      Parameters:
        `url` - The `Uri`.
      Returns:
        Whether the snapshot of the playlist referenced by the provided `Uri` is valid.

    - #### maybeThrowPrimaryPlaylistRefreshError

          public void maybeThrowPrimaryPlaylistRefreshError()
                                                     throws IOException

      Description copied from interface: `HlsPlaylistTracker`
      If the tracker is having trouble refreshing the master playlist or the primary playlist, this method throws the underlying error. Otherwise, does nothing.
      Specified by:
        `maybeThrowPrimaryPlaylistRefreshError` in interface `HlsPlaylistTracker`
      Throws:
        `IOException` - The underlying error.

    - #### maybeThrowPlaylistRefreshError

          public void maybeThrowPlaylistRefreshError​(Uri url)
                                              throws IOException

      Description copied from interface: `HlsPlaylistTracker`
      If the playlist is having trouble refreshing the playlist referenced by the given `Uri`, this method throws the underlying error.
      Specified by:
        `maybeThrowPlaylistRefreshError` in interface `HlsPlaylistTracker`
      Parameters:
        `url` - The `Uri`.
      Throws:
        `IOException` - The underyling error.

    - #### refreshPlaylist

          public void refreshPlaylist​(Uri url)

      Description copied from interface: `HlsPlaylistTracker`
      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.

      Specified by:
        `refreshPlaylist` in interface `HlsPlaylistTracker`
      Parameters:
        `url` - The `Uri` of the playlist to be refreshed.

    - #### isLive

          public boolean isLive()

      Description copied from interface: `HlsPlaylistTracker`
      Returns whether the tracked playlists describe a live stream.
      Specified by:
        `isLive` in interface `HlsPlaylistTracker`
      Returns:
        True if the content is live. False otherwise.

    - #### excludeMediaPlaylist

          public boolean excludeMediaPlaylist​(Uri playlistUrl,
                                              long exclusionDurationMs)

      Description copied from interface: `HlsPlaylistTracker`
      Excludes the given media playlist for the given duration, in milliseconds.
      Specified by:
        `excludeMediaPlaylist` in interface `HlsPlaylistTracker`
      Parameters:
        `playlistUrl` - The URL of the media playlist.
        `exclusionDurationMs` - The duration for which to exclude the playlist.
      Returns:
        Whether exclusion was successful.

    - #### onLoadCompleted

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

      Description copied from interface: `Loader.Callback`
      Called when a load has completed.

      Note: There is guaranteed to be a memory barrier between `Loader.Loadable.load()` exiting and this callback being called.

      Specified by:
        `onLoadCompleted` in interface `Loader.Callback<ParsingLoadable<HlsPlaylist>>`
      Parameters:
        `loadable` - The loadable whose load has completed.
        `elapsedRealtimeMs` - `SystemClock.elapsedRealtime()` when the load ended.
        `loadDurationMs` - The duration in milliseconds of the load since `Loader.startLoading(T, com.google.android.exoplayer2.upstream.Loader.Callback<T>, int)` was called.

    - #### onLoadCanceled

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

      Description copied from interface: `Loader.Callback`
      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 `Loader.Loadable.load()` exiting and this callback being called. If the `Loader` has been released then this callback may be called before `Loader.Loadable.load()` exits.

      Specified by:
        `onLoadCanceled` in interface `Loader.Callback<ParsingLoadable<HlsPlaylist>>`
      Parameters:
        `loadable` - The loadable whose load has been canceled.
        `elapsedRealtimeMs` - `SystemClock.elapsedRealtime()` when the load was canceled.
        `loadDurationMs` - The duration in milliseconds of the load since `Loader.startLoading(T, com.google.android.exoplayer2.upstream.Loader.Callback<T>, int)` was called up to the point at which it was canceled.
        `released` - True if the load was canceled because the `Loader` was released. False otherwise.

    - #### onLoadError

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

      Description copied from interface: `Loader.Callback`
      Called when a load encounters an error.

      Note: There is guaranteed to be a memory barrier between `Loader.Loadable.load()` exiting and this callback being called.

      Specified by:
        `onLoadError` in interface `Loader.Callback<ParsingLoadable<HlsPlaylist>>`
      Parameters:
        `loadable` - The loadable whose load has encountered an error.
        `elapsedRealtimeMs` - `SystemClock.elapsedRealtime()` when the error occurred.
        `loadDurationMs` - The duration in milliseconds of the load since `Loader.startLoading(T, com.google.android.exoplayer2.upstream.Loader.Callback<T>, int)` was called up to the point at which the error occurred.
        `error` - The load error.
        `errorCount` - The number of errors this load has encountered, including this one.
      Returns:
        The desired error handling action. One of `Loader.RETRY`, `Loader.RETRY_RESET_ERROR_COUNT`, `Loader.DONT_RETRY`, `Loader.DONT_RETRY_FATAL` or a retry action created by `Loader.createRetryAction(boolean, long)`.