DASH stream playback with licence extension example code

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

CONNECT-protected DASH playback with licence extension is implemented in the connect-post-delivery-dash-renewal example code as follows.

1. As an alternative to the example illustrated in the (5.33.x) DASH stream playback example code, the Operator Vault (OpVault) is asynchronously downloaded from the licence server rather than kept in the application's resources. This is typically done once per licence server and is shown in the requestConnectOpVault() method. Playback is not attempted until an OpVault is successfully fetched by disabling the UI buttons controlling playback.

   JAVA

     private void requestConnectOpVault(String xOpVaultUri) {
       FileDownload.ResponseListener listener = new FileDownload.ResponseListener() {
         @Override
         public void onSuccess(byte[] xResponse) {
           // Keep the operator vault somewhere as a byte array.
           mOpVault = xResponse;
           // Can now continue with playback.
         }
   
         @Override
         public void onFailure(int xErrorCode, String xErrorMsg) {
           // Report the error, as playback with Connect is not possible without an operator vault.
         }
       };
       // Perform the asynchronous request.
       FileDownload opVaultDownload = new FileDownload(xOpVaultUri, listener);
       opVaultDownload.requestData();
     }

2. As per the example illustrated in the (5.33.x) DASH stream playback example code, you need to set up the OTVConnectMediaDrmCallback and pass its instance to setMediaDrmCallback () method of OTVVideoView before setting the stream source and starting playback.

   JAVA

    private void setDrmCallback(String xToken) {
       mConnectDrmCallback = new OTVConnectMediaDrmCallback(DRM_URI);
       // Server headers specific for Connect licence server.
       mConnectDrmCallback.setKeyRequestProperty("Accept", "application/json");
       mConnectDrmCallback.setKeyRequestProperty("Content-Type", "application/json");
       mConnectDrmCallback.setKeyRequestProperty("nv-authorizations", xToken);
       mConnectDrmCallback.setKeyRequestProperty("nv-tenant-id", TENANT_ID);
       // set operator vault for Connect.
       mConnectDrmCallback.setDrmPropertyByteArray("nagraOpVault", mOpVault);
       //set application data if necessary
       //Replace the value with the real application data.
       mConnectDrmCallback.setKeyRequestOption("clientData", "thisIsClientData");
     }

3. Licence extension is supported through the OTVLicenseHelper instance's methods. The OTVLicenseHelper instance can be accessed by the getLicenseHelper method of the OTVVideoView instance. The OTVLicenseHelper provides the application with the expiry time (by notification or query) and another method to extend the licence. A dedicated listener, OTVLicenseExpirationListener captures the licence expiry time of each decryption session (usually only one per stream playback).

   JAVA

   OTVLicenseExpirationListener licenseExpirationListener = (MediaDrm xMd, String xSessionId, long xExpirationTimeMs) -> {
     // License expiration time provided. Store the session ID (String) for later (required for extension of expiry queries).
     currentDrmSession = xSessionId;
     // Expiry time (long) is given in epoch time in milliseconds.
     licenceExpiryTimeMs = xExpirationTimeMs;
     // A value of 0 means no expiry time is set.
     if (xExpirationTimeMs > 0) {
       // Calculate time remaining, or do something else with this data.
     }
   };
   :
   : 
   mOTVVideoView.getLicenseHelper().setLicenseExpirationListener(licenseExpirationListener);

   The expiration notification onExpirationUpdate() is called when the licence is fetched or extended. The expiry time can also be queried:

   JAVA

    licenceExpiryTimeMs = mOTVVideoView.getLicenseHelper().getLicenseExpirationTimeMs(currentDrmSession);

4. The application needs to keep track of the licence's remaining time and decide if it wishes to extend the licence. In the example code, this is done through a timer. When the application chooses to extend the licence, it may need to provide a new content token to the OTVConnectMediaDrmCallback instance, and then calls the OTVLicenseHelper instance:

   JAVA

   // Fetch a new token (if required) and update the DRM callback.
   mConnectDrmCallback.setKeyRequestProperty("nv-authorizations", token);
   // New expiry time will be provided in the OTVLicenseExpirationListener listener method.
   mOTVVideoView.getLicenseHelper().extendCurrentDrmLicense(currentDrmSession);

5. Once the licence is extended, the application will be notified through the OTVLicenseExpirationListener instance of a new expiry time.

   

   Licence extension and the consequent expiry notification may not occur immediately, but when the DRM session manager identifies that the existing (previous) licence is no longer valid.

   Extending the CONNECT licence expiry time requires the CONNECT MediaDrm plugin version 3.2.0 or above. The details of the content token set extension of licence expiry. 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.