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).
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
If a different DRM handler is implemented, the
OTVHttpMediaDrmCallbackclass must be replaced with a relevant implementation of the
OTVMediaDrmCallbackinterface. See for example the customised-encrypted-playback example code.
- 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.
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
Content-Typevalues must be set to
application/octet-stream(binary). JSON format is not supported.
OTVHttpMediaDrmCallbackinstance assigned to the
Playback started by assigning the path to the
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).