YouTube 字幕翻譯工具
下載 YouTube 影片,提取並處理字幕(校對 + 加標點 + 翻譯),然後將字幕燒錄回影片中。處理自動生成的字幕和手動上傳的字幕,並在沒有字幕時使用 ASR 作為備援。
硬性規則
- 字幕區塊處理時最多使用 3 個並行子代理。當有超過 3 個區塊時,以批次方式執行,並在一個子代理完成後才啟動下一個區塊。
- 區塊數量不等於並行數量。您可以將字幕分割成 10 個區塊,但不得同時啟動 10 個 Codex 進程/子代理;任何時候最多只能有 3 個活躍的工作者。
- 始終只下載來源字幕軌:首選英文,如果沒有英文,則使用影片的原始語言。不要下載 YouTube 提供的自動翻譯目標語言字幕;而是從來源字幕進行翻譯。
- 切勿使用 YouTube 提供的目標語言字幕軌作為捷徑,即使對於長影片也是如此,即使
automatic_captions中列出了zh-Hans或其他目標語言。 - 影片下載預設為 1080p。如果 1080p 不可用,則下載 1080p 以下的最佳可用版本。
- 翻譯必須由子代理對區塊檔案執行。請勿使用本地模型輔助程式進行翻譯。
- 在寫入 SRT/ASS 之前,從文字中移除不合法的字幕字元,尤其是那些會在影片中可見地呈現的單獨反斜線 (
\)。
工作流程概覽
第一階段:下載 → 取得影片資訊,下載影片,提取字幕
第二階段:準備 → 如果沒有字幕:提取音訊 → 執行 ASR
第三階段:處理 → 分割成區塊 → 並行代理進行校對 + 翻譯
第四階段:合併 → 合併區塊 → 生成 SRT/ASS 檔案
第五階段:渲染 → 使用 ffmpeg 將字幕燒錄到影片上
第一階段:下載
1.1 取得影片資訊
使用 YouTube MCP 工具來獲取元資料:
youtube_get_video_info(videoId="...", detail="standard")
記錄:標題、時長、頻道、是否有字幕。
1.2 建立輸出目錄
以影片標題命名目錄。為檔案系統進行清理:
mkdir -p "/output/path/<Video Title>"
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="<source-language>")
如果結果超過 token 限制,它會被儲存到工具結果檔案中 — 請分段讀取。
這是一項不可協商的來源字幕政策:
- 當可用時,優先選擇英文字幕/逐字稿。
- 如果英文不可用,則使用影片的原始口語語言。
- 忽略
zh-Hans、zh-Hant以及 YouTube 顯示的任何其他目標語言軌道,包括自動翻譯的軌道。 - 不要請求、重試、合併或渲染 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,請不要重試目標語言請求。該請求一開始就不應該被發出;改為從來源字幕繼續,並透過第三階段進行翻譯。
如果有字幕:將原始片段儲存為 JSON,並繼續進行第三階段。 如果沒有字幕(404/錯誤):繼續進行第二階段(ASR 備援)。
儲存原始資料:
raw_segments.json— 包含所有片段及其文字/偏移/時長raw_subtitles.srt— 初始 SRT 轉換
第二階段: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 輸出解析回第三階段預期的片段 JSON 格式。
第三階段:並行校對與翻譯
對於長影片來說,這是最耗時的步驟。策略:分割成區塊並使用子代理進行處理,同時對並行子代理的數量設定硬性限制為 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 錯誤,添加標點符號)
- 翻譯成自然流暢的簡體中文(保留科技術語為英文)
- 儲存為 JSON 陣列,每個片段包含
{index, start, end, en, zh} - 從
en和zh中移除不合法的字幕字元,尤其是單獨的反斜線 (\)、控制字元以及原始的 ASS 覆蓋大括號。
重要:最大並行數量為 3 個子代理/進程。如果有超過 3 個區塊,則以批次方式執行。請勿為 10 個區塊啟動 10 個 Codex 子進程。
3.3 等待完成
監控哪些 result_XX.json 檔案出現。在所有區塊完成之前,不要繼續執行。
第四階段:合併並生成輸出檔案
執行合併腳本:
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}s)')
"
如果發現任何問題,請修正它們(將 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',''))
"
第五階段:將字幕渲染到影片上
這是最棘手的部分。請勿直接使用系統 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)
- 播放第一分鐘和最後一分鐘以確認字幕出現
陷阱與經驗教訓
這些是從實際使用中得來的寶貴經驗。遵循它們可以避免浪費時間。
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...」錯誤而卡住。即使使用正確的 shell 引號也會發生。
解決方案:在傳遞給 ffmpeg 之前,將字幕檔案複製到 /tmp/subs_<pid>.ass。渲染腳本會自動執行此操作。
moviepy TextClip API 衝突(避免使用)
問題:moviepy 2.x 的 TextClip 具有位置引數和關鍵字參數之間的參數衝突(font 在內部出現兩次)。多種錯誤變體,從錯誤訊息中無法明顯看出。
建議:不要將 moviepy 用於生產環境的字幕渲染。改為使用 ffmpeg 的 ass 濾鏡 — 它更快、更可靠,並能透過 libass/fontconfig 正確處理 CJK 字型。
用於 ffmpeg 的 SRT 與 ASS
問題:ffmpeg 的 subtitles 濾鏡(直接讀取 SRT)在某些建置版本中也會遇到路徑解析問題。ass 濾鏡更可靠。
解決方案:首先使用 scripts/srt-to-ass.py 將 SRT 轉換為 ASS,然後使用 ass 濾鏡。ASS 格式還允許您精細控制字型、大小、定位和樣式。
不合法字幕字元
問題:原始或翻譯後的字幕文字可能包含單獨的反斜線 (\) 或 ASS 覆蓋字元。在 ASS 渲染中,文字反斜線可能會出現在螢幕上,或意外地與 ASS 跳脫語法互動。
解決方案:在寫入 SRT/ASS 之前清理字幕文字:
- 從使用者可見的字幕文字中移除反斜線
- 移除除正常空白之外的控制字元
- 從字幕文字中剝離原始的
{和}大括號 - 讓
srt-to-ass.py僅添加其擁有的 ASS 控制序列,例如雙語行之間的\N
並行代理處理導致的異常字幕時長
問題:在並行處理字幕區塊時(第三階段),個別代理可能會產生帶有損壞時間戳的條目 — 特別是 end 值遠大於 start(例如,時長為 2600 秒或 4800 秒,而不是約 6 秒)。這導致這些字幕行在影片的大部分時間裡保持可見,與所有其他內容重疊。
根本原因:代理在合併跨區塊邊界的碎片化 ASR 片段時,有時會錯誤分配結束時間。問題是資料層面的,而不是渲染問題 — 因此 ffmpeg 錯誤無法捕捉到它。
解決方案:三層防禦:
scripts/srt-to-ass.py自動偵測時長 > 120 秒的條目,並將其上限設為 6 秒,同時發出警告- 第四階段驗證:合併區塊後,始終掃描
(end - start) > 120秒的條目 - 渲染前檢查:在執行 ffmpeg 之前,使用 grep 檢查 ASS 檔案中可疑的長對話行
# 快速渲染前檢查:查找任何持續時間 > 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('時長檢查通過')
"
字型大小調整
問題:在高解析度 1080p+ 影片上,預設字型大小 (16-20px) 可能太小,尤其是在較小的螢幕上或從遠處觀看時。
解決方案:使用 --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自動建置 - Python 3:用於合併和轉換腳本
- yt-dlp:用於影片下載(可選,如果 MCP 工具不可用時作為備援)