PallyCon DRM CLI 패키져 가이드

개요

본 문서는 PallyCon 멀티 DRM 클라우드 서비스에 사용되는 CLI(Command Line Interface) 기반 콘텐츠 패키징 툴의 기본 개념과 사용 방법을 설명합니다.

콘텐츠 패키징은 아래와 같이 다섯 가지 유형이 있습니다.

  1. DASH : MPEG-DASH CENC 규격으로 스트리밍 콘텐츠를 패키징하여 PlayReady와 Widevine Modular DRM을 적용하는 방식
  2. HLS : HLS-AES 스트리밍 콘텐츠를 패키징하여 FPS(FairPlay Streaming) DRM을 적용하는 방식
  3. CMAF : Common Media Application Format 방식 출력으로 단일 콘텐츠에 Widevine, PlayReady, FPS DRM 적용
  4. NCG : 잉카엔트웍스의 자체 규격인 NCG(Netsync Content Guard) DRM으로 콘텐츠를 암호화하여 다운로드 또는 Progressive Download용 콘텐츠로 패키징하는 방식
  5. HLS-NCG : SAMPLE-AES 방식의 클리어키 HLS 콘텐츠를 NCG DRM을 통해 보호하는 방식

본 문서는 4.0.0 버전의 DRM CLI 패키져를 기준으로 작성되었습니다. DRM CLI 패키져는 Github 저장소에서 다운받을 수 있습니다.

PallyCon DRM CLI 패키져는 파일 기반의 온디멘드(VOD) 콘텐츠 전용 패키져입니다. 라이브 스트림 콘텐츠에 대한 DRM 패키징이 필요한 경우, Wowza, AWS Elemental 등 각종 서드파티 라이브 솔루션을 PallyCon 키 서버와 연동해 사용할 수 있습니다.

동영상 튜토리얼

PallyCon DRM CLI 패키져에 대한 설명과 윈도우즈 OS에서의 사용 방법에 대한 튜토리얼 영상입니다. (영문 버전)

연동 구조 및 설치 환경

패키징 플로우
패키징 플로우

PallyCon DRM CLI 패키져는 PallyCon 멀티 DRM 클라우드 서버와 연동되어 동작 합니다. PallyCon 클라우드 서버는 서비스 사이트 별 콘텐츠 키 정보를 관리하며, 클라이언트에서 DRM 라이선스 정보 요청 시 CID에 연결된 키(CEK) 정보를 찾아서 라이선스를 발급합니다.

  • 지원 OS: 64비트 기반의 Windows, Linux(Ubuntu, CentOS), macOS(Intel, Apple Silicon) 지원
  • 리눅스 환경의 경우 gcc와 g++ 라이브러리 9.0 버전 이상이 설치되어 있어야 합니다.
  • macOS 환경은 도커를 이용해 Ubuntu 빌드를 실행하는 방식으로 지원됩니다.
  • 패키징 하는 디스크에 콘텐츠 크기의 최소 2배 이상의 여유 공간이 있어야 정상적으로 패키징이 진행됩니다.
  • 입출력 파일 명으로는 영문, 숫자 조합만 허용됩니다.

PallyCon DRM CLI 패키져는 구글의 Shaka Packager를 기반으로 개발되었습니다. Shaka Packager에 대한 상세 설명과 문서, 소스 코드 등은 해당 Github 페이지를 참고하시기 바랍니다.

리눅스 환경에서의 패키져 실행

리눅스 환경에서는 OS 배포판 및 버전에 따라 특정 버전의 라이브러리가 필요할 수 있습니다.

Ubuntu 환경

Ubuntu 18.04 이하 버전의 경우, 더 높은 버전의 glibc 라이브러리가 필요하므로 아래와 같이 gcc/g++ 버전 9를 설치합니다.

$ 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

Ubuntu 22.04 이상 버전에서는 기본적으로 OpenSSL 버전 3.x만 설치되어 있으므로 아래와 같이 버전 1.1.x를 설치합니다.

$ 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 환경

1.16.0 버전 이상의 c-ares 라이브러리를 설치합니다.

$ 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

macOS 환경에서의 패키져 실행

DRM CLI 패키져 v3.9.0 이후 버전은 다음과 같은 방법으로 macOS 실행 환경을 지원합니다.

  1. Dockerfile 생성: 다음과 같은 스크립트로 Dockerfile을 생성합니다.
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"]
  1. Ubuntu 이미지 빌드: 생성한 Dockerfile을 이용해 Ubuntu 이미지를 빌드합니다.
docker build -t <user-name>/ubuntu-packager .
  1. 패키져 커맨드 실행: Ubuntu 컨테이너에서 다음과 같은 커맨드로 패키져를 실행합니다. (예시)
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
도커를 통해 실행할 패키져 바이너리는 해당 실행 환경(인텔 또는 애플 실리콘)에 따라 각각 x86_64 또는 aarch64 용 Ubuntu 빌드 파일을 사용해야 합니다.

패키져 실행 인자

아래 옵션에 Shaka Packager의 명령어 옵션들을 추가로 사용할 수 있습니다.

실행 명령 형식 (기본)

./PallyConPackager --enc_token value --content_id value -i value -o value (--dash || --hls || -cmaf || --ncg || --hls_ncg)
DRM CLI 패키져 v3.8.1부터는 이전 버전에서 사용하던 PallyCon 독자 규격의 키 서버 통신 방식 대신 표준 CPIX API 기반의 KMS(Key Management Server) 통신을 기본 옵션으로 지원합니다. 기존 사용자들을 위해 이전 버전과의 하위 호환성도 지원합니다. (기존과 동일한 파라미터 사용 가능) 자세한 사항은 아래 명령어 옵션 목록을 참고하시기 바랍니다.

명령어 옵션 목록

Name Type Required Description
--enc_token string Y (CPIX 통신 사용 시) PallyCon KMS와의 CPIX API 통신에 사용되는 KMS 토큰 값. PallyCon 콘솔의 멀티 DRM > DRM 세팅 화면에서 확인 가능.
--site_id string Y (기존 독자 방식 통신 사용 시) 이전 버전의 PallyCon 독자 규격 연동에 사용되는 PallyCon 서비스 사이트 ID (4바이트). PallyCon 콘솔의 멀티 DRM > DRM 세팅 화면에서 확인 가능.
--access_key string Y (기존 독자 방식 통신 사용 시) 서비스 사이트에 발급되는 인증 키. site_id와 마찬가지로 PallyCon 콘솔 사이트에서 확인 가능
--content_id string Y 패키징 대상 콘텐츠의 고유 ID. 고객사 CMS에서 관리하는 ID 값을 입력하며, 이후 클라이언트 연동 단계에서 동일한 CID를 사용해야 함. (최대 200 바이트)
--cmaf bool Y (본 옵션 및 아래 네가지 패키징 옵션 중 최소 하나 이상 필수 입력) 단일 콘텐츠로 세 가지 멀티 DRM(Widevine, PlayReady, FPS)을 지원 가능한 CMAF 패키징 수행. 다른 유형의 패키징과 동시에 처리할 수 없음.
--dash bool DASH-CENC(Widevine, PlayReady 지원) 패키징 수행
--hls bool HLS-AES (FPS 지원) 패키징 수행
--ncg bool NCG 패키징 수행
--hls_ncg bool HLS-AES (NCG) 패키징 수행, NCG DRM을 이용하여 키를 보호하는 HLS-AES 콘텐츠 생성. --dash, --hls 등 다른 유형의 패키징과 동시에 처리할 수 없음.
-i (--input_file) string Y 원본 파일명, 파일을 2개 이상 입력 시 Adaptive Streaming으로 패키징.
[추가 옵션] 입력파일명 뒤에 :{key}={value} 형태로 이어서 입력.
- :name 비디오 또는 오디오 트랙명 설정 (예 :name=1080p 또는 :name='한국어 음성') 공백, 온점(.), 언더바(_) 외 특수문자는 입력 불가
- :lang 오디오 트랙 언어코드(ISO 639-1, 영문 소문자 두자리) 설정 (예 :lang=ko)
- :video_bandwidth 비디오 트랙 bandwidth (bps 단위) 설정 (예 :video_bandwidth=5000000)
-o (--output_dir) string N Output 폴더명
기본 값: 현재 위치에 output 디렉터리 생성 (폴더 및 파일 덮어쓰기를 허용 할 경우 -f 명령어 추가)
--config_file string N Site ID, Access key와 같이 고정된 값들을 저장한 파일 주소. Json, XML 규격을 지원하며 기본은 Json (파일 확장자가 xml일 경우 xml 파싱 적용)
--clear_lead number N 영상 초반에 암호화 비활성화 구간을 적용. 기본 값: 0 (초 단위)
--skip_audio_encryption bool N 오디오 트랙 암호화 여부. 기본 값: false(오디오트랙 암호화)
--multi_key bool N 트랙 별로 각각 다른 키로 암호화(멀티키 패키징). NCG 패키징에는 적용할 수 없음.
--max_sd_height number N SD 트랙으로 패키징될 최대 해상도 설정. 기본값: 480
--max_hd_height number N HD 트랙으로 패키징될 최대 해상도 설정. 기본값: 1080
--max_uhd1_height number N UHD 트랙으로 패키징될 최대 해상도 설정. 기본값: 2160
--fragment_duration number N Fragment 간격 (초 단위)
--segment_duration number N Segment 간격 (초 단위)
--on_demand bool N DASH 패키징 Profile을 on-demand로 설정
미입력 또는 ‘N’으로 설정 시 live profile로 패키징
--output_single_file bool N HLS 패키징 출력을 fMP4 파일 형태로 출력
--mpd_filename string N DASH manifest (.mpd) 파일명
--m3u8_filename string N HLS master manifest (.m3u8) 파일명
--subtitle string N 자막 파일명
[추가 옵션] 입력파일명 뒤에 :{key}={value} 형태로 이어서 입력하며 value에 특수문자는 입력 불가.
- :name 자막 언어명 설정 (예 :name=한국어)
- :lang 자막 언어코드(ISO 639-1, 영문 소문자 두자리) 설정 (예 :lang=ko)
--mp4_subtitle bool N --subtitle 파라미터로 자막 입력 시, 출력되는 자막 형식을 Embedded MP4로 설정. 해당 파라미터 생략 시 기본 값으로 Text VTT 형식 자막이 생성됨
- :format MP4 컨테이너 내부 포맷 지정(예 :format=ttml또는 :format=vtt)
--generate_tracktype_manifests bool N 멀티키 패키징 시 트랙별 매니페스트(플레이리스트) 파일 생성. SD부터 UHD 트랙까지 포함된 어댑티브 스트림의 경우, ‘SD_ONLY’, ‘SD_HD’, ‘SD_UHD’ 세 가지 매니페스트가 생성됨.
--enable_average_bandwidth_mpd bool N MPD 파일 내 각 트랙 별 대역폭을 최대 값 대신 평균 값으로 적용 (기본: false)
--skip_pallycon_custom_info bool N 매니페스트 파일(mpd, m3u8)에 Custom Info를 추가하지 않음 (기본: false)
--stop_indicator bool N 패키징 진행 상태 표시기 숨김
--quiet bool N 패키징 로그 숨김
--license_url string N 라이선스 발급 URL. 외부키 사용 시에는 필수로 입력.
기본 값: https://license.pallycon.com/ri/licenseManager.do
--generate_pssh bool N 해당 옵션 적용 시 키 서버에서 생성한 PSSH 대신 패키져 자체 생성 값을 사용
--ascending_track_order_in_manifest bool N 해당 옵션 적용 시, ABR 콘텐츠의 Manifest 내 영상 트랙들을 Bandwidth에 따라 오름차순으로 정렬. 미 적용 시 내림차순 정렬 (기본값)

외부 키 사용 시 필요한 옵션

PallyCon 키 서버에서 생성한 암호 키를 사용하지 않고, 서비스 사이트에서 별도로 관리하는 키를 이용해 패키징하는 경우 사용하는 옵션입니다.

외부 키 사용 시에는 PallyCon 키 서버와의 통신을 하지 않으므로 --enc_token, --site_id, --access_key 등의 옵션이 사용되지 않습니다.

Name Type Required Description
--enable_raw_key_encryption bool Y External key 사용 여부
--provider string N Widevine PSSH 생성을 위한 DRM provider 문자열
기본 값: inkaentworks
--keys string Y 암호화 key 와 key ID 쌍 (각각 16바이트 HEX 문자열)
값 형식: label=:key_id=<16byte hex>:key=<16byte hex>
--ncg_cek string Y (NCG DRM 패키징 시) 32바이트 NCG 암호화 키 (HEX)
--iv string Y (HLS-FPS 패키징 시) 16바이트 초기화 벡터 (HEX)
--pssh string N PlayReady, Widevine PSSH 데이터 수동 입력

에러 코드

결과 포맷

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

RESULT: 성공이면 ‘0’, 에러가 발생한 경우는 ‘0’이 아닌 에러 코드 값

에러 코드 설명

Error Code Description
0 성공
1101 실행 명령어 뒤에 인자 값들이 하나도 전달되지 않았습니다.
1102 잘못된 인자 값이 입력되었습니다. (INFO 참조 바랍니다.)
1103 실행 명령어 다음의 인자 값의 개수가 맞지 않습니다.
1201 파일이 지정된 경로에 위치하지 않습니다.
1202 파일에 접근 할 수 없습니다. (권한 / 파일이름 문제)
1203 파일/폴더의 경로가 너무 길어서 생성에 실패 하였습니다.
1204 파일/폴더의 이름이 너무 길어서 생성에 실패 하였습니다.
1205 저장 용량이 부족하여 파일/폴더 생성에 실패하였습니다.
1206 파일의 해당 위치로 이동을 실패하였습니다.
1207 파일의 크기를 얻어오는데 실패하였습니다.
2001 서버로 요청을 보내는 중 오류가 발생하였습니다.
2002 서버로부터 오류가 반환되었습니다. (INFO 참조 바랍니다.)
2003 잘못된 블록 사이즈입니다.
2004 개인 키가 없습니다.
2005 잘못된 개인 키 입니다.

예제

입력 값 중 --enc_token (KMS 토큰) 파라미터는 --site_id--access_key의 조합으로 대체할 수 있습니다. (이전 버전 호환성 지원) 해당 값들은 PallyCon 서비스 가입 후 콘솔 사이트에서 확인할 수 있으며, 아래 예제의 입력 값들은 고객사의 PallyCon 계정에 발급된 값으로 변경하셔야 합니다.

DASH 패키징

PlayReady, Widevine DRM으로 보호되는 DASH 스트림 패키징입니다. 일반적으로 HLS 패키징과 함께 실행합니다. (--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 패키징

FairPlay Streaming DRM으로 보호되는 HLS 스트림 패키징입니다. 일반적으로 DASH 패키징과 함께 실행합니다. (--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 패키징

PlayReady, Widevine, FPS DRM으로 보호되는 CMAF 방식 스트림 패키징입니다.

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

NCG 패키징

다운로드 또는 Progressive Download 시나리오에 사용되는 NCG DRM으로 암호화된 MP4 파일 패키징입니다. (.ncg 확장자 파일 생성)

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

HLS-NCG 패키징

NCG DRM으로 clear key를 보호하는 SAMPLE-AES 방식 HLS 스트림 패키징입니다. 이 유형은 DASH 또는 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

Adaptive-Streaming 패키징

DASH 또는 HLS 패키징 시, 여러 해상도의 콘텐츠를 입력해 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

외부 키 입력 (DASH, HLS)

PallyCon 키 서버에서 생성하는 암호 키 대신, 서비스 사이트가 직접 관리하는 키를 이용해 멀티 DRM으로 패키징하는 방법입니다.

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

외부 키 입력 (NCG, HLS-NCG)

PallyCon 키 서버에서 생성하는 암호 키 대신, 서비스 사이트가 직접 관리하는 키를 이용해 NCG DRM으로 패키징하는 방법입니다.

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

설정 파일 사용

입력 파라미터 중에서 고정된 설정 값들을 별도의 설정 파일로 저장해 사용하는 방법입니다.

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

설정 파일 예제

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

자막 패키징

VTT 포맷의 외부 자막만 지원됩니다.

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

멀티 키 패키징

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

멀티 키 패키징 (외부 키 사용 시)

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

멀티 매니페스트 생성

./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 
이전
다음