PallyCon DRM CLI Packager Guide

Overview

This document describes the basic concepts and how to use the command line interface (CLI) based content packaging tool used for the PallyCon multi-DRM cloud service.

There are five types of content packaging:

  1. DASH: A method of applying PlayReady and Widevine Modular DRM by packaging streaming contents with MPEG-DASH CENC standard.
  2. HLS: A method of applying FPS (FairPlay Streaming) DRM by packaging HLS-AES streaming contents.
  3. CMAF: Applying PlayReady, Widevine, and FairPlay DRM by packaging contents with CMAF(Common Media Application Format) type.
  4. NCG: Content encryption by Inka Entworks' proprietary NCG (Netsync Content Guard) DRM for downloading or progressive download scenario.
  5. HLS-NCG: HLS content packaging with SAMPLE-AES clear key protected by NCG DRM.

This guide is based on the 3.9.0 version of CLI packager. You can download the latest CLI packager from the Github repository.

PallyCon DRM CLI Packager is a file-based, on-demand (VOD) content-only packager. If you need DRM packaging for live stream content, you can use various third-party live solutions such as Wowza and AWS Elemental in conjunction with the PallyCon key server.

Tutorial Video

This is a tutorial video about explaining the PallyCon DRM CLI Packager and how to use it in Windows OS.

Integration architecture and supported environments

Packaging Flow
Packaging Flow

PallyCon DRM CLI Packager works in conjunction with PallyCon Multi DRM Cloud Server. PallyCon cloud server manages the content key information for each service site, and when a client requests DRM license information, it finds the key (CEK) information associated with the CID and issues a license.

  • Supported OS: Support 64 bit Windows, Linux (Ubuntu, CentOS), macOS (Intel, Apple Silicon)
  • For Linux environment, gcc and g ++ library version 7.0 or later must be installed.
  • macOS environment is supported by running Ubuntu builds using Docker.
  • Available disk space should be at least twice the size of the contents for packaging.
  • Only alphanumeric characters are allowed for input / output filenames.

PallyCon DRM CLI Packager is based on Google’s Shaka Packager. Please refer to Github page for details, documentation and source code of Shaka Packager.

Running CLI Packager on Linux

In addition to the gcc and g++ libraries, the following additional libraries are required to run the CLI packager in a Linux environment such as Ubuntu or CentOS.

Ubuntu environment

Install libc-ares-dev library as below:

$ sudo apt-get update -y 
$ sudo apt-get install -y libc-ares-dev

CentOS environment

Install c-ares library as below:

$ sudo yum makecache 
$ sudo yum -y install c-ares

Running CLI Packager on macOS

DRM CLI Packager v3.9.0 or later supports macOS environment in the following ways.

  1. Create Dockerfile: Create Dockerfile with the following script.
FROM ubuntu:18.04

RUN apt-get update -y && apt-get upgrade -y
RUN apt-get -y install libc-ares-dev

RUN mkdir packager
COPY --chmod=755 ./PallyConPackager /packager

WORKDIR /packager

ENTRYPOINT ["/packager/PallyConPackager"]
  1. Build Ubuntu Image: Build an Ubuntu image using the Dockerfile you created.
# docker build -t <user-name>/ubuntu-packager .
  1. Run packager command: Run the packager with the following example command in the Ubuntu container.
# docker run
     --name packager
     -v /Users/my/workspace/contents:/contents
     -v /Users/my/workspace/packaging-output:/packaging-output
     -it
     --rm
     <user-name>/ubuntu-packager
     -o /packaging-output -i /contents/sintel/Sintel.2010.480P.mp4 --disable_encryption --dash
Packager binaries (x86 or arm builds) to run via Docker must match the execution environment (Intel or Apple Silicon).

Packager execution parameters

You can use additional Shaka Packager commands in the command format below.

Basic command format

./PallyConPackager --enc_token value --content_id value -i value -o value (--dash || --hls || --cmaf || --ncg || --hls_ncg)
From DRM CLI Packager v3.8.1, the standard CPIX API-based KMS (Key Management Server) communication is supported as a default option instead of the PallyCon proprietary key server communication method used in the previous version. Backwards compatibility is also supported for existing users. (Same parameters as before are available) For details, refer to the list of command parameters below.

Command parameters

Name Type Required Description
--enc_token string Y (for CPIX communication) KMS token value used for CPIX API communication with PallyCon KMS. You can check it on the Multi DRM > DRM Settings screen of the PallyCon console.
--site_id string Y (for the old proprietary communication) PallyCon service site ID (4 bytes) used for the old type proprietary communication. You can check it on the Multi DRM > DRM Settings screen of the PallyCon console.
--access_key string Y (for the old proprietary communication) An authentication key issued to the service site. You can check it on the PallyCon console site the same as site_id value.
--content_id string Y Unique ID of the content being packaged. Enter the ID value managed by the customer’s CMS, and the same CID must be used in the subsequent client integration step. (Maximum 200 bytes)
--cmaf bool Y (Must input at least one of the five packaging type parameters) Perform CMAF packaging which supports three multi-DRM (Widevine, PlayReady, FPS) with a single content. Cannot be processed simultaneously with other types of packaging.
--dash bool Perform DASH-CENC(Widevine, PlayReady) packaging
--hls bool Perform HLS-AES (FPS) packaging
--ncg bool Perform NCG packaging
--hls_ncg bool Perform HLS-AES (NCG) packaging. Generate HLS-AES content to protect keys using NCG DRM. Cannot be apply with other packaging types such as --dash and --hls.
-i (--input_file) string Y Source filename. Enable adaptive streaming if two or more files are input.
[Additional options] Add after the source filename in :{key}={value} format with no special character in the value.
- :name Name of video/audio track (e.g. :name=1080p or :name='English Audio') Can input space, period, and underscore characters.
- :lang Language code(ISO 639-1, lowercase two-letter) of audio track (e.g. :lang=en)
- :video_bandwidth Video track bandwidth(bps) (e.g. :video_bandwidth=5000000)
-o (--output_dir) string N Output folder name.
Default: Create an output directory at the current location (add the -f command to allow folders and files to be overwritten)
--config_file string N Config filename with fixed options such as Site ID and access key. Json and XML standards are supported. The default is Json (xml parsing is applied if the file extension is xml)
--clear_lead number N Apply clear(unencrypted) part at the beginning of the packaged content. Default: 0 (second)
--skip_audio_encryption bool N Disable audio track encryption. Default: false(encrypt audio)
--multi_key bool N Apply multiple key sets for each track. Cannot be applied to NCG packaging.
--max_sd_height number N Max resolution to be packaged as SD track. Default: 480
--max_hd_height number N Max resolution to be packaged as HD track. Default: 1080
--max_uhd1_height number N Max resolution to be packaged as UHD track. Default: 2160
--fragment_duration number N Fragment duration (seconds)
--segment_duration number N Segment duration (seconds)
--on_demand bool N Apply on-demand profile in DASH packaging.
If omitted or ‘N’, live profile is used.
--output_single_file bool N Set HLS packaging output as fMP4 file
--mpd_filename string N Filename of DASH manifest (.mpd)
--m3u8_filename string N Filename of HLS master manifest (.m3u8)
--subtitle string N Filename of subtitles
[Additional options] Add after the subtitle filename in :{key}={value} format with no special character in the value.
- :name Name of subtitle language (e.g. :name=English)
- :lang Language code(ISO 639-1, lowercase two-letter) of subtitle (e.g. :lang=en)
--mp4_subtitle bool N When entering subtitles with the --subtitle parameter, the output subtitle format can be set to Embedded MP4 with this parameter. If the parameter is omitted, the subtitle in Text VTT format is created by default.
--generate_tracktype_manifests bool N Create multiple manifest (playlist) files for multi-key packaging. For adaptive streams containing SD to UHD tracks, three manifests are created: ‘SD_ONLY’, ‘SD_HD’, and ‘SD_UHD’.
--enable_average_bandwidth_mpd bool N Apply the bandwidth of each track in the MPD file as an average value instead of the maximum value (default: false)
--skip_pallycon_custom_info bool N Don’t input Custom Info to manifest files(mpd, m3u8) (default: false)
--stop_indicator bool N Hide packaging status indicator
--quiet bool N Hide packaging logs
--license_url string N License acquisition URL. Required when using external key.
Default: https://license.pallycon.com/ri/licenseManager.do
--generate_pssh bool N When this option is applied, the PSSH value generated by the packager itself is used instead of getting the value from the key server.
--ascending_track_order_in_manifest bool N When this option is applied, video tracks in the manifest of ABR content are sorted in ascending order according to their bandwidth. If not applied, sort in descending order (default)

Options for using external keys

This option is used when packaging with a key that is managed separately by the service site, without using the encryption key generated by PallyCon key server.

When using external keys, parameters such as --enc_token, --site_id, and --access_key are not used because it does not require communication with the PallyCon key server.

Name Type Required Description
--enable_raw_key_encryption bool Y Enable the use of external key
--provider string N DRM Provider name for Widevine PSSH
Default: inkaentworks
--keys string Y Encryption key and key ID pair (16byte HEX string)
label=:key_id=<16byte hex>:key=<16byte hex>
--ncg_cek string Y (for NCG DRM packaging) 32 bytes key for NCG DRM (HEX)
--iv string Y (for HLS-FPS packaging) 16 bytes initial vector (HEX)
--pssh string N PlayReady, Widevine PSSH data

Error code

Result format

<?xml version="1.0" encoding="UTF-8"?> 
<PallyconPackager>
    <RESULT>0</RESULT>
</PallyconPackager>

RESULT: ‘0’ if succeeded. Error code if failed.

Error codes

Error Code Description
0 Succeeded
1101 None of the argument values after the run command are passed.
1102 An invalid parameter value was entered. (Please refer to INFO.)
1103 The number of the following argument values is not correct.
1201 The file is not located in the specified path.
1202 Can not access file. (Permission / file name problem)
1203 Creation failed because the path to the file / folder is too long.
1204 Creation failed because file / folder name is too long.
1205 File / folder creation failed due to insufficient storage space.
1206 Moving to that location in the file failed.
1207 Failed to get file size.
2001 An error occurred while sending the request to the server.
2002 An error was returned from the server. (Please refer to INFO.)
2003 Invalid block size.
2004 You do not have a private key.
2005 Invalid private key.

Example

Among the input values, the --enc_token (KMS token) parameter can be replaced with a combination of --site_id and --access_key. (Backward compatibility support) You can find these values on the console site after signing up for the PallyCon service, and the input values in the example below must be changed to the values issued to your PallyCon account.

DASH packaging

PlayReady, Widevine DRM-protected DASH stream packaging. Usually run with HLS packaging. (type --dash --hls)

./PallyConPackager --enc_token YOUR-KMS-TOKEN-VALUE --content_id test-content-1 --dash -i ./input/test-content-1.mp4 -o ./output/test-content-1

HLS packaging

FairPlay Streaming DRM-protected HLS stream packaging. Usually run with DASH packaging. (type --dash --hls)

./PallyConPackager --enc_token YOUR-KMS-TOKEN-VALUE --content_id test-content-1 --hls -i ./input/test-content-1.mp4 -o ./output/test-content-1

CMAF packaging

PlayReady, Widevine, FPS DRM-protected CMAF stream packaging.

./PallyConPackager --enc_token YOUR-KMS-TOKEN-VALUE --content_id test-content-1 --cmaf -i ./input/test-content-1.mp4 -o ./output/test-content-1

HLS-NCG packaging

HLS stream packaging that protects clear keys of SAMPLE-AES with NCG DRM. This cannot be done along with other types of packaging such as DASH or HLS(FPS).

./PallyConPackager --enc_token YOUR-KMS-TOKEN-VALUE --content_id test-content-1 --hls_ncg -i ./input/test-content-1.mp4 -o ./output/test-content-1

NCG packaging

NCG DRM-encoded MP4 file packaging used for download or progressive download scenarios. (creates .ncg extension file)

./PallyConPackager --enc_token YOUR-KMS-TOKEN-VALUE --content_id test-content-1 --ncg -i ./input/test-content-1.mp4 -o ./output/test-content-1

Adaptive-Streaming packaging

For DASH or HLS packaging, you can enter content with multiple resolutions and package it for adaptive streaming.

./PallyConPackager --enc_token YOUR-KMS-TOKEN-VALUE --content_id test-content-1 --dash --hls -i ./input/test-content-1-480p.mp4 ./input/test-content-1-720p.mp4 ./input/test-content-1-1080p.mp4 -o ./output/test-content-1

Using external key (DASH, HLS)

This is a method of multi DRM packaging using the key managed by the service site instead of the encryption key generated by PallyCon key server.

./PallyConPackager --content_id test-content-1 --dash --hls --enable_raw_key_encryption --keys label=:key_id=f3c5e0361e6654b28f8049c778b23946:key=a4631a153a443df9eed0593043db7519 -i ./input/test-content-1.mp4 -o ./output/test-content-1

Using external key (NCG, HLS-NCG)

This is a method of packaging NCG DRM using the key managed by the service site instead of the encryption key generated by PallyCon key server.

./PallyConPackager --site_id SITE --content_id test-content-1 --enable_raw_key_encryption --ncg_cek a4631a153a443df9eed0593043db7519f3c5e0361e6654b28f8049c778b23946 --ncg --hls_ncg -i ./input/test-content-1.mp4 -o ./output/test-content-1

Using configuration file

It is a method to save fixed setting values among input parameters as a separate config file.

./PallyConPackager --config_file ./config.txt --content_id test-content-1 -i ./input/test-content-1.mp4 -o ./output/test-content-1

Example of config file

  • config.txt (Default = Json)

    {
        "site_id": "SITE",
        "access_key": "DgBluIlxajZpPPjSIuqS6NcknqqG7RCt"
    }
    
  • config.xml

    <?xml version="1.0" encoding="UTF-8"?>
    <config> 
    <site_id>SITE</site_id> 
    <access_key>DgBluIlxajZpPPjSIuqS6NcknqqG7RCt</access_key>
    </config>
    

Packaging subtitles

Supports external subtitles in VTT format only.

./PallyConPackager --enc_token YOUR-KMS-TOKEN-VALUE --content_id test-content-1 -i ./input/test-content-1.mp4 -o ./output/test-content-1 --dash --hls --subtitle ./input/test-content-1-en.vtt:lang=en:name=English ./input/test-content-1-ko.vtt:lang=ko:name=Korean ./input/test-content-1-fr.vtt:lang=fr:name=French ... 

Multi-key Packaging

./PallyConPackager --enc_token YOUR-KMS-TOKEN-VALUE --content_id test-content-1 -i ./input/test-content-1-720p.mp4 ./input/test-content-1-1080p.mp4 -o ./output/test-content-1 --dash --multi_key

Multi-key Packaging with external keys

./PallyConPackager --content_id test-content-1 --dash --enable_raw_key_encryption --keys label=SD:key_id=f3c5e0361e6654b28f8049c778b23946:key=a4631a153a443df9eed0593043db7519, label=HD:key_id=8f8049c778b23946f3c5e0361e6654b2:key=eed0593043db7519a4631a153a443df9, label=AUDIO:key_id=e0361e6654b28f80f3c549c778b23946:key=1a153a443df9eed0a463593043db7519 -i ./input/test-content-1-480p.mp4 ./input/test-content-1-720p.mp4 ./input/test-content-1-audio.m4a -o ./output/test-content-1

Multiple manifests for allowed track types

./PallyConPackager --site_id <site id> --access_key <access key> --content_id <content id> -o <output directory> --dash --multi_key -i <input file1> <input file2> ... --generate_tracktype_manifests
Previous
Next