PallyCon Wowza DRM Plugin Guide

Overview

PallyCon 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.

For more information on the Wowza Streaming Engine and a demonstration of the PallyCon Wowza Interaction SDK, please see the links below.

Wowza Streaming Engine website : https://www.wowza.com/products/streaming-engine
Wowza real time packaging demo : https://sample.pallycon.com/drm/wowza

You can download PallyCon Wowza DRM Plugin file from the Download page.

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

Requirements

Wowza Streaming Engine: 4.8.5 or later
JAVA version : JDK 9 or later

Streaming protocol and DRM support

DASH-CENC: Widevine, PlayReady DRM
HLS-SampleAES: FairPlay Streaming DRM
CMAF-DASH: Widevine, PlayReady DRM
HLS-AES128: NCG DRM

Integration Workflow

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.

Request for content playback

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

Request for package key info

Request the key information needed for real-time packaging to the PallyCon 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.

Realtime Packaging

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

DRM License Issuance

The client asks PallyCon cloud server for the key needed to play the encrypted streaming content, and PallyCon 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.

- pallycon-cpix-common-2.1.0-jar-with-dependencies.jar
- pallycon-wowza-cpix-1.3.0.jar
- pallycon-wowza-cpix-ncg-1.0.0.jar

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) and NCG DRM application should be separately created and set up as below.

Multi-DRM Configuration

For multi-DRM packaging, set the Wowza Application as follows.

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>

By default, Wowza Streaming Engine adds a streaming session ID to the encryption URI value in the HLS manifest. 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 above example.

Add module for Multi-DRM

<Modules>
    ...
    <Module>
        <!-- add property -->
        <!-- Settings for MPEG-DASH(Widevine, PlayReady), 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>
        <!-- pallycon kms v2 url-->
        <Value>https://kms.pallycon.com/v2/cpix/pallycon/getKey</Value>
    </Property>
    <Property>
        <!-- true : live key rotation / false : single key -->
        <Name>KeyRotation</Name>
        <Value>false</Value>
    </Property>
    <Property>
        <Name>PallyConEncToken</Name>
        <Value>YOUR_KMS_TOKEN</Value>
    </Property>
</Properties>

KeyRotation: Set whether to apply the key rotation function that periodically changes the encryption key during live stream packaging (true: enable key rotation)
PallyConEncToken: KMS token value issued to PallyCon service account for the authentication of KMS URL (shown on PallyCon Console site)

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.

NCG-HLS Configuration

For NCG-HLS packaging, set the Wowza Application as follows.

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>
        <!-- pallycon kms v2 url-->
        <Value>https://kms.pallycon.com/v2/cpix/pallycon/getKey</Value>
    </Property>
    <Property>
        <!-- true : live key rotation / false : single key -->
        <Name>KeyRotation</Name>
        <Value>false</Value>
    </Property>
    <Property>
        <Name>PallyConEncToken</Name>
        <Value>YOUR_KMS_TOKEN</Value>
    </Property>
    <Property>
        <Name>SiteID</Name>
        <Value>YOUR_SITE_ID</Value>
    </Property>
    <Property>
        <Name>HLSKeyPackUrl</Name>
        <Value>https://kms.pallycon.com/ncg/hlskeyPackager.do</Value>
    </Property>
</Properties>

KeyRotation: Set whether to apply the key rotation function that periodically changes the encryption key during live stream packaging (true: enable key rotation)
PallyConEncToken: KMS token value issued to PallyCon service account for authentication of KMS URL (can be found on PallyCon Console)
SiteID: Site ID issued to your PallyCon 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

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 PallyCon 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

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)

Last updated on Apr 7, 2023