Playback of Widevine encrypted content

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

The CONNECT Player SDK provides tools to enable the playback of Widevine encrypted streams. Enabling playback typically comprises the following steps:

• The user requests the application to start the playback of an encrypted stream.

• The application retrieves the necessary metadata for playing the required content, for example, from a Content Management System (CMS). This metadata contains information for enabling 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 a CONNECT Player instance.

  • Sets up a DRM handler.

  • Starts playback by setting the video path.

• The SDK player uses the DRM handler to fetch the Widevine keys and play the encrypted content, such as tokens.

DRM handler

The SDK defines the OTVMediaDrmCallback interface 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’s Widevine Content Decryption Module (CDM) requires renewal of the licence key; this is achieved by the same getKeyRequest() implementation of the OTVMedaDrmCallback interface.

Security Level

Android widevine devices may be revoked by the Widevine server due to non-compliance with widevine device robustness rules and rendered inactive. If the security level 1 device has not been permanently revoked, it can be overridden to use security level 3 to use the Widevine client plugin to decrypt data continuously. For example, Pixel C, Nexus 7 and Nexus 9 have been revoked by the Widevine server, see https://www.widevine.com/news. This is done through an OTVHttpMediaDrmCallback object or any other object that extends the OTVCommonMediaDrmCallback), by using the OTVCommonMediaDrmCallback.setDrmPropertyString method. 

String securityLevel = "L1" // This can be any of [L1, L2, L3]
callbackObject.setDrmPropertyString("securityLevel", securityLevel)

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 following are required:

• The player has been created.

• The application has all (or can fetch) the information for the licence server and the encrypted content.

• An encrypted stream and an Android device (not a simulator) with Widevine support are available for testing.

Example code

Widevine is implemented by including the following methods to fetch the relevant data for the stream and Licence Server. If session management is required, see the process for Widevine SSM.

The OTVHttpMediaDrmCallback is instantiated with the licence server URI.

OTVHttpMediaDrmCallback drmCallback = new OTVHttpMediaDrmCallback(DRM_URI);

The DRM handler is 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);

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

The OTVHttpMediaDrmCallback instance is assigned to the OTVVideoView.

otvVideoView.setMediaDrmCallback(drmCallback);

Playback is started by assigning the path to the OTVVideoView instance.

otvVideoView.setVideoPath(STREAM_URI);