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

The CONNECT Player SDK provides tools to enable playback of Widevine encrypted streams.

Enabling playback of Widevine encrypted streams typically comprises the following steps:

  • The user requests the application to start 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 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 a CONNECT 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 plays the encrypted content; for example 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 a renewal of the licence key. This is achieved by the same getKeyRequest() implementation of the OTVMedaDrmCallback interface.

Security Level

If Widevine Security Level 1 is supported by the device it will be used by default, even with Level 3 keys, for performance purposes.

The Widevine security level can be manually set in instances where this is problematic. This is done through an OTVHttpMediaDrmCallback object, or any other object that extends OTVCommonMediaDrmCallback), by using the OTVCommonMediaDrmCallback.setDrmPropertyString method. See below for an example:

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

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 is 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.

  • OTVHttpMediaDrmCallback instantiated with the licence server URI.

    OTVHttpMediaDrmCallback drmCallback = new OTVHttpMediaDrmCallback(DRM_URI);
    JAVA
  • 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);
    JAVA

    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);
    JAVA
  • Playback started by assigning the path to the OTVVideoViewinstance.

    otvVideoView.setVideoPath(STREAM_URI);
    JAVA