Communitygithub.com

自動字幕

將任何音頻或視訊檔案離線轉換為字幕,支援 99 種語言自動偵測、精準轉寫、重新分段、中譯,並輸出雙語 SRT/ASS 字幕,甚至可燒錄到影片中。

自動字幕 是什麼?

此技能(hangzhouspark/dsh-auto-subtitle)讓開發者或 AI agent 能將使用者提供的音頻或視訊檔案(如 mp3, wav, mp4, mkv 等),完全在本地機器上離線生成雙語字幕(原語言 + 中文)。它透過 babelscribe(whisper.cpp 封裝)進行自動語言偵測(支援 99 種語言)與字詞級時間戳轉寫,然後利用自訂腳本將過長或破碎的字幕段落重新分割為易讀的短句(中文 ≤20 字、英文 ≤48 字)。對於中文、日文等缺乏標點符號的語言,它會自動插入標點(句號、逗號等)以確保每條字幕結尾落在正確標點上,並透過分段校驗機制防止文本改動。接著,若有需要,它會將原文翻譯成中文,並注意跨行語意連貫與閱讀速度匹配。最後合併為雙語 SRT/ASS 字幕,或選擇將字幕燒錄到影片中。此技能支援 Windows 環境(需設定 UTF-8 編碼),依賴 Python 3.10+、babelscribe 與 ffmpeg,且 GPU 加速(Vulkan)自動啟用。典型使用情境包括使用者上傳音視頻檔案時未附指令(預設就是要字幕)或主動要求「轉字幕」、「加字幕」、「翻譯這段音頻」。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add hangzhouspark/dsh-auto-subtitle

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

自動字幕 是做什麼的?

把任意音視頻變成字幕。預設產出「原語言 + 中文」雙語字幕,全程本地推理,不需要任何 API Key。

觸發

兩類都要接住:

  1. 零指令:使用者只是丟來一個音頻/視訊檔案,沒說幹什麼 → 那就是要字幕,直接開跑,不要反問。
  2. 一句話:「轉字幕」「生成字幕」「做個字幕」「加個字幕」「翻譯這段音頻」+ 檔案。

只有一種情況需要先問:使用者明確說要只有中文(不要原文行),那就加 --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_TRANSLATIONyes = 需要翻譯成中文;no = 原聲就是中文
PUNCTUATION_LOSTyes = 斷句品質不夠,走第 2 步
TRANSCRIPT_TXT僅當 PUNCTUATION_LOST=yes 時出現,第 2 步的輸入

為什麼要重新切分:whisper 的天然 segment 經常一條 7–8 秒、上百字元,直接當字幕會糊滿螢幕。腳本用詞級時間戳按標點+停頓重切成 ≤20 字(中文)/ ≤48 字元(英文)的短句。

第 2 步 · 中文/日文原聲補標點(僅當 PUNCTUATION_LOST=yes)

whisper 對中日文只零星吐標點,剩下靠停頓硬切。中文會切出「轉成文 / 字」;日文更糟——日語沒有詞間空格,whisper 的段落又首尾相接,連停頓都找不到,結果每條字幕都卡在正好 20 字處硬切,切出「申 / し訳ない」「くま / るさん」這種東西。修法是讓字幕落到真正的標點上:

  1. 讀 TRANSCRIPT_TXT(一整段無標點純文字)。
  2. 只插入標點,一個字都不要改。 包括聽起來明顯錯的字——ASR 把「機翻」聽成「擊翻」、把「詞級」聽成「自己」、把「おやすみ」聽成「おやすい」,都照原樣保留。改字會讓重新對齊失敗,標點就貼不回去了。
  3. 寫成 <STEM>.punct.txt(UTF-8)。
  4. 帶 --punct-file 重跑第 1 步(會自動複用 <STEM>.raw.json,秒級完成,不會重新轉寫):
python scripts/make_subtitles.py "<輸入>" --outdir "<輸出目錄>" --punct-file "<STEM>.punct.txt"

標點密度是這一步唯一真正重要的指標。 字幕上限是 20 字,所以標點必須比書面語更密:每 8~18 字就要有一個「、」或「。」。密度不夠,字幕照樣硬切——同一份 51 分鐘日語音頻實測:

標點密度條數收在標點上
不補82125%
~32 字/標點(太稀)100576%
8~18 字/標點108198%

「、」用在詞組邊界、助詞後的小停頓、口語換氣處——為字幕斷行服務,比書面日語用得更勤是對的,這不是把文字改壞了。另外只能用 。 、 ! ? …:「」 這類括號不在腳本的標點表裡,會被直接丟掉。

補完標點後,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 字元

相關技能