Shaka Packager 연동 가이드

이 가이드에서는 DoveRunner 키 관리 서비스(KMS)와 Google의 오픈소스 미디어 패키징 도구인 Shaka Packager를 사용하여 미디어 콘텐츠를 암호화하는 방법을 설명합니다. Widevine, PlayReady, FairPlay 등 다양한 DRM 시스템을 지원합니다.

Shaka Packager vs. DRM CLI Packager

DoveRunner는 Shaka Packager에 기반한 두 가지 패키징 옵션을 제공합니다. 필요에 따라 선택하세요.

특징	Shaka Packager 연동	DRM CLI Packager
적합한 사용자	기존 Shaka 워크플로우가 있는 개발자	추가 설정 없이 빠르게 시작하려는 사용자
유연성	모든 Shaka Packager 기능 사용 가능	일반적인 사용 사례에 맞게 사전 구성됨
설정	Python 환경 및 수동 구성 필요	독립 실행형, 최소한의 설정
커스터마이징	패키징 파라미터 완전 제어	표준 시나리오를 위한 간소화된 옵션
업데이트	최신 Shaka Packager 버전 독립적으로 사용 가능	DoveRunner 호환성 검증된 관리형 릴리스

사전 요구사항

시작하기 전에 다음 항목을 준비하세요:

요구사항	세부 내용
Python	버전 3.6 이상
DoveRunner 계정	KMS 접근 권한이 있는 활성 구독
암호화 토큰	DoveRunner 콘솔에서 발급

다음 구성 요소도 다운로드해야 합니다:

DoveRunner CPIX API 클라이언트 — KMS 통신용 Python 모듈
Shaka Packager 연동 샘플 — 연동 스크립트 및 예제
Shaka Packager v3.2.0 — 미디어 패키징 바이너리

설치

연동 샘플 저장소를 클론합니다.

git clone https://github.com/doverunner/shaka-packager-integration-sample
cd shaka-packager-integration-sample

같은 디렉터리에 CPIX API 클라이언트를 클론합니다.
Terminal window
```
git clone https://github.com/doverunner/cpix-api-client.git
```
Shaka Packager 바이너리를 다운로드하여 프로젝트 디렉터리에 배치합니다.
플랫폼별 바이너리
운영체제에 맞는 바이너리를 다운로드하세요:
- Windows: packager-win-x64.exe
- macOS: packager-osx-x64
- Linux: packager-linux-x64
필요한 경우 스크립트에서 바이너리 이름을 수정하세요.

디렉터리 구조는 다음과 같아야 합니다.

shaka-packager-integration-sample/
├── cpix-api-client/
├── doverunner-integration-script.py
└── packager-win-x64.exe (또는 플랫폼에 맞는 바이너리)

사용법

다음 구문으로 연동 스크립트를 실행합니다.

python3 doverunner-integration-script.py \
  --enc_token <토큰> \
  --content_id <ID> \
  --drm_type <DRM 유형> \
  [옵션] \
  [shaka_packager_args]

필수 인자

인자	설명
`--enc_token`	CPIX API 인증을 위한 DoveRunner KMS 암호화 토큰
`--content_id`	콘텐츠의 고유 식별자. DRM 라이선스 요청 토큰에 설정된 콘텐츠 ID와 일치해야 합니다.
`--drm_type`	쉼표로 구분된 DRM 시스템 목록: `widevine`, `playready`, `fairplay`

선택 인자

인자	설명	기본값
`--encryption_scheme`	암호화 모드: `cenc`, `cbc1`, `cens`, `cbcs`	`cenc`
`--track_type`	쉼표로 구분된 트랙 유형: `all_tracks`, `audio`, `sd`, `hd`, `uhd1`, `uhd2`	`all_tracks`

Shaka Packager 인자 전달

위에 나열되지 않은 모든 인자는 Shaka Packager로 직접 전달됩니다. 사용 가능한 옵션은 Shaka Packager 문서를 참조하세요.

사용 예시

다음 예시는 H.264 영상 파일을 Widevine 및 PlayReady DRM으로 암호화하고 DASH 매니페스트를 출력합니다.

python3 doverunner-integration-script.py \
  --enc_token your-enc-token \
  --content_id movie123 \
  --drm_type widevine,playready \
  'in=h264_720p.mp4,stream=video,init_segment=output/video/init.mp4,segment_template=output/video/$Number$.m4s' \
  'in=h264_720p.mp4,stream=audio,init_segment=output/audio/init.mp4,segment_template=output/audio/$Number$.m4s' \
  --generate_static_live_mpd \
  --mpd_output output/stream.mpd \
  --clear_lead 0

이 명령어는 다음 작업을 수행합니다.

DoveRunner KMS에서 Widevine 및 PlayReady 키를 조회합니다.
비디오와 오디오 스트림을 개별적으로 암호화합니다.
output/ 디렉터리에 세그먼트 파일을 생성합니다.
output/stream.mpd 경로에 DASH 매니페스트를 생성합니다.
clear_lead를 0으로 설정하여 처음부터 모든 콘텐츠를 암호화합니다.

동작 원리

연동 스크립트를 실행하면 다음 과정이 진행됩니다.

스크립트가 암호화 토큰을 사용하여 DoveRunner KMS에 인증합니다.
CPIX API를 통해 지정된 DRM 시스템의 콘텐츠 키를 요청합니다.
스크립트가 암호화 키와 파라미터를 포함한 Shaka Packager 명령어를 구성합니다.
Shaka Packager가 패키징 작업을 실행하여 지정된 DRM으로 콘텐츠를 암호화합니다.
암호화된 출력 파일이 지정된 위치에 저장됩니다.

문제 해결

문제	해결 방법
인증 오류	`--enc_token`이 유효하고 만료되지 않았는지 확인하세요.
콘텐츠 ID 불일치	`--content_id`가 라이선스 토큰에 설정된 ID와 일치하는지 확인하세요.
바이너리를 찾을 수 없음	Shaka Packager 실행 파일이 스크립트 디렉터리에 있고 실행 권한이 있는지 확인하세요.
지원하지 않는 DRM 유형	DRM 유형이 올바르게 입력되었는지 확인하세요. `widevine`, `playready`, `fairplay`