Developer center

Advanced Test Tool Guide

Introduction

The ExpressPlay Advanced Test Tool (ATT) is a suite of command-line debugging tools for advanced Marlin BB use cases. In such cases you may need to examine the license data from a particular token or check that the content key or content ID is correct. The ATT provides such tools to run Marlin client functions in order to debug this information. The ATT is available to download from the ExpressPlay Admin site (https://admin.expressplay.com).

This document is a guide describing usage of various command-line media file-handling tools provided by ExpressPlay for validating tokens acquired via the ExpressPlay REST API and licenses obtained as a result of processing tokens. These tools are provided to illustrate the functions of an ExpressPlay client application, such as those used to manage Marlin Broadband and MS3 licenses, to evaluate such licenses to determine whether they allow playback of specified Marlin content, to process Marlin action tokens to acquire licenses and to perform registrations of devices to users, etc. This guide assumes you are already familiar with the Marlin and other concepts, content file formats, etc. that are referenced by the tools, other than providing a very brief overview below of the main Marlin-protected content formats.

NOTE: It is recommended that you use Marlin MS3 tokens wherever possible as this format is much simpler and sufficient for all streaming use cases, but there are advanced cases such as download and playback offline, were Marlin BB tokens must be used. Those use cases may require the help of the ATT to confirm that your storefront hookup is correct. The ExpressPlay ATT can be obtained from the ExpressPlay Admin web console with a valid ExpressPlay account.

Summary of Tools

Ms3SampleClient	Parses and validates a specific MS3 URL. Returns hash of the content ID and the content key in clear as well as other optional elements: the authenticator, flags, the output control and extensions.
WasabiDashInfo	Parses a specified DASH MPD file and outputs content information
WasabiDashToMp4	Downloads the content referenced by an MPD and creates an MP4 file containing the content.
WasabiDashToMpeg2Ts	A command line example to download clear or protected DASH presentation.
WasabiDashTrace	Downloads the MPD and its media segments and prints information based on the same.
WasabiDbWiper	Deletes the Sushi and License Store databases used by Wasabi.
WasabiFile	Returns information about a specified media file (MP4,, DCF, MPEG-2 TS, BBTS,…). Includes the content type, protection type (if any), the track numbers and types, file or track content IDs (as relevant), and file metadata. Specifies whether there is an embedded license, and lists Silent License Acquisition URLs (if any).
WasabiLicenseStore	Manages a database of Marlin Broadband licenses.
WasabiMp4Decrypt	Given a URL (which may optionally be an MS3 URL) referencing PDCF content, this tool downloads the content (if it is not local), decrypts it, and produces an MP4 file with the clear content.
WasabiMp4License	Used to insert a license into an MP4-based media file, or to obtain the license embedded within an MP4-based media file.
WasabiSushiAction	Used to obtain a description of license requirements, or to determine whether a requested action (typically ‘Play’) on particular Marlin content is allowed, given a specified license.
WasabiSushiInfo	Provides information about Sushi Marlin DRM Engine (the core component of Wasabi) versions, property settings, and Nodes, Links, etc. currently in the Sushi database. Also indicates whether or not the device this is run on has been personalized.
WasabiSushiPersonalize	Personalizes the device on which it is run, obtaining keys, certificates, etc. necessary to provide a unique identity required for interactions with other Marlin entities.
WasabiSushiProcessToken	Processes an “action token” XML document and sends appropriate requests to a Marlin Broadband Server in order to request acquisition of a license or to perform a registration, such as registering a device to a user or registering a user as a subscriber of a subscription.

Tool Details

Each of the following sections provides documentation for a single tool. Each contains a tool description, a usage statement, information about all the parameters, and one or more example calls.

How to interpret the usage statements:

• Items in angle brackets represent placeholders for actual values. For example, one of the options for the mp4dump tool is shown as

–verbosity <n>

Here, <n> is a placeholder for a number between 0 and 3, so the option specified in an actual call would look something like the following:

–verbosity 2

• Items in square brackets are optional. For example, the usage statement for WasabiSushiPersonalize has the following at the end:

[<personalization-token-filename>]

This indicates that you can optionally include the name of a personalization token file.

• In many cases, the usage statement includes [options], indicating that one or more options are allowed at that position. The subsequent Parameters subsection lists all the possible options.
• You can see the usage statement for each of the mp4* and Ts2* tools by calling the tool with no parameters. This is not the case for the tools whose names start with “Wasabi”. Some of those tools do not have any parameters, or have parameters that can all be defaulted. If you call such a tool without parameters, it simply executes.
• Currently, if you call a tool (that has parameters) whose name starts with WasabiSushi and you pass it –help (or don’t specify any parameters), the usage statement that is displayed erroneously starts with “Sushi” instead of “WasabiSushi”. For example, here is a call to WasabiSushiAction with the –help option, and the resulting printout:

WasabiSushiAction –help
SushiAction [–accept] [–parameters <filename> ] <operation>
<action-name> <license-data-file> <content-id> [<content-id> …]

As you can see, the usage statement starts with SushiAction, but any calls you make should actually start with WasabiSushiAction, as shown in the example in 4.33.

• Many example calls are longer than can fit on a single line. For each of these, each line contains the maximum number of characters that will fit on the line, and the subsequent line(s) contain the rest of the call. All this should be concatenated together (without extra spaces) into a single “line” in order to make an actual call with the specified parameters.

Ms3SampleClient

Description

Given a MS3 URL returns hash of the content ID and the content key in clear as well as other optional elements: the authenticator, flags, the output control and extensions. The Ms3 URL may be an SAS url, an SAS compound URL, an SAD url or the name of a file containing an SAD.

Usage

Ms3SampleClient [options] <url-or-filename>

Parameters

[options]:

–help

Print usage information.

–accept-self-signed-certs

Accept self-signed server certificates.

–accept-hostname-mismatch

Allow certs with a mismatched hostname.

Examples

The following command causes Ms3SampleClinet to parse the specified Ms3 compound URL and output the URL information. Please note that the URL used in this example is not longer valid.

Ms3SampleClient https://ms3.eval.hostedmarlin.com:8443/hms/ms3/rights/?b=ABEAAwAAAasAB3dzYnRlc3RYIgAQ1-2TdoUVIckPJZ1UxTQt7QCA1706lA44YQfJmSC7haOeylltKaEniwGPehRta0Dx-Yc0A-3cSJuztYg4XcaI9qyShzJUeq1G0NamOtv9t_2cvu17y3ApiA5quVyPAuP5fDJA9UZ1yCr83xnavUD18LVsu20EQtdAYMT0tpPB3cic016uyfPR-AbLXzO7zYSQZwIAAAAUr0ll_
7p2tfkApkyiHD807OgkuMI#http%3A%2F%2Fcontent.intertrust.com%2Fexpress%2Fdash%2Fmpd.xml

WasabiDashInfo

Description

Given an MPD DASH manifest file, WasabiDashInfo parses the file and outputs information about the content, either to the console or to a specified text file.

Usage

WasabiDashInfo [options]

Parameters

[options]:

–pretty-print <url>

This option is required. It specifies the URL (local or remote) to the MPD file.

–output-file <filename>

If included, this option specifies the name of the output file to be used to store the tool output. If this option is not included, the tool output will be written to the console/stdout.

Example

The following command causes WasabiDashInfo to parse the specified MPD file and output content information. Some of the output is shown.

WasabiDashInfo –pretty-print http://content.acme.com/dash/cleartext-split/mpd.xml

WasabiDashToMp4

Description

Given a URL to an MPEG DASH MPD (Media Presentation Description), WasabiDashToMp4 creates an MP4 file containing the content referenced by the MPD.

Usage

WasabiDashToMp4 [options] <url> <mp4file>

Parameters

[options]:

–skip-to-ms <ms> – number of milliseconds of input content to skip before adding content to the output MP4 file. If this option is not specified, all the content will be included in the output file.

–extract-upto <seconds> – The number of seconds (in real-time) that the MPD will be processed and written to the mp4file. Typically used in the case of dynamic MPDs where the MPD does not necessarily end and to exit out of this tool after gathering enough output.

–accept-all-codecs – if this option is specified, codec filtering is not used and the client will accept all codecs that are in the MPD. If this option is not specified, the default codec filter will ingest only avc1 and mp4a content and write that to the mp4file.

–key <kid>:<key> – decryption key ID and key, where both are 32 hex characters (16 bytes). There can be more than one –key option specified.

<url> – URL to the MPD specifying the input content. This URL can start with http:// (or, equivalently, dash://) or https:// (or equivalently, dashs://).

<mp4file> – The MP4 file created.

Examples

The following outputs the clear DASH content specified in the mpd.xml file to the MP4 output file output.mp4, skipping the first 10 seconds of input content:

WasabiDashToMp4 –skip-to-ms 10000 http://localhost/acme/mpd.xml output.mp4

WasabiDashToMp4 –accept-all-codecs http://www.somecompany.com/somecontent/test.mpd ~/movies/test.mp4

The example above makes use of the accept-all-codecs option.

WasabiDashToMp4 –extract-upto 30 http://www.comecompany.com/somecontent/dynamic.mpd ~/movies/test.mp4

The example above makes use of the extract-upto option.

WasabiDashToMpeg2TS

Description

WasabiDashToMpeg2Ts is a command line example to download clear or encrypted DASH presentation with MPEG-2 TS segments of different bitrate depending on available bandwidth and save it to a MPEG-2 transport stream file.

Usage

WasabiDashToMpeg2TS [options] <url> <mpeg2tsfile>

Parameters

[options]:

–skip-to-ms <ms> – (Only for static MPD.) Number of milliseconds of input content to skip before adding content to the output file. If this option is not specified, all the content will be included in the output file.

–extract-up <seconds> – Seconds of time to extract

–accept-all-codecs – if this option is specified, codec filtering is not used and the client will accept all codecs that are in the MPD. If this option is not specified, the default codec filter will ingest only avc1 and mp4a content and write that to the mp4file.

–key <kid>:<key> – Content id and decryption key ID. Each consists of 32 hex characters (16 bytes). There can be more than one –key option specified.

WasabiDashTrace

Description

Given a URL to DASH MPD (Media Presentation Description), WasabiDashTrace downloads the MPD and its media segments and prints information based on the same. The WasabiDashTrace implementation uses the Wasabi MediaAccess SDK API’s and callbacks. This example can be used to implement a custom solution.

Usage

WasabiDashTrace [options] <url>

Parameters

[options]:

–audio-codec <codec> – Default value: mp4a

–video-codec <codec> – Default value: avc1

–audio-representation-id <id> – By default, the value is set to the first audio representation that matches the default audio codec.

–video-representation-id <id> – By default, the value is be set to the first video representation that matches the default video codec.

–audio-language <language> – By default, the value is set to whatever language the matched audio representation has.

–video-role <role> – Will be defaulted to urn:mpeg:dash:role:2011 (based on requirements of HbbTV spec).

If any of these options are given, only the stream matching these criteria will be considered for download.

–key <kid>:<key> –key ID and key. Required for decryption of encrypted streams

Example

WasabiDashTrace http://content.intertrust.com/dash_examples/bunny.mpd

In this example, WasabiDashTrace takes only a URL and no options. Therefore, only the defaults are used.

WasabiDbWiper

Description

Deletes the Sushi and License Store databases used by Wasabi.

Usage

WasabiDbWiper

Parameters

None.

Example

#WasabiDbWiper

WasabiFile

Description

Returns information about a specified media file (MP4, PDCF, DCF, MPEG-2, BBTS,…). Includes the content type, protection type (if any), the track numbers and types, file or track content IDs (as relevant), and file metadata. Specifies whether there is an embedded license, and lists Silent License Acquisition URLs (if any).

Usage

WasabiFile <input>

Parameters

<input> – The media file whose information will be returned.

Examples

Here is an example of calling WasabiFile to obtain information about an MP4 file:

#WasabiFile bigbucksbunny-trailer.mp4

Here is an example of calling WasabiFile on a PDCF file created from the above MP4 file, for example by calling mp4encrypt (§4.10):

#WasabiFile bigbucksbunny-trailer.mlv

Here are sample calls on an MPEG-2 TS file and a corresponding BBTS file (e.g., created from the MPEG-2 TS file using Ts2Encrypt, §4.19), respectively:

#WasabiFile bigbucksbunny-trailer.ts

#WasabiFile bigbucksbunny-trailer.bbts

WasabiLicenseStore

Description

Manages a database of Marlin Broadband licenses.

Usage

WasabiLicenseStore [options]

Parameters

[options]:

–help

Outputs the usage statement for this tool.

–list

Lists the license number and license ID for all the licenses in the License Store.

–insert <license-file-name> [tag]

Inserts the license from the specified file into the License Store. Returns a license ID assigned by the License Store to the license that was added. If you include an optional string tag, that tag will be associated with the license in the License Store.

–enumerate <flag>

Enumerates all the licenses in the License Store, and for each includes the license number and the type of information signaled by the flag. The possible flag values are the following:

. LD specifies inclusion of license data, that is, the XML specifying the license that was previously passed to the –insert option.

. ED specifies inclusion of expiration dates, that is, the date each license expired (in minutes since midnight January 1, 1970), with -1 signaling that a license has not yet expired.

. ID specifies inclusion of insertion dates, the date each license was inserted into the store, in minutes since midnight January 1, 1970.

. LT specifies inclusion of the license tag (if any) assigned to each license when it was inserted.

–find <content-ID>…

Finds and lists all the licenses in the License Store referencing the specified content ID(s). If there is more than one content ID, the IDs should be separated by whitespace (such as one or more spaces).

–get <license-ID> <output-filename>

Finds the license in the License Store with the specified license ID, and stores the license in a file with the specified output filename.

–remove <license-ID>

Removes from the License Store the license with the specified license ID.

Examples

The following call inserts into the License Store the license in the file saved-license.xml, and returns the license ID assigned by the License Store to the newly inserted license.

#WasabiLicenseStore –insert saved-license.xml

Here is an example of what a call with the –list option would return if the License Store was empty before the previous call. The –list option results in the listing of one line per license, and for each license it shows the license number and the license ID.

#WasabiLicenseStore –list

Suppose you insert another license, and for this license you specify a tag (BigBuckyLicense) to be associated with it:

#WasabiLicenseStore –insert license2.xml BigBuckyLicense

Now the –list option will return information about two licenses:

#WasabiLicenseStore –list

and the –enumerate LT option will show that the first license inserted did not have a tag, but the second license inserted was assigned the tag BigBuckyLicense:

#WasabiLicenseStore –enumerate LT

You can store a copy of the license with ID 1 in a file named license-1.xml via the following:

#WasabiLicenseStore –get 1 license-1.xml

You can find all the licenses in the License Store that reference the content ID urn:marlin:intertrust:test-webstore:0001 via the following. If that is the content ID for a media file whose license is specified in saved-license.xml (the license first stored as shown above in the License Store), the result will be the following:

#WasabiLicenseStore –find urn:marlin:intertrust:test-webstore:0001

The following shows an example of enumerating license expiration dates, for a situation where the license with license number 0 has not yet expired (signaled by a value of -1) but the one with license number 1 has:

#WasabiLicenseStore –enumerate ED

The following shows removing the license with license ID 2, and the subsequent License Store listing.

#WasabiLicenseStore –remove 2

#WasabiLicenseStore –list

WasabiMp4Decrypt

Description

Given a URL (which may optionally be an MS3 URL) referencing PDCF content, this tool downloads the content (if it is not local), decrypts it, and produces an MP4 file with the clear content.

Usage

WasabiMp4Decrypt <input> <output>

Parameters

<input> – The MS3 compound URI referencing PDCF or DCF content.

<output> – The MP4 file produced by WasabiMp4Decrypt.

Example

The following command redeems the MS3 compound URI specified in the file ms3_dcf_compound_uri.txt, retrieves the associated content file, decrypts it, and stores the result in decrypted.mp4. Please note that the use of text within backtick characters (`) referencing a subcommand to be executed prior to the top-level command is available for shells like bash, sh, csh, and so on. In the Windows default shell (the Command Prompt window), the command line should contain the MS3 compound URI itself, instead of `cat ms3_dcf_compound_uri.txt`.

WasabiMp4Decrypt `cat ms3_dcf_compound_uri.txt` decrypted.mp4

WasabiMp4License

Description

This tool is used to insert a license into an MP4-based media file, or to output to stdout the license embedded within such a media file.

Usage

WasabiMp4License [<license-filename>] <mp4-filename>

Parameters

<license-filename>

If this parameter is specified, WasabiMp4License embeds the license from the specified file into the MP4 file, replacing any license that is already embedded.

<mp4-filename>

The MP4 file into which a license should be embedded (if a license file is specified), or from which the embedded license bytes (if any) should be obtained and output to stdout.

Example

The following embeds the license from license-to-insert.xml into magicalevent.mp4.

WasabiMp4License license-to-insert.xml magicalevent.mp4

WasabiSushiAction

Description

Used to obtain a description of the control program code in a license (that is, the license requirements), or to determine whether a requested action (typically ‘Play’) on particular Marlin content is allowed, given a specified license. The exact behavior depends on the specified operation and action name. If the operation is Describe, then the license requirements description is returned, specifying the set of all conditions checked. If the operation is Check or Perform, then the license is examined to determine whether the requested action is allowed. If it is not, then these specify which condition(s) failed. If the action is allowed, and the operation is Perform, this tool returns the content key(s) required to decrypt the content.

Usage

WasabiSushiAction [options] <operation> <action-name> <license-data-filename> <content-ID> [<content-ID> …]

Parameters

[options]:

–accept

Blindly accept all obligations and callbacks. This option is only useful for the Perform operation. It will be ignored for all other operations.

–parameters <filename>

Read the action parameter block from <filename>. This option can only be used for actions that expect parameters.

<operation> – One of the following: Describe, Check, or Perform.

<action-name> – The possible action names depend on the control in the license. The Play action is most commonly used, but others such as Export may also be available.

<license-data-filename> – The name of the license file.

<content-ID> – A content ID. There may be more than one, separated by whitespace.

Examples

The following is an example of calling WasabiSushiAction with the Describe operation and the Play action to find out the constraints of a particular license. In this example, there is a single Node Reachability constraint that indicates that the Play action on the content will be allowed only if the specified Node representing the user is “reachable.” A Node is considered reachable if there is a Link (or multiple Links) from the Node representing the device on which the tool is run to the specified Node. There is a Link from the device Node to the user Node if the device has been registered to the user.

WasabiSushiAction Describe Play permanent-user-bound-license.xml urn:m arlin:intertrust:test-webstore:0001

The following two example calls are the same as the previous example, except for the operation being Check and Perform, respectively, instead of Describe. As you can see, both of these indicate that the Play action is granted, and when the specified operation is Perform, the key needed to decrypt the content is also returned.

WasabiSushiAction Check Play permanent-user-bound-license.xml urn:marl in:intertrust:test-webstore:0001

WasabiSushiAction Perform Play permanent-user-bound-license.xml urn:ma rlin:intertrust:test-webstore:0001

Here is another example of calling WasabiSushiAction with the Describe operation. In this example, the specified license has both a device constraint (indicating that the license allows the content to be played only on the specified device) and temporal constraints indicating that the content can be played only between midnight January 1, 2009 and the end of 2010.

WasabiSushiAction Describe Play old-license.xml urn:marlin:intertrust: test-webstore:0001

If you make the same call to WasabiSushiAction, this time specifying the Check or Perform operation, the output shows that the Play action is denied, and the reason it is denied (failure of the NotAfter condition) is displayed:

WasabiSushiAction Perform Play old-license.xml urn:marlin:intertrust:t est-webstore:0001

WasabiSushiInfo

Description

Provides information about Sushi version numbers, property settings, Nodes, Links, etc., and indicates whether or not the device this is run on has been personalized.

Usage

WasabiSushiInfo

Parameters

There are no parameters.

Example

WasabiSushiInfo

WasabiSushiPersonalize

Description

Personalizes the device on which it is run, obtaining credentials (keys, certificates, etc.) necessary to provide a unique identity required for interactions with other Marlin entities. Personalization is described in detail in the Sushi Deployment Guide.

Usage

WasabiSushiPersonalize [–update] [–config <filename>] [<personalization-token-filename>]

Parameters

–update

If specified, this option causes an update of the public credential of existing personality using the renewal action token from personalization-token-filename argument. If no personalization token filename is specified, a default personalization token is used, supplying the device with credentials suitable only for testing purposes.

If the –update option is not specified, personalization is performed as before.

–config <filename>

Specifies a configuration file setting Sushi and/or Wasabi properties, with each property name and value specified as a name=value pair, one per line.

<personalization-token-filename>

Specifies an XML file containing a personalization token. If no personalization token filename is specified, a default personalization token is used, supplying the device with credentials suitable only for testing purposes.

Example

WasabiSushiPersonalize

WasabiSushiProcessToken

Description

Processes an “action token” XML document, and sends appropriate requests to a Marlin Broadband Server in order to request acquisition of a license or to perform a registration, such as registering a device to a user (represented by a Link from the device Personality Node to the User Node) or registering a user as a subscriber of a subscription (represented by a Link from the User Node to the Subscription Node).

An action token may be sent by a web store to a Marlin Broadband Client application whenever the client (Sushi) needs to interact with a Marlin Broadband Server (which, in turn, interacts with the web store backend) in order to perform operations and obtain objects required to implement DRM functionality necessary to satisfy a user request.

Usage

WasabiSushiProcessToken [options] <token-filename>

Parameters

[options]:

–config <filename>

Specifies a configuration file setting Sushi and/or Wasabi properties, with each property name and value specified as a name=value pair, one per line.

–save-license <filename>

For a license acquisition, this specifies the name of the file into which the license should be stored.

<token-filename> – The action token XML document.

Examples

Here is a sample license acquisition action token for acquiring a device-bound license:

The following command processes the license acquisition action token specified in license-a-t.xml, and saves the acquired license in a file named license.xml.

WasabiSushiProcessToken –save-license license.xml license-a-t.xml

The following is an example of a registration action token for registering a device to a particular user:

Here is an example of calling WasabiSushiProcessToken with the above registration action token, in a file named bb-registration-action-token.xml:

#WasabiSushiProcessToken bb-registration-action-token.xml

The output will look like the following: