Instantiating the OTVDownloadManager

The OTVDownloadManager needs to be instantiated in the lifecycle of your application, for example, in the onCreate() method of your main activity. Upon instantiation, the OTVDownloadManager recovers the persistent database of previous download operations and makes them accessible to the application. However, operations cannot be triggered unless the application implements a listener for download events.

Implement a listener class (either an internal class within your activity or your class can implement the listener interface), instantiate it, and pass the object reference to your OTVDownloadManager instance.

Click here to view the example code.

JAVA

import nagra.otv.sdk.OTVSDK;import nagra.otv.sdk.OTVVideoView;
import nagra.otv.sdk.offline.OTVDownloadItem;
import nagra.otv.sdk.offline.OTVDownloadListener;
import nagra.otv.sdk.offline.OTVDownloadManager;

...
public class MainActivity extends Activity {

  private OTVDownloadManager mDlManager = null;

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    OTVSDK.load(this);

    mDlManager = new OTVDownloadManager(new MyDownloadListener());

    ...
  }

  private class MyDownloadListener implements OTVDownloadListener {
    @Override
    public void onDownloadAdded(OTVDownloadItem dlItem) {
      // A download for a stream is added to the persistent database.
      // Not downloading yet.
      // The details of this entry are present in dlItem.
    }

    @Override
    public void onDownloadRemoved(String uuid) {
      // The entry, identified by its UUID, was removed from the persistent database
    }

    @Override
    public void onDownloadStateChange(OTVDownloadItem dlItem, OTVDownloadState state) {
      // The entry dlItem has changed its download state.
      switch (mDlState) {
      case STATE_PREPARING:
        // This is the initial state after an entry is added
        // OTVDownloadManager is processing the stream URL, and then
        // downloads and parses the manifest preparing the download process.
        break;
      case STATE_PREPARED:
        // The stream's manifest was processed, and OTVDownloadManager
        // is now ready to start a download
        break;
      case STATE_RUNNING:
        // Download is ongoing. Frequent progress reports are sent via onDownloadProgress().
        break;
      case STATE_PAUSED:
        // Download is paused, and can be resumed by calling dlItem.resumeDownload()
        break;
      case STATE_SUCCESSFUL:
        // Download of the stream is complete
        break;
      case STATE_FAILED:
        // Download progress was interrupted due to a failure (e.g. network loss).
        // The nature of the failure can be retrieved via dlItem.getError()
        // The downoload entry still persists. The application may attempt
        // to resume the download (e.g. afternetwork is recovered) by calling
        /// dlItem.pauseDownload() and then dlItem.resumeDownload().
        break;
      default:
        break;
      }
    }

    @Override
    public void onDownloadProgress(OTVDownloadItem dlItem, float progress) {
      // Progress report of a specific download entry.
      // The progress value is between 0 and 1.
    }
  }
}

Setting the storage location for downloaded content

The SDK will choose by default to store all persistent offline data inside the application's data path under the offline sub-directory. The application can change the path by calling setStorage(). However, this is not recommended, particularly for API level 29 or above, as the application and the SDK must be granted write permissions to the new path, should the path change.

If you need to set a different path, such as external storage, the storage’s root path may differ between devices. To fetch the root path, use Context.getExternalFilesDir() for API level 29 - Android 10 or above, or Environment.getExternalStorageDirectory() for older versions. Ensure the storage exists and permissions are granted using Environment.getExternalStorageState(); see Android Developers’ Guide - Access from external storage.

Finding existing download items

Especially at the application start-up, it may be necessary to determine what downloads persist in the database. OTVDownloadManager provides a method for this:

JAVA

OTVDownloadItem[] items = mDlManager.getDownloadItems();

All download items are indexed by their UUID, assigned when a download is ‘added’. Most download operations are actioned by calling the OTVDownloadManager instance’s API, with the UUID as a parameter. For example:

JAVA

mDlManager.removeDownload(uuid);

For some operations, it is necessary to access the OTVDownloadItem instance. A reference to such an instance is sometimes passed in the listener’s event methods but can also be fetched based on the UUID index:

JAVA

OTVDownloadItem item = mDlManager.getDownloadByUUID(uuid);

The opposite can also be achieved - finding a download item’s UUID:

JAVA

String uuid = dlItem.getUUID();

Recovering items in downloading progress

If the application terminates during the download process, items downloading remain at STATE_RUNNING even though there is no longer an active thread progressing the download. When the application restarts, we recommend these items are brought to the paused state and let the users decide whether they wish to resume the download (with resumeDownload(uuid)). For example, call the following just after creating the Download Manager and retrieving the items:

JAVA

private void pauseRunningDownloads() {
  for (OTVDownloadItem downloadItem : mDlManager.getDownloadItems()) {
    if (downloadItem.getState() == OTVDownloadState.STATE_RUNNING) {
      mDlManager.pauseDownload(downloadItem.getUUID());
    }
  }
}

Next step: Register the download