트랜스코딩
TubePress가 분산 FFmpeg 워커를 사용해 업로드 파일을 웹에 최적화된 화질 버전으로 변환하는 방법을 설명합니다.
트랜스코딩은 단일 업로드 파일을 여러 웹 친화적 MP4 렌디션으로 변환하여, 시청자가 화질 메뉴와 빠른 재생 시작을 경험하고 업로드된 파일에 관계없이 일관된 코덱을 제공합니다. 또한 워터마크 및 인트로/아웃트로 클립과 같은 선택적 부가 기능을 적용하고, 플레이어가 사용하는 스크럽 미리보기 스프라이트를 생성합니다.
여기의 모든 설정은 /admin/settings?tab=transcode 아래에서 구성되며, 포맷, 대기열, 서버, 워터마크, 인트로 및 타임라인 하위 탭으로 나뉩니다. 트랜스코딩은 CMS 서버 자체에서 실행하거나 전용 워커에 분산할 수 있습니다.
트랜스코딩 이유
원본 업로드 파일은 어떤 해상도, 코덱 또는 컨테이너일 수 있습니다. 트랜스코딩은 이를 +faststart가 적용된 MP4/H.264 렌디션으로 표준화하여 파일이 완전히 다운로드되기 전에 재생이 시작되며, 예를 들어 720p 및 480p와 같이 여러 크기를 생성하여 플레이어가 화질 선택기를 제공하고 작은 화면에 더 작은 파일을 제공할 수 있습니다. 워터마크 및 프리/포스트롤 클립도 이 단계에서 각 렌디션에 인코딩됩니다.
트랜스코딩 파이프라인
비디오가 처리 준비가 되면, TubePress는 각 출력에 대해 transcode_jobs 테이블에 하나의 작업을 큐에 넣고 처리합니다:
- 대기열. 전체 해상도 소스 단계와 소스 높이 이하의 각 활성 포맷에 대한 작업이 생성되며, 미리보기가 활성화된 경우 타임라인 작업도 생성됩니다.
- 작업 수령. 워커 — 이 서버 또는 원격 서버 — 가 소스 단계부터 시작하여 다음 대기 작업을 가져갑니다.
- 다운로드. 원격 워커가 HTTP를 통해 소스를 가져옵니다(서명된 미디어 링크를 우회하는 직접 키 인증 URL).
- 트랜스코딩. FFmpeg이 설정된 대로 트림, 워터마크 및 인트로를 적용하여 렌디션을 인코딩하며, 진행률을 퍼센트로 보고합니다.
- 업로드 & 콜백. 결과가 청크 단위로 업로드되고 콜백이 작업 완료를 표시합니다.
비디오의 상태가 이를 추적합니다: 작업이 실행되는 동안 처리 중으로 유지되고, 소스 단계가 완료되면 게시됨으로 전환되며, 소스 단계를 절대 생성할 수 없는 경우에만 오류가 됩니다. 하위 렌디션은 게시 후에도 계속 채워집니다.
렌디션 & 포맷
출력 포맷은 포맷 탭에서 완전히 편집 가능하며 video_formats 테이블에 저장됩니다. 각 포맷에는 이름, 파일 접미사(예: _720p.mp4), 목표 해상도, 원시 FFmpeg 옵션, 화면 비율 유지 플래그 및 활성화 토글이 있습니다. 기본 내장 설정은 다음과 같습니다:
| 포맷 | 해상도 |
|---|---|
| 720p | 1280 × 720 |
| 480p | 854 × 480 |
| 360p | 640 × 360 |
두 가지 규칙이 품질을 유지합니다. TubePress는 업스케일하지 않습니다: 소스 높이 이상의 포맷은 건너뜁니다. 그리고 원본 최고 품질은 항상 유지됩니다 — 워터마크나 트림이 적용되는 경우 전체 해상도 소스 렌디션으로 재인코딩되며(대기열에서 별표로 표시), 그렇지 않으면 소스 파일이 그대로 제공됩니다. 트림 시작 옵션(0–300초)은 모든 비디오의 처음 몇 초를 제거할 수 있으며, 워터마크와 마찬가지로 소스를 포함한 모든 포맷에 적용됩니다.
작업 대기열
대기열 탭(/admin/settings?tab=transcode&sub=queue)은 작업을 비디오별로 그룹화하고 전체 / 대기 / 처리 중 / 완료 / 실패로 필터링할 수 있습니다. 각 비디오는 단계별 배지를 표시합니다 — 별표가 있는 소스 단계, 각 해상도, 그리고 TIMELINE — 작업 상태별로 색상이 지정됩니다:
비디오별 콘솔(터미널 아이콘)은 실시간 작업 목록, 각 단계를 처리하는 워커, 경과 시간 및 오류 메시지를 스트리밍합니다. 실패한 작업 재시도 버튼을 클릭하면 현재 실패한 모든 작업을 한 번에 다시 대기열에 넣습니다.
원격 트랜스코드 서버
트랜스코딩은 CPU를 많이 사용하므로 웹 서버에서 분리할 수 있습니다. 서버 탭에서 이 서버는 동시에 로컬로 실행되는 FFmpeg 작업 수(1–4개, 또는 원격 워커만 사용하려면 0)를 설정하고 FFmpeg 경로를 재정의할 수 있습니다. 그 아래에서 원격 워커를 등록합니다; 작업은 가장 부하가 낮은 워커에 자동으로 분산되며, 각 워커에는 최대 동시 작업 제한이 있습니다(좋은 규칙은 CPU 코어 2개당 작업 1개).
- 서버 추가. 서버 추가를 클릭하고 이름과
http://YOUR-IP:8090과 같은 URL을 입력한 다음 저장합니다. API 키와 시작 명령이 즉시 표시됩니다. - FFmpeg + PHP 설치. 워커 서버에서
sudo apt install ffmpeg php-cli php-curl을 실행합니다. - 워커 배포.
transcode-worker.php를 다운로드하고(/api/transcode-worker-download또는 임시wget링크에서), 업로드한 후sudo ufw allow 8090/tcp로 포트를 엽니다. - 시작. 키와 함께 워커를 실행합니다:
php transcode-worker.php --port=8090 --key=YOUR_API_KEY- 확인. 확인을 클릭합니다; 정상 워커는 감지된 인코더 및 실시간 CPU/GPU 사용량과 함께 온라인을 보고합니다.
GPU 가속(NVIDIA, AMD, Intel 또는 Apple)이 자동으로 감지되어 사용됩니다. 워커는 소스를 가져오고, 트랜스코딩하고, 진행률을 보고하며 결과를 청크 단위로 CMS에 업로드합니다 — 청크 업로드가 각 요청을 Cloudflare의 100 MB 제한 아래로 유지합니다. 무인 호스트의 경우 설치 가이드에 systemd 유닛이 포함되어 있어 워커가 부팅 시 재시작됩니다.
모니터링 & 재시도
시스템은 비디오가 자동으로 방치되지 않도록 구축되어 있습니다. 실패한 인코딩은 약 30초에서 몇 시간까지 점점 증가하는 대기 시간으로 자동으로 재시도됩니다 — 대부분의 실패는 일시적이기 때문입니다(느리거나 불안정한 CDN). 그 외에도 시간별 복구 작업이 여전히 실패로 표시된 작업을 다시 대기열에 넣어 렌디션이 완성될 때까지 계속 시도합니다. 수동 클릭이 필요하지 않지만, 강제로 실행하려면 실패한 작업 재시도 버튼을 사용할 수 있습니다.
소스 단계 자체가 영구적으로 실패하면, 의존하는 하위 포맷 작업이 취소되고(소스 없이 진행할 수 없음) 비디오는 오류로 표시됩니다; 복구는 여전히 이를 복원하려고 시도합니다. 소스 단계가 마침내 완료되면 비디오가 자동으로 게시됩니다.
요구 사항
FFmpeg는 트랜스코딩이 실행되는 어디서나 사용 가능해야 합니다:
- 로컬 처리: CMS 서버에 FFmpeg를 설치합니다(
sudo apt install ffmpeg). 트랜스코드 페이지에 감지된 버전이 표시됩니다. - 원격 처리: 각 워커에는 FFmpeg과
php-cli및php-curl, 최소 CPU 코어 2개 및 RAM 2 GB, 그리고 열린 워커 포트가 필요합니다.