Registering the download

An application must first register an asset to the downloader before actually downloading it. The registration step retrieves the metadata related to the asset. The downloader retrieves the stream manifest (DASH .mpd file) as soon as an application registers a URL.

When information contained in the playlist is available to the application for reading, the state of the download will change to STATE_PREPARED.
If the manifest cannot be acquired or parsed, the download state changes to STATE_FAILED.
For encrypted content, a callback class is passed on during the registration. The OTVDownloadManager then uses this callback class to acquire the licence for the content and store it locally. The callback class can be the same as the callback class used for playing back Widevine-encrypted content.

Assets marked for download and are in the PREPARED state (where the bitrate has not yet been selected and the download not started) will be removed if the application terminates and restarts. Although preparing and starting downloads are separate steps, we recommend that the application combines the two into a single step.

Clear content

Given a URL of an online stream you wish to download, register the stream for download operations.

JAVA

String uuid = mDlManager.registerDownload("http://path/to/stream.mpd");

Encrypted content

PRM-protected content

PRM needs to be initialised with device and server information before any download operations; this is usually done at application start-up. For the specific content to be downloaded, the OTVPRMNonSilentCallback instance used for PRM initialisation is configured with the content’s token.

To work with PRM-protected content, you must use the PRM-supporting SDK libraries (sdk-prm-integration.aar and sdk-prm-production.aar).

JAVA

prmCallback.setLicenseRequestClientProtectedPrivateData("STREAM_TOKEN");
String uuid = mDlManager.registerDownload("http://path/to/stream.mpd");

Widevine-protected content

The application must instantiate an OTVMediaDrmCallback callback class with server and content parameters and pass that callback as a second parameter to registerDownload().

JAVA

// Set-up callback instance with specific headers for this licence server
OTVHttpMediaDrmCallback callback =
    new OTVHttpMediaDrmCallback("https://path/to/licence/server/");

callback.setKeyRequestProperty("Accept", "application/octet-stream");
callback.setKeyRequestProperty("Content-Type", "application/octet-stream");
// Tenant ID is a specific implementation of an SSP licence server
callback.setKeyRequestProperty("nv-tenant-id", "TENANT_ID");
// Content token is a specific implementation of an SSP licence server
callback.setKeyRequestProperty("nv-authorizations", "STREAM_TOKEN");

// Register the donload asset with the callback object as second parameter
String uuid = mDlManager.registerDownload("http://path/to/stream.mpd", callback);

The uuid string returned is a unique identification for this download entry. You would use it whenever you need to operate on this entry.

The download does not start at this stage. Only when the onDownloadAdded() is called, and the download state changes to STATE_PREPARED can the download actually begin.

For encrypted content, the licence keys have to be retrieved and stored before the actual download.

In the case of Widevine-protected content, OTVDownloadManager does it automatically during the preparation phase through the provided OTVHttpMediaDrmCallback instance.

For PRM content, you have to download the keys upon receiving the STATE_PREPARED state, using information OTVDownloadManager has acquired.

JAVA

 @Override
   public void onDownloadStateChange(OTVDownloadItem dlItem, OTVDownloadState state) {
     // The entry dlItem has changed its download state.
     switch (mDlState) {
     ...
     case STATE_PREPARED:
       // The stream's manifest was processed, and OTVDownloadManager
       // is now ready to start a download
       mPrmManager.downloadLicense(dlItem.getAsset().getPRMSyntax(), dlItem.getAsset().getPRMContentId(),true);
       break;
   ...

Next step: Start the download