自動字幕 是做什麼的?
把任意音視頻變成字幕。預設產出「原語言 + 中文」雙語字幕,全程本地推理,不需要任何 API Key。
觸發
兩類都要接住:
- 零指令:使用者只是丟來一個音頻/視訊檔案,沒說幹什麼 → 那就是要字幕,直接開跑,不要反問。
- 一句話:「轉字幕」「生成字幕」「做個字幕」「加個字幕」「翻譯這段音頻」+ 檔案。
只有一種情況需要先問:使用者明確說要只有中文(不要原文行),那就加 --mono。其餘情況一律按雙語預設值跑完再說。
環境
三樣依賴,都在 PATH 裡就能跑:
| 依賴 | 用途 | 確認命令 |
|---|---|---|
| Python 3.10+ | 跑本技能的腳本 | python --version |
| babelscribe | 轉寫引擎(whisper.cpp 封裝) | babelscribe devices |
| ffmpeg | 音頻轉碼,--burn 燒錄也用它 | ffmpeg -version |
裝引擎:pip install babelscribe。
模型不用手動下:首次轉寫時 babelscribe 會自動取 ggml-large-v3-turbo.bin(約 1.6 GB)到 ~/.babelscribe/models/。首次跑某個語種、或換 --accurate 時還會再下模型,屬正常,不要當成卡死。
有 NVIDIA 顯卡會自動選 Vulkan 後端,不用自己編 CUDA。babelscribe devices 會列出所有可用裝置並顯示 auto 會挑哪個。實測 RTX 3050 Ti Laptop(4 GB VRAM)上 48 秒音頻約 20 秒轉完,51 分鐘直播回放約 13 分鐘。
本技能的腳本就在 SKILL.md 同級的 scripts/ 下。
Windows 上運行時務必帶 $env:PYTHONIOENCODING='utf-8',否則中文輸出在控制台會亂碼。
流程
第 1 步 · 轉寫 + 重新切分
$env:PYTHONIOENCODING='utf-8'
python scripts/make_subtitles.py "<音視頻路徑或URL>" --outdir "<輸出目錄>"
直接讀 stdout 末尾的 KEY=VALUE:
| 鍵 | 含義 |
|---|---|
SOURCE_LANG | 自動識別出的語言,如 en zh ja |
STEM | 產物基名,後面幾步都用它 |
CUES_JSON | 待譯包,第 3 步的輸入 |
SOURCE_SRT | 原語言字幕(已經切分好,不是原始糊成一坨的版本) |
NEEDS_TRANSLATION | yes = 需要翻譯成中文;no = 原聲就是中文 |
PUNCTUATION_LOST | yes = 斷句品質不夠,走第 2 步 |
TRANSCRIPT_TXT | 僅當 PUNCTUATION_LOST=yes 時出現,第 2 步的輸入 |
為什麼要重新切分:whisper 的天然 segment 經常一條 7–8 秒、上百字元,直接當字幕會糊滿螢幕。腳本用詞級時間戳按標點+停頓重切成 ≤20 字(中文)/ ≤48 字元(英文)的短句。
第 2 步 · 中文/日文原聲補標點(僅當 PUNCTUATION_LOST=yes)
whisper 對中日文只零星吐標點,剩下靠停頓硬切。中文會切出「轉成文 / 字」;日文更糟——日語沒有詞間空格,whisper 的段落又首尾相接,連停頓都找不到,結果每條字幕都卡在正好 20 字處硬切,切出「申 / し訳ない」「くま / るさん」這種東西。修法是讓字幕落到真正的標點上:
- 讀
TRANSCRIPT_TXT(一整段無標點純文字)。 - 只插入標點,一個字都不要改。 包括聽起來明顯錯的字——ASR 把「機翻」聽成「擊翻」、把「詞級」聽成「自己」、把「おやすみ」聽成「おやすい」,都照原樣保留。改字會讓重新對齊失敗,標點就貼不回去了。
- 寫成
<STEM>.punct.txt(UTF-8)。 - 帶
--punct-file重跑第 1 步(會自動複用<STEM>.raw.json,秒級完成,不會重新轉寫):
python scripts/make_subtitles.py "<輸入>" --outdir "<輸出目錄>" --punct-file "<STEM>.punct.txt"
標點密度是這一步唯一真正重要的指標。 字幕上限是 20 字,所以標點必須比書面語更密:每 8~18 字就要有一個「、」或「。」。密度不夠,字幕照樣硬切——同一份 51 分鐘日語音頻實測:
| 標點密度 | 條數 | 收在標點上 |
|---|---|---|
| 不補 | 821 | 25% |
| ~32 字/標點(太稀) | 1005 | 76% |
| 8~18 字/標點 | 1081 | 98% |
「、」用在詞組邊界、助詞後的小停頓、口語換氣處——為字幕斷行服務,比書面日語用得更勤是對的,這不是把文字改壞了。另外只能用 。 、 ! ? …:「」 這類括號不在腳本的標點表裡,會被直接丟掉。
補完標點後,SOURCE_SRT 裡每條字幕都會落在標點上。若輸出 WARN: ... 對齊失敗率 NN%,說明改動了原字,回去只補標點重試。
長音頻怎麼補:51 分鐘音頻的全文有 14000+ 字,一次補不完。按 ~1500 字切塊,每塊交一個並行 agent(附前後各 200 字上下文,但只輸出本塊),最後用腳本校驗「去掉所有標點後與原文逐字元相等」再拼接。這個校驗不能省,也不能信 agent 的自述——實測 10 塊裡有 2 塊嘴上說「已逐字元校驗通過」、實際丟了字或改了字,全靠這一步抓出來。
改密度重跑很便宜:因為 raw.json 會複用,密度的試錯成本接近零。第一次補完發現只有 76% 收在標點上時,直接重補一遍就好,不要將就。
第 3 步 · 翻譯(僅當 NEEDS_TRANSLATION=yes)
讀 CUES_JSON,裡面是 {"cues": [{"id":1,"start":...,"end":...,"text":"..."}]}。
- 先通讀整段、按整句理解,再把中文分配到各條 cue 上。 逐條獨立翻譯會把跨條的一句話翻斷(比如
replacing people.單看會譯成「取代人們」而丟掉上文)。 - 每條中文控制在 16 字以內,且與這條 cue 的時長匹配(中文閱讀速度約 4–5 字/秒,1.2 秒的 cue 塞 18 個字觀眾讀不完)。
- 譯文寫成
<STEM>.zh.json,{"1": "第一條譯文", "2": "..."},id 必須與 cues 對得上。 - 術語前後一致;專有名詞保留原文或按通行譯法。
第 4 步 · 合成產物
python scripts/merge_bilingual.py "<STEM>.cues.json" "<STEM>.zh.json"
可選參數:
--mono—— 只留譯文,不疊原文(用戶要純中文字幕時)--order zh-first—— 中文放上面(預設原文在上)--burn "<視頻路徑>"—— 把雙語字幕燒進畫面,輸出<STEM>.bilingual.burned.mp4。只在用戶給了視頻、且確實需要硬字幕時才燒,燒錄很慢且不可逆。
產物:
<STEM>.bilingual.srt—— 雙語 SRT,任何播放器/平台通用<STEM>.bilingual.ass—— 中文大、原文小,適合燒錄或專業播放器
第 5 步 · 回報
跑完給一句話結論 + 關鍵數字(語言、時長、條數、產物路徑)。挑 2–3 條成品字幕貼出來讓用戶直觀看看品質。不要貼大段日誌。
常用開關
| 場景 | 參數 |
|---|---|
| 音頻嘈雜、口音重、術語多 | --accurate(換 large-v3 + beam search,慢約 2–3 倍但更準) |
| 自動識別語種出錯 | --lang zh(或 en ja th …) |
| 想要更短/更長的字幕 | --max-chars 16(中文按「字」算) |
| 影片連結 | 直接傳 URL,腳本內部走 yt-dlp |
| 換標點/換切分策略重跑 | --punct-file <檔案>(自動複用 <STEM>.raw.json,秒級)或顯式 --from-raw <STEM>.raw.json |
坑
- 不要用 babelscribe 自帶的
.srt輸出當成品——它一條就是 whisper 的一個 segment,沒有長度控制。本技能的腳本已經重切好了。 - 不要為了「順手改錯字」去動轉寫文字。要改就改翻譯那一層。
- 純音樂/靜音檔案會返回
ERROR: 轉寫結果為空,這不是 bug,如實告訴用戶。 - 長音頻(>30 分鐘)第 3 步的 cues 會很多,分批翻譯但保持 id 對應,別漏條。並行 agent 報
ok不等於檔案真的寫出來了——實測 20 個翻譯批次裡 1 個返回status: ok卻沒落盤、1 個返回 null。收尾前必須用腳本核對「每個 cue id 都有譯文」,不要信 agent 自述。 - 不要用
python -c "..."在 PowerShell 裡跑帶引號的腳本,引號會被吃掉導致SyntaxError。寫成.py檔案再跑。 - 首次跑某語種/換
--accurate會額外下載模型,耗時屬正常。
自檢
改過腳本後,用 examples/ 下的固定素材回歸:
powershell -NoProfile -ExecutionPolicy Bypass -File "examples\gen_fixtures.ps1"
python scripts/make_subtitles.py "examples\audio\zh.wav" --outdir "examples\out"
python scripts/make_subtitles.py "examples\audio\en.wav" --outdir "examples\out"
examples\zh.txt / examples\en.txt 由 Windows SAPI 念成 examples\audio\zh.wav / en.wav(需要中文語音 Microsoft Huihui Desktop,中文版 Windows 自帶)。期望值:
- 中文:未補標點 9 條、其中約 6 條末尾無標點(
PUNCTUATION_LOST=yes);按上面補標點後 10 條、全部以標點收尾 - 英文:19 條、最長 ≤48 字元