Widevine API Mapping

Version 1.0

Status: Final
Version: 1.0
th
Date: 7 January 2013
Author: Smart TV Alliance inc.
Category: Confidential
Reference: DRMWVAPISPEC

 Smart TV Alliance inc. 2013

All rights are reserved. Reproduction or transmission in whole or in part, in any form or by any
means, electronic, mechanical or otherwise, is prohibited without the prior written consent of the
copyright owner
-2-
1. CHANGE HISTORY ................................................................................................................................... 4
2. INTRODUCTION ........................................................................................................................................ 5
2.1. OVERVIEW ...................................................................................................................................................5
2.2. DEFINITIONS ................................................................................................................................................5
2.3. REFERENCES ...............................................................................................................................................5
2.4. TRADEMARKS AND COPYRIGHTS ..................................................................................................................5
3. WIDEVINE APIS OVERVIEW .................................................................................................................... 6
3.1. DESCRIPTION ...................................................................................................................................................6
4. OIPF DRMAGENT APIS ............................................................................................................................ 7
4.1. DESCRIPTION ...................................................................................................................................................7
4.2. OIPF DRMAGENT METHODS AND EVENTS......................................................................................................7
4.2.1. OIPF DRMAgent Methods................................................................................................................ 7
4.2.2. OIPF DRMAgent Events .................................................................................................................. 7
5. WIDEVINE WVPLAYBACK APIS ............................................................................................................. 9
6. HOW WIDEVINE APIS MAPPING TO THE OIPF APIS ......................................................................... 10
6.1. DESCRIPTION............................................................................................................................................ 10
6.2. USE OITF FUNCTIONS IN THE W IDEVINE CASE ......................................................................................... 10
6.2.1. Credentials Information ................................................................................................................. 10
6.2.2. DRM Agent Result ......................................................................................................................... 11
6.2.3. Playback Error ............................................................................................................................... 12
6.3. PLAYBACK SEQUENCES............................................................................................................................. 12

-3-
1. Change history
Version Date Changes
0.1 2012-10-20 First draft version 0.1
0.9 2012-11-30 Draft for Google Review
1.0 2012-12-12 Approved

-4-
2. Introduction
2.1. Overview
This document specifies the mapping from Widevine APIs to OIPFAgent APIs. The goal is to provide a
standardized method for application developers and TV manufacturers to support Widevine DRM.

Note that this specification is optional for compliance with Smart TV Alliance version 2.0.

2.2. Definitions
API Application Programming Interface
DRM Digital Rights Management
OIPF Open IPTV Forum
URL Uniform Resource Locator
XML Extensible Markup Language

References
[1] Widevine Technologies, Inc, “Widevine Playback API”
[2] Open IPTV Forum Release 1 specification, volume 5 (V1.1): "Declarative Application Environment".

2.3. Trademarks and copyrights

All trademarks and copyrights are the property of their respective owners.

-5-
3. Widevine APIs overview
3.1. Description
Applications interface with Widevine via the following interfaces:

 HTML5 video object

o The src element shall be set to the URL of the Widevine-encrypted content.
o In case of an error, the error attribute of the HTML5 video object shall be set to
MEDIA_ERR_DECODE.

 OIPF DRM Agent

o Applications shall use the OIPF DRM Agent API [2] applied to Widevine as described in this
document. The oipfDrmAgent.sendDRMMessage method is used to pass requests to
Widevine, and results are returned via onDRMMessageResult.

-6-
4. OIPF DRMAgent APIs

4.1. Description
OIPF DRMAgent is a standardized API that can help vendors to implement a single architecture and apply it
to any DRM solution.

4.2. OIPF DRMAgent Methods and Events

4.2.1. OIPF DRMAgent Methods

Table 1: String sendDRMMessage(String msgType, String msg, String DRMSystemID)
String sendDRMMessage(String msgType, String msg, String DRMSystemID)
Description Send message to the DRM agent using a message type as defined by the DRM
system. Returns a unique ID to identify the message, which is subsequently
passed as the msgID argument by the onDRMMessageResult callback function.
This is an asynchronous method. Applications will be notified of the results of the
operation via events dispatched to onDRMMessageResult and corresponding
DOM level 2 events.
Arguments msgType A globally unique message type as defined by the DRM
system, for example:
application/smarttv-alliance.widevine+xml’l
msg The message to be provided to the underlying DRM agent
formatted according to the message type as indicated by
attribute msgType.
DRMSystemID For example, for Widevine, the DRMSystemID value is “
urn:dvb:casystemid:19156”.

4.2.2. OIPF DRMAgent Events

Table 2: function onDRMMessageResult( String msgID, String resultMsg,Integer resultCode)
function onDRMMessageResult( String msgID, String resultMsg,Integer resultCode )
The function that is called when the underlying DRM agent has a result message to report to the
current HTML document as a consequence of a call to sendDRMMessage. The specified
function is called with three arguments msgID, resultMsg and resultCode which are defined as
follows:
 String msgID – identifies the original message which has led to this resulting message.
 String resultMsg – DRM system specific result message.
 Integer resultCode – result code. Valid values include:

Result Description Semantics

Code
0 Successful The action(s) requested by sendDRMMessage() completed
successfully.
1 Unknown sendDRMMessage() failed because an unspecified error occurred.
error
2 Cannot sendDRMMessage() failed because the DRM agent was unable to
process complete the request.
request
3 Unknown sendDRMMessage() failed, because the specified Mime Type is
-7-
 MIME type unknown for the specified DRM system indicated in the
DRMSystemId.
4 User consent sendDRMMessage() failed because user consent is needed for that
needed action.

-8-
5. Widevine WVPlayback APIs
Please refer to [1].

-9-
6. How Widevine APIs Map to the OIPF DRM Agent APIs
6.1. Description
In the chapter, we will introduce how to map Widevine APIs to the OIPF DRM Agent APIs.

6.2. Use of the OIPF DRM Agent for Widevine

6.2.1. Credentials Information

Before receiving streaming data, this instance of Widevine needs to be configured with credentials
information. The credentials information and required parameters are sent via the
oipfDrmAgent.sendDRMMessage method according to the XML schema described by this specification
below:

Table 3: Credentials Information

<?xml version =”1.0” encoding=”UTF-8”?>
<xs:schema xmlns:xs=http://www.w3.org/2011/XMLSchema>
<xs:element name=” WidevineCredentialsInfo”>
<xs:complexType>
<xs:sequence>
<xs:element name=”ContentURL” type=”xs:string” minOccurs=”1” maxOccurs=”1”/>
<xs:element name=”DeviceID” type=”xs:string”/>
<xs:element name=”StreamID” type=”xs:string”/>
<xs:element name=”ClientIP” type=”xs:string”/>
<xs:element name=”DRMServerURL” type=”xs:string” minOccurs=”1” maxOccurs=”1” />
<xs:element name=”DRMAckServerURL” type=”xs:string”/>
<xs:element name=”DRMHeartBeatURL” type=”xs:string”/>
<xs:element name=”DRMHeartBeatPeriod” type=”xs:string”/>
<xs:element name=”UserData” type=”xs:string”/>
<xs:element name=”Portal” type=”xs:string”/>
<xs:element name=”StoreFront” type=”xs:string”/>
<xs:element name=”BandwidthCheckURL” type=”xs:string”/>
<xs:element name=”BandwidthCheckInterval” type=”xs:string”/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>

String sendDRMMessage(msgType = “application/widevine+xml”,

msg = “
<?xml version="1.0" encoding="utf-8"?>
<WidevineCredentialsInfo xmlns="http://www.smarttv-alliance.org/DRM/widevine/2012/protocols/" >
<ContentURL>$(ContentURL)</ContentURL>
<DeviceID>$(DeviceID)</DeviceID>
<StreamID>$(StreamID)</StreamID>
<ClientIP>$(Client)</ClientIP>
<DRMServerURL>$(DRMServerURL)</DRMServerURL>
<DRMAckServerURL>$(DRMSAckerverURL)</DRMAckServerURL>
<DRMHeartBeatURL>$( HeartbeatServerURL)</DRMHeartBeatURL>
<DRMHeartBeatPeriod>$(DRMHeartBeatPeriod)</DRMHeartBeatPeriod>
<UserData>$(UserData) </UserData>
- 10 -
 <Portal>$(Portal)</Portal>
<StoreFront>$(Portal)</StoreFront>
<BandwidthCheckURL>$(BandwidthCheckURL) </BandwidthCheckURL>
<BandwidthCheckInterval>$(BandwidthCheckInterval)</BandwidthCheckInterval>
</WidevineCredentialsInfo >
”, DRMSystemID = “urn:dvb:casystemid:19156”);

Table 4: Element descriptions.

Element Support by CSP Description
ContentURL Mandatory Content URL
DRMServerURL Mandatory The URL for the Widevine DRM key server
DeviceID Optional Identifier of device.
ClientIP Optional Clinet IP address
StreamID Optional Identifier of stream being requested in the
entitlement request.
DRMAckServerURL Optional The URL for entitlement delivery
acknowledgements.
DRMHeartBeatURL Optional The URL of a server that handles a
heartbeat request.
DRMHeartBeatPeriod Optional Duration between consecutive heartbeats
(in seconds).
UserData Optional User data
Portal Optional Portal URL
StoreFront Optional StoreFront URL
BandwidthCheckURL Optional The URL for bandwidth check server.
BandwidthCheckInterval Optional An interval of bandwidth check.

6.2.2. DRM Agent Result

The method oipfDrmAgent.sendDRMMessage is asynchronous (that is, a non blocking function). Once the
underlying DRM agent has a result message to report to the current HTML document, the DRM agent will
invoke an event to notify the result via OIPF function onDRMMessageResult. This specification provides the
XML schema to describe the resultMsg and also defines the resultCode below:

Table 5: onDRMMessageResult parameter description

msgID identifies the original message which has lead to this resulting message. returned
value of sendDRMMessage().
resultMsg <?xml version="1.0" encoding="utf-8"?>
<xs :schema xmlns :xs= »http://www.w3.org/2001/XMLSchema »>
<xs :element name= »WidevineResultMsg »>
<xs :complexType>
<xs :element name= »WV_Status » minOccurs= »1 » maxOccurs= »1 »/>
</xs :complexType>
</xs :element>
</xs :schema>

<?xml version="1.0" encoding="utf-8"?>

- 11 -
 <WidevineResultMsg>
<WV_Status> $(WV_Status Code, please refer WV_Status.h) </WV_Status>
</WidevineResultMsg>

resultCode 0 :Successful
1 :Unknown error
2. Cannot process request
3. Unknow MIME type
4. User Consent Needed

6.2.3. Playback Error

In case of an error during playback, the error attribute of the HTML5 video object shall be set to
MEDIA_ERR_DECODE.

6.3. Playback sequences

Figure 1 shows an example of a playback sequence. It depicts the sequence between the CSP application
of client side, the Browser and the OIPF DRMAgent. Detailed sequences between the Widevine Library and
the Player are ommitted. (They are described in reference document [1].)

Fig. 1: Playback sequence

- 12 -