YouTube Bilingual Hardburn
將外語影片轉換為中英雙語硬字幕影片。確定性步驟由腳本處理;翻譯步驟由代理(LLM)執行,這是所有風險所在。
鐵律:每個英文行對應一個中文行。絕不將一個英文行分成兩個中文行(或將兩個合併成一個)。每完成一批翻譯後,立即執行 verify_align.py。單行錯位會使後續所有字幕不同步——而且直到燒錄完成後你才會發現。
原始來源有標點符號 vs. 沒有標點符號
- YouTube 自動字幕(以及大多數 ASR)幾乎沒有標點符號 → 依賴「以 .!? 分割」的方法會失敗(將所有內容合併成一個字幕提示)。此技能通過將短語合併到字元上限來解決此問題。這是默認路徑。
- 如果原始來源已經有乾淨的帶標點字幕,相同的流程仍然適用。
先決條件
yt-dlp(下載)、ffmpeg(硬燒錄)、python3(腳本)。無需 Python 套件。- 安裝了支援中日韓 (CJK) 字型的字體。macOS:
PingFang SC(預設)。Linux:傳遞--font "Noto Sans CJK SC"。Windows:--font "Microsoft YaHei"。 SCRIPTS=此技能scripts/目錄的絕對路徑。設定一次後即可重複使用。
工作流程
Bilingual Hardburn 進度:
- [ ] 步驟 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)。產生一個純文字的中文檔案:每個英文行精確對應一個中文行,順序相同。 寫入換行分隔的文字(非 JSON — 中文引號會破壞 JSON 轉義)。
防止違反鐵律的規則:
- 一個輸入行 → 一個輸出行。 將每個英文行作為獨立單元進行翻譯。如果某一行在句子中間斷開(ASR 經常如此),讓中文在同一位置斷開。不要通過跨行合併來「修正」它。
- 分批處理,每批約 120–150 行。每完成一批後,寫入其檔案並立即對累積結果執行
verify_align.py。 - 保持專有名詞的正確形式(ChatGPT、OpenAI、Claude、Gemini、Grok、DeepSeek…)。ASR 會弄錯它們("chpd"→ChatGPT、"grock"→Grok、"ha cou"→haiku)— 修正為真實名稱。
- 使用自然的中文口語,而不是僵硬的翻譯。與說話者的語氣匹配。
將所有批處理檔案串聯成一個 zh.txt(每個英文行對應一個中文行,按順序)。
步驟 4:verify_align.py ⛔ 阻斷
python3 "$SCRIPTS/verify_align.py" lines.json zh.txt
- 顯示
OK→ 繼續。 - 顯示
MISMATCH+ 並列表格 → 找到英文和中文含義不再對應的行。該行可能是拆分(一個英文行變成了兩個中文行)或合併。修正它(將兩個中文行合併回一個,或將一個拆分為兩個),然後重新執行。在得到 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
與使用者確認:中文能正確渲染(無 tofu 方塊 □□□)、雙層佈局看起來正確、大小和位置可接受。如有必要,調整 --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 中相同時間戳的字幕提示是否來自相同的原始行(低解析度幀容易誤讀)。
反模式
- 翻譯過程中拆分/合併行 — 導致完整影片不同步的第一大原因。始終保持一個英文行等於一個中文行。
- 將翻譯寫成 JSON — 中文彎引號 “ ” 和「」會默默地破壞 JSON 解析。使用換行分隔的純文字。
- 信任字幕結束時間進行排序 — 滾動字幕的結束時間重疊;
merge_lines.py僅按開始時間排序。不要按結束時間重新排序。 - 跳過測試幀 — 花費 2 小時燒錄後才發現 tofu 方塊或錯誤的字型,會浪費整個編碼過程。
- 重新編碼音訊 — 使用
-c:a copy。只有影像軌會改變。 - 對自動字幕使用來自影片下載技能的舊版
build_bilingual.py— 它會根據標點符號分割,並將整個轉錄稿合併成一個字幕提示。此技能已取代它。
交付前檢查清單
-
verify_align.py顯示OK(英文行數 == 中文行數)在建立 .ass 之前 - 測試幀已檢查:中文正確渲染,無 □ 方塊,佈局/大小正確
- 抽樣檢查最終 mp4 的開頭/中間/結尾幀 — 字幕同步
- 輸出檔案名稱清晰(例如
<標題>_中英雙語.mp4);原始影片未修改 - 專有名詞已修正(中文中無 "chpd"/"grock"/"ha cou" 殘留)
跨平台(OpenAI Codex 等)
所有腳本均為純 python3 + ffmpeg/yt-dlp — 無 Claude 特定依賴。要在 Codex(或任何支援 shell 的代理)下執行此工作流程,請載入 references/codex-usage.md。