VideoCaptioner CLI

AI 驅動的字幕工具：語音轉寫 → 優化字幕 → 翻譯 → 以精美樣式嵌入影片。

使用時機

使用者想要為影片加入字幕
使用者想要將音訊/影片轉寫為文字
使用者想要將字幕翻譯成另一種語言
使用者想要自訂字幕外觀（顏色、字型、圓角背景）
使用者想要下載並為線上影片加上字幕

開始之前

執行命令前，一律先執行 videocaptioner <command> --help 以查看最新選項與預設值。以下範例為常見模式，但 --help 才是最終依據。

安裝：pip install videocaptioner
影片合成需 FFmpeg（macOS 上使用 brew install ffmpeg）
免費（無需 API 金鑰）： 轉寫（bijian/jianying）、翻譯（Bing/Google）
需要 LLM API 金鑰： 字幕優化、字幕重新分段、LLM 翻譯。可透過 OPENAI_API_KEY 環境變數或 --api-key 旗標設定

常見情境

1. 為中文影片加上英文字幕（單一指令，完全免費）

videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
  --subtitle-mode hard --quality high -o output.mp4

2. 將影片轉寫為 SRT（免費）

videocaptioner transcribe video.mp4 --asr bijian -o output.srt

# 以 JSON 格式輸出至目錄
videocaptioner transcribe video.mp4 --asr bijian --format json -o ./subtitles/

3. 翻譯現有字幕

# 免費 Bing → 英文，雙語輸出，翻譯在上
videocaptioner subtitle input.srt --translator bing --target-language en --layout target-above -o translated.srt

# 免費 Google → 日文，僅輸出翻譯（捨棄原文）
videocaptioner subtitle input.srt --translator google --target-language ja --no-optimize --layout target-only -o output_ja.srt

# 使用 LLM 高品質翻譯，啟用反思模式
videocaptioner subtitle input.srt --translator llm --target-language en --reflect \
  --api-key $OPENAI_API_KEY -o output_en.srt

4. 完整流程，包含精美樣式字幕

# 動漫風字幕（暖色 + 橘色邊框），高畫質影片
videocaptioner process video.mp4 --asr bijian --translator bing --target-language ja \
  --subtitle-mode hard --style anime --quality high -o output_ja.mp4

# 現代圓角背景字幕
videocaptioner process video.mp4 --asr bijian --translator google --target-language ko \
  --subtitle-mode hard --render-mode rounded -o output_ko.mp4

# 自訂顏色：白色文字 + 紅色邊框，超高畫質
videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
  --subtitle-mode hard --quality ultra \
  --style-override '{"outline_color": "#ff0000", "primary_color": "#ffffff"}' -o output_en.mp4

5. 僅輸出字幕，ASS 格式（不合成影片）

videocaptioner process video.mp4 --asr bijian --translator bing --target-language en \
  --format ass --no-synthesize -o ./output/

6. 逐步控制（分別進行轉寫 → 翻譯 → 合成）

# 步驟 1：轉寫
videocaptioner transcribe video.mp4 --asr bijian -o video.srt

# 步驟 2：翻譯（雙語，原文在上）
videocaptioner subtitle video.srt --translator bing --target-language en --layout source-above -o video_en.srt

# 步驟 3：嵌入字幕，圓角背景，高畫質
videocaptioner synthesize video.mp4 -s video_en.srt --subtitle-mode hard \
  --render-mode rounded --quality high -o video_with_subs.mp4

7. 處理音訊檔案（自動跳過影片合成）

videocaptioner process podcast.mp3 --asr bijian --translator bing --target-language en -o ./output/

8. 轉寫其他語言（whisper-api）

videocaptioner transcribe french_video.mp4 --asr whisper-api \
  --whisper-api-key $OPENAI_API_KEY --language fr -o french.srt

9. 僅使用 LLM 優化字幕（修正 ASR 錯誤，不翻譯）

videocaptioner subtitle raw_subtitle.srt --no-translate --api-key $OPENAI_API_KEY -o optimized.srt

10. 自訂圓角背景樣式與字型

videocaptioner synthesize video.mp4 -s subtitle.srt --subtitle-mode hard \
  --style-override '{"text_color": "#ffffff", "bg_color": "#000000cc", "corner_radius": 10, "font_size": 36}' \
  --font-file ./NotoSansSC.ttf --quality high -o styled_video.mp4

指令參考

指令	用途
`transcribe`	語音 → 字幕。引擎：`bijian`（免費）`jianying`（免費）`whisper-api` `whisper-cpp`
`subtitle`	優化（LLM）及/或翻譯（LLM/Bing/Google）字幕檔案
`synthesize`	將字幕嵌入影片，可自訂樣式
`process`	完整流程：轉寫 → 優化 → 翻譯 → 合成
`download`	從 YouTube、Bilibili 等下載影片
`config`	管理設定（`show` `set` `get` `path` `init`）
`style`	列出所有字幕樣式預設及其參數

執行 videocaptioner <command> --help 以查看完整選項。

字幕樣式

兩種渲染模式提供美觀字幕：

ASS 模式（預設）— 邊框/陰影樣式：

預設：default（白色+黑色邊框）、anime（暖色+橘色邊框）、vertical（直式影片）
可自訂欄位：font_name、font_size、primary_color、outline_color、outline_width、bold、spacing、margin_bottom

圓角模式 — 現代圓角背景框：

預設：rounded（半透明背景上的深色文字）
可自訂欄位：font_name、font_size、text_color、bg_color（#rrggbbaa）、corner_radius、padding_h、padding_v、margin_bottom

樣式選項僅適用於 --subtitle-mode hard。

目標語言

BCP 47 代碼：zh-Hans zh-Hant en ja ko fr de es ru pt it ar th vi id 等 23 種以上。

環境變數

變數	用途
`OPENAI_API_KEY`	LLM API 金鑰
`OPENAI_BASE_URL`	LLM API 基礎 URL

退出代碼

0 成功 · 2 參數錯誤 · 3 找不到檔案 · 4 缺少依賴 · 5 執行階段錯誤

提示

使用 -q 進行腳本化（標準輸出僅為結果路徑）
Bing/Google 翻譯免費，無需 API 金鑰
bijian/jianying ASR 免費，但僅支援中文與英文
執行 videocaptioner style 以查看所有樣式預設

VideoCaptioner — 燒字幕

VideoCaptioner — 燒字幕是什麼？

在你喜歡的 AI 中提問

說明文件