DoveRunner Wowza DRM Plugin Guide

DoveRunner Wowza DRM Plugin is an addon module of Wowza Streaming Engine that supports streaming service with DASH (CENC) and HLS (FPS and NCG) content by DRM packaging original MP4 video or live stream in real time.

You can download DoveRunner Wowza DRM Plugin file from the Github repository.

This document describes how to apply the Wowza plugin after installing Wowza Streaming Engine.

Requirements

• Wowza Streaming Engine: 4.9.1 or later
• JAVA version : JDK 17 or later

Streaming protocol and DRM support

• DASH-CENC: Widevine, PlayReady, WisePlay DRM
• HLS-SampleAES: FairPlay Streaming DRM, Clear key
• CMAF-CENC: Widevine, PlayReady DRM (see more information below)
• HLS-AES128: NCG DRM, Clear key

Note

Wowza Streaming Engine does not support CBCS encryption mode for CMAF packaging currently. Therefore, you cannot use Wowza CMAF packaging for FairPlay which requires CBCS mode.

Wowza team didn’t announce the support for CMAF HLS packaging officially, but both CMAF DASH and HLS packaging work fine with CTR mode (CENC).

Integration Workflow

1. Upload original content

• Upload original MP4 content to storage associated with Wowza streaming server. For adaptive streaming, upload resolution-specific MP4 files and SMIL files.
• If you are servicing live stream, set the live source for the Wowza application separately created for live stream.

2. Request for content playback

• The client (HTML5 player or mobile application) requests streaming playback via a DASH (mpd) or HLS (m3u8) streaming URL.

3. Request for package key info

• Request the key information needed for real-time packaging to the DoveRunner cloud server. When requesting key information, you can specify the content ID (CID) value corresponding to the original MP4 file or live stream name in the form of a mapping file.

4. Realtime Packaging

• Package the original content in DASH or HLS format using the key information received from DoveRunner cloud.

5. DRM License Issuance

• The client asks DoveRunner cloud server for the key needed to play the encrypted streaming content, and DoveRunner cloud server sends the key information to the client verified through license management API.

Installing Wowza and DRM plugin

Creating Wowza Application

Install the Wowza Streaming Engine on a server for streaming. Create a Wowza streaming application on the Applications tab after connecting to Wowza Streaming Engine Manager on your browser. You can choose VoD or live applications. If you use both methods, you have to create and configure each application separately.

Setting Libraries

Copy the DRM plugin’s library files in the /lib folder of the zip file to the [WOWZA_HOME]/lib/ folder. (The numbers in the filename change depending on the version of the plugin)

- pallycon-cpix-client-java-x.x.x-jar-with-dependencies.jar
- pallycon-wowza-cpix-x.x.x.jar
- pallycon-wowza-cpix-ncg-x.x.x.jar
- pallycon-wowza-cpix-clearkey-x.x.x.jar

Note

You can remove the pallycon-wowza-cpix-ncg-x.x.x.jar, pallycon-wowza-cpix-clearkey-x.x.x.jar files and the related configuration if you don’t need NCG DRM or Clear key feature for HLS packaging.

Configuring Wowza Application

Add DRM plugin related settings by modifying /[WOWZA_HOME]/conf/[APPLICATION]/Application.xml file or using Wowza Streaming Engine Manager on a browser. Wowza application for Multi DRM (PlayReady, Widevine, FPS, WisePlay) and NCG DRM application should be separately created and set up as below.

Multi-DRM Configuration

<Modules>
    ...
    <Module>
        <!-- add property -->
        <!-- Settings for MPEG-DASH(Widevine, PlayReady, WisePlay), HLS(FairPlayStream) -->
        <Name>DrmModule</Name>
        <Descript>Multi DRM CPIX Module</Descript>
        <Class>com.pallycon.wowza.DrmModule</Class>
        <Description></Description>
    </Module>
</Modules>

Add property for Multi-DRM

<Properties>
    ...
    <!-- add property -->
    <Property>
        <Name>cupertinoEncryptionAPIBased</Name>
        <Value>true</Value>
        <Type>Boolean</Type>
    </Property>
    <Property>
        <Name>KmsUrl</Name>
        <!-- DoveRunner kms v2 url-->
        <Value>https://drm-kms.doverunner.com/v2/cpix/doverunner/getKey/{enc-token}</Value>
    </Property>
    <!-- (optional) enable WisePlay DRM  -->
    <Property>
      <Name>EnableWisePlay</Name>
      <Value>false</Value>
      <Type>Boolean</Type>
    </Property>
</Properties>

• {enc-token}: KMS token value issued to DoveRunner service account for the authentication of KMS URL (shown on DoveRunner Console site)
• EnableWisePlay: Flag to apply WisePlay DRM for DASH packaging (Default: false)

Note

To apply key rotation when packaging a live stream, you need to add the key-rotation=true parameter to the above KMS URL V2. Please refer to the example URL shown below.

https://drm-kms.doverunner.com/v2/cpix/doverunner/getKey/{enc-token}?key-rotation=true

Caution

Since a large number of DRM license requests occur when key rotation is applied, testing with a trial account may exceed the limit of trial licenses. (1,000 licenses per month) And you need to subscribe to a separate key rotation plan to use the key rotation feature on a commercial account.

FairPlay Configuration for HLS

Add property for FairPlay

Configure Wowza settings as below by referring to the Wowza guide. (https://www.wowza.com/docs/how-to-configure-apple-hls-packetization-cupertinostreaming)

...
<LiveStreamPacketizer>
    <Property>
        <Name>cupertinoChunkDurationTarget</Name>
        <Value>10000</Value>
        <Type>Integer</Type>
    </Property>
    <Property>
        <Name>cupertinoMaxChunkCount</Name>
        <Value>10</Value>
        <Type>Integer</Type>
    </Property>
    <Property>
        <Name>cupertinoPlaylistChunkCount</Name>
        <Value>3</Value>
        <Type>Integer</Type>
    </Property>
    <Property>
        <Name>cupertinoRepeaterChunkCount</Name>
        <Value>-1</Value>
        <Type>Integer</Type>
    </Property>
    <Property>
        <Name>cupertinoCalculateChunkIDBasedOnTimecode</Name>
        <Value>false</Value>
        <Type>Boolean</Type>
    </Property>
</LiveStreamPacketizer>

Add HTTPStreamer property for FairPlay

 ...
 <HTTPStreamer>
     <Properties>
         <Property>
             <Name>cupertinoExtXVersion</Name>
             <Value>5</Value>
             <Type>Integer</Type>
         </Property>
         <Property>
             <Name>cupertinoAppendQueryParamsToEncUrl</Name>
             <Value>false</Value>
             <Type>Boolean</Type>
         </Property>
     </Properties>
 </HTTPStreamer>

Session ID option for FairPlay

By default, Wowza Streaming Engine adds a streaming session ID to the encryption URI value in the HLS manifest as shown below.

sdk://content-id?wowzasessionid=30273096

For DoveRunner integration, you need to change the Wowza setting so that the session ID is not added to that value. Please set the cupertinoAppendQueryParamsToEncUrl property to false as shown in the example XML above. (reference link)

CMAF-CENC Configuration

You can configure the Wowza application as below to generate CMAF-CENC live stream with PlayReady and Widevine DRM support. If you also want to serve Apple devices, you’ll need to set up an HLS stream for FairPlay in a separate Wowza application.

Wowza does not support CMAF packaging for VoD yet.

Set LiveStreamPacketizers

Add cmafstreamingpacketizer to the property. You can add it to the prepopulated comma-separated list, or it can be the only packetizer specified. For a workflow that only delivers only CMAF streams, the XML looks like this:

<LiveStreamPacketizers>cmafstreamingpacketizer</LiveStreamPacketizers>

Set HTTPStreamers

For the HTTPStreamers property, make sure both HLS (cupertinostreaming) and MPEG-DASH (mpegdashstreaming) are specified.

<HTTPStreamers>mpegdashstreaming, cupertinostreaming</HTTPStreamers>

NCG-HLS Configuration

To integrate NCG-HLS packaging, create a separate Wowza application and set it up as shown below.

Add module for NCG-HLS packaging

<Modules>
    ...
    <Module>
        <Name>NetsyncModule</Name>
        <Descript>NCG Module V2</Descript>
        <Class>com.pallycon.wowza.ncg.NetsyncModule</Class>
        <Description></Description>
    </Module>
</Modules>

Add property for NCG-HLS packaging

<Properties>
    ...
    <!-- add property -->
    <Property>
        <Name>cupertinoEncryptionAPIBased</Name>
        <Value>true</Value>
        <Type>Boolean</Type>
    </Property>
    <Property>
        <Name>KmsUrl</Name>
        <!-- DoveRunner kms v2 url-->
        <Value>https://drm-kms.doverunner.com/v2/cpix/doverunner/getKey/{enc-token}</Value>
    </Property>
    <Property>
        <Name>SiteID</Name>
        <Value>YOUR_SITE_ID</Value>
    </Property>
    <Property>
        <Name>HLSKeyPackUrl</Name>
        <Value>https://drm-kms.doverunner.com/ncg/hlskeyPackager.do</Value>
    </Property>
</Properties>

• {enc-token}: KMS token value issued to DoveRunner service account for authentication of KMS URL (can be found on DoveRunner Console)
• SiteID: Site ID issued to your DoveRunner service account (four alphanumeric characters)
• HLSKeyPackUrl: Information to set the randomly generated key and NCG key URL when there is a problem in communication with the KMS URL

HLS Clear key Configuration

To integrate HLS Clear key packaging, create a separate Wowza application and set it up as shown below.

Add module for Clear key packaging

<Modules>
    ...
    <Module>
        <Name>ClearKeyModule</Name>
            <Descript>DOVERUNNER Clear Key Module</Descript>
            <Class>com.pallycon.wowza.clearkey.ClearKeyModule</Class>
        <Description></Description>
    </Module>
</Modules>

Add property for Clear key packaging

<Properties>
    ...
    <!-- add property -->
    <Property>
        <Name>cupertinoEncryptionAPIBased</Name>
        <Value>true</Value>
        <Type>Boolean</Type>
    </Property>
    <Property>
        <Name>KmsUrl</Name>
        <!-- DoveRunner kms v2 url-->
        <Value>https://drm-kms.doverunner.com/v2/cpix/doverunner/getKey/{enc-token}</Value>
    </Property>
    <Property>
        <Name>SiteID</Name>
        <Value>YOUR_SITE_ID</Value>
    </Property>
    <Property>
        <Name>LicenseUrl</Name>
        <Value>https://drm-license.doverunner.com/ri/clearkey/licenseManager.do</Value>
    </Property>
    <!-- (optional) Apply SAMPLE-AES instead of AES-128 as the HLS encryption method (default: false)  -->
    <Property>
      <Name>SampleAes</Name>
      <Value>false</Value>
      <Type>Boolean</Type>
    </Property>
</Properties>

• {enc-token}: KMS token value issued to DoveRunner service account for authentication of KMS URL (can be found on DoveRunner Console)
• SiteID: Site ID issued to your DoveRunner service account (four alphanumeric characters)
• LicenseUrl: Clear key licence request URL
• SampleAes: Flag for whether to set HLS Encryption method to SAMPLE-AES (Default: false)

Note

In the event of a failure in CPIX communication with the KMS URL, DRM packaging is handled with a key generated internally by the Wowza DRM plug-in instead of the CPIX response data to prevent stream playback failure or output of an unencrypted stream.

Setting Content ID (CID)

From DoveRunner Wowza DRM Plugin v2.2.0, the content ID setting function using a text-based mapping table is supported.

CID is a value used to identify content during the DRM packaging and license request/issuance process. You can input any value you want to use for CID. (up to 200 alphanumeric, hyphen, or underscore characters) Usually the content ID value managed by the CMS (Content Management System) is used.

Create CID Mapping File

Create the following text file in the path of Wowza application to apply CID mapping.

/[WOWZA_HOME]/conf/[APPLICATION_NAME]/PallyconStreamMap.txt

In the generated text file, specify the CID for each input stream as shown below.

SOURCE_NAME={"contentId" : "CID_VALUE"}

• SOURCE_NAME: The source video name of the Wowza application. In case of VOD, input the file name, in case of live stream, input the stream name (e.g. sample.mp4 or sample.stream)
• CID_VALUE: Enter a unique content ID for the stream

Note

• If you input multiple items separated by line breaks, each CID can be mapped for different input streams.

• You can use a wildcard character (*) in the SOURCE_NAME value. You can specify the same CID for all input streams by setting only *, or you can set a single CID for streams with a matching prefix, such as myStream*.

• If the CID mapping file is not set or for a stream that is not entered in the mapping file, the corresponding StreamName in the Wowza application configuration is used as the CID.

• Modifications to the CID mapping file take effect only after restarting the Wowza application.

Mapping File Settings

Add CID mapping settings to the Application.xml file of the Wowza application as follows.

<Properties>
...
  <Property>
    <Name>PallyconMapFile</Name>
    <Value>PallyconStreamMap.txt</Value>
  </Property>
</Properties>

Restarting Application and Applying HTTPS

Restart the Wowza Application after completing the settings and it will work with the set information.

Note: HTTPS must be applied to all streaming-related URLs, such as DASH (.mpd) or HLS (.m3u8) URLs. (enforced by browser)