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.

You can download PallyCon 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.8.21 or later
  • JAVA version : Open JDK 11 or later

Streaming protocol and DRM support

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

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.
  1. Request for content playback
  • The client (HTML5 player or mobile application) requests streaming playback via a DASH (mpd) or HLS (m3u8) streaming URL.
  1. 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.
  1. Realtime Packaging
  • Package the original content in DASH or HLS format using the key information received from PallyCon cloud.
  1. 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. (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
You can remove the pallycon-wowza-cpix-ncg-x.x.x.jar file and the related configuration if you don’t need NCG DRM 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) 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), 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.

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

Previous
Next