Widevine protected playback

To test this feature and view the example code, please see the Example Code Quick Setup guide.

Playback of Widevine encrypted content typically comprises the following steps:

  • The user requests the application to start playback of an encrypted stream.
  • The application fetches the necessary metadata for playing the required content; for example, from a Content Management System (CMS). This metadata contains information for enabling the playback:
    • The URL of the asset.
    • Whether the content is clear or protected.
    • The Licence server that provides keys for a protected asset.
    • Additional information associated with the licence server and the asset.
  • The application then:
    • Initialises an OpenTV Player instance.
    • Sets-up a DRM handler.
    • Starts playback by setting the video path.

The SDK player makes use of the DRM handler to fetch the Widevine keys, and/or with those keys it plays the encrypted content (e.g. tokens).

DRM handler

The OpenTV Player SDK defines the OTVMediaDrmCallbackinterface for all the methods needed to handle DRM operations. Implementation of this interface has to be specific to the nature of the Licence Server. However, to make integration easier, the SDK provides a generic default implementation OTVHttpMediaDrmCallback. This default implementation should be sufficient in many cases and is used in the encrypted-playback example code. The OTVHttpMediaDrmCallback object, is instantiated with a licence server URL, and can be configured after instantiation with key-value pairs that define specific HTTP POST headers. An example of a non-default implementation is demonstrated in the customised-encrypted-playback example code.

Periodically, the device Widevine Content Decryption Module (CDM) requires a renewal of the licence key. This is achieved by the same getKeyRequest() implementation of the OTVMedaDrmCallback interface.

If a different DRM handler is implemented, the OTVHttpMediaDrmCallback class must be replaced with a relevant implementation of the OTVMediaDrmCallback interface. See for example the customised-encrypted-playback example code.

Prerequisites

  • The application has all (or can fetch) the information for the licence server and the encrypted content.
  • An encrypted stream is available for testing
  • An Android device (not a simulator) with Widevine support.

Example code

Widevine is implemented by including the following methods to fetch the relevant data for the stream and Licence Server.

  • OTVHttpMediaDrmCallbackinstantiated with the Licence Server URI

    OTVHttpMediaDrmCallback drmCallback = new OTVHttpMediaDrmCallback(DRM_URI);
    
  • DRM handler configured using the setKeyRequestProperty() method. The values below are for illustration purposes only as they are specific to the type of licence server, the account and the content.

    drmCallback.setKeyRequestProperty("Accept",            "application/octet-stream");
    drmCallback.setKeyRequestProperty("Content-Type",      "application/octet-stream");
    drmCallback.setKeyRequestProperty("nv-tenant-id",      TENANT_ID_STR);
    drmCallback.setKeyRequestProperty("nv-authorizations", STREAM_TOKEN);
    

    Note that for Nagra-provided licence servers, the Accept and Content-Type values must be set to application/octet-stream (binary). JSON format is not supported.

  • OTVHttpMediaDrmCallback instance assigned to the OTVVideoView

    otvVideoView.setMediaDrmCallback(drmCallback);
    
  • Playback started by assigning the path to the OTVVideoView instance

    otvVideoView.setVideoPath(STREAM_URI);
    

Key rotation in live streams

Key rotation for live streams is where a live stream encryption key changes periodically and a new key needs to be fetched. No additional API is required for this feature, although there may be a slight pause in playback when key rotation occurs.

Depending on the licence server used, the default OTVHttpMediaDrmCallback class may not be able to handle key rotation request if, for example, a new token is required for each key request. In that case, a bespoke class implementing OTVMediaDrmCallback may be needed instead. For an example with a dedicated OTVCustomisedMediaDrmCallback class, see the (customised-encrypted-playback) example code.

Key rotation and temporal licence pre-delivery

To reduce key request calls to the licence server when playing a stream with key-rotation, along with the key for the next session, the licence server may send back keys for subsequent sessions. These additional keys are cached, and when required, the player checks for them before submitting a request to the licence server. There is no additional API for this feature either.

Storing pre-delivered keys is not supported for API levels below 23 (Marshmallow).