TnP API로 Transcoding & Packaging 사용하기

DRM: —FWM: —상태: 대기 중

TnP API로 할 수 있는 일

Transcoding & Packaging(TnP) API는 DoveRunner Console에서 하는 작업을 코드나 스크립트로 실행합니다. 작업 하나로 원본 영상을 트랜스코딩하고 CMAF로 패키징하며, Multi-DRM으로 보호하고 포렌식 워터마킹용으로 전처리까지 마칩니다. 결과 스트림은 DRM 재생과 워터마크 삽입에 바로 쓸 수 있습니다.

흐름은 다섯 번의 호출입니다. 토큰 발급, 입력/출력 스토리지 등록, 작업 생성, 상태 확인, 결과 확인 순서입니다.

시작하기 전에

DoveRunner Site ID와 Access Key: DoveRunner Console에서 확인합니다.
AWS S3 버킷 두 개(입력용, 출력용)와 두 버킷을 읽고 쓸 수 있는 IAM 사용자의 액세스 키
입력 버킷에 업로드한 원본 MP4
사이트에서 DRM과 포렌식 워터마킹이 활성화되어 있어야 합니다.
curl, Postman 또는 직접 만든 코드 같은 HTTP 클라이언트

모든 호출은 https://tnp.doverunner.com/api로 보냅니다.

1. 액세스 토큰 발급

accountId:accessKey를 Base64로 인코딩해 Basic 인증 헤더로 보냅니다. Lab의 Playground > Common Tools에 있는 Base64 인코더/디코더로 인코딩할 수 있습니다.

GET /api/token/{siteId}
Authorization: Basic <base64(accountId:accessKey)>

응답의 data.token을 다른 모든 호출의 Authorization 헤더에 넣어 사용합니다.

Basic은 대문자 B로 씁니다. 일부 예제에 나오는 소문자 basic을 쓰면 401 E9001 Token value is invalid가 반환됩니다.

2. 입력/출력 스토리지 등록

버킷마다 한 번씩 POST /api/storage/{siteId}로 등록합니다. 응답으로 storage_id가 반환되며, 두 개 모두 보관해 둡니다.

필드	값
`storage_name`	스토리지 이름
`aws_bucket`	S3 버킷 이름
`io_type`	`input` 또는 `output`
`access_key_id` / `secret_key`	IAM 사용자의 액세스 키
`region`	서비스 리전 코드(`RGxxx`)
`description`	선택 사항인 설명

등록된 스토리지는 GET /api/storage/{siteId}로 조회할 수 있습니다. 입력/출력 버킷은 TnP 서비스 리전과 같은 리전에 있어야 합니다.

3. 작업 생성

POST /api/job/{siteId}로 작업을 만듭니다. 요청에는 작업 이름과 콘텐츠 ID, input 섹션, output 섹션이 들어갑니다.

{
  "job_name": "my-tutorial-job",
  "content_id": "my-content-id",
  "input": {
    "storage_id": "<input storage_id>",
    "files": [
      {
        "file_type": "multi",
        "file_path": "folder/source.mp4",
        "audios": [{ "in": { "track": 0 }, "remap": { "track": 0 } }]
      }
    ]
  },
  "output": {
    "storage_id": "<output storage_id>",
    "path": "lab-contents",
    "transcodings": [ ... ],
    "packaging": { "dash": false, "hls": false, "cmaf": true },
    "drm": { "enabled": true },
    "forensic_watermarking": { "enabled": true }
  }
}

content_id는 플레이어와 라이선스 요청에서 사용하는 ID입니다.
output.path는 Output Directory Path입니다. TnP가 그 아래에 콘텐츠 ID 폴더를 만듭니다.
audios는 원본의 오디오 트랙을 출력에 연결합니다. 이 값과 오디오 트랜스코딩의 sources가 없으면 작업이 400 E2141로 실패합니다.

트랜스코딩

transcodings에는 출력 화질(rendition)마다 항목을 하나씩 넣습니다. 비디오 항목에는 track_id, track_type, codec(h264 또는 h265), width, height, bitrate_mode, bitrate를 지정합니다. 오디오 항목에는 codec(aac), bitrate, language, sources를 지정합니다.

{ "track_id": "video1", "track_type": "video", "codec": "h264",
  "width": 1920, "height": 1080, "bitrate_mode": "cbr", "bitrate": 2500000 },
{ "track_id": "video2", "track_type": "video", "codec": "h264",
  "width": 1280, "height": 720, "bitrate_mode": "cbr", "bitrate": 1200000 },
{ "track_id": "audio1", "track_type": "audio", "codec": "aac",
  "bitrate_mode": "cbr", "bitrate": 128000, "language": "en",
  "sources": [{ "track": 0 }] }

패키징, DRM, 워터마킹

packaging.cmaf를 true로 하면 CMAF로 패키징하며, 하나의 세그먼트 세트로 Widevine, PlayReady, FairPlay를 모두 지원합니다. drm과 forensic_watermarking은 { "enabled": true }만 있으면 됩니다. 그 밖의 옵션은 선택 사항이며 DoveRunner Docs에서 확인할 수 있습니다.

요청이 성공하면 data.job_id가 반환됩니다. 실패하면 error_code와 error_message가 반환됩니다.

4. 작업 상태 확인

GET /api/job/{siteId}/{jobId}

응답의 job_status를 확인합니다. 정상적으로 진행될 때 나타나는 코드는 다음과 같습니다.

코드	상태
`TP010`	미디어 정보 확인 완료
`TP100100`	트랜스코딩 중
`TP300100`	패키징 중
`TP500`	완료

TP600은 작업 실패를 뜻합니다. 전체 코드 목록은 상태 및 오류 코드 페이지에서 볼 수 있습니다. 이 영상과 같은 작업은 몇 분 정도 걸립니다.

5. 결과 확인

상태가 TP500이 되면 출력 버킷의 wm-contents/<path>/<콘텐츠 ID>/ 아래에 결과가 저장됩니다.

wm-contents/
└── <output.path>/
    └── <콘텐츠 ID>/
        ├── 0/cmaf/   (stream.mpd, master.m3u8, video/, audio/)
        └── 1/cmaf/

0과 1은 두 가지 워터마크 버전(A/B)입니다. DoveRunner Console의 Transcoding & Packaging > Job History에서도 작업을 교차 확인할 수 있습니다. 작업이 끝나거나 실패하면 알림 이메일도 발송됩니다.

위 영상이 이런 결과물입니다. CMAF, DRM, 워터마크 버전이 포함되어 있으며 Lab의 Session URL API로 재생됩니다. 다음 단계는 워터마크 삽입입니다.