com.brightcove.player.offline

## Class MediaDownloadable

- java.lang.Object
- - com.brightcove.player.offline.MediaDownloadable

- Direct Known Subclasses:
    DashDownloadable, Mp4Downloadable

      public abstract class MediaDownloadable
      extends java.lang.Object

  An abstract class that holds information related to a remote media (`Video`) to be downloaded and responsible to manage the download of its components such as video, audio and text.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `MediaDownloadable.DownloadEventListener` Interface definition for a callback to be invoked when a media download is either completed, cancelled or failed because an error has occurred.
    `static interface` | `MediaDownloadable.MediaFormatListener` Interface definition for a callback to be invoked when the video tracks have been read and are available.
    `static interface` | `MediaDownloadable.OnVideoSizeCallback`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `AUDIO_LANGUAGE_ROLES` The key for the Bundle which returns the available audio language roles as ArrayList, matching the size and indexes of `AUDIO_LANGUAGES`.
    `static java.lang.String` | `AUDIO_LANGUAGES` The key for the Bundle which returns the available audio languages as ArrayList
    `static java.lang.String` | `CAPTIONS` The key for the Bundle which returns the available captions as ArrayList
    `protected android.os.Bundle` | `configurationBundle`
    `protected android.content.Context` | `context`
    `static java.lang.String` | `DEFAULT_MPD_NAME` The name of that will be used for saving DASH manifest.
    `protected MediaDownloadable.DownloadEventListener` | `downloadEventListener`
    `protected DownloadManager` | `downloadManager`
    `protected long` | `estimatedSize`
    `protected RequestConfig` | `requestConfig`
    `protected Video` | `video`
    `static java.lang.String` | `VIDEO_RENDITIONS` The key for the Bundle which returns the available video renditions as ArrayList

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MediaDownloadable(android.content.Context context, Video video, MediaDownloadable.DownloadEventListener downloadEventListener, RequestConfig requestConfig)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `cancelDownload()` Cancels download of the media if it has not been completed yet.
    `static MediaDownloadable` | `create(android.content.Context context, java.lang.String videoUrl, MediaDownloadable.DownloadEventListener downloadEventListener, RequestConfig requestConfig)` Creates the best `MediaDownloadable` for the given video url on the supported delivery types.
    `static MediaDownloadable` | `create(android.content.Context context, Video video, MediaDownloadable.DownloadEventListener downloadEventListener, RequestConfig requestConfig)` Creates the best `MediaDownloadable` for the given video based on the supported delivery types.
    `protected DownloadManager.Request` | `createDownloadRequest(android.net.Uri requestUri, android.net.Uri destinationUri)` Create a download request which can be enqueued with the `DownloadManager`.
    `boolean` | `deleteDownload()` Deletes the offline copy of the media.
    `protected void` | `enqueueDownloadRequest(DownloadManager.Request... requests)` Enqueues a list of download requests to the download manager.
    `void` | `estimatedSize(MediaDownloadable.OnVideoSizeCallback callback)` Returns the estimated total size of the media, which includes all assets such video, audio and subtitles.
    `android.os.Bundle` | `getConfigurationBundle()`
    `java.io.File` | `getDownloadDirectory()` Gets the directory the will hold all the assets related to this media.
    `DownloadStatus` | `getDownloadStatus()` Checks the overall download status by inspecting the status of each request in the entire download set.
    `long` | `getEstimatedSize()` Returns the estimated total size of the media, which includes all assets such video, audio and subtitles.
    `abstract void` | `getMediaFormatTracksAvailable(MediaDownloadable.MediaFormatListener mediaFormatListener)` An asynchronous call to retrieve the MediaFormat tracks available for the current video.
    `protected abstract java.util.HashMap<java.lang.String,java.io.Serializable>` | `getMediaProperties()`
    `protected void` | `onMediaDownloadCancelled()` Called when the media download has been removed before the download has completed.
    `protected void` | `onMediaDownloadComplete(DownloadStatus status)` Called when the media download has completed successfully.
    `protected void` | `onMediaDownloadDeleted()` Called when the media download has been removed after the download has completed.
    `protected void` | `onMediaDownloadFailed(DownloadStatus status)` Called when the media download has failed.
    `protected void` | `onMediaDownloadPaused(DownloadStatus status)` Called when the media download has been paused.
    `protected void` | `onMediaDownloadProgress(DownloadStatus status)` Called when the media download progress has changed.
    `protected void` | `onMediaDownloadRequested()` This method will be called when the `MediaDownloadable` starts to process the download request.
    `protected void` | `onMediaDownloadStarted()` This method will be called when the `MediaDownloadable` starts to download the media.
    `int` | `pauseDownload()` Attempts to pause download of this media.
    `static void` | `registerDownloadable(DeliveryType deliveryType, java.lang.Class<? extends MediaDownloadable> downloadableClass)` Registers the downloadable class that must be used to handled download of the specified media delivery type.
    `boolean` | `requestDownload()` Requests the media to be downloaded asynchronously.
    `int` | `resumeDownload()` Attempts to resume download of this media.
    `void` | `setConfigurationBundle(android.os.Bundle bundle)`
    `void` | `setVideoBitrate(int videoBitrate)` Sets the video bitrate cap which will be used to determine what rendition will be downloaded.

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

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

- - ### Field Detail

    - #### DEFAULT_MPD_NAME

          public static final java.lang.String DEFAULT_MPD_NAME

      The name of that will be used for saving DASH manifest.
      See Also:
        Constant Field Values

    - #### VIDEO_RENDITIONS

          public static final java.lang.String VIDEO_RENDITIONS

      The key for the Bundle which returns the available video renditions as ArrayList
      See Also:
        Constant Field Values

    - #### AUDIO_LANGUAGES

          public static final java.lang.String AUDIO_LANGUAGES

      The key for the Bundle which returns the available audio languages as ArrayList
      See Also:
        Constant Field Values

    - #### AUDIO_LANGUAGE_ROLES

          public static final java.lang.String AUDIO_LANGUAGE_ROLES

      The key for the Bundle which returns the available audio language roles as ArrayList, matching the size and indexes of `AUDIO_LANGUAGES`.
      See Also:
        Constant Field Values

    - #### CAPTIONS

          public static final java.lang.String CAPTIONS

      The key for the Bundle which returns the available captions as ArrayList
      See Also:
        Constant Field Values

    - #### configurationBundle

          protected final android.os.Bundle configurationBundle

    - #### context

          protected final android.content.Context context

    - #### downloadManager

          protected final DownloadManager downloadManager

    - #### video

          protected final Video video

    - #### downloadEventListener

          protected final MediaDownloadable.DownloadEventListener downloadEventListener

    - #### requestConfig

          protected final RequestConfig requestConfig

    - #### estimatedSize

          protected long estimatedSize

  - ### Constructor Detail

    - #### MediaDownloadable

          public MediaDownloadable(@NonNull
                                   android.content.Context context,
                                   @NonNull
                                   Video video,
                                   @Nullable
                                   MediaDownloadable.DownloadEventListener downloadEventListener,
                                   @Nullable
                                   RequestConfig requestConfig)

  - ### Method Detail

    - #### getMediaFormatTracksAvailable

          public abstract void getMediaFormatTracksAvailable(@NonNull
                                                             MediaDownloadable.MediaFormatListener mediaFormatListener)

      An asynchronous call to retrieve the MediaFormat tracks available for the current video. The result will be given through the `MediaDownloadable.MediaFormatListener` listener.

      Note: Only the video type `DeliveryType.DASH` is currently supported.

      Parameters:
        `mediaFormatListener` - the media format listener

    - #### registerDownloadable

          public static void registerDownloadable(@NonNull
                                                  DeliveryType deliveryType,
                                                  @NonNull
                                                  java.lang.Class<? extends MediaDownloadable> downloadableClass)

      Registers the downloadable class that must be used to handled download of the specified media delivery type.
      Parameters:
        `deliveryType` - the deliverty type
        `downloadableClass` - the media downloadable class.

    - #### create

          @Nullable
          public static MediaDownloadable create(@NonNull
                                                           android.content.Context context,
                                                           @NonNull
                                                           Video video,
                                                           @Nullable
                                                           MediaDownloadable.DownloadEventListener downloadEventListener,
                                                           @Nullable
                                                           RequestConfig requestConfig)

      Creates the best `MediaDownloadable` for the given video based on the supported delivery types.
      Parameters:
        `context` - the context of the application.
        `video` - the video to be downloaded.
        `requestConfig` - the request configuration object passed to the `DownloadManager`.
      Returns:
        null if the video is not flagged for offline playback or if no suitable delivery type was found in the video, otherwise reference to a `MediaDownloadable` that can be used download/manage the video.

    - #### create

          @Nullable
          public static MediaDownloadable create(@NonNull
                                                           android.content.Context context,
                                                           @NonNull
                                                           java.lang.String videoUrl,
                                                           @Nullable
                                                           MediaDownloadable.DownloadEventListener downloadEventListener,
                                                           @Nullable
                                                           RequestConfig requestConfig)

      Creates the best `MediaDownloadable` for the given video url on the supported delivery types.
      Parameters:
        `context` - the context of the application.
        `videoUrl` - the fully qualified URL of the video to be downloaded.
        `requestConfig` - the request configuration object passed to the download manager.
      Returns:
        null if no suitable delivery type was found in the video, otherwise reference to a `MediaDownloadable` that can be used download/managed the video.

    - #### setVideoBitrate

          public void setVideoBitrate(int videoBitrate)

      Sets the video bitrate cap which will be used to determine what rendition will be downloaded. If there's no rendition lower than the video bitrate provided, the next higher will be picked.
      Parameters:
        `videoBitrate` - the video bitrate

    - #### getDownloadDirectory

          @NonNull
          public java.io.File getDownloadDirectory()

      Gets the directory the will hold all the assets related to this media.
      Returns:
        the directory the will hold all the assets related to this media.

    - #### getEstimatedSize

          public long getEstimatedSize()

      Returns the estimated total size of the media, which includes all assets such video, audio and subtitles. Please note the method should be called after calling `requestDownload()`

      The actual size of the media that will be used by the host device may vary based on the partition type and format of the storage.

      Returns:
        the approximate size of the media

    - #### estimatedSize

          public void estimatedSize(MediaDownloadable.OnVideoSizeCallback callback)

      Returns the estimated total size of the media, which includes all assets such video, audio and subtitles.

      The actual size of the media that will be used by the host device may vary based on the partition type and format of the storage. This method requires the Media Manifest to estimate the size, therefore it might download the manifest and store it to the directory provided in the `RequestConfig()` object in the constructor, if it has not been done already.

      Parameters:
        `callback` - the approximate size of the media.

    - #### getConfigurationBundle

          public android.os.Bundle getConfigurationBundle()

    - #### setConfigurationBundle

          public void setConfigurationBundle(android.os.Bundle bundle)

    - #### enqueueDownloadRequest

          @NonNull
          protected void enqueueDownloadRequest(@NonNull
                                                         DownloadManager.Request... requests)

      Enqueues a list of download requests to the download manager. The actual status of the download request will be published to the `downloadEventListener`. Please use `getDownloadStatus()` to query the download status.

      Please note that this method must only be called once to enqueue all download requests.

      Parameters:
        `requests` - an array of download requests
      Throws:
        `java.lang.IllegalStateException` - If the video has been already queued for download.

    - #### onMediaDownloadRequested

          protected void onMediaDownloadRequested()

      This method will be called when the `MediaDownloadable` starts to process the download request.

    - #### getMediaProperties

          @NonNull
          protected abstract java.util.HashMap<java.lang.String,java.io.Serializable> getMediaProperties()

    - #### onMediaDownloadStarted

          protected void onMediaDownloadStarted()

      This method will be called when the `MediaDownloadable` starts to download the media.

    - #### onMediaDownloadPaused

          protected void onMediaDownloadPaused(@NonNull
                                               DownloadStatus status)

      Called when the media download has been paused.

    - #### onMediaDownloadProgress

          protected void onMediaDownloadProgress(@NonNull
                                                 DownloadStatus status)

      Called when the media download progress has changed.

    - #### onMediaDownloadComplete

          protected void onMediaDownloadComplete(@NonNull
                                                 DownloadStatus status)

      Called when the media download has completed successfully.

    - #### onMediaDownloadFailed

          protected void onMediaDownloadFailed(@NonNull
                                               DownloadStatus status)

      Called when the media download has failed.

    - #### onMediaDownloadCancelled

          protected void onMediaDownloadCancelled()

      Called when the media download has been removed before the download has completed.

    - #### onMediaDownloadDeleted

          protected void onMediaDownloadDeleted()

      Called when the media download has been removed after the download has completed.

    - #### requestDownload

          public boolean requestDownload()

      Requests the media to be downloaded asynchronously.
      Returns:
        true if the request was successfully placed in the download queue, otherwise false. Please note that a true value does not mean that media has been downloaded successfully. The actual status of the download request will be published to the `downloadEventListener`. Please use `getDownloadStatus()` to query the download status.
      Throws:
        `java.lang.IllegalStateException` - If the video has been already queued for download.

    - #### pauseDownload

          public int pauseDownload()

      Attempts to pause download of this media.
      Returns:
        the status of the media download.

    - #### resumeDownload

          public int resumeDownload()

      Attempts to resume download of this media.
      Returns:
        the status of the media download.

    - #### cancelDownload

          public boolean cancelDownload()

      Cancels download of the media if it has not been completed yet. If the media has been downloaded already, then calling this method will have no effect. Please call `deleteDownload()` method instead to delete the media.

      Returns:
        true if the media was found in the download queue and cancelled, otherwise false.

    - #### deleteDownload

          public boolean deleteDownload()

      Deletes the offline copy of the media. If the media has not been fully downloaded yet, then it will be removed from the download queue and any partially download assets belonging to the media will be deleted.
      Returns:
        true if the media was removed from the download queue and the storage, otherwise false.

    - #### getDownloadStatus

          public DownloadStatus getDownloadStatus()

      Checks the overall download status by inspecting the status of each request in the entire download set. Please note that this is a blocking call. Checking the status of large media with multiple assets may take time.

    - #### createDownloadRequest

          @NonNull
          protected DownloadManager.Request createDownloadRequest(@NonNull
                                                                           android.net.Uri requestUri,
                                                                           @NonNull
                                                                           android.net.Uri destinationUri)

      Create a download request which can be enqueued with the `DownloadManager`.
      Parameters:
        `requestUri` - the request uri
        `destinationUri` - the destination uri
      Returns:
        the download request
      See Also:
        `enqueueDownloadRequest(DownloadManager.Request...)`