PlayReady App Creation Tutorial

Transcription

1 Version 0.93 Samsung Smart TV 1

2 1. OVERVIEW INTRODUCTION DEVELOPMENT ENVIRONMENT FILES NEEDED FOR A PLAYREADY VIDEO APPLICATION SAMSUNG TV PLAYREADY SPECIFICATION PLAYREADY AND WMDRM 10 FOR PORTABLE DEVICES DIRECT LICENSE ACQUISITION (DLA) SILENT LICENSE ACQUISITION WITH USER CUSTOM DATA Set Cookie in HTTP Header Set User Custom Data POST-DELIVERY AND PRE-DELIVERY LICENSE ACQUISITION WEB INITIATORS DOMAIN JOIN AND LEAVE EMBEDDED LICENSE SECURITY VERSION / CLIENT VERSION / USER-AGENT SECURITY LEVEL DELETE LICENSE API GUIDELINE PLAYREADY URL FORMAT SET COOKIE IN HTTP HEADER SET USER CUSTOM DATA CHANGING LICENSE SERVER URL PROCESS WEB INITIATORS JOIN DOMAIN LEAVE DOMAIN DELETE LICENSE

3 Preface Purpose of Document. This document is a tutorial that is aimed at application developers for Samsung Smart TVwho 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 ( It is recommended that you read Application Development Guide for Samsung 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

4 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 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 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 Internet@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

5 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 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 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 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 don t support any intermediate step asking for user input during license acquisition process. 5

6 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 If your service is based on PlayReady, you can set the custom data in the cookie of HTTP Header as described in or set the data in challenge message as described in The data is used when calling Drm_LicenseAcq_GenerateChallenge function. Please refer to the PlayReady Specification for more information 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: 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

7 <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body><acquirelicense xmlns=" <challenge> <Challenge xmlns=" <LA xmlns=" Id="SignedData" xml:space="preserve"> <Version>1</Version> <ContentHeader><WRMHEADER xmlns= version=" ">. </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

8 3.5. Web Initiators This feature is only available in PlayReady-based service. 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 Domain Join and Leave This feature is only available in PlayReady-based service. 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 Embedded License This feature is only available in PlayReady-based service. 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 Security Version / Client Version / User-Agent If your license server checks the values of Security Version, Client Version, or User-Agent in the 8

9 license challenge request message before issuing license, you should add the following values in your accept list for Samsung TVs Products 2011 Products < SECURITYVERSION> < CLIENTVERSION> User-Agent WMDRM_DLA Windows-Media-DRM/ PlayReadyClient 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 Security Level Samsung Devices use Security Level 2000 certificates 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

10 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 Products 2011 Products WMDRM10 WMDRM10 PlayReady Set Cookie SetPlayerProperty (1) O * O O Set User Custom Data SetPlayerProperty (3) X X O Changing License Server URL SetPlayerProperty (4) X O O Process Web Initiator ProcessInitiatorsFromUrl X X O ProcessInitiatorsFromXml Join/Leave Domain JoinDomain X X O LeaveDomain Delete License SetPlayerProperty (6) X O ** O ** * Supported after T-INFOLINK ** Supported after T-INFOLINK

11 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 = 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.initplayer(url COMPONENT=WMDRM); playerplugin.setplayerproperty (1, document.cookie, document.cookie.length); playerplugin.startplayback(); 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 Set User Custom Data You can use SetPlayerProperty before calling StartPlayback() function. playerplugin.initplayer(url COMPONENT=WMDRM); playerplugin.setplayerproperty (3, customdata, customdata.length); playerplugin.startplayback(); 4.4. Changing License Server URL You can use SetPlayerProperty before calling StartPlayback() function. playerplugin.initplayer(url COMPONENT=WMDRM); playerplugin.setplayerproperty (4, serverurl, serverurl.length); playerplugin.startplayback(); 11

12 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 = ; 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 = document.getelementbyid('pluginsefplayready'); SefPluginPlayReady.Open("PlayReadyDrm", "1.000", "PlayReadyDrm"); SefPluginPlayReady.Execute ( ProcessInitiatorsFromXml, xml, xml.length); SefPluginPlayReady.Close (); 4.6. Join Domain You can use JoinDomain to join a specific domain. SefPluginPlayReady = document.getelementbyid('pluginsefplayready'); var certserver = " ; var serviceid = "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}"; var accountid = "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}"; var customdata = customdata ; SefPluginPlayReady = document.getelementbyid('pluginsefplayready'); SefPluginPlayReady.Open("PlayReadyDrm", "1.000", "PlayReadyDrm"); SefPluginPlayReady.Execute("JoinDomain", certserver, serviced, accounted, customdata, customdata.length); SefPluginPlayReady.Close (); 12

13 4.7. Leave Domain You can use LeaveDomain to leave a specific domain. SefPluginPlayReady = document.getelementbyid('pluginsefplayready'); var certserver = " ; var serviceid = "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}"; var accountid = "{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}"; var customdata = customdata ; SefPluginPlayReady = document.getelementbyid('pluginsefplayready'); SefPluginPlayReady.Open("PlayReadyDrm", "1.000", "PlayReadyDrm"); SefPluginPlayReady.Execute("LeaveDomain", certserver, serviced, accounted, customdata, customdata.length); SefPluginPlayReady.Close (); 4.8. Delete License You can use SetPlayerProperty before calling StartPlayback() function. playerplugin.initplayer(url COMPONENT=WMDRM); playerplugin.setplayerproperty (6, NULL, 1); playerplugin.startplayback(); 13