DoveRunner DRM CLI Packager Guide

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

There are five types of content packaging:

1. DASH: A method of applying PlayReady, Widevine Modular, or Huawei WisePlay 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 DoveRunner’s 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 4.1.0 version of CLI packager. You can download the latest CLI packager from the Github repository.

Note

DoveRunner 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 DoveRunner key server.

Tutorial Video

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

Integration architecture and supported environments

DoveRunner DRM CLI Packager works in conjunction with DoveRunner Multi DRM Cloud Server. DoveRunner 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 9.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.

DoveRunner 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 Linux environments, specific versions of libraries may be required depending on the OS distribution and version.

Ubuntu environment

For Ubuntu 18.04 and earlier, because it requires a higher version of the glibc library, install gcc/g++ version 9 as below:

$ sudo apt install software-properties-common
$ sudo add-apt-repository ppa:ubuntu-toolchain-r/test
$ sudo apt update
$ sudo apt install gcc-9 g++-9
$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 700 --slave /usr/bin/g++ g++ /usr/bin/g++-7
$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-9 900 --slave /usr/bin/g++ g++ /usr/bin/g++-9

For Ubuntu version 22.04 or later, because only OpenSSL version 3.x is installed by default, install version 1.1.x as below:

$ sudo apt-get update
$ sudo apt-get install -y gcc make perl wget
$ wget https://www.openssl.org/source/openssl-1.1.1o.tar.gz
$ sudo tar -zxvf openssl-1.1.1o.tar.gz
$ cd openssl-1.1.1o
$ ./config && make
$ export LD_LIBRARY_PATH=<installed_directory_path>:$LD_LIBRARY_PATH

CentOS environment

Install the c-ares library with version 1.16.0 or later as below:

$ sudo yum c -y "Development Tools"
$ wget https://c-ares.haxx.se/download/c-ares-1.16.1.tar.gz
$ sudo tar -zxvf c-ares-1.16.1.tar.gz
$ cd c-ares-1.16.1
$ ./configure && make
$ sudo make install
$ sudo ldconfig
$ export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

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:20.04

RUN apt update
RUN apt-get update -y && apt-get upgrade -y
RUN apt-get install -y git

RUN git clone https://github.com/inka-pallycon/pallycon-drm-cli-packager.git
RUN chmod 755 /pallycon-drm-cli-packager/bin/Ubuntu/aarch64/PallyConPackager

ENTRYPOINT ["/pallycon-drm-cli-packager/bin/Ubuntu/aarch64/PallyConPackager"]

2. Build Ubuntu Image: Build an Ubuntu image using the Dockerfile you created.

docker build -t <user-name>/ubuntu-packager .

3. Run packager command: Run the packager with the following example command in the Ubuntu container.

docker run \
  -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

Note

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)

Note

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 DoveRunner 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 DoveRunner KMS. You can check it on the Multi DRM > DRM Settings screen of the DoveRunner console.
--site_id	string	Y (for the old proprietary communication)	DoveRunner 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 DoveRunner console.
--access_key	string	Y (for the old proprietary communication)	An authentication key issued to the service site. You can check it on the DoveRunner 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. - :format Internal formatting within the MP4 container(e.g. :format=ttmlor :format=vtt)
--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://drm-license.doverunner.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)
--wiseplay_drm	bool	N	Apply WisePlay DRM for Huawei devices to DASH packaging when this option is applied. Must be used with the --dash option.

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 DoveRunner 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 DoveRunner 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: doverunner
--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

Note

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 DoveRunner service, and the input values in the example below must be changed to the values issued to your DoveRunner 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

WisePlay packaging

You can use the below command to package DASH content protected by WisePlay DRM for support on Huawei devices.

./PallyConPackager --enc_token YOUR-KMS-TOKEN-VALUE --content_id test-content-1 --dash --wiseplay_drm -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 DoveRunner 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 DoveRunner 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