ahkamboh/agent-caption

agent-caption — SKILL (日本語訳)

あなたはAIの字幕エージェントです。このリポジトリは、あらゆる動画や音声に対して、あらゆる言語（デフォルトは英語）で正確で完璧なタイミングの字幕/サブタイトルを追加します。音声と音楽の両方に対応し、ヒングリッシュ / コードスイッチを第一級でサポートします。Windows、macOS、Linuxで動作します。

リポジトリ: https://github.com/ahkamboh/agent-caption — クローン: git clone https://github.com/ahkamboh/agent-caption このファイル（生）: https://raw.githubusercontent.com/ahkamboh/agent-caption/master/SKILL.md

基本原則: 単語は音声認識から取得しますが、タイミングは波形上の強制アライメントから取得します — 生のASRタイムスタンプは使いません。そのため、文字起こしにスペルミスがあっても、字幕が早くなったり遅くなったりすることはありません。

初回セットアップ（Windows / macOS / Linux）

必要なもの: Python 3.10+、ffmpeg、約4GBのディスク容量。（torchは3.14までのwheelを提供していますが、whisperxが新しいPython用のwheelを提供していない場合は3.11～3.12を使用してください。）

python setup.py        # クロスプラットフォーム: ./.venv-whisperx を作成し、すべてをインストール
# macOS/Linux 便利コマンド: bash setup.sh      ·      Windows 便利コマンド: setup.bat

ffmpeg: macOS brew install ffmpeg · Ubuntu sudo apt install ffmpeg · Windows winget install ffmpeg。 モデル（Whisper large-v3 — デフォルト — MMS_FA、whisperX）は初回実行時に自動ダウンロードされます。

最も簡単な方法 — 単一コマンドのラッパー（推奨）

「この動画に字幕をつけて」というリクエストには、トップレベルのラッパーを実行するだけです。文字起こし→アライメント→自動プロポーション調整された字幕（あらゆる解像度に対応した正しいサイズ・間隔・配置）の焼き込みを実行し、ユーザーのffmpegが字幕機能をサポートしていない場合は、libassを使用しないレンダラー（Pillow + overlay）にフォールバックします:

python caption.py <video>                                  # 英語、cleanスタイル、プロポーション調整 → <video>.captioned.mp4
python caption.py <video> --hinglish --style tiktok        # ヒングリッシュ + TikTokボックス
python caption.py <video> --lang ur --pos center --size 6  # 他の言語 / 配置 / サイズ
python caption.py <video> --srt                            # .srt のみ出力（焼き込みなし）
python caption.py <video> --from-srt FILE                  # 既存の .srt をプロポーション調整して焼き込み

15スタイル（バンドルフォント）: clean（デフォルト）bold hormozi green beast impact bebas tiktok pill boxed yellow neon gradient minimal subtitle。生の文字起こし、カスタムレンダリング、翻訳が必要な場合にのみ、以下の個別スクリプトを使用してください。

モデル: large-v3 がデフォルト（最高精度）です — フラグは不要。setup.py が事前にダウンロードします。クリーンな英語で速度を重視する場合は --fast（小モデル）を追加します。--accurate は引き続き使用可能ですが、現在は冗長です。ヒングリッシュパスは常にlarge-v3を使用します。

カスタムスタイル — ユーザーが説明する任意の見た目を構築します。 ユーザーの言葉を以下のフラグにマッピングします（--style を上書き）:

• --font <名前|パス> — バンドルフォント（Poppins-Bold、Poppins-Black、Anton-Regular、BebasNeue-Regular、ArchivoBlack-Regular）、または任意の .ttf ファイルパス
• --fill #hex（テキスト色） · --outline #hex · --box #hex|#hexAA|none（テキスト背景のピル）
• --caps / --no-caps · --gradient "#hex,#hex,#hex" · --glow · --ow N（アウトラインの太さ）
• --size <pct>（高さ） · --pos bottom|center|top

例 — ユーザーが 「ホットピンクの大文字、暗い角丸ボックス、大きめ、Antonフォントで」 と言った場合 →

python caption.py v.mp4 --fill "#ff3da6" --box "#10141ae0" --caps --font Anton-Regular.ttf --size 6

新しい名前付きスタイルを永続的にするには、caption.py の STYLES 辞書にエントリを追加します。

精度 — 聞き間違えを排除する（無料、トークン不要、人間の確認不要）

強制アライメントにより、タイミングは構造的に正しくなります。修正できない唯一のことは、単語が正しく聞き取れたかどうかです（「their」/「there」、固有名詞、スラングなど）。3つの無料の手段でこれをほぼゼロに近づけられます:

• --glossary "..." — 固有名詞/ブランド名/スラングを指定します（リストまたは .txt ファイルのパス）。ASRの初期プロンプトにバイアスをかけ、固有名詞の聞き間違いを防ぎます。固有名詞に対して最大の効果があります。一度リストを作成すればOK。

  python caption.py talk.mp4 --glossary "Xaibridge, Hinglish, Xotion, Kamboh"
  

• --script FILE — 正しい単語がすでに存在する場合（歌詞、台本など）、それを渡します。ツールはASRを完全にスキップし、指定された単語に対して強制アライメントのみを実行します → コンテンツの精度100%。

  python caption.py song.mp4 --script lyrics.txt
  

• --grammar — 字幕に対してオフラインの同音異義語/文法チェックを実行します（「their」→「there」、「your」→「you're」など）。ローカルでLanguageToolを実行します（アップロードなし、トークン消費なし）。タイミングは一切変更しません。オプションの依存関係 — python setup.py --grammar で一度有効化します（Java/JRE 8+が必要）。ない場合は正常にスキップされます。

  python caption.py talk.mp4 --accurate --glossary names.txt --grammar    # 組み合わせて使用
  

費用対効果の順序: --glossary（固有名詞）→ --script（テキストが存在する場合）→ --grammar（同音異義語）。 ベースモデルはデフォルトですでに large-v3 です。これらで捕捉できない残りの誤りは、人間またはLLMが必要です — これがトークンを費やす価値のある唯一のコストであり、文字起こし全体ではなく、フラグが立った単語に対してのみです。

楽曲 — まずボーカルを分離する（--content）

音楽の場合、ASRの前にボーカルステムを分離すると、歌詞の文字起こしが格段にきれいになります（Whisperがバックトラックと戦わなくて済みます）。これは条件付きです — クリーンな音声には無意味/低速なので、ゲートで制御します:

python caption.py song.mp4 --content music                 # ボーカル分離を強制（demucs）
python caption.py clip.mp4                                  # --content auto（デフォルト）: 音楽を検出した場合のみ分離
python caption.py podcast.mp4 --content speech              # 分離しない（または --no-isolate）
python caption.py song.mp4 --content music --script lyrics.txt   # 最もクリーンな楽曲: 既知の歌詞、ボーカルステム上でタイミングを取得

auto は簡易的な音楽/音声プローブを実行し、音楽を検出した場合のみ分離します — そのためポッドキャストやインタビューが遅くなることはありません。焼き込みは常に元の動画を使用します。書き起こし/アライメントするのは分離されたステムのみです。demucs が必要です（python setup.py でインストール）。ない場合は元の音声にフォールバックします。

スクリプトは常にvenvのpythonで実行 — ここでは PY と表記:

• macOS / Linux: PY = ./.venv-whisperx/bin/python
• Windows: PY = .venv-whisperx\Scripts\python

スクリプト一覧

• transcribe.py — Whisper → 単語レベルの文字起こし（デフォルト英語。他の言語は --lang xx）。
• align.py — 強制アライメント によるフレーム単位の正確なタイミング。ヒングリッシュ/混合言語は --code-switch。
• cs_transcribe.py — コードスイッチに強い単語認識（セグメントごとの言語ID）。
• mms_align.py — ユニバーサルMMS_FA強制アライナー（1100以上の言語、あらゆる文字体系）。
• validate_timing.py — コードスイッチパスで使用されるタイミングの健全性チェック。
• export-subs.py — 文字起こし → .srt + .vtt。
• multilang-subs.py — 字幕を多くの言語にオフラインで翻訳。
• grammar_fix.py — .srt に対するオフラインの同音異義語/文法修正（タイミング保持）。--grammar で使用。
• isolate_vocals.py — 楽曲用のDemucsボーカル分離と音楽vs音声プローブ。--content で使用。
• qa.py — 高速で決定論的なQAゲート（キュー健全性 + ffprobe出力チェック）→ work/<base>.qa.json。すべての焼き込み後に自動実行。--strict で出力に問題がある場合は非ゼロ終了コード。
• footprint.py — <base>.footprint.svg をレンダリング: ひと目でわかる字幕ヘルスマップ（各単語が強制アライメントの信頼度で色分け + ギャップマーカー + 判定）。各キャプション後に自動実行。スキップするには --no-footprint。
• benchmark.py — 実際の精度向上を測定: 旧デフォルト（small）と新デフォルト（large-v3 [+ Demucs]）のWERをリファレンス文字起こしと比較。PY scripts/benchmark.py CLIP --ref truth.txt [--music] [--hinglish]。
• caption.py — オールインワンのスタイル付きキャプション（カラオケ/ワード/ライン。Hormozi、TikTok、ネオン…）→ アニメーション captions.js。

動画に字幕をつける（メインジョブ） — デフォルト言語 = 英語

他の言語の場合は --lang <コード> を渡します。ヒングリッシュ/混合の場合は --code-switch を使用します。

1) フレーム精度の単語タイミング

音声（トーク、ポッドキャスト、UGC）:

PY scripts/align.py INPUT --lang en --out work/transcript.json

ヒングリッシュ / ヒンディー語と英語の混合（または任意のコードスイッチ音声）:

PY scripts/align.py INPUT --code-switch --dual hi en --out work/transcript.json

その他の言語（ウルドゥー語、スペイン語、アラビア語、中国語…）:

PY scripts/align.py INPUT --lang ur --out work/transcript.json

2a) 字幕（.srt / .vtt）+ 動画への焼き込み

PY scripts/export-subs.py work/transcript.json --out work/subs
ffmpeg -i INPUT -vf "subtitles=work/subs.srt" -c:a copy captioned.mp4

.srtはそのままYouTubeにアップロードするのにも最適です（選択可能 + SEO効果）。

2b) スタイル付き/アニメーション字幕（Hormozi、TikTok、カラオケ — ショートフォーム向け）

PY scripts/caption.py INPUT --lang en --content speech --style karaoke --preset hormozi --out out/

プリセット: hormozi、beast、pill、neon、gradient、minimal、tiktok。楽曲/歌詞の場合は --content music を使用。詳細は docs/caption-styles.md を参照。

3) 字幕を任意の言語に翻訳（オプション）

PY scripts/multilang-subs.py work/subs.srt --to "hi,ur,es,fr,ar,de" [--burn INPUT]

ルール（組み込み済み — 上書きしないでください）

• タイミングは常に強制アライメント、生のASRタイムスタンプは使用しません（先行/遅延は発生しません）。
• デフォルトの字幕言語 = 英語。他の言語には --lang を渡します。
• 音楽/歌 → --content music。音声/トーク → --content speech。
• すべてのスクリプトは PY（venvのpython）で実行し、whisperx/torchが使用可能であることを確認します。
• 納品前に、いくつかのキャプションを単語の開始時点でスポットチェックし、同期を確認します。

言語コード

en（デフォルト）、hi、ur、pa、es、fr、de、pt、ar、zh、ja、ko、ru、it、tr、id、nl、pl、uk、… — Whisperは約99言語をサポート。MMS_FAは1100以上の言語をアライメント。