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

## Interface HlsPlaylistTracker

- All Known Implementing Classes:
    `DefaultHlsPlaylistTracker`

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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static interface` | `HlsPlaylistTracker.Factory` | Factory for `HlsPlaylistTracker` instances.
    `static interface` | `HlsPlaylistTracker.PlaylistEventListener` | Called on playlist loading events.
    `static class` | `HlsPlaylistTracker.PlaylistResetException` | Thrown when the media sequence of a new snapshot indicates the server has reset.
    `static class` | `HlsPlaylistTracker.PlaylistStuckException` | Thrown when a playlist is considered to be stuck due to a server side error.
    `static interface` | `HlsPlaylistTracker.PrimaryPlaylistListener` | Listener for primary playlist changes.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addListener​(HlsPlaylistTracker.PlaylistEventListener listener)` | Registers a listener to receive events from the playlist tracker.
    `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` | `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 listener)` | Starts the playlist tracker.
    `void` | `stop()` | Stops the playlist tracker and releases any acquired resources.

- - ### Method Detail

    - #### start

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

      Starts the playlist tracker.

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

      Parameters:
        `initialPlaylistUri` - Uri of the HLS stream. Can point to a media playlist or a master playlist.
        `eventDispatcher` - A dispatcher to notify of events.
        `listener` - A callback for the primary playlist change events.

    - #### stop

          void stop()

      Stops the playlist tracker and releases any acquired resources.

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

    - #### addListener

          void addListener​(HlsPlaylistTracker.PlaylistEventListener listener)

      Registers a listener to receive events from the playlist tracker.
      Parameters:
        `listener` - The listener.

    - #### removeListener

          void removeListener​(HlsPlaylistTracker.PlaylistEventListener listener)

      Unregisters a listener.
      Parameters:
        `listener` - The listener to unregister.

    - #### getMasterPlaylist

          @Nullable
          HlsMasterPlaylist getMasterPlaylist()

      Returns the master playlist.

      If the uri passed to `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.

      Returns:
        The master playlist. Null if the initial playlist has yet to be loaded.

    - #### getPlaylistSnapshot

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

      Returns the most recent snapshot available of the playlist referenced by the provided `Uri`.
      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

          long getInitialStartTimeUs()

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

    - #### isSnapshotValid

          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:
        `url` - The `Uri`.
      Returns:
        Whether the snapshot of the playlist referenced by the provided `Uri` is valid.

    - #### maybeThrowPrimaryPlaylistRefreshError

          void maybeThrowPrimaryPlaylistRefreshError()
                                              throws IOException

      If the tracker is having trouble refreshing the master playlist or the primary playlist, this method throws the underlying error. Otherwise, does nothing.
      Throws:
        `IOException` - The underlying error.

    - #### maybeThrowPlaylistRefreshError

          void maybeThrowPlaylistRefreshError​(Uri url)
                                       throws IOException

      If the playlist is having trouble refreshing the playlist referenced by the given `Uri`, this method throws the underlying error.
      Parameters:
        `url` - The `Uri`.
      Throws:
        `IOException` - The underyling error.

    - #### refreshPlaylist

          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:
        `url` - The `Uri` of the playlist to be refreshed.

    - #### isLive

          boolean isLive()

      Returns whether the tracked playlists describe a live stream.
      Returns:
        True if the content is live. False otherwise.