도브러너 DRM CLI 패키져 가이드
본 문서는 도브러너 멀티 DRM 클라우드 서비스에 사용되는 CLI(Command Line Interface) 기반 콘텐츠 패키징 툴의 기본 개념과 사용 방법을 설명합니다.
콘텐츠 패키징은 아래와 같이 다섯 가지 유형이 있습니다.
DASH: MPEG-DASH CENC 규격으로 스트리밍 콘텐츠를 패키징하여 PlayReady와 Widevine Modular 또는 Huawei WisePlay DRM을 적용하는 방식HLS: HLS-AES 스트리밍 콘텐츠를 패키징하여 FPS(FairPlay Streaming) DRM을 적용하는 방식CMAF: Common Media Application Format 방식 출력으로 단일 콘텐츠에 Widevine, PlayReady, FPS DRM 적용NCG: 도브러너의 자체 규격인 NCG(Netsync Content Guard) DRM으로 콘텐츠를 암호화하여 다운로드 또는 Progressive Download용 콘텐츠로 패키징하는 방식HLS-NCG: SAMPLE-AES 방식의 클리어키 HLS 콘텐츠를 NCG DRM을 통해 보호하는 방식
본 문서는 4.1.0 버전의 DRM CLI 패키져를 기준으로 작성되었습니다. DRM CLI 패키져는 Github 저장소에서 다운받을 수 있습니다.
동영상 튜토리얼
Section titled “동영상 튜토리얼”도브러너 DRM CLI 패키져에 대한 설명과 윈도우즈 OS에서의 사용 방법에 대한 튜토리얼 영상입니다. (영문 버전)
연동 구조 및 설치 환경
Section titled “연동 구조 및 설치 환경”
도브러너 DRM CLI 패키져는 도브러너 멀티 DRM 클라우드 서버와 연동되어 동작 합니다. 도브러너 클라우드 서버는 서비스 사이트 별 콘텐츠 키 정보를 관리하며, 클라이언트에서 DRM 라이선스 정보 요청 시 CID에 연결된 키(CEK) 정보를 찾아서 라이선스를 발급합니다.
- 지원 OS: 64비트 기반의 Windows, Linux(Ubuntu, CentOS), macOS(Intel, Apple Silicon) 지원
- 리눅스 환경의 경우 gcc와 g++ 라이브러리 9.0 버전 이상이 설치되어 있어야 합니다.
- macOS 환경은 도커를 이용해 Ubuntu 빌드를 실행하는 방식으로 지원됩니다.
- 패키징 하는 디스크에 콘텐츠 크기의 최소 2배 이상의 여유 공간이 있어야 정상적으로 패키징이 진행됩니다.
- 입출력 파일 명으로는 영문, 숫자 조합만 허용됩니다.
도브러너 DRM CLI 패키져는 구글의 Shaka Packager를 기반으로 개발되었습니다. Shaka Packager에 대한 상세 설명과 문서, 소스 코드 등은 해당 Github 페이지를 참고하시기 바랍니다.
리눅스 환경에서의 패키져 실행
Section titled “리눅스 환경에서의 패키져 실행”리눅스 환경에서는 OS 배포판 및 버전에 따라 특정 버전의 라이브러리가 필요할 수 있습니다.
Ubuntu 환경
Section titled “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++-9Ubuntu 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_PATHCentOS 환경
Section titled “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_PATHmacOS 환경에서의 패키져 실행
Section titled “macOS 환경에서의 패키져 실행”DRM CLI 패키져 v3.9.0 이후 버전은 다음과 같은 방법으로 macOS 실행 환경을 지원합니다.
Dockerfile 생성: 다음과 같은 스크립트로 Dockerfile을 생성합니다.
FROM ubuntu:20.04
RUN apt updateRUN apt-get update -y && apt-get upgrade -yRUN apt-get install -y git
RUN git clone https://github.com/inka-pallycon/pallycon-drm-cli-packager.gitRUN chmod 755 /pallycon-drm-cli-packager/bin/Ubuntu/aarch64/PallyConPackager
ENTRYPOINT ["/pallycon-drm-cli-packager/bin/Ubuntu/aarch64/PallyConPackager"]Ubuntu 이미지 빌드: 생성한 Dockerfile을 이용해 Ubuntu 이미지를 빌드합니다.
docker build -t <user-name>/ubuntu-packager .패키져 커맨드 실행: 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패키져 실행 인자
Section titled “패키져 실행 인자”아래 옵션에 Shaka Packager의 명령어 옵션들을 추가로 사용할 수 있습니다.
실행 명령 형식 (기본)
Section titled “실행 명령 형식 (기본)”./PallyConPackager --enc_token value --content_id value -i value -o value (--dash || --hls || -cmaf || --ncg || --hls_ncg)명령어 옵션 목록
Section titled “명령어 옵션 목록”| Name | Type | Required | Description |
|---|---|---|---|
--enc_token | string | Y (CPIX 통신 사용 시) | 도브러너 KMS와의 CPIX API 통신에 사용되는 KMS 토큰 값. 도브러너 콘솔의 멀티 DRM > DRM 세팅 화면에서 확인 가능. |
--site_id | string | Y (기존 독자 방식 통신 사용 시) | 이전 버전의 도브러너 독자 규격 연동에 사용되는 도브러너 서비스 사이트 ID (4바이트). 도브러너 콘솔의 멀티 DRM > DRM 세팅 화면에서 확인 가능. |
--access_key | string | Y (기존 독자 방식 통신 사용 시) | 서비스 사이트에 발급되는 인증 키. site_id와 마찬가지로 도브러너 콘솔 사이트에서 확인 가능 |
--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://drm-license.doverunner.com/ri/licenseManager.do |
--generate_pssh | bool | N | 해당 옵션 적용 시 키 서버에서 생성한 PSSH 대신 패키져 자체 생성 값을 사용 |
--ascending_track_order_in_manifest | bool | N | 해당 옵션 적용 시, ABR 콘텐츠의 Manifest 내 영상 트랙들을 Bandwidth에 따라 오름차순으로 정렬. 미 적용 시 내림차순 정렬 (기본값) |
--wiseplay_drm | bool | N | 해당 옵션 적용 시 DASH 패키징에 Huawei 기기용 WisePlay DRM을 적용. 반드시 --dash 옵션과 함께 사용되어야 함. |
외부 키 사용 시 필요한 옵션
Section titled “외부 키 사용 시 필요한 옵션”도브러너 키 서버에서 생성한 암호 키를 사용하지 않고, 서비스 사이트에서 별도로 관리하는 키를 이용해 패키징하는 경우 사용하는 옵션입니다.
외부 키 사용 시에는 도브러너 키 서버와의 통신을 하지 않으므로
--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 문자열 기본 값: doverunner |
--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’이 아닌 에러 코드 값
에러 코드 설명
Section titled “에러 코드 설명”| Error Code | Description |
|---|---|
| 0 | 성공 |
| 1101 | 실행 명령어 뒤에 인자 값들이 하나도 전달되지 않았습니다. |
| 1102 | 잘못된 인자 값이 입력되었습니다. (INFO 참조 바랍니다.) |
| 1103 | 실행 명령어 다음의 인자 값의 개수가 맞지 않습니다. |
| 1201 | 파일이 지정된 경로에 위치하지 않습니다. |
| 1202 | 파일에 접근 할 수 없습니다. (권한 / 파일이름 문제) |
| 1203 | 파일/폴더의 경로가 너무 길어서 생성에 실패 하였습니다. |
| 1204 | 파일/폴더의 이름이 너무 길어서 생성에 실패 하였습니다. |
| 1205 | 저장 용량이 부족하여 파일/폴더 생성에 실패하였습니다. |
| 1206 | 파일의 해당 위치로 이동을 실패하였습니다. |
| 1207 | 파일의 크기를 얻어오는데 실패하였습니다. |
| 2001 | 서버로 요청을 보내는 중 오류가 발생하였습니다. |
| 2002 | 서버로부터 오류가 반환되었습니다. (INFO 참조 바랍니다.) |
| 2003 | 잘못된 블록 사이즈입니다. |
| 2004 | 개인 키가 없습니다. |
| 2005 | 잘못된 개인 키 입니다. |
DASH 패키징
Section titled “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-1HLS 패키징
Section titled “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-1CMAF 패키징
Section titled “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-1NCG 패키징
Section titled “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-1HLS-NCG 패키징
Section titled “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-1WisePlay 패키징
Section titled “WisePlay 패키징”Huawei 기기 지원을 위해 WisePlay DRM으로 보호되는 DASH 콘텐츠를 패키징하는 경우입니다.
./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-1Adaptive-Streaming 패키징
Section titled “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)
Section titled “외부 키 입력 (DASH, HLS)”도브러너 키 서버에서 생성하는 암호 키 대신, 서비스 사이트가 직접 관리하는 키를 이용해 멀티 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)
Section titled “외부 키 입력 (NCG, HLS-NCG)”도브러너 키 서버에서 생성하는 암호 키 대신, 서비스 사이트가 직접 관리하는 키를 이용해 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설정 파일 사용
Section titled “설정 파일 사용”입력 파라미터 중에서 고정된 설정 값들을 별도의 설정 파일로 저장해 사용하는 방법입니다.
./PallyConPackager --config_file ./config.txt --content_id test-content-1 -i ./input/test-content-1.mp4 -o ./output/test-content-1설정 파일 예제
Section titled “설정 파일 예제”-
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>
자막 패키징
Section titled “자막 패키징”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 ...멀티 키 패키징
Section titled “멀티 키 패키징”./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멀티 키 패키징 (외부 키 사용 시)
Section titled “멀티 키 패키징 (외부 키 사용 시)”./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멀티 매니페스트 생성
Section titled “멀티 매니페스트 생성”./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