---
title: "Shaka Packager 연동 가이드"
description: "DoveRunner Multi-DRM과 Google Shaka Packager를 연동하여 Widevine, PlayReady, FairPlay DRM으로 미디어 콘텐츠를 암호화하는 방법을 안내합니다."
---
> For the complete documentation index, see [llms.txt](/llms.txt).

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

## Shaka Packager vs. DRM CLI Packager

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

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

:::tip[어떤 것을 선택해야 할까요?]
고급 Shaka 기능이 필요하거나 기존 인코딩 파이프라인이 있다면 본 가이드의 **Shaka Packager 연동**을 사용하세요. DoveRunner Multi-DRM과 바로 연동되는 턴키 솔루션을 원한다면 [**DRM CLI Packager**](/ko/content-security/multi-drm/packaging/cli-packager/)를 사용하세요.
:::

## 사전 요구사항

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

| 요구사항 | 세부 내용 |
|----------|-----------|
| Python | 버전 3.6 이상 |
| DoveRunner 계정 | KMS 접근 권한이 있는 활성 구독 |
| 암호화 토큰 | [DoveRunner 콘솔](https://console.doverunner.com)에서 발급 |

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

- [DoveRunner CPIX API 클라이언트](https://github.com/doverunner/cpix-api-client) — KMS 통신용 Python 모듈
- [Shaka Packager 연동 샘플](https://github.com/doverunner/shaka-packager-integration-sample) — 연동 스크립트 및 예제
- [Shaka Packager v3.2.0](https://github.com/shaka-project/shaka-packager/releases/tag/v3.2.0) — 미디어 패키징 바이너리

:::note[호환성 안내]
이 가이드는 Shaka Packager v3.2.0에서 테스트되었습니다. 이후 버전에서도 동작할 수 있으나 호환성을 보장하지는 않습니다. 호환성 관련 문의는 [지원 티켓을 생성](https://support.doverunner.com)해 주세요.
:::

## 설치

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

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

2. **같은 디렉터리에 CPIX API 클라이언트를 클론합니다.**

   ```bash
   git clone https://github.com/doverunner/cpix-api-client.git
   ```

3. **Shaka Packager 바이너리를 다운로드**하여 프로젝트 디렉터리에 배치합니다.

   :::tip[플랫폼별 바이너리]
   운영체제에 맞는 바이너리를 다운로드하세요:
   - **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 (또는 플랫폼에 맞는 바이너리)
```

## 사용법

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

```bash
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 문서](https://shaka-project.github.io/shaka-packager/html/)를 참조하세요.

## 사용 예시

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

```bash
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으로 설정하여 처음부터 모든 콘텐츠를 암호화합니다.

## 동작 원리

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

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

## 문제 해결

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

## 관련 문서

- [CPIX API 레퍼런스](/ko/content-security/multi-drm/packaging/cpix-api/) — DoveRunner 키 관리 API 문서
- [DoveRunner CPIX API 클라이언트](https://github.com/doverunner/cpix-api-client) — Python 클라이언트 라이브러리 소스 코드
- [Shaka Packager 문서](https://shaka-project.github.io/shaka-packager/html/) — 공식 Shaka Packager 문서