name: video-subtitle description: 本地影片/音訊字幕生成（零雲 API）。支援抽音軌、Whisper 本地識別、專名校對詞表、中英雙語字幕、VAD 靜音過濾、斷句最佳化、字幕樣式控制、批次處理、可選硬燒/封裝。當用戶需要給影片配字幕、轉寫音訊、生成中英雙語字幕，或要求"本地/離線/不調 API"完成時呼叫。

Video Subtitle（本地字幕生成）v1.2

本地指令碼流水線：抽音軌 → Whisper 識別 → 詞表校對 → 斷句最佳化 → 輸出 srt/vtt（可選雙語、硬燒、封裝）。 零雲 API、零按量費用。預設模型 base，預設源語言 zh。 v1.1 重構為 SubtitleEngine 類 + CLI 薄封裝，新增依賴自檢 / 流式進度 / VAD / 斷句最佳化 / 字幕樣式 / 批次處理 / 配置檔案 / Docker。 v1.2 經真實端到端跑通後修復三處硬傷，並補上模型下載映象 / 快取重定位 / 離線執行。

何時用

• 給影片/音訊配字幕，且不想調雲 API（隱私 / 省 token / 省錢）
• 需要中英雙語字幕
• 內容含專屬名詞（角色名、命理術語、品牌），需要識別後自動糾一遍
• 一次要處理一批影片/整目錄

前置依賴（一次性）

• ffmpeg（抽音軌、燒錄、封裝）—— 必須加入 PATH
• ASR 引擎二選一：pip install faster-whisper（推薦，支援 VAD）或 pip install openai-whisper
• 首次執行自動下載模型權重（base≈140MB）到 ~/.cache/huggingface
• 國內直連 huggingface.co 通常超時 → 程式會自動探測並切到 hf-mirror.com
• 家目錄不可寫時用 --download-root D:/models/whisper 重定位快取
• 依賴自檢：python scripts/cli.py --check

工作流程

1. 先跑 python scripts/cli.py --check 確認 ffmpeg + 引擎就緒（缺什麼會明確提示）。
2. 執行識別：python scripts/cli.py 輸入.mp4 --wordlist assets/wordlist.example.json。
3. 看生成的 srt 校對；需要畫面帶字幕時最後再 --burn（硬燒不可逆，先校後燒）。

   小蔥技能7w4.net持續更新中。

4. 批次：把多個檔案或目錄直接作為引數傳入即可。

命令模板

# 依賴自檢（不處理檔案，只報環境）
python scripts/cli.py --check

# 中文影片 -> 中文 srt + 詞表校對（最常用）
python scripts/cli.py 輸入.mp4 --wordlist assets/wordlist.example.json

# 整目錄批次 + 詞表
python scripts/cli.py ./videos/ --wordlist assets/wordlist.example.json

# 中文影片 -> 中英雙語 srt（開啟 VAD + 斷句最佳化）
python scripts/cli.py 輸入.mp4 --mode bilingual --vad --wordlist assets/wordlist.example.json

# 中文影片 -> 僅英文 srt
python scripts/cli.py 輸入.mp4 --mode translate

# 直接給音訊
python scripts/cli.py 錄音.m4a --lang zh

# 用配置檔案（推薦儲存偏好）
python scripts/cli.py 輸入.mp4 --config config.example.toml

# 硬燒進畫面 + 自定義字號/字型（Windows 防中文方塊）
python scripts/cli.py 輸入.mp4 --burn --font-name "Microsoft YaHei" --font-size 28

# 封裝軟字幕流到 mp4（播放器可開關，推薦交付）
python scripts/cli.py 輸入.mp4 --mux

# 三種形態疊加：外掛 srt + 封裝軟字幕 + 硬燒，一次出齊
python scripts/cli.py 輸入.mp4 --mux --burn

# 追求精度（需 GPU/耐心）
python scripts/cli.py 輸入.mp4 --model large-v3 --mode bilingual --vad

關鍵引數

校對詞表（重點）

Whisper 對同音字、專有名詞最容易翻車。把專屬詞列進詞表，識別後自動糾一遍。 支援字典式 {"錯": "正"} 或列表式 [{"wrong":"錯","right":"正"}]，長詞優先匹配。 示例見 assets/wordlist.example.json（已含角色名/命理術語樣例，按需替換）。

注意事項

• 雙語 = 同音頻跑兩次模型（transcribe + translate），CPU 較慢但可用。
• Windows 中文硬燒坑：用 --font-name "Microsoft YaHei" 或 --font-file 指定中文字型（詳見 references/usage.md）。
• 識別非 100% 準確，專名密集內容務必過詞表 + 人工校對。
• 詳細安裝、詞表格式、VAD、樣式、雙語、Docker 見 references/usage.md。

這個 Skill 質量不錯，核心功能齊全，文件寫得清楚明白，對國內使用者很友好（映象切換、快取重定位）。依賴自檢、中文字型處理等細節考慮周到，使用起來比較省心。不足是測試覆蓋不夠全面，部分邊界情況的穩定性有待驗證。如果你是普通使用者，按文件操作基本不會踩坑，但識別結果仍需人工核對。