MPS TSC SDK Quick Guide

공식문서: https://www.tencentcloud.com/document/product/1041

MPS의 Top Speed Codec(TSC)은 클라우드 API로만 쓰는 줄 아는 사람이 많다. 실제로는 서버 측 SDK를 직접 받아서 온프레미스나 자체 인프라에서 돌릴 수 있다. ffmpeg 바이너리에 TSC 인코더(libten264)가 통합된 형태로 배포되며, 기존 ffmpeg 워크플로우를 거의 그대로 유지하면서 비트레이트만 30~50% 줄일 수 있다.

이 글에서는 SDK를 받아서 실제로 트랜스코딩을 돌려보는 과정을 처음부터 끝까지 다룬다.

(SDK 파일은 공식 사이트에서 제공하지 않으므로, Tencent Cloud의 담당자에게 문의하여 받아야한다.)

들어가기 전에

TSC의 핵심은 "같은 화질, 적은 비트레이트"다. 일반 x264 대비 동일 VQA 스코어에서 비트레이트를 30% 이상 줄이는 게 목표이고, CPU 사용량은 거의 동일하거나 오히려 줄어든다. 클라우드 MPS API를 통해 쓸 수도 있지만, 자체 인프라에서 대량 트랜스코딩을 돌리거나, 기존 ffmpeg 파이프라인에 TSC를 끼워 넣고 싶은 경우에는 이 SDK가 필요하다.

AWS로 치면 MediaConvert의 QVBR(Quality-Defined Variable Bitrate) 모드와 비슷한 포지션이며, TSC는 별도 인코더 바이너리로 빠져 있어서 자체 인프라에서도 사용가능하다.

SDK 구성

tscsdk-8.0.tar.gz를 풀면 아래 구조가 나온다:

tscsdk-8.0/
├── bin/
│   ├── ffmpeg          ← TSC 인코더가 통합된 ffmpeg 바이너리
│   └── ffprobe
├── lib/
│   └── libtscsdk_center.so   ← TSC 코어 라이브러리
├── include/
│   └── libtscsdk.h
├── src/
│   └── libtscsdk.c    ← 자체 ffmpeg에 통합할 때 사용
└── sdk_config          ← 인증 + 내부 설정 파일

버전 확인 명령을 실행하면 아래처럼 나와야 정상이다: tscsdk version all: 'source-6582ae2-build-20260522193741-config-20260522'

사전 준비

1. 네트워크 확인

SDK는 트랜스코딩 시 Tencent Cloud API(mps.tencentcloudapi.com)와 통신한다. 인증과 라이선스 확인 용도이므로, 이 엔드포인트로의 네트워크 연결이 필수다.

curl -s -o /dev/null -w "%{http_code}" https://mps.tencentcloudapi.com

200이 아니면 방화벽이나 DNS를 확인한다.

2. Tencent Cloud 계정 준비

3. SDK 압축 해제

tar -xzf tscsdk-8.0.tar.gz
cd tscsdk-8.0

sdk_config 설정

sdk_config 파일을 열어서 인증 정보를 채운다:

vi sdk_config

수정할 필드:

필드

설명

예시

tencentcloud_id

Secret ID (36자)

AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxx

tencentcloud_key

Secret Key (32자)

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

tencentcloud_region

API 엔드포인트 리전

ap-singapore, ap-seoul 등

이 글에서 엔드포인트 리전은 ap-seoul을 사용한다.

주의: sdk_config 안에 config 필드가 있는데, 이건 인코딩 내부 동작과 인증을 제어하는 비공개 설정이다. 절대 임의로 수정하지 않는다. SDK 버전을 업데이트할 때 이 필드도 함께 바뀔 수 있으며, 프로덕션 환경에서는 바이너리, 라이브러리, sdk_config를 항상 같은 버전으로 맞춰야 한다. 버전이 어긋나면 인증 실패나 인코딩 오류가 조용히 발생한다.

트랜스코딩 실행

기본 명령어

./bin/ffmpeg -i input.mp4 \
  -vf "scale=w='if(gte(iw,ih),-2,720)':h='if(gte(iw,ih),720,-2)':flags=bicubic" \
  -c:v libten264 \
  -preset:v slower \
  -ten264-params tune=XXXX:crf=25:vbv-maxrate=2000:vbv-bufsize=4000:keyint=90:threads=4 \
  -sdk_config sdk_config \
  -movflags +faststart \
  -y output_720p.mp4

명령어를 뜯어보면:

부분

설명

-c:v libten264

TSC 인코더 지정 (일반 x264 대신)

-preset:v slower

인코딩 속도/품질 트레이드오프. 프리셋이 느릴수록 압축률 향상

tune=XXXX

특수 튜닝 프로파일 (Tencent Cloud의 커스텀 옵션을 추가한 경우, 없는 경우 제거한다.)

crf=25

품질 기준 모드. 낮을수록 고화질 (범위: 0~51)

vbv-maxrate=2000

최대 비트레이트 제한 (kbps)

vbv-bufsize=4000

VBV 버퍼 크기 (kbps)

keyint=90

키프레임 간격 (프레임 수). 30fps 기준 3초

threads=4

인코딩 스레드 수

-sdk_config sdk_config

인증 설정 파일 경로

-movflags +faststart

moov atom을 파일 앞으로. 스트리밍 재생에 필수

해상도별 권장 파라미터

출력 해상도

SCALE

CRF

MAXRATE

BUFSIZE

720p

720

25

2000

4000

480p

480

24

1000

2000

288p

288

23

500

1000

CRF 값이 해상도가 낮아질수록 줄어드는 이유는, 저해상도에서는 디테일이 적어 같은 CRF 값이라도 품질 손실이 더 눈에 띄기 때문이다. 낮은 CRF로 품질을 확보하되, maxrate로 비트레이트 상한을 잡는 구조다.

결과 비교: libx264 vs libten264

동일 소스 영상으로 x264(기본)와 ten264(TSC)를 비교한 결과다.

libx264

libten264 (TSC)

TSC 절감률

해상도

Bitrate

CPU

VQA

Bitrate

CPU

VQA

Bitrate

CPU

720p

1194 kbps

129%

4.052

781 kbps

122%

4.065

34.6%

5.4%

480p

505 kbps

70%

3.746

374 kbps

69%

3.757

25.9%

1.4%

288p

191 kbps

38%

3.123

162 kbps

38%

3.146

15.2%

0%

핵심 포인트:

  • 비트레이트 절감 15~35%, 해상도가 높을수록 절감 효과가 크다.

  • VQA 스코어는 동일하거나 오히려 TSC가 미세하게 높다. 화질을 희생하지 않는다.

  • CPU 사용량은 동일하거나 오히려 줄어든다. 인코딩이 느려지지 않는다.

테스트 환경: AWS c6a.16xlarge (AMD EPYC 7R13). VQA는 No-Reference 기반 화질 평가 모델로, 점수가 높을수록 시각적 품질이 좋다.

쉽게 말하면, 같은 서버에서 같은 시간에 같은 화질을 뽑는데 파일 크기만 30% 줄어든다. CDN 비용이 트래픽 비례인 환경에서는 이게 그대로 돈이다.

libten264 인코더 파라미터 레퍼런스

파라미터

설명

범위

preset

인코딩 속도 프리셋

0(ultrafast) ~ 9(placebo)

bitrate

ABR 모드 출력 비트레이트 (kbps)

1 ~ 2,000,000

crf

CRF 모드 품질 값. 낮을수록 고화질

0 ~ 51

vbv-maxrate

VBV 최대 비트레이트 (kbps)

1 ~ 2,000,000

vbv-bufsize

VBV 버퍼 크기 (kbps). 기본값: bitrate × 4

1 ~ 2,000,000

rc-lookahead

미리보기 프레임 수. 클수록 품질↑ 지연↑

1 ~ 250

keyint

최대 키프레임 간격 (프레임 수). 기본 256

0 ~ 100,000

threads

스레드 풀 크기. 0 = 자동 감지

0 ~ 128

라이브 환경에서는 rc-lookahead를 너무 크게 잡으면 인코딩 지연이 올라간다. VOD 트랜스코딩이면 크게 잡아도 상관없지만, 라이브면 30~60 정도가 적당하다.

테스트

위 내용 대로 서버에서 인코딩을 돌려보면,

image.png
image.png

실제 검증 환경에서 예제 명령어를 실행한 결과, libtscsdk 라이브러리 로딩, 라이선스 발급, 인코더 초기화가 모두 정상적으로 수행되었으며, 최종적으로 libten264 기반 H.264 출력 파일이 성공적으로 생성되었다.

image.png

자체 FFmpeg에 TSC 통합하기

이미 자체 빌드한 FFmpeg 환경이 있다면, SDK에서 제공하는 소스를 FFmpeg에 통합하여 TSC 인코더를 추가할 수 있다. SDK에 포함된 bin/ffmpeg를 그대로 사용하는 것이 가장 간단하지만, 실제 서비스 환경에서는 자체 빌드한 FFmpeg를 유지하는 경우가 많다.

예를 들어 서비스에서 사용하는 FFmpeg에 이미 자체 패치가 적용되어 있거나, 특정 버전으로 고정되어 있을 수 있다. 또한 커스텀 필터, 디먹서(Demuxer), 프로토콜 모듈, 하드웨어 가속 기능(NVENC, QSV 등)을 함께 사용해야 하는 경우도 있다. 이때 SDK에서 제공하는 FFmpeg 바이너리를 그대로 사용하는 대신, 기존 FFmpeg 빌드에 TSC 인코더만 추가하는 방식이 운영 측면에서 더 유리하다.

TSC SDK는 FFmpeg의 인코더 플러그인 형태로 동작한다. 내부적으로는 libtscsdk.c가 FFmpeg와 TSC 엔진 사이의 인터페이스 역할을 수행하며, 실제 인코딩은 SDK 라이브러리인 libtscsdk_center.so가 담당한다.

구조를 단순화하면 다음과 같다.

FFmpeg CLI
    ↓
libavcodec
    ↓
libtscsdk.c
    ↓
libtscsdk_center.so
    ↓
Tencent Smart Codec Engine

통합이 완료되면 기존 FFmpeg 사용 방식과 거의 동일하게 TSC 인코더를 사용할 수 있다.

ffmpeg -i input.mp4 -c:v libten264 output.mp4

또한 하나의 SDK로 여러 코덱을 동시에 지원한다.

ℹ️

AVC = libten264 , HEVC = libten265 , VVC = libten266 , AV1 = libtenav1

즉 하나의 libtscsdk.c를 추가하는 것만으로 H.264뿐 아니라 HEVC, VVC, AV1까지 동일한 방식으로 사용할 수 있다. 기존 FFmpeg 워크플로우를 크게 변경하지 않으면서 Tencent Smart Codec(TSC)을 적용할 수 있다는 점이 가장 큰 장점이다.

Step 1. Makefile에 인코더 오브젝트 추가

libavcodec/Makefile:

OBJS-$(CONFIG_LIBTEN264_ENCODER) += libtscsdk.o
OBJS-$(CONFIG_LIBTEN265_ENCODER) += libtscsdk.o
OBJS-$(CONFIG_LIBTEN266_ENCODER) += libtscsdk.o
OBJS-$(CONFIG_LIBTENAV1_ENCODER) += libtscsdk.o

Step 2. allcodecs.c에 인코더 선언 추가

libavcodec/allcodecs.c (ffmpeg-5.1.4 기준):

extern const FFCodec ff_libten264_encoder;
extern const FFCodec ff_libten265_encoder;
extern const FFCodec ff_libten266_encoder;
extern const FFCodec ff_libtenav1_encoder;

ffmpeg 버전에 따라 FFCodec 대신 AVCodec을 쓰거나 선언 형태가 다를 수 있다. ff_libx264_encoder의 패턴을 따라가면 된다.

Step 3. 소스 파일 복사

cp tscsdk-8.0/src/libtscsdk.c /path/to/ffmpeg/libavcodec/

Step 4. configure 옵션 설정

기본 (런타임 동적 로딩):

./configure \
  --extra-cflags='-I/path/to/tscsdk-8.0/include' \
  ... (기존 옵션들)

이 경우 libtscsdk_center.so는 런타임에 dlopen으로 로딩된다. 실행 시 LD_LIBRARY_PATH에 lib 경로를 넣어줘야 한다.

컴파일 타임 링킹 (선택):

./configure \
  --extra-cflags='-I/path/to/tscsdk-8.0/include -DLIBTSCSDK_DYLOAD=0' \
  --extra-ldflags='-L/path/to/tscsdk-8.0/lib' \
  --extra-libs='-ltscsdk_center' \
  ... (기존 옵션들)

export LD_LIBRARY_PATH=/path/to/tscsdk-8.0/lib:$LD_LIBRARY_PATH

Step 5. 빌드

make -j$(nproc)

빌드 후 ./ffmpeg -encoders | grep ten으로 TSC 인코더가 등록됐는지 확인한다:

V..... libten264   libten264 H.264 / AVC (codec h264)
V..... libten265   libten265 H.265 / HEVC (codec hevc)
V..... libten266   libten266 H.266 / VVC (codec vvc)
V..... libtenav1   libtenav1 AV1 (codec av1)

libten264만 있는 게 아니라 H.265, H.266/VVC, AV1까지 한 번에 들어간다. 하나의 libtscsdk.c가 4개 인코더를 모두 커버하는 구조다.

주의사항

  • sdk_config 버전 일치: bin/ffmpeg, lib/libtscsdk_center.so, sdk_config는 항상 같은 릴리즈에서 나온 것을 사용해야 한다. 하나만 구버전이면 인증 실패하거나 인코딩이 깨진다.

  • 네트워크 의존성: 트랜스코딩 시작 시 Tencent Cloud API와 통신한다. 네트워크 단절 환경에서는 동작하지 않는다.

  • Linux 전용: libtscsdk_center.so가 Linux ELF 바이너리이므로 macOS/Windows에서는 직접 실행 불가. Docker나 Linux VM에서 테스트한다.

  • config 필드 금지 수정: sdk_config의 config 필드는 인코딩 파라미터와 인증 로직을 담고 있다. 임의 수정 시 예상 불가능한 동작이 발생한다.

마치며

TSC SDK는 "클라우드 API 호출 없이 TSC 인코딩을 자체 인프라에서 돌리고 싶다"는 요구에 대한 답이다. ffmpeg 기반이라 기존 파이프라인에 끼워 넣기 쉽고, 실제 테스트 결과 x264 대비 30% 이상의 비트레이트 절감을 CPU 부하 증가 없이 달성한다.

다만 네트워크 의존성이 있다는 점은 기억해야 한다. 트랜스코딩 시작 시 라이선스 인증을 위해 Tencent Cloud API에 접속하므로, 완전히 오프라인인 환경에서는 쓸 수 없다. 그래도 매번 파일을 COS에 올렸다가 결과를 내려받는 것보다는 훨씬 빠르고 유연하다. 대량 VOD 트랜스코딩을 자체 GPU/CPU 클러스터에서 처리하면서도 TSC의 압축 효율을 누리고 싶다면, 이 SDK가 가장 현실적인 선택이다. 비용 또한 실제 클라우드에서 과금하는 것과 동일한 로직으로 (단가는 다를 수 있다.) Pay-as-you-go 과금되는 방식이기 때문에 비용효율적으로 사용할 수 있다.