YouTube 자막 번역기
YouTube 동영상을 다운로드하고, 자막을 추출 및 처리(교정+구두점+번역)한 후 동영상에 다시 굽습니다. 자동 생성 자막과 수동 업로드 자막을 모두 처리하며, 자막이 없을 경우 ASR로 대체합니다.
하드 규칙
- 자막 청크 처리를 위해 최대 3개의 동시 하위 에이전트를 사용합니다. 청크가 3개보다 많으면 웨이브 단위로 실행하고, 하나의 하위 에이전트가 완료된 후에만 다음 청크를 시작합니다.
- 청크 수는 동시 실행 수가 아닙니다. 10개의 청크로 분할할 수 있지만, 한 번에 10개의 Codex 프로세스/하위 에이전트를 시작해서는 안 됩니다. 항상 최대 3개의 활성 워커만 실행합니다.
- 항상 소스 자막 트랙만 다운로드합니다: 가능하면 영어, 그렇지 않으면 동영상의 원래 언어입니다. YouTube의 자동 번역 대상 언어 자막을 다운로드하지 말고, 소스 자막에서 번역합니다.
- 긴 동영상의 경우에도,
zh-Hans또는 다른 대상 언어가automatic_captions에 나열되어 있더라도 YouTube에서 제공하는 대상 언어 자막 트랙을 지름길로 사용하지 마십시오. - 동영상 다운로드 기본값은 1080p입니다. 1080p를 사용할 수 없으면 1080p 미만의 사용 가능한 최상의 버전을 다운로드합니다.
- 번역은 반드시 청크 파일에 대해 하위 에이전트가 수행해야 합니다. 번역에 로컬 모델 도우미를 사용하지 마십시오.
- SRT/ASS를 작성하기 전에 자막 텍스트에서 불법 문자, 특히 동영상에서 눈에 띄게 렌더링되는 잘못된 백슬래시(
\)를 제거합니다.
워크플로 개요
1단계: 다운로드 → 동영상 정보 가져오기, 동영상 다운로드, 자막 추출
2단계: 준비 → 자막이 없는 경우: 오디오 추출 → ASR 실행
3단계: 처리 → 청크로 분할 → 병렬 에이전트 교정 + 번역
4단계: 병합 → 청크 결합 → SRT/ASS 파일 생성
5단계: 렌더링 → ffmpeg를 사용하여 동영상에 자막 굽기
1단계: 다운로드
1.1 동영상 정보 가져오기
YouTube MCP 도구를 사용하여 메타데이터를 가져옵니다:
youtube_get_video_info(videoId="...", detail="standard")
기록: 제목, 길이, 채널, 자막 사용 가능 여부.
1.2 출력 디렉토리 생성
디렉토리 이름은 동영상 제목을 따릅니다. 파일 시스템에 맞게 정리합니다:
mkdir -p "/output/path/<동영상 제목>"
1.3 동영상 다운로드
youtube_download(videoId="...", outputPath="<dir>/video.mp4", quality="1080p", force=true)
yt-dlp를 사용하는 경우, 1080p를 선호하고 1080p 미만의 최상의 형식으로 대체합니다:
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]/best" --merge-output-format mp4 \
-o "<dir>/video.%(ext)s" "<url>"
1.4 소스 자막만 추출
youtube_get_transcript(videoId="...", language="<소스 언어>")
결과가 토큰 제한을 초과하면 도구 결과 파일에 저장됩니다. 청크 단위로 읽습니다.
이것은 양보할 수 없는 소스 자막 정책입니다:
- 가능하면 영어 자막/캡션을 선호합니다.
- 영어를 사용할 수 없으면 동영상의 원래 음성 언어를 사용합니다.
- YouTube에 표시된
zh-Hans,zh-Hant및 기타 모든 대상 언어 트랙(자동 번역 트랙 포함)을 무시합니다. - YouTube에서 제공하는 대상 언어 자막 트랙을 요청하거나, 재시도하거나, 병합하거나, 렌더링하지 마십시오.
- 대상 언어 자막은 소스 자막에서 하위 에이전트 번역을 통해서만 생성되어야 합니다.
도구가 en-orig, zh-Hans와 같은 목록을 반환하면 en-orig만 선택하십시오. 다운로드 명령에 zh-Hans를 포함하지 마십시오.
yt-dlp를 사용하는 경우, 소스 자막만 작성합니다:
yt-dlp --skip-download --write-auto-subs --write-subs \
--sub-langs "en.*" --sub-format srt --convert-subs srt \
-o "<dir>/video.%(ext)s" "<url>"
잘못된 실행, 실행하지 마십시오:
yt-dlp --write-auto-subs --sub-langs "en-orig,zh-Hans" ...
영어/원본 자막 다운로드는 성공했지만 대상 언어 요청이 HTTP 429로 실패한 경우, 대상 언어 요청을 재시도하지 마십시오. 해당 요청은 이루어지지 말았어야 합니다. 소스 자막에서 계속 진행하고 3단계를 통해 번역하십시오.
자막이 있는 경우: 원시 세그먼트를 JSON으로 저장하고 3단계로 진행합니다. 자막이 없는 경우 (404/오류): 2단계(ASR 대체)로 진행합니다.
원시 데이터 저장:
raw_segments.json— 텍스트/오프셋/지속 시간이 포함된 모든 세그먼트raw_subtitles.srt— 초기 SRT 변환
2단계: ASR 대체 (자막을 사용할 수 없는 경우)
동영상에 캡션이나 트랜스크립트가 없는 경우:
-
ffmpeg를 사용하여 동영상에서 오디오 추출:
ffmpeg -i video.mp4 -vn -acodec pcm_s16le -ar 16000 -ac 1 audio.wav -
ASR 실행 — 사용자가 qwen3-asr을 지정했지만 모든 whisper 호환 모델이 작동합니다:
qwen3-asr audio.wav --output-format srt > raw_subtitles.srt또는 hyperframes-media 스킬의 transcribe 명령을 통해 내장된 접근 방식을 사용합니다.
-
SRT 출력을 3단계에서 예상하는 세그먼트 JSON 형식으로 다시 구문 분석합니다.
3단계: 병렬 교정 및 번역
긴 동영상의 경우 가장 시간이 많이 걸리는 단계입니다. 전략: 청크로 분할하고 하위 에이전트로 처리하며, 동시 하위 에이전트는 최대 3개로 제한합니다.
매우 긴 동영상의 경우에도 이 단계를 수행하십시오. 길이는 YouTube의 대상 언어 자동 자막을 다운로드하거나 사용하는 이유가 아닙니다. 긴 동영상에 대한 올바른 지름길은 청킹과 3방향 하위 에이전트 동시성이며, 대상 자막을 재사용하는 것이 아닙니다.
3.1 세그먼트를 청크로 분할
scripts/merge-chunks.py의 역 논리를 사용하여 raw_segments.json을 N개의 청크 파일로 분할합니다:
# 검토/번역에 적합한 크기로 청크 분할.
n = len(segments)
chunk_count = min(10, max(1, (n + 75) // 76))
chunk_size = n // chunk_count + 1
for i in range(0, n, chunk_size):
save_chunk(i, segs[i:i+chunk_size])
chunk_00.json, chunk_01.json 등으로 저장합니다. 각각 {"chunk_id", "start_idx", "end_idx", "segments": [...]}를 포함합니다.
3.2 병렬 에이전트 실행
각 청크에 대해 백그라운드 하위 에이전트를 생성합니다. 한 번에 3개 이하의 하위 에이전트를 시작합니다. 10개의 청크가 있으면 00, 01, 02 청크를 먼저 시작합니다. 하나가 완료되면 다음 대기 중인 청크를 시작합니다. 절대 모든 10개의 청크를 한 번에 시작하지 마십시오. 각 에이전트에게 제공:
- 해당
chunk_XX.json의 경로 - 전체 사양을 위해 references/subtitle-proofreading.md를 읽으라는 지침
- 출력 경로: 동일한 디렉토리의
result_XX.json
에이전트는 다음을 수행해야 합니다:
- 청크의 모든 세그먼트 읽기
- 영어 교정(ASR 오류 수정, 구두점 추가)
- 자연스러운 간체 중국어로 번역(기술 용어는 영어 유지)
- 세그먼트당
{index, start, end, en, zh}가 포함된 JSON 배열로 저장 en및zh에서 불법 자막 문자, 특히 잘못된 백슬래시(\), 제어 문자 및 원시 ASS 재정의 중괄호를 제거합니다.
중요: 최대 동시 실행은 3개의 하위 에이전트/프로세스입니다. 청크가 3개보다 많으면 웨이브 단위로 실행하십시오. 10개의 청크에 대해 10개의 Codex 자식 프로세스를 시작하지 마십시오.
3.3 완료 대기
어떤 result_XX.json 파일이 나타나는지 모니터링합니다. 모든 청크가 완료될 때까지 진행하지 마십시오.
4단계: 병합 및 출력 파일 생성
병합 스크립트를 실행합니다:
python3 scripts/merge-chunks.py <output_dir>
이렇게 하면 모든 result_*.json 파일을 자동으로 검색하여 다음을 생성합니다:
| 파일 | 내용 |
|---|---|
final_subtitles.json | 타임스탬프별로 정렬된 병합된 JSON |
subtitles_bilingual.srt | 영어 + 중국어 줄 |
subtitles_zh.srt | 중국어만 |
subtitles_en.srt | 영어만 |
4.2 데이터 품질 검증
렌더링 전에 항상 병합된 데이터의 유효성을 검사하십시오. 병렬 에이전트 처리는 타임스탬프 손상을 일으킬 수 있습니다:
# 비정상적인 지속 시간 확인 (>120초 = 거의 확실히 손상됨)
python3 -c "
import json
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if s['end'] - s['start'] > 120]
print(f'비정상적인 지속 시간: {len(bad)} / {len(segs)}')
for s in bad: print(f' [{s[\"index\"]}] {s[\"start\"]:.1f}->{s[\"end\"]:.1f} ({s[\"end\"]-s[\"start\"]:.0f}초)')
"
발견되면 수정하고(end를 start + 6으로 제한) SRT/ASS를 다시 생성하십시오. merge-chunks.py와 srt-to-ass.py 모두 이 문제에 대한 자동 감지 및 자동 수정을 포함합니다.
출력을 확인합니다: 처음 및 마지막 몇 항목의 타임스탬프가 정확하고 텍스트를 읽을 수 있는지 확인합니다.
또한 텍스트 위생 처리를 확인합니다:
python3 -c "
import json
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if '\\\\' in s.get('en','') or '\\\\' in s.get('zh','')]
print(f'백슬래시 아티팩트: {len(bad)}')
for s in bad[:10]: print(s['index'], s.get('en',''), s.get('zh',''))
"
5단계: 동영상에 자막 렌더링
여기가 까다로운 부분입니다. 시스템 ffmpeg를 직접 사용하지 마십시오 — 아래 함정을 참조하십시오.
5.1 렌더링 스크립트 실행
bash scripts/render-subtitles.sh <video.mp4> <subtitles_bilingual.srt> [output.mp4]
스크립트가 모든 것을 처리합니다:
- libass 지원이 포함된 ARM64 네이티브 ffmpeg 감지/빌드
- 적절한 CJK 글꼴 구성으로 SRT → ASS 변환
- 특수 문자 경로 문제를 피하기 위해 파일을 /tmp로 복사
- ffmpeg의 ass 필터로 렌더링
- 출력 검증
5.2 출력 확인
다음 사항을 확인합니다:
- 출력 파일이 존재하고 10MB보다 큼(오디오 전용이 아님)
- 지속 시간이 원본 동영상과 일치함(ffprobe 사용)
- 처음과 마지막 1분을 재생하여 자막이 나타나는지 확인
함정 및 교훈
다음은 실제 사용에서 얻은 어려운 교훈입니다. 이를 따라 시간 낭비를 피하십시오.
ffmpeg 아키텍처 불일치 (매우 중요)
문제점: macOS Homebrew의 ffmpeg는 libass, libfreetype 및 fontconfig 없이 컴파일됩니다. ass, subtitles 및 drawtext 필터가 존재하지 않습니다.
더 심각한 문제: evermeet.cx의 정적 ffmpeg 빌드는 x86_64(Intel) 바이너리입니다. Apple Silicon Mac에서 Rosetta 2 에뮬레이션을 통해 약 8-10배 느리게 실행됩니다. 1.5시간 동영상은 2시간 이상 걸렸습니다.
해결책: scripts/ensure-ffmpeg.sh를 사용하십시오. 이 스크립트는 이러한 문제를 감지하고 필요한 모든 라이브러리와 함께 ARM64 네이티브 ffmpeg를 소스에서 컴파일합니다. 첫 번째 빌드는 약 5분이 걸립니다. 후속 재빌드는 즉시 수행됩니다(캐시된 오브젝트 파일).
전체 자막 지원을 위한 필수 구성 플래그:
--enable-libass --enable-libfreetype --enable-fontconfig --enable-libdav1d
AV1 디코딩 누락
문제점: 많은 최신 YouTube 동영상이 AV1(codec_name: av1)로 인코딩됩니다. --enable-libdav1d 없이 빌드된 ffmpeg는 디코딩 중 "Function not implemented" 오류와 함께 실패하여 68MB 오디오 전용 파일을 생성합니다.
해결책: ffmpeg를 빌드할 때 항상 --enable-libdav1d를 포함하십시오.
경로 특수 문자로 인한 ffmpeg 필터 중단
문제점: 동영상 또는 자막 경로에 엠 대시(—), 스마트 따옴표 또는 비ASCII 문자가 포함되면 ffmpeg의 필터 파서가 "No option name near..." 오류로 중단됩니다. 이는 적절한 셸 인용 부호를 사용하더라도 발생합니다.
해결책: ffmpeg에 전달하기 전에 자막 파일을 /tmp/subs_<pid>.ass로 복사하십시오. 렌더링 스크립트가 자동으로 이 작업을 수행합니다.
moviepy TextClip API 충돌 (사용 금지)
문제점: moviepy 2.x의 TextClip은 위치 인수와 키워드 인수 사이에 매개변수 충돌이 있습니다(font가 내부적으로 두 번 나타남). 오류 메시지에서 명확하지 않은 여러 오류 변형이 있습니다.
권장 사항: 프로덕션 자막 렌더링에 moviepy를 사용하지 마십시오. 대신 ffmpeg의 ass 필터를 사용하십시오. 더 빠르고, 더 안정적이며, libass/fontconfig를 통해 CJK 글꼴을 적절히 처리합니다.
ffmpeg용 SRT와 ASS 비교
문제점: SRT를 직접 읽는 ffmpeg의 subtitles 필터도 일부 빌드에서 경로 구문 분석 문제가 있습니다. ass 필터가 더 안정적입니다.
해결책: 먼저 scripts/srt-to-ass.py를 사용하여 SRT를 ASS로 변환한 다음 ass 필터를 사용하십시오. ASS 형식은 글꼴, 크기, 위치 및 스타일을 세밀하게 제어할 수 있습니다.
불법 자막 문자
문제점: 원시 또는 번역된 자막 텍스트에 잘못된 백슬래시(\) 또는 ASS 재정의 문자가 포함될 수 있습니다. ASS 렌더링에서 리터럴 백슬래시는 화면에 나타나거나 ASS 이스케이프 구문과 우발적으로 상호 작용할 수 있습니다.
해결책: SRT/ASS를 작성하기 전에 자막 텍스트를 정리합니다:
- 사용자에게 표시되는 자막 텍스트에서 백슬래시 제거
- 일반 공백을 제외한 제어 문자 제거
- 자막 텍스트에서 원시
{및}중괄호 제거 srt-to-ass.py가 이중 언어 줄 사이의\N과 같은 ASS 제어 시퀀스만 추가하도록 합니다.
병렬 에이전트 처리로 인한 비정상적인 자막 지속 시간
문제점: 청크 병렬 처리(3단계) 중에 개별 에이전트가 손상된 타임스탬프가 있는 항목을 생성할 수 있습니다. 특히 start보다 훨씬 큰 end 값(예: ~6초 대신 2600초 또는 4800초의 지속 시간)이 있습니다. 이로 인해 해당 자막 줄이 대부분의 동영상 동안 화면에 표시되어 다른 모든 콘텐츠와 겹칩니다.
근본 원인: 에이전트가 청크 경계를 넘어 분할된 ASR 세그먼트를 통합할 때 종료 시간을 잘못 할당하는 경우가 있습니다. 이 문제는 데이터 수준의 문제이며 렌더링 문제가 아니므로 ffmpeg 오류로 포착되지 않습니다.
해결책: 세 가지 방어 계층:
- **
scripts/srt-to-ass.py**는 지속 시간이 120초를 초과하는 항목을 자동 감지하고 경고와 함께 6초로 제한합니다. - 4단계 검증: 청크를 병합한 후 항상
(end - start) > 120초인 항목을 검사합니다. - 렌더링 전 검사: ffmpeg를 실행하기 전에 ASS 파일에서 의심스러울 정도로 긴 Dialogue 줄을 grep합니다.
# 빠른 렌더링 전 검사: 2분 이상 지속되는 자막 찾기
python3 -c "
import json, sys
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if s['end'] - s['start'] > 120]
if bad: print(f'경고: {len(bad)}개의 비정상적인 지속 시간이 발견되었습니다!'); sys.exit(1)
else: print('지속 시간 검사 통과')
"
글꼴 크기 조정
문제점: 기본 글꼴 크기(16-20px)는 고해상도 1080p+ 동영상, 특히 작은 화면에서 멀리서 볼 때 너무 작을 수 있습니다.
해결책: --font-size 플래그를 사용하여 조정하십시오. 권장 기준 크기:
- 1080p 동영상:
--font-size 24(이중 언어) 또는--font-size 28(단일 언어) - 4K 동영상:
--font-size 36이상 render-subtitles.sh스크립트는 이를srt-to-ass.py에 전달합니다.
종속성
- YouTube MCP 도구:
mcp__plugin_youtube_youtube__*(동영상 다운로드, 트랜스크립트, 정보) - ffmpeg:
scripts/ensure-ffmpeg.sh로 자동 빌드