Package com.jwplayer.pub.api.offline

Interface OfflineDownloadManager

public interface OfflineDownloadManager
Offline download API.

Obtain the implementation from OfflineDownloadFactory.getOfflineDownloadManager(Context); this interface is not intended to be implemented by hosts. Methods added after the interface first shipped are default and throw UnsupportedOperationException, so that a host which does implement or wrap it - a bridge layer, a test double - keeps compiling when the interface grows. Override the ones you need. The SDK's own implementation overrides all of them.

  • Method Details

    • prepareMediaDownload

      void prepareMediaDownload(android.content.Context context, PlaylistItem item)
      Prepares a download for the provided PlaylistItem and notifies the listener as updates become available

    • setMediaDownloadResultListener

      void setMediaDownloadResultListener(MediaDownloadResultListener listener)
      Prepare listener to notifies the download status from the download request.

    • downloadMedia

      void downloadMedia(android.content.Context context, MediaDownloadOption videoDownloadOption, MediaDownloadOption audioDownloadOption)
      Downloads the provided video and audio options.

    • downloadMedia

      void downloadMedia(android.content.Context context, MediaDownloadOption videoDownloadOption, List<MediaDownloadOption> audioDownloadOptions)
      Downloads the provided video and audio options.

    • downloadMedia

      void downloadMedia(android.content.Context context, MediaDownloadOption videoDownloadOption, List<MediaDownloadOption> audioDownloadOptions, List<MediaDownloadOption> textDownloadOptions)
      Downloads the provided video, audio, and text options.

    • getAllDownloads

      Set<String> getAllDownloads()
      Returns a Set of all downloaded mediaIDs

    • getDownloads

      default List<OfflineDownloadInfo> getDownloads(android.content.Context context)
      Returns every download the SDK knows about, complete or still in progress, with its size, progress and the PlaylistItem needed to play it back offline.

      Prefer this to combining getAllDownloads() with per-id lookups: this reads the download index once, whereas the per-id calls each read it again.

      Includes downloads in every state, not only completed ones - failed, paused, queued and in-progress downloads all appear. Check OfflineDownloadInfo.isComplete() before treating an entry as playable: OfflineDownloadInfo.getPlaylistItem() is non-null for partially downloaded items too, and playing one hands the player incomplete media.

      Each item's OfflineDownloadInfo.getPlaylistItem() is rebuilt from the fields persisted with the download; anything that cannot be persisted - in particular a host-supplied MediaDrmCallback - is not carried and must be re-attached by the host before playback. See OfflineDownloadInfo.getPlaylistItem().

      Blocking. Reads the download index from disk and rebuilds one PlaylistItem per download, so cost grows with the size of the library. Call it off the main thread when rendering a list. Safe from any thread: the in-progress snapshot is read on the download manager's own thread internally.

      Returns an empty list when nothing has been downloaded. Ordering is unspecified.

      Parameters:
      context - any Context; currently unused, reserved for future use

    • startService

      void startService(android.content.Context context)
      Starts the Download Service

    • removeDownload

      void removeDownload(android.content.Context context, String mediaId)
      Removes the provided download from memory.

      Once the removal has completed, the SDK makes a best-effort attempt to release the download's offline DRM licence back to the licence server. Limits of that attempt, stated plainly:

      • The release uses the licence URL stored when the download was created. If that URL is token-signed with a short expiry, the server will typically reject the late release; the local MediaDrm licence state is still updated on a best-effort basis.
      • A host-supplied MediaDrmCallback is used for the release when one is available. The callback attached to the PlaylistItem you prepared is remembered only while the OfflineDownloadManager that prepared it is alive, and is not persisted - so it is gone after OfflineDownloadFactory.destroyAll() and after an app restart. To have a callback available for every removal, register an OfflineDrmCallbackProvider once per process with OfflineDownloadFactory.setOfflineDrmCallbackProvider(OfflineDrmCallbackProvider), normally from Application.onCreate(); the SDK then asks it for a callback whenever it needs one, from any screen and in any later run of the app. With neither available the release falls back to the stored licence URL, and does nothing at all if the item was configured with a callback and no URL.
      • The release runs in the app process; if the process dies right after the removal, the release may be lost. Release failures never block or fail the removal itself.

    • pauseDownload

      default void pauseDownload(android.content.Context context, @NonNull String mediaId)
      Stops a download without discarding it.

      Whatever has already been written stays on disk, so resumeDownload(Context, String) continues from that point rather than starting over. The download then reports OfflineDownloadState.PAUSED.

      The pause is persisted, so it survives the app being killed: a paused download does not restart by itself and stays paused until you resume it. To discard a download instead, use removeDownload(Context, String).

      Does nothing if there is no download for mediaId, or if it has already completed. Applied asynchronously through the download service, so getDownloads(Context) may briefly still report the previous state.

      Parameters:
      mediaId - the download to pause; must not be null. A null id is ignored - it is never treated as "pause everything".

    • resumeDownload

      default void resumeDownload(android.content.Context context, @NonNull String mediaId)
      Continues a download stopped by pauseDownload(Context, String), from the bytes it had already written.

      Subject to the same conditions as any other download - notably an available network - so a resumed download may report OfflineDownloadState.QUEUED until it can actually run.

      Does nothing if there is no download for mediaId, or if it is not stopped. Applied asynchronously through the download service, so getDownloads(Context) may briefly still report the previous state.

      Parameters:
      mediaId - the download to resume; must not be null. A null id is ignored - it is never treated as "resume everything".

    • isDownloaded

      boolean isDownloaded(String mediaId)
      Returns if the media associated with the provided mediaId is downloaded

    • getDownloadedPlaylistItem

      @Nullable PlaylistItem getDownloadedPlaylistItem(String mediaId)
      Returns the PlaylistItem to be used for setting up Offline DRM.

      The item is reconstructed from the fields persisted with the download, not the original object passed to prepareMediaDownload(android.content.Context, com.jwplayer.pub.api.media.playlists.PlaylistItem). Anything that cannot be persisted is absent - in particular a host-supplied MediaDrmCallback is not carried; only whether the item used Widevine is stored. A host using a custom MediaDrmCallback must re-attach it to the returned item's DrmConfig before playback.

    • getDownloadedBytes

      default long getDownloadedBytes(android.content.Context context)
      Returns the total number of bytes the offline download cache occupies on disk.

      This is cache space, not the sum of completed downloads: it also covers partially written content for downloads that are in progress, paused or being removed, so it will not equal the sum of getDownloadedBytes(Context, String) across every item.

      Returns 0 until the offline download stack has been initialized - before the first download component is built, and after teardown - because there is no open cache to measure. It does not open one itself, so a 0 from this method is indistinguishable from "nothing downloaded". Cheap once initialized: reads an in-memory byte count.

      Use this to surface storage usage in your UI, or to decide when to remove downloads with removeDownload(Context, String).

    • getDownloadedBytes

      default long getDownloadedBytes(android.content.Context context, String mediaId)
      Returns the number of bytes downloaded for a single media item, or 0 if nothing has been downloaded for it.

      Useful for showing per-item storage in your UI, and for deciding which download to remove when freeing space. These per-item figures come from the download index and will not sum to getDownloadedBytes(Context), which measures the cache as a whole.

      Blocking. Reads the download index; prefer getDownloads(Context) when you need more than one item, since each call here re-reads the whole index.

    • refreshOfflineLicense

      default void refreshOfflineLicense(android.content.Context context, @NonNull String mediaId, @NonNull OfflineLicenseRefreshListener listener)
      Renews the offline DRM licence of a download that is already on disk, without re-fetching the media.

      Offline licences expire. Without this, the only way to keep downloaded content playable is to remove it and download it again - gigabytes over the network to replace a licence of a few hundred bytes, and every such re-download used to strand the licence it replaced.

      What happens: the SDK asks the licence server to renew the licence, which produces a new key set; the download's stored key set is replaced with it through the download service; and the superseded licence is then released back to the licence server on a best-effort basis, exactly as removeDownload(Context, String) does.

      The download briefly re-enters the download queue. Replacing the key set means re-submitting the download request, so the download reports OfflineDownloadState.QUEUED and then OfflineDownloadState.DOWNLOADING again before settling back to OfflineDownloadState.COMPLETED, and MediaDownloadResultListener.onDownloadComplete(String) fires a second time. The media itself is not fetched again - it is already in the download cache - but the manifest is re-read, so the refresh needs a network connection for more than just the licence call.

      Requires a licence server the SDK can still authenticate to. Same constraint as the release path documented on removeDownload(Context, String): a host-supplied MediaDrmCallback is only available while the OfflineDownloadManager that prepared the download is alive, and otherwise the refresh falls back to the licence URL stored when the download was created. If that URL was token-signed with a short expiry, the renewal will be refused and OfflineLicenseRefreshListener.onOfflineLicenseRefreshFailed(java.lang.String, java.lang.Exception) fires.

      Fails, rather than doing nothing, when there is no download for mediaId or when that download carries no offline licence (non-DRM content). An already-expired licence cannot be renewed either - see getOfflineLicenseDurationRemaining(Context, String, OfflineLicenseDurationListener).

      Returns immediately; the work runs off the calling thread and the listener is called on the main thread.

      Parameters:
      mediaId - the download whose licence to renew; must not be null
      listener - notified of the outcome, on the main thread; must not be null

    • getOfflineLicenseDurationRemaining

      default void getOfflineLicenseDurationRemaining(android.content.Context context, @NonNull String mediaId, @NonNull OfflineLicenseDurationListener listener)
      Reads how much of a download's offline DRM licence is left, so you can decide when to call refreshOfflineLicense(Context, String, OfflineLicenseRefreshListener) instead of guessing.

      Opens a DRM session to ask the DRM system directly, so it is not free - query when you show a downloads list or run a maintenance pass, not on a timer. It does not need the network and does not contact the licence server on the callback path; on the URL path it still builds a session from the stored licence URL.

      Fails when there is no download for mediaId or when that download carries no offline licence.

      Returns immediately; the work runs off the calling thread and the listener is called on the main thread.

      Parameters:
      mediaId - the download to query; must not be null
      listener - notified of the outcome, on the main thread; must not be null