HLS stream playback with NAGRA CONNECT

To test this feature and view the example code, please see the (5.33.x) PRM Example Code Quick Start guide.

The client code for HLS playback uses the OTVConnectManager  provided by the CONNECT Player SDK, which handles access to the MediaDRM plugin. The OTVConnectManager also handles device provisioning, which enables the device to use NAGRA CONNECT.

Enabling the HLS playback of encrypted streams comprises the following steps:

• CONNECT preparation
  An OTVConnectManager is created and configured with the appropriate OpVault and an OTVMediaDrmCallback that interacts with the provisioning and licence servers.

• Device provisioning status
  The OTVConnectManager determines if the device is provisioned for this operator. If it is not, provisioning must be performed.

• Device provisioning (if not provisioned)
  The OTVConnectManager sets up a provisioning request. Its data is sent to the provisioning server, located at the URL specified in the request. The response is then processed and stored by the MediaDRM plugin.

• Setting the stream token
  Specific for each stream, providing the token for requesting a licence.

Provisioning is 'per device, per operator', and must be done once for each application (containing your OpVault) installed on that device.

OTVConnectManager

The OTVConnectManager handles device provisioning and licence requests. It obtains provisioning and key requests, provides request data to the appropriate server (via the  OTVMediaDrmCallback) and then uses the response, with the help of the MediaDRM plugin, to handle licences and decrypt the content. It is implemented as a singleton and so cannot be instantiated directly; its lifecycle is controlled through the createInstance(), getInstance() and releaseInstance() methods.

OTVConnectMediaDrmCallback

The SDK provides OTVConnectMediaDrmCallback as the default implementation of the OTVMediaDrmCallback interface, which handles communication with the provisioning and licence servers and is used in the example code.

Rather than directly implementing the OTVMediaDrmCallback interface, OTVConnectMediaDrmCallback implements the abstract OTVCommonMediaDrmCallback class, which has a single constructor with the parameter defaultLicenseUrl.

Some licence servers expect extra information from the application. This information is a blob of data in a specific data field within the key request challenge data from the MediaDRM plugin sent to the licence server. The MediaDRM plugin library can be configured to add that extra data by setting an option in the  OTVConnectMediaDrmCallback class instance. For example, configuring the clientData and/or protectedClientData fields with application data will add this data to key requests' challenge data as third-party applicationClearData and applicationProtectedData data fields respectively.

For more information, please refer to your licence server documentation.

OTVConnectProvisionListener

The OTVConnectProvisionListener interface must be implemented in the client code to handle the result of each provisioning attempt via the onProvisionCompleted() and onProvisionFailure() methods. The example code provides a basic implementation that displays the provisioning result via a toast message and starts playback if provisioning is successful.

Post-delivery renewal

In a typical scenario, especially on handheld devices, a licence is fetched and used for the decryption key when a user views some protected content. The licence is limited by an expiry time that provides the user ample time (for example, 24 or 48 hours) to use and watch the content before the licence expires.

However, for set-top boxes, content playback could span several days beyond the original expiry time. The Example code for HLS stream playback with licence extension option page illustrates a mechanism for the application to be aware of the expiry time and to extend the licence.

Extension of the CONNECT licence expiry time requires the CONNECT MediaDrm plugin version 3.2.0 or above. Extension of licence expiry is set by the details of the content token. Setting expiry time can be done by either providing a duration value (in seconds) or by specifying an end time (UTC date).

• When setting a floating duration, the extension occurs only after the current licence has expired, and the app will not be notified with a meaningful expiry time in the onExpirationUpdate event.

• When setting an end time, the extension occurs immediately, and the app will be notified within the onExpirationUpdate event with time (in ms) since Unix epoch.