zaddy99999/captions

captions は何をしますか？

ローカルでの単語レベル文字起こし、ショートフォームキャプションのスタイリングと焼き込み。

スクリプトは scripts/ にあります：

スクリプト	機能
transcribe.py	word_timestamps=True を指定した faster-whisper で words.json にキャッシュ
make-captions.mjs	words.json から ASS（スタイル付き、アクティブワードハイライト）と SRT を生成
burn.mjs	libass（ass / subtitles フィルタ）で ASS/SRT を焼き込み
snap-to-words.mjs	カットポイントを単語間の最も近いギャップに移動

ワークフロー

1. 文字起こし（ソースごとに1回、結果はキャッシュされます）：

   pip install faster-whisper            # 一度だけ
   python3 scripts/transcribe.py --input clip.mp4 --out edit/clip.words.json --model small --language en
   

   初回実行時に Hugging Face からモデルをダウンロードします。これがブロックされた場合、 スクリプトはトレースバックではなく終了コード4と JSON の fix メッセージで終了します。 偽のトランスクリプトを書き込むことはありません。オフラインで動作するには、--model をローカルの CTranslate2 モデルフォルダに指定します。
2. キャプションをビルド：

   node scripts/make-captions.mjs --words edit/clip.words.json --out-ass edit/clip.ass --out-srt edit/clip.srt
   

   スタイルはブランドパック（captions ブロック：サイズ、マージン、アウトライン、 ハイライト；colors.accent はアクティブ単語の色）から取得されます。
3. 焼き込み（最後の視覚的ステップとして）：

   node scripts/burn.mjs --input edit/clip-hook.mp4 --subs edit/clip.ass --out edit/clip-captioned.mp4
   

   キャプションフォントがインストールされているフォントではなくファイルの場合、--fonts-dir を使用します。
4. 検証：render-qc プルーフシートで確認：読みやすいこと、セーフエリア内にあること、フックプレートにかからないこと。

ルール

• 単語の途中でカットしないでください。音声を分割する前に、カットを単語のギャップにスナップします： node scripts/snap-to-words.mjs --words edit/clip.words.json --markers edit/cuts.json --out edit/cuts.json
• キャプションは最後に行います：カット、オーバーレイ、色の後に。書き起こし後にクリップをトリミングする場合は、make-captions.mjs に --offset -<トリミングした秒数> を渡します。
• ショート動画では1チャンクあたり1〜3単語（maxWords、maxChars）。チャンクは句読点とポーズで区切ります。
• キャプションを下部約15％（プラットフォームUI）とフックプレートから遠ざけます：captions.marginV を調整します。
• トランスクリプトはキャッシュされます：オーディオが変更された場合のみ --force を付けて再実行します。
• 単語をオーディオとスポットチェックします。whisper は名前や専門用語を聞き間違える可能性があります。必要に応じて words.json を手動で修正します。

ffmpeg libass がない場合

burn.mjs が ass フィルタがないと報告した場合、ffmpeg ビルドに libass が含まれていません。フルビルドをインストールするか（ほとんどのパッケージマネージャが提供しています）、SRT を焼き込む代わりに個別のキャプショントラックとしてアップロードします。