Starting the download

The start download operation can take place on a registered event in the STATE_PREPARED state. The data downloaded will consist of all subtitle and audio tracks available and the video track with the chosen bitrate.

At the STATE_PREPARED state, the download manager has all the information necessary for starting the download. However, unlike in later stages of the process, this information will not persist; if an app is terminated and restarted, downloaded items in STATE_PREPARING or STATE_PREPARED will not be recovered on restart. Although preparing and starting downloads are separate steps, we recommend that the application combines the two into a single step.

As soon as the application starts a registered download, the application is notified that the download has switched to STATE_RUNNING. When all files of the provided assets have downloaded successfully, the download state changes to STATE_SUCCESSFUL. If an error is encountered, the download enters the STATE_FAILED state.

Selecting video track to download

A registered download in STATE_PREPARED can provide a list of available video track bitrates to download. The selected bitrate value has to be one of the bitrates provided.

JAVA

// List the available bitrates
for (OTVDownloadMediaInfo info : item.getAsset().getMediaInfo()) {
  // the bitrate can be fetched through info.getBitrate()
  // the resolution can be fetched through info.getResolution()
}

Starting the download

The following code example shows how to start the download.

JAVA

//Get the download object by Universal Unique ID.
OTVDownloadItem dlItem = mDlManager.getDownloadByUUID(uuid);

//Kick off downloading. downloadBitrate is target bitrate to be download.
mDlManager.startDownload(dlItem.getUUID(), bitrate);

See the OTVDownloadManager class reference for details of the API calls used above.

The SDK will estimate the storage size required for the content to be downloaded based on the selected bitrate. If it determines there is not enough storage space, it will change the state to STATE_FAILED and send a notification to that effect.

Monitoring status and progress

The overridden onDownloadStateChange() method in the implementation of the OTVDownloadListener class should capture the state changes. The overridden onDownloadProgress() method in the implementation of the OTVDownloadListener class should capture the current progress.

Pausing and resuming download

While in STATE_RUNNING, the download can be paused by calling:

JAVA

mDlManager.pauseDownload(uuid);

The download state will change to STATE_PAUSED. The download can then be resumed by calling:

JAVA

mDlManager.resumeDownload(uuid);

Due to system limitations, if playback started on a partially downloaded item, resumeDownload() will fail while the playback is ongoing.

Handling errors

If an error occurs while downloading, the state will change to STATE_FAILED. The application can inquire about the latest error by calling:

JAVA

OTVDownloadError errorCode = dlItem.getError();

The download data received until the failure persists and may even be available for (partial) playback. The application can attempt to recover a failed download (e.g. after a lost network is recovered) using the resumeDownload() method:

JAVA

mDlManager.resumeDownload(uuid);

DownloadManager may or may not attempt to restart a download upon calling resumeDownload(). This depends on the nature of the failure as reported in the error codes. For example, if the manifest file is corrupt, there is no point in renewing the download as the content will still not download. In such cases, the download state will remain in STATE_FAILED and will not change to STATE_RUNNING.

Handling asset licences (Widevine)

You must provide an OTVMediaDrmCallback class instance for the download manager to retrieve the licence for the asset you are downloading. All Widevine licences have expiration dates set, and the licence for the downloaded stream may have expired. You can check the acquired licence by calling:

JAVA

OTVDownloadItem dlItem = mDlManager.getDownloadByUUID(uuid);
Pair<Long, Long> licenseDurationRemaining = dlItem.getAsset().getLicenseDurationRemaining();

The first item of the pair provides the remaining license duration (in seconds), and the second item provides the remaining playback duration for the licence. The application can renew the licence if it has expired or about to expire:

JAVA

mDlManager.renewLicense(uuid, drmCallback);

Next step: Play the download