Communitygithub.com

중영 바이링구얼 하드번인 — 뮤트 안전 출고

임의 외국어 영상을 중영 바이링구얼 컷으로, 자막을 화면에 하드번인 — 모든 플레이어/플랫폼에서 보임.

중영 바이링구얼 하드번인 — 뮤트 안전 출고란 무엇인가요?

Video Localization 3단계(하드서브 출고): tengfei0114us youtube-bilingual-hardburn. SRT+립싱크 더빙 후 중영 하드번인.

지원 대상✓Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add tengfei0114us/youtube-bilingual-hardburn

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

YouTube Bilingual Hardburn

외국어 동영상을 중-영 이중 자막 동영상으로 변환합니다. 결정론적 단계는 스크립트로 처리되며, 번역 단계는 에이전트(LLM)가 수행하며 모든 위험이 집중되는 부분입니다.

철칙: 영어 줄 하나당 중국어 줄 하나. 절대로 하나의 영어 줄을 두 개의 중국어 줄로 나누거나 (또는 두 개를 하나로 합치지) 마십시오. 각 번역 배치 후에는 verify_align.py를 실행하십시오. 한 줄이라도 어긋나면 이후의 모든 자막이 동기화에서 벗어납니다. 그리고 자막을 입힐 때까지 알아차리지 못할 것입니다.

원본에 구두점이 있는 경우와 없는 경우

  • YouTube 자동 자막(및 대부분의 ASR)에는 구두점이 거의 없습니다. → .!? 기준으로 분할하는 방식은 실패합니다(모든 내용을 하나의 큐로 압축). 이 스킬은 문자 수 제한까지 구문을 병합하여 이 문제를 해결합니다. 이것이 기본 경로입니다.
  • 원본에 이미 깔끔한 구두점이 있는 자막이 있다 하더라도 동일한 파이프라인이 여전히 작동합니다.

사전 요구 사항

  • yt-dlp(다운로드), ffmpeg(하드번), python3(스크립트). Python 패키지는 필요하지 않습니다.
  • CJK 지원 글꼴이 설치되어 있어야 합니다. macOS: PingFang SC(기본값). Linux: --font "Noto Sans CJK SC" 전달. Windows: --font "Microsoft YaHei".
  • SCRIPTS= 이 스킬의 scripts/ 디렉토리에 대한 절대 경로. 한 번 설정하고 재사용하십시오.

워크플로우

이중 자막 하드번 진행 상황:

- [ ] 1단계: 동영상 + 자막 가져오기 ⚠️ 필수
- [ ] 2단계: 자막 추출 및 읽기 가능한 줄로 재분할
- [ ] 3단계: 모든 줄 번역 (1:1) — 주의할 부분 ⚠️ 필수
- [ ] 4단계: verify_align.py == OK ⛔ 차단 (통과할 때까지 진행 불가)
- [ ] 5단계: 이중 언어 .ass 빌드 + 하나의 테스트 프레임에서 스타일 확인 ⚠️ 필수
- [ ] 6단계: 전체 동영상 하드번 (긴 인코딩) + 지점별 프레임 확인

1단계: 동영상 + 자막 가져오기 ⚠️ 필수

yt-dlp -o "%(upload_date)s_%(title)s.%(ext)s" \
  -f "bestvideo[height<=1080][ext=mp4]+bestaudio[ext=m4a]/best[height<=1080]/best" \
  --merge-output-format mp4 --write-subs --write-auto-subs --sub-langs "en" \
  --no-mtime "<URL>"
  • --write-auto-subs가 자막 파일을 생성하지 않는 경우(일부 동영상에는 자막이 없음) 먼저 오디오를 (예: whisper로) 전사하여 .vtt/.srt 파일을 만든 후 계속 진행해야 합니다.
  • 두 개의 출력 파일을 확인하십시오: VIDEO.mp4 및 VIDEO.en.vtt.

2단계: 추출 및 재분할 ⚠️

python3 "$SCRIPTS/extract_phrases.py" "VIDEO.en.vtt" > phrases.json
python3 "$SCRIPTS/merge_lines.py" phrases.json lines.json   # --max-chars 95 --gap 12

이것은 lines.json ([{start,end,en}]) 및 lines_en.txt (번호가 매겨진 idx<TAB>English 파일)을 생성합니다. lines_en.txt를 번역하십시오. 필요한 경우 나중에 조정하십시오:

  • 자막이 화면에 너무 길게 느껴지는 경우 → --max-chars를 낮추십시오 (예: 70)
  • 자연스러운 쉼표에서 끊고 싶은 경우 → --gap을 낮추십시오 (예: 2.5) — 더 많고 짧은 줄이 생성됩니다.

3단계: 모든 줄 번역 (1:1) ⚠️ 필수 — 주의할 부분

lines_en.txt를 읽으십시오 (0부터 N-1까지 번호가 매겨져 있습니다). 일반 텍스트 ZH 파일을 생성하십시오: 각 영어 행에 대해 정확히 하나의 중국어 줄, 동일한 순서로. 줄바꿈으로 구분된 텍스트를 작성하십시오 (JSON이 아님 — 중국어 따옴표는 JSON 이스케이프를 깨뜨립니다).

철칙 위반을 방지하는 규칙:

  • 하나의 행 입력 → 하나의 줄 출력. 영어 행을 독립적인 단위로 번역하십시오. 행이 문장 중간에 끊어지더라도 (ASR에서는 자주 발생합니다 — 정상입니다) 중국어도 같은 위치에서 끊어지도록 하십시오. 행 간에 내용을 흘려 "수정"하지 마십시오.
  • ~120–150행씩 배치로 작업하십시오. 각 배치 후에 파일을 작성하고 즉시 누적 결과에 대해 verify_align.py를 실행하십시오.
  • 고유 명사는 올바른 형태로 유지하십시오 (ChatGPT, OpenAI, Claude, Gemini, Grok, DeepSeek…). ASR은 이를 왜곡합니다 ("chpd"→ChatGPT, "grock"→Grok, "ha cou"→haiku) — 실제 이름으로 수정하십시오.
  • 딱딱한 번역이 아닌 자연스러운 구어체 중국어로 번역하십시오. 화자의 말투에 맞추십시오.

모든 배치 파일을 하나의 zh.txt로 연결하십시오 (EN 행당 하나의 ZH 줄, 순서대로).

4단계: verify_align.py ⛔ 차단

python3 "$SCRIPTS/verify_align.py" lines.json zh.txt
  • OK 출력 → 계속 진행하십시오.
  • MISMATCH + 나란히 비교 테이블 출력 → EN과 ZH 의미가 일치하지 않는 행을 찾으십시오. 해당 행은 분할(하나의 EN 행이 두 개의 ZH 줄이 됨) 또는 병합(두 개의 EN 행이 하나의 ZH 줄이 됨)된 것입니다. 수정(두 개의 ZH 줄을 다시 하나로 병합하거나 하나를 두 개로 분할)한 후 다시 실행하십시오. OK가 나올 때까지 진행하지 마십시오.

5단계: .ass 빌드 + 하나의 테스트 프레임에서 확인 ⚠️ 필수

python3 "$SCRIPTS/build_bilingual_ass.py" lines.json zh.txt styled.ass
# 중국어 위쪽 (흰색 44px) + 영어 아래쪽 (회색 30px), 하단 중앙.
# Linux/Windows: --font "Noto Sans CJK SC" / --font "Microsoft YaHei" 추가

긴 인코딩 전에 자막이 있는 것으로 알려진 타임스탬프에서 하나의 프레임을 렌더링하고 확인하십시오:

ffmpeg -ss 60 -i "VIDEO.mp4" -copyts -vf "ass=styled.ass" -frames:v 1 -y test_frame.png

사용자와 확인하십시오: 중국어가 올바르게 렌더링되는지 (사각형 □□□ 없음), 2단 레이아웃이 적절해 보이는지, 크기/위치가 허용 가능한지. 필요한 경우 --zh-size/--en-size/--margin/--font를 조정하고 다시 빌드하십시오. 테스트 프레임이 올바르게 보일 때까지 전체 인코딩을 시작하지 마십시오.

6단계: 전체 동영상 하드번 + 지점별 확인

ffmpeg -y -i "VIDEO.mp4" -vf "ass=styled.ass" \
  -c:v libx264 -preset fast -crf 22 -c:a copy -sn "VIDEO_中英双语.mp4"

2시간짜리 1080p 동영상은 약 15~40분이 소요됩니다. 백그라운드에서 실행하십시오. 완료되면 시작, 중간, 끝 부분에서 프레임을 캡처하여 자막이 전체적으로 동기화되어 있는지 확인하십시오:

for t in 600 3900 7200; do ffmpeg -ss $t -i "VIDEO_中英双语.mp4" -frames:v 1 -y "chk_$t.png"; done

프레임이 정렬되지 않은 것으로 보이면 lines.json+zh.txt에서 동일한 타임스탬프의 큐가 동일한 소스 행인지 다시 확인한 후 버그로 간주하십시오 (저해상도 프레임은 잘못 읽기 쉽습니다).

안티 패턴

  • 번역 중 줄 분할/병합 — 전체 동영상 동기화 불일치의 #1 원인. 항상 하나의 EN 행 = 하나의 ZH 줄입니다.
  • 번역을 JSON으로 작성 — 중국어 따옴표 “ ” 및 「」는 조용히 JSON 파싱을 깨뜨립니다. 줄바꿈으로 구분된 일반 텍스트를 사용하십시오.
  • 자막 종료 시간으로 순서 지정 — 롤링 캡션의 종료 시간은 겹칩니다. merge_lines.py는 시작 시간만 기준으로 순서를 정합니다. 종료 시간으로 재정렬하지 마십시오.
  • 테스트 프레임 건너뛰기 — 2시간을 인코딩한 후 사각형이나 잘못된 글꼴을 발견하면 전체 인코딩이 낭비됩니다.
  • 오디오 재인코딩 — -c:a copy를 사용하십시오. 비디오 트랙만 변경됩니다.
  • 자동 자막에 video-download 스킬의 이전 build_bilingual.py 사용 — 구두점을 기준으로 분할하여 전체 대본을 하나의 큐로 압축합니다. 이 스킬이 이를 대체합니다.

전달 전 체크리스트

  • verify_align.py가 OK 출력 (EN 개수 == ZH 개수) 후 .ass 빌드
  • 테스트 프레임 확인: 중국어 렌더링, □ 상자 없음, 레이아웃/크기 정확
  • 최종 mp4의 시작/중간/끝 프레임 지점별 확인 — 자막 동기화됨
  • 출력 파일 이름 명확하게 지정 (예: <title>_中英双语.mp4); 원본 동영상은 그대로 유지
  • 고유 명사 수정됨 (중국어에 "chpd"/"grock"/"ha cou" 없음)

크로스 플랫폼 (OpenAI Codex 등)

모든 스크립트는 순수 python3 + ffmpeg/yt-dlp입니다 — Claude 특정 종속성이 없습니다. Codex(또는 셸을 실행할 수 있는 모든 에이전트)에서 이 워크플로우를 실행하려면 references/codex-usage.md를 참조하십시오.

관련 스킬