PlayReady App Creation Tutorial (V0.94)

PlayReady App Creation Tutorial
Version 0.94
Samsung Smart TV
@Samsung Electronics Copyright All Rights Reserved
1
1.
OVERVIEW .............................................................................................................................................................. 4
2.
INTRODUCTION .................................................................................................................................................... 4
3.
2.1.
DEVELOPMENT ENVIRONMENT ............................................................................................................................ 4
2.2.
FILES NEEDED FOR A PLAYREADY VIDEO APPLICATION ....................................................................................... 5
SAMSUNG TV PLAYREADY SPECIFICATION ................................................................................................ 5

3.1.
PLAYREADY AND WMDRM 10 FOR PORTABLE DEVICES .................................................................................... 5
3.2.
DIRECT LICENSE ACQUISITION (DLA) ................................................................................................................. 5
3.3.
SILENT LICENSE ACQUISITION WITH USER CUSTOM DATA .................................................................................. 5
3.3.1.
Set Cookie in HTTP Header ....................................................................................................................... 6
3.3.2.
Set User Custom Data ................................................................................................................................. 6
3.4.
POST-DELIVERY AND PRE-DELIVERY LICENSE ACQUISITION ................................................................................ 7
3.5.
WEB INITIATORS .................................................................................................................................................. 8
3.6.
DOMAIN JOIN AND LEAVE .................................................................................................................................... 8
3.7.
EMBEDDED LICENSE ............................................................................................................................................ 8
3.8.
SECURITY VERSION / CLIENT VERSION / USER-AGENT ........................................................................................ 8
3.9.
SECURITY LEVEL ................................................................................................................................................. 9
3.10.
4.
DELETE LICENSE ............................................................................................................................................. 9
API GUIDELINE.................................................................................................................................................... 10
4.1.
PLAYREADY URL FORMAT ................................................................................................................................ 11
4.2.
SET COOKIE IN HTTP HEADER .......................................................................................................................... 11
4.3.
SET USER CUSTOM DATA................................................................................................................................... 11
4.4.
CHANGING LICENSE SERVER URL..................................................................................................................... 11
4.5.
PROCESS WEB INITIATORS ................................................................................................................................. 12
4.6.
JOIN DOMAIN..................................................................................................................................................... 12
4.7.
LEAVE DOMAIN ................................................................................................................................................. 13
4.8.
DELETE LICENSE ............................................................................................................................................... 13

2
Preface
Purpose of Document
This document is a tutorial that is aimed at application developers for SMART TV who plan to
use PlayReady Technology for protecting their streaming content. This document focuses on the
features supported by Samsung TV and does not provide a detailed description about PlayReady
Technology itself. For more information about the technology, please refer to the official
Microsoft Web Site (http://www.microsoft.com/playready/default.mspx).
It is recommended that you read Application Development Guide for SMART TV (hereinafter
referred to as "the Guide") first. This document provides references to the Guide for your
understanding.
Target Readers
This document is aimed at programmers who have used web development languages such as HTML,
CSS and JavaScript, and will be even more helpful for those who have web development
experience. This document has been written on the assumption that readers have a background in
Microsoft DRM and have already read the Guide.

3
1. Overview
This document will go step by step through the development of an application that features a
PlayReady video playback. The PlayReady features of Samsung TV are described in section 3 and
how to implement those features using Samsung TV Apps SDK is described in section 4.
2. Introduction
PlayReady is a content access and protection technology that is the successor to WMDRM. It
provides new advanced and frequently-requested features, such as domain control, embedded
licenses, and the ability to protect a wide range of content types and formats. Also, it provides
backward compatibility with WMDRM.
Samsung TV released in 2011 supports PlayReady Technology, whereas the previous product only
supports WMDRM. Since PlayReady provides backward compatibility with WMDRM, Samsung
TV can acquire content from both existing WMDRM-based services and new PlayReady-based
services.
In order to develop the PlayReady video Application, developers are required to have background
knowledge such as HTML, JavaScript and CSS. There will be no explanation about HTML,
JavaScript or CSS provided in this document. Developing applications suited for TVs is different
from developing applications on PCs in several aspects. You can get more information on this from
the Guide. This document explains each development stage with the source code and analyzes how
each code is completed. But please note that the code snippets provided is indicative and detailed
source code is not provided in the document.
2.1. Development environment

The application uses Samsung TV Apps SDK made by Samsung to create the application. With use
of the emulator provided with the SDK, you can operate your application before actually putting it
in your TV, note that the actual PlayReady playback is not supported in the SDK as per the current
version of SDK, this can only be tested on TV.
It is possible to run the application on a real SMART TV device (for example, a TV) using the
"User Application" features. For details of this process please see the document "User Application".
Before porting the application on real target, ensure that the target is capable of playing a
PlayReady video.

4
2.2. Files needed for a PlayReady Video Application

You will be provided with the basic source code for the PlayReady video application. Unzip the
files, and refer to section 3.3 to locate them in the appropriate places.
Please note that this tutorial does not supply any video files for playback for copyright reasons.
3. Samsung TV PlayReady Specification

This section briefly explains the PlayReady features supported by Samsung TV.
3.1. PlayReady and WMDRM 10 for Portable Devices

Samsung TVs launched in 2011 support Microsoft PlayReady Technology. Microsoft PlayReady
provides backward compatibility with Windows Media DRM, therefore Samsung device can
acquire content from both existing WMDRM 10 for Portable Devices and new Microsoft
PlayReady-based services.
3.2. Direct License Acquisition (DLA)

o Direct License Acquisition (DLA) means the ability to acquire license directly from a license
server over an IP network rather than through a proxy client.
o Indirect License Acquisition (ILA) means the ability to acquire license indirectly through a proxy
client such as a personal computer by using Media Transfer Protocol over a USB connection.
Since Samsung TV can acquire a license directly from a license server, we only support DLA
mode.
3.3. Silent License Acquisition with User Custom Data

In silent license acquisition, whenever a license challenge is received by a license server, the license server
responds by sending a license response to the device. There are some instances where the license server may
need additional information from the user before issuing a license. These instances are called non-silent license
acquisition scenarios; for example, a user's identity is not authenticated and therefore needs to enter a user
name and password.
We dont support any intermediate step asking for user input during license acquisition process.

5

Instead, you can add any custom data generated in authentication or payment stage to the license
challenge message.
If your service is based on WMDRM10, you can set your custom data using cookie property as
described in 3.3.1. If your service is based on PlayReady, you can set the custom data in the
cookie of HTTP Header as described in 3.3.1 or set the data in challenge message as described in
3.3.2. The data is used when calling Drm_LicenseAcq_GenerateChallenge function. Please refer
to the PlayReady Specification for more information.
3.3.1.
Set Cookie in HTTP Header
You can set a string which should be contained in HTTP Header of license challenge message
using SetPlayerProperty function. Please refer to section 4 for the detailed API usage.
Here is an example of HTTP Header of the license challenge message with cookie.
POST /Janus/testcases/9TC1.asp HTTP/1.0
Host: wmtap.smdisp.net
User-Agent: PlayReadyClient
Content-Type: application/x-www-form-urlencoded
Pragma: no-cache
Cookie :MyCookie
Content-Length: 22742
3.3.2.
Set User Custom Data
This feature is only available in PlayReady-based service.

You can set a custom data which should be contained in challenge message using
SetPlayerProperty function. Please refer to section 4 for the detailed API usage.
Here is an example of license challenge message with user custom data.

6

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body><AcquireLicense xmlns="http://schemas.microsoft.com/DRM/2007/03/protocols">
<challenge>
<Challenge xmlns="http://schemas.microsoft.com/DRM/2007/03/protocols/messages">
<LA xmlns="http://schemas.microsoft.com/DRM/2007/03/protocols" Id="SignedData" xml:space="preserve">
<Version>1</Version>
<ContentHeader><WRMHEADER xmlns=http://schemas.microsoft.com/DRM/2007/03/PlayReadyHeader
version="4.0.0.0"> . </WRMHEADER>
</ContentHeader>
<ClientInfo> </ClientInfo>
<CustomData>MyCustomData</CustomData>
3.4. Post-delivery and Pre-delivery License Acquisition

The most common pattern of acquiring a license is to download a piece of content and
acquire a license based on the data contained within the header of the content. This
approach is called post-delivery.
An alternative approach is license pre-delivery. Here, the license is acquired for the
content before the content available to the client.
Post-delivery : Samsung TV invokes License Acquisition when the media file is played. After the
header of the media file is processed, it acquires a license based on the data contained within the
header of the file.
o By default, Samsung TV uses license acquisition URL parsed from the header. But, you
can modify or replace the URL by using SetPlayerProperty function. Please refer to
section 4 for the detailed API usage.
Pre-delivery: If you want to acquire a license before the media file is available, you can use
License Acquisition Web Initiator in PlayReady-based Service.

7
3.5. Web Initiators

Web initiators are XML document which are sent from the portal to the device to
initiate a DRM protocol between client and service. Web Initiators can be sent to
initiate a license acquisition, metering, a join domain or a leave domain protocol.
Samsung TV supports all defined PlayReady Web Initiators.
You can use ProcessInitiatorsFromXml or ProcessInitiatorsFromUrl to initiate a DRM
protocol. Please refer to section 4 for the detailed API usage.
3.6. Domain Join and Leave

PlayReady allows a group of devices that are members of a domain to play back all
content that binds to the same domain. Previously, only device-bound licenses could
be issued for content. Only one client in a domain needs to acquire a license for a
given piece of content, and then the license can be embedded into the content. The
content can then be shared and played among all members of the domain.
Samsung TV can join a specific domain by JoinDomain function or leave the domain by
LeaveDomain function. Please refer to section 4 for the detailed API usage.
3.7. Embedded License

PlayReady allows an application to store the license for a DRM-protected content file
in the PlayReady object of the content file itself. Because the license is stored (or
embedded) in the content file, it is immediately available, enabling a player
application to decrypt and begin playing the content without first needing to complete
the license acquisition process or check the HDS store.
Samsung TV is able to parse and playback PlayReady media file which has Embedded License.
3.8. Security Version / Client Version / User-Agent

If your license server checks the values of Security Version, Client Version, or User-Agent in the

8

license challenge request message before issuing license, you should add the following values in
your accept list for Samsung TVs.
2010 Products
2011 Products
< SECURITYVERSION>
2.4.115.165
2.4.117.27
< CLIENTVERSION>
9.00.00.2778
11.2.0.1404
User-Agent
WMDRM_DLA
PlayReadyClient
Windows-Media-DRM/11.0.7600.16385
Note that the requirement of minimum security version is not necessary for devices.
<SECURITYVERSION> corresponds to the robustness version of the PC client black box, and
it is only meaningful when the client is PC application. Enforcing a minimum security version on
PCs (includes Silverlight clients) is to ensure that in case of a PC breach only patched PC receive
the content. For devices the value is not meaningful because in case of a breach the device
certificate itself would have been revoked and the server will just not deliver a license.
3.9. Security Level

Samsung Devices use Security Level 2000 certificates.
3.10. Delete License

After acquiring a valid license from a license server, Samsung TVs store the license in the
permanent storage in order not to perform the license acquisition process during the validity
period. But, if you want to delete a license after playing a content using the license, you can use
the SetPlayerProperty function. The license is deleted when the play is stopped. Please refer to
section 4 for the detailed API usage.

9
4. API Guideline
<object id="pluginPlayer" border=0 classid="clsid:SAMSUNG-INFOLINK-PLAYER"></object>
<object id="PluginSefPlayReady" border=0 classid="clsid:SAMSUNG-INFOLINK-SEF"></object>
The two objects shall be defined in HTML file for using pluginPlayer and PluginSefPlayReady.
2010 Products
2011 Products
WMDRM10
WMDRM10
PlayReady
Set Cookie
SetPlayerProperty (1)
O*
Set User Custom Data
Changing License Server URL
Process Web Initiator
ProcessInitiatorsFromUrl
O**
O**
ProcessInitiatorsFromXml
Join/Leave Domain
JoinDomain
LeaveDomain
Delete License
* Supported after T-INFOLINK-2010-1009

** Supported after T-INFOLINK-2011-1002

10
4.1. PlayReady URL Format

If you want to play PlayReady/WMDRM protected content, you should add predefined postfix
|COMPONENT=WMDRM to your original URL.
var url = http://www.server.com/a.wmv;
var playerPlugin = document.getElementById("pluginPlayer");
playerPlugin.InitPlayer(url+|COMPONENT=WMDRM);
playerPlugin.StartPlayback();
4.2. Set Cookie in HTTP Header

You can use SetPlayerProperty before calling StartPlayback() function.
playerPlugin.SetPlayerProperty (1, document.cookie, document.cookie.length);
You can change the second and third parameters of SetPlayerProperty function to your custom data
like DUID or tokens which is not an actual cookie set by Server. But, note that your license server
finds the value in the cookie property in HTTP Header of license challenge message.
4.3. Set User Custom Data

playerPlugin.SetPlayerProperty (3, customdata, customdata.length);
4.4. Changing License Server URL

playerPlugin.SetPlayerProperty (4, serverurl, serverurl.length);

11
4.5. Process Web Initiators

You can use ProcessInitiatorsFromUrl to pass the Web Initiator URL. Samsung TV sends HTTP
GET Request to the url and parse the result.
var url =http://www.yourserver.com/initiators/LicenseAcquisitionInitiator.xml;
SefPluginPlayReady = document.getElementById('PluginSefPlayReady');
SefPluginPlayReady.Open("PlayReadyDrm", "1.000", "PlayReadyDrm");
SefPluginPlayReady.Execute (ProcessInitiatorsFromUrl, url);
SefPluginPlayReady.Close ();
Or, you can use ProcessInitiatorsFromXml to pass the xml string which complies with the XML
Schema defined by PlayReady Technology.
var xml = <?xml version=\1.0\;
SefPluginPlayReady.Execute (ProcessInitiatorsFromXml, xml, xml.length);
4.6. Join Domain

You can use JoinDomain to join a specific domain.
var certserver = "http://www.yourdomainserver;
var serviceid = "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}";
var accountid = "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}";
var customdata = customdata;
SefPluginPlayReady.Execute("JoinDomain", certserver, serviced, accounted, customdata, customdata.length);

12
4.7. Leave Domain

You can use LeaveDomain to leave a specific domain.
var certserver = "http://www.yourdomainserver;
var serviceid = "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}";
var accountid = "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}";
var customdata = customdata;
SefPluginPlayReady.Execute("LeaveDomain", certserver, serviced, accounted, customdata, customdata.length);
4.8. Delete License

playerPlugin.SetPlayerProperty (6, NULL, 1);

13

PlayReady App Creation Tutorial (V0.94)

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

PlayReady App Creation Tutorial (V0.94)

Uploaded by

Copyright:

Available Formats

PlayReady App Creation Tutorial