Starting the download

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

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; in the case of killing an app and restarting it, a download item with the state of STATE_PREPARING or STATE_PREPARED will not be recovered on restart. Although from an integrators' point of view preparing and starting downloads are separate steps, it is recommended that the application combines the two into a single step; see the offline-service example code.

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

If an error is encountered, the download enters the STATE_FAILED state.

Example code

Selecting video track to download

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

// 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:

//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);

Based on the selected bitrate, the SDK will estimate the storage size required for the content to be downloaded. 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 overriden onDownloadStateChange() method in the implementation of the OTVDownloadListener class should capture the state changes. The overriden onDownloadProgress() method in the implementation of the`OTVDownloadListener' class should capture the current progress.

Pausing and resuming download

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


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


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 check the latest error by calling:

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 (for example after a lost network is recovered) using the resumeDownload() method:


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 attempting to renew 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.

Next step: Watch the downloaded content