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. 中国語の動画に英語の字幕を付ける（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 を実行してください。

字幕スタイル

美しい字幕のための2つのレンダリングモード：

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 — 字幕焼き込み