一條本機字幕流水線, 掛在你的 AI CLI 上。
xiaohu-video-translate 把「外語影片 → 中文字幕影片」這件事拆成一條全自動流水線,交給你的 AI Coding CLI 執行。它的本體不是 App,而是「腳本 + 指令說明檔」的組合:一組 Python 腳本負責實際處理,搭配寫給 AI 的 SKILL 說明檔。支援的工具包含 Claude Code、OpenClaw、Gemini CLI 等。
你給它一段影片連結或本機檔案,它依序跑完五個階段:下載 → 抽音訊並用 Whisper 轉錄 → 翻譯 → 潤稿 → 字幕燒錄。整段流程在本機完成,使用 mlx-whisper(Apple Silicon)或 faster-whisper(其他平台)做語音辨識,不需要付費 API。Whisper 會自動偵測來源語言,英文、日文、韓文、法文、西班牙文等都能轉成中文。
輸出有兩種字幕模式:純中文,或中英雙語(中文大、英文小,以 ASS 格式排版)。它使用字級時間戳避免字幕與口型脫拍,並對轉錄結果做人工等級的處理——修正辨識錯字、依語意斷行、保留專有名詞的英文原文。字幕燒錄與浮水印在單次編碼中一起完成。也可以只輸出逐字稿,不燒字幕。
下載
抽音訊轉錄
翻譯
潤稿
字幕燒錄
你只需要下一個指令, 下載、轉錄、翻譯、潤稿、燒字幕 全部在本機完成。
先裝好三個依賴, 再 clone 跑 install。
需要的外部工具是 yt-dlp(下載)、FFmpeg(音訊與影片處理),以及 Whisper 引擎——Apple Silicon 用 mlx-whisper,其他平台用 faster-whisper。裝好依賴後 clone 本專案,執行 install.sh 把技能放到位。下面是 macOS 的完整步驟。
# 1. 安裝下載與影音處理工具
brew install yt-dlp ffmpeg
# 2. 安裝 Whisper(Apple Silicon 用 mlx-whisper)
pip3 install --break-system-packages mlx-whisper
# 3. clone 並執行安裝腳本
git clone https://github.com/xiaohuailabs/xiaohu-video-translate.git
cd xiaohu-video-translate && bash install.shWindows / Linux:換 Whisper 引擎與字型
非 Apple Silicon 平台改用 faster-whisper。Windows 建議走 WSL2;原生 Windows 可用 Git Bash 執行 install.sh 或手動複製技能資料夾,並把燒錄字型由 PingFang SC 改成 Microsoft YaHei。Linux 步驟與 WSL2 相同,字型用 Noto Sans CJK。
sudo apt install ffmpeg
pip3 install yt-dlp faster-whisper
git clone https://github.com/xiaohuailabs/xiaohu-video-translate.git
cd xiaohu-video-translate && bash install.sh三個技能, 各管一段流水線。
專案由三個可組合的技能構成。xiaohu-video-md 是協調者,負責下載、轉錄與整體流程,並輸出 Markdown 逐字稿;xiaohu-subtitle-polish 負責翻譯、修正、斷行與雙語排版;xiaohu-video-download 是獨立的下載器,可單獨用來抓影片、音訊或整個播放清單。下方卡片列出三個模組與它們對應的關鍵能力。
模組 · 01
xiaohu-video-md
流程協調者
主控整條流水線:下載、抽音訊、Whisper 轉錄、協調翻譯與潤稿,並輸出 Markdown 逐字稿。讀取 config.json 的 output_dir。
模組 · 02
xiaohu-subtitle-polish
字幕潤稿
負責翻譯、修正轉錄錯字、依語意斷行,以及中英雙語排版。把機器轉錄的草稿處理成可直接燒錄的字幕。
模組 · 03
xiaohu-video-download
獨立下載器
可單獨使用的下載模組,基於 yt-dlp,支援單支影片、純音訊與整個播放清單。不需要跑完整翻譯流程也能用。
能力 · 04
Whisper 自動辨識
多語言轉錄
Whisper 自動偵測來源語言——英、日、韓、法、西等——再翻成中文。Apple Silicon 走 mlx-whisper,其他平台走 faster-whisper。
能力 · 05
字級時間戳
不脫拍字幕
以字級時間戳對齊口型,避免字幕與說話者脫拍。兩種模式:純中文,或中英雙語(中文大、英文小,ASS 格式)。
能力 · 06
單次編碼燒錄
字幕加浮水印
字幕燒錄與浮水印在單次 FFmpeg 編碼中一起完成。保留專有名詞英文原文,也可只輸出逐字稿不燒字幕。
各平台依賴一覽
| 平台 | Whisper 引擎 | 燒錄字型 |
|---|---|---|
| macOS(Apple Silicon) | mlx-whisper | PingFang SC |
| Windows(WSL2,建議) | faster-whisper | Noto Sans CJK |
| Windows(原生) | faster-whisper | Microsoft YaHei |
| Linux | faster-whisper | Noto Sans CJK |
用自然語言下不同任務。
觸發方式是直接用自然語言對 AI CLI 講你要的結果。同一個技能組能依你的描述切換行為:雙語或純中文、燒字幕或只要逐字稿、線上連結或本機檔案。以下技巧全部來自官方說明文件。
技巧 01 · 一句話翻譯線上影片
直接貼連結並說明需求:「翻譯這個連結成中文字幕影片:https://youtu.be/xxxx」。它會自動跑完下載到燒錄的五個階段,輸出中文字幕影片。
來源 · 官方 README 使用範例
技巧 02 · 指定中英雙語字幕
在指令裡點明字幕模式,例如「翻譯這個日語影片,要中英雙語字幕」。雙語模式以 ASS 格式排版,中文大、英文小;不指定則輸出純中文。
來源 · 官方 README 使用範例
技巧 03 · 只要逐字稿,不燒字幕
說「把這個影片轉成文字」就只會輸出文字稿,跳過字幕燒錄。適合做筆記、摘要或後續再加工,省下編碼時間。
來源 · 官方 README 使用範例
技巧 04 · 處理本機檔案
不限線上影片,本機檔案一樣可加字幕:「給我本地這個影片加中文字幕 ~/Movies/talk.mp4」。略過下載階段,直接從轉錄開始。
來源 · 官方 README 使用範例
技巧 05 · 趕時間用快速模式
說「用快速模式轉寫」會改用較快但精度較低的模型。適合先看大意、之後再決定要不要用標準模型重跑的情境。
來源 · 官方 README 使用範例
技巧 06 · YouTube 擋下載時掛代理
遇到 YouTube 403 或 token 錯誤,腳本會自動讀取瀏覽器 cookie;若仍失敗,可加 --proxy http://127.0.0.1:7890 走本機代理。
來源 · 官方 README 疑難排解
一段 YouTube 影片到雙語字幕的全程。
以下是一段示意情境:你有一支英文技術演講,想要中英雙語字幕版本。你只需要在 AI CLI 裡用自然語言下指令,技能組會依序跑完五個階段。指令與檔案路徑為官方文件記載的實際用法,進度數字為示意。
$ You ›
翻譯這個影片,要中英雙語字幕:
https://youtu.be/xxxxxxxxxxx
claude: Claude ›
收到。雙語字幕模式,五階段流水線開始。
hl: 階段 1/5 · 下載
[yt-dlp] fetching video + audio ...
ok: 下載完成 · talk.mp4 (1080p)
hl: 階段 2/5 · 抽音訊 + Whisper 轉錄
[ffmpeg] extract audio → talk.wav
[mlx-whisper] 偵測語言: English
[mlx-whisper] 字級時間戳轉錄中 ...
ok: 轉錄完成 · 642 段、word-level timestamps
hl: 階段 3/5 · 翻譯(xiaohu-subtitle-polish)
英文 → 中文,保留專有名詞英文原文
hl: 階段 4/5 · 潤稿
· 修正轉錄錯字
· 依語意斷行
· 中英雙語排版(ASS · 中文大、英文小)
hl: 階段 5/5 · 字幕燒錄
[ffmpeg] 單次編碼 · 字幕 + 浮水印
ok: 完成 · talk.zh-bilingual.mp4
$ You ›
這支 YouTube 擋下載,403 了。
claude: Claude ›
先自動讀取瀏覽器 cookie 重試;若仍失敗,加本機代理:
hl: --proxy http://127.0.0.1:7890
一個指令,五個階段, 輸出雙語字幕影片與逐字稿。 全程在本機,沒有付費 API。
這段流程的關鍵在哪
值得注意的不是「能翻譯」,而是每個階段的工程細節都被做掉了:字級時間戳避免字幕脫拍、潤稿階段修正辨識錯字並依語意斷行、燒錄與浮水印在單次編碼完成。這些是手動用 Whisper + FFmpeg 拼流程時最容易卡住的地方。
因為轉錄與翻譯都在本機跑(mlx-whisper / faster-whisper),處理量大時不會累積 API 費用;模型第一次下載約 1.5GB 之後就常駐本機。
上手前, 先知道這些邊界。
把它接進你的內容流程。
它的本體是腳本加說明檔,因此能依你的工作流程組合與調整。以下是幾個方向。
實用組合
1. 批次處理整個播放清單。xiaohu-video-download 支援播放清單下載,可先把整個系列抓下來,再逐支跑轉錄與字幕。
**2. 只做逐字稿管線。**需要文字而非影片時,用「轉成文字」模式輸出 Markdown 逐字稿,接你的筆記、摘要或翻譯後製流程。
**3. 跨 AI CLI 使用。**除了 Claude Code,專案也能在 OpenClaw、Gemini CLI 等工具上運作。同一組技能,換工具不用換流程。
**4. 調整燒錄字型與字幕模式。**依輸出語言與平台改字型設定,並在指令中切換純中文或中英雙語,適配不同發佈平台。
延伸閱讀
① xiaohuailabs/xiaohu-video-translate——專案 README:安裝、使用範例與疑難排解。 ② 各平台安裝段落——macOS、Windows(WSL2 / 原生)、Linux 的依賴與字型設定。 ③ ~/.claude/skills/xiaohu-video-md/config.json——輸出目錄與模型設定。
外部依賴裝好、輸出目錄設好, 剩下的交給一句自然語言指令。