Detailed Description

This class offers the downloading and the storage management of adaptive streaming assets.

The client application can register, start, pause or remove the download of assets. Information pertaining to the downloads can be queried. The queries extract snapshots of the downloads in the form of one or more OTVDownloadItem objects.

Before usage, the DownloadManager must be provided with a storage path and an IDownloadListener interfacing object. Once the path has been set and one IDownloadListener has been registered, the client application can start registering downloads. Downloads registered to the DownloadManager will immediately attempt to access the network and retrieve metadata pertaining to the asset requested, but the raw media data will not be downloaded before the download is explicitly started by the client application.

The preparing and downloading are driven by the callbacks of IDownloadListener.

Objects of this class can be instantiated multiple times, but all instances will point to a single underlying database maintaining all ongoing or finished downloads. The lifecycle of downloads are directly linked to the DownloadManager.

The DownloadManager currently supports the following adaptive streaming protocols and protocol versions :

DASH View On Demand stream

To setup the DownloadManager, the client application must do the following :

DownloadManager manager = new DownloadManager();
manager.setStorage("/path/to/my/desired/storage");
manager.registerDownloadStateListener(myListener);
...

The DownloadManager can also be configured to perform metadata refreshes when a download items is resumed, enabling this functionality can be useful where the remote content is load balanced and the ideal server may have changed since the download was paused. By default, this functionality is disabled. To do this, the client application must do the following :

DownloadManager manager = new DownloadManager(context, true); // true parameter added
manager.setStorage("/path/to/my/desired/storage");
manager.registerDownloadStateListener(myListener);
...

To create a download and start it, the client application can do the following :

String contentURL = "http://somewhere.out.there/on/a/cdn/index.m3u8";
String uuid = manager.registerDownload(contentURL);
manager.setPrivateData(uuid, MyPrivateJSONString);
manager.startDownload(uuid);
...

Public Member Functions
	OTVDownloadManager (Context xContext)
	Creates the OTVDownloadManager. More...

boolean	registerDownloadStateListener (OTVDownloadListener xListener)
	Register an OTVDownloadListener interface object to receive callbacks around downloads being added / removed, download state changes and download progress. More...

boolean	unregisterDownloadStateListener (OTVDownloadListener xListener)
	Unregister an OTVDownloadListener interface object that has been previously added by registerDownloadListener. More...

boolean	setStorage (String xPath)
	Provide the storage area to the DownloadManager. More...

String	getStorage ()
	Retrieve the storage area currently in use by the DownloadManager. More...

String	registerDownload (String xUrl)
	Register a content to be downloaded to the OTVDownloadManager. More...

String	registerDownload (@NonNull String xUrl,@Nullable OTVMediaDrmCallback xMediaDrmCallback, int xContentType)
	Register a content to be downloaded to the OTVDownloadManager, explicitly specifying content type. More...

String	registerDownload (String xUrl,@Nullable OTVMediaDrmCallback xMediaDrmCallback)
	Register a content to be downloaded to the OTVDownloadManager. More...

OTVDownloadItem[]	getDownloadItems ()
	Returns all downloads currently registered in the OTVDownloadManager. More...

OTVDownloadItem	getDownloadByUUID (String xUUID)
	Returns the download registered to the OTVDownloadManager matching the UUID specified in parameter. More...

boolean	removeDownload (String xUUID)
	Removes the download specified in parameter. More...

boolean	startDownload (String xUUID, int xBitrate)
	Starts the download specified in parameter. More...

boolean	pauseDownload (String xUUID)
	Pauses the running download specified in parameter. More...

boolean	resumeDownload (String xUUID)
	Resumes the paused download specified in parameter. More...

void	setPrivateMetadata (String xUUID, String xMetadata)
	Associate a private string to the download. More...

String	getPrivateMetadata (String xUUID)
	Returns the private string previously associated to the download. More...

boolean	renewLicense (String xUUID,@NonNull OTVMediaDrmCallback xMediaDrmCallback)
	Renew the widevine license for Dash encrypted stream. More...

Constructor & Destructor Documentation

OTVDownloadManager ( Context xContext )

Creates the OTVDownloadManager.

Parameters

xContext The application context for the OTVDownloadManager to use

Member Function Documentation

OTVDownloadItem getDownloadByUUID ( String xUUID )

Returns the download registered to the OTVDownloadManager matching the UUID specified in parameter.

Parameters

xUUID Universal Unique ID of the download

Returns: An OTVDownloadItem object or null if not found.

OTVDownloadItem [] getDownloadItems ( )

Returns all downloads currently registered in the OTVDownloadManager.

Returns: An array of OTVDownloadItem objects.

String getPrivateMetadata ( String xUUID )

Returns the private string previously associated to the download.

Parameters

xUUID Universal Unique ID of the download

Returns: the private string previously associated, null if no string has ever been set.

String getStorage ( )

Retrieve the storage area currently in use by the DownloadManager.

Returns: xPath - Path where the OTVDownloadManager shall store all assets.

boolean pauseDownload ( String xUUID )

Pauses the running download specified in parameter.

The download will change to the STATE_PAUSED state.

Parameters

xUUID Universal Unique ID of the download

Returns: true if the action succeeded; false otherwise.

String registerDownload ( String xUrl )

Register a content to be downloaded to the OTVDownloadManager.

Parameters

xUrl	The URL to the manifest of an adaptive streaming asset.

Returns: The Universal Unique ID attributed to the download, or null if the download could not be registered.

String registerDownload	(	@NonNull String	xUrl,
		@Nullable OTVMediaDrmCallback	xMediaDrmCallback,
		int	xContentType
	)

Register a content to be downloaded to the OTVDownloadManager, explicitly specifying content type.

Parameters

xUrl	The URL to the manifest of an adaptive streaming asset.
xMediaDrmCallback	Callback used in offline license acquisition if the content is encrypted
xContentType	indicate the stream content type. The available values are: OTVContentType#CONTENT_TYPE_UNKNOWN OTVContentType#CONTENT_TYPE_HLS OTVContentType#CONTENT_TYPE_DASH OTVContentType#CONTENT_TYPE_PROGRESSIVE_MP4

Remarks: setting content type to OTVContentType#CONTENT_TYPE_UNKNOWN means the SDK will auto-detect type.

Returns: The Universal Unique ID attributed to the download, or null if the download could not be registered.

String registerDownload	(	String	xUrl,
		@Nullable OTVMediaDrmCallback	xMediaDrmCallback
	)

Register a content to be downloaded to the OTVDownloadManager.

Parameters

xUrl	The URL to the manifest of an adaptive streaming asset.
xMediaDrmCallback	Callback used in offline license acquisition if the content is encrypted

Returns: The Universal Unique ID attributed to the download, or null if the download could not be registered.

boolean registerDownloadStateListener ( OTVDownloadListener xListener )

Register an OTVDownloadListener interface object to receive callbacks around downloads being added / removed, download state changes and download progress.

Parameters

xListener and OTVDownloadListener interfacing object to receive callbacks

Returns: true if the listener is successfully added false if the listener is null, already in the list, or fails to add for any other reason

boolean removeDownload ( String xUUID )

Removes the download specified in parameter.

The download will disappear from the list of downloads and be unregistered from OTVDownloadManager. onDownloadRemoved() will be fired when effective.

Parameters

xUUID Universal Unique ID of the download

Returns: true if the action succeeded; false if the UUID does not exist or there is no permission to remove the download (Android M onwards).

boolean renewLicense	(	String	xUUID,
		@NonNull OTVMediaDrmCallback	xMediaDrmCallback
	)

Renew the widevine license for Dash encrypted stream.

This sync method is used for renew an expired Widevine offline license only. Downloading of license will be automatically handled by SDK. It cannot be called in main thread because there is risk of ANR when license request takes long time.

Parameters

xUUID	Universal Unique ID of the download
xMediaDrmCallback	Callback used in offline license acquisition

Returns: true if the renew succeeded; false otherwise.

Exceptions

IllegalStateException If this method is called in main thread

boolean resumeDownload ( String xUUID )

Resumes the paused download specified in parameter.

The download will change to the STATE_RUNNING state.

Parameters

xUUID Universal Unique ID of the download

Returns: true if the action succeeded; false if the UUID does not exist or there is no permission to remove the download (Android M onwards).

void setPrivateMetadata	(	String	xUUID,
		String	xMetadata
	)

Associate a private string to the download.

This allows the client application to associate applicative data with the download. The format is at the developer's convenience. (JSON, XML, ...)

Parameters

xUUID	Universal Unique ID of the download
xMetadata	String to associate to the download

boolean setStorage ( String xPath )

Provide the storage area to the DownloadManager.

This URL should not change over time. If the application developer wishes to move it, it must copy that directory and set a new storage path to the DownloadManager while no downloads are active.

Parameters

xPath Path where the DownloadManager shall store all assets.

Returns: true if the action succeeded; false otherwise. Failure reasons can include: Wrong formatting of the path.

boolean startDownload	(	String	xUUID,
		int	xBitrate
	)

Starts the download specified in parameter.

The download will change to the STATE_RUNNING state.

Parameters

xUUID	Universal Unique ID of the download
xBitrate	The consumption bitrate to use with the download. Only bitrates found in OTVDownloadMediaInfo objects are eligible.

Returns: true if the action succeeded; false if the UUID does not exist or there is no permission to remove the download (Android M onwards).

boolean unregisterDownloadStateListener ( OTVDownloadListener xListener )

Unregister an OTVDownloadListener interface object that has been previously added by registerDownloadListener.

Parameters

xListener the listener to unregister

Returns: true if the listener is unregistered successfully false if the listener is null or the listener could not be removed for any other reason

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation