動画にキャプションを付ける
ユーザーがトーキング動画を提供します。ユーザーはキャプションスタイルのカタログから選択し、それは自分の映像上でプレビュー表示され、キャプション付きのMP4を提供します。すべてローカルでHyperFramesを使って実行されます。After Effectsは不要です。
キット: .claude/skills/caption-video/kit/（スタジオリポジトリ内）。プロジェクトは videos/captions/<name>/ に作成され、完成した動画は out/captions/<name>.mp4 に出力されます（どちらもスタジオルートからの相対パス）。
スタジオルートから、K="$PWD/.claude/skills/caption-video/kit" と設定し、python3 "$K/caption.py" … を実行します（パスは引用符で囲みます。フォルダ名にスペースが含まれる可能性があります）。システムのPythonに numpy/scipy がない場合は、スタジオのvenv Python（.venv/bin/python）を使用してください。setup/setup.sh で作成されます。
フロー
1. 動画を取得する
動画パスが指定されていない場合は、ユーザーに尋ねてください。そのファイルが存在し、話している人物が含まれていることを確認します。実行:
python3 "$K/caption.py" new "<動画パス>" <ショートネーム>
これにより動画がコピーされ、H.264に再エンコードされ、WhisperXで単語単位で文字起こしされます。久しぶりの初回実行は1分程度かかることがあります。長い動画はおおよそ実時間÷4で処理されます。
2. 文字起こしを表示する
コマンド出力から文字起こしを読みやすいブロックで表示します。特にブランド名や専門用語（製品名、「HyperFrames」、略語など）の間違いと思われる箇所を指摘し、ユーザーに確認または修正を求めます。修正内容はビルド時に --fix "間違い=正しい,…" で指定します。文字起こしが無意味な場合、または音声に音声が含まれていない場合は、停止してその旨を伝えてください。作った単語にキャプションを付けないでください。
3. すべてのスタイルをユーザーの映像で表示する
python3 "$K/caption.py" styles でリストを取得し、python3 "$K/caption.py" preview <name> でビジュアルシートを取得します。シートは videos/captions/<name>/previews/styles.png にあります。自分で確認し、SendUserFile（render を表示）で送信します。その横に、各スタイルの「最適な用途」を記載した番号付きリストを表示します:
- Lime Hook: テンプレートの見た目（Anton大文字、ライム色の話し言葉）
- Karaoke Pop: 大きな2単語のバースト、黄色の話し言葉
- One Word: 一度に1つの大きな単語
- Clean Box: 白いカードに濃い文字、話し言葉にマーカー
- Editorial: 落ち着いた文節、キーワードがイタリックのセリフ体
- Subtitle: 小さな全文字幕
- Neon: 話し言葉にシアンのグロー
コンテンツに基づいて1行で1つを推奨します: ハイプ系やソーシャル系 → 1か2、解説や広告 → 4、創業者ストーリーやプレミアム → 5、インタビューやポッドキャスト → 6、テックやAI → 7。その後、番号を選ぶようにユーザーに依頼します。caption.py のカタログが変更されている場合は、このコピーではなく styles が出力するものをリストしてください。
4. フック（オプション）
話し手が実際に話した内容から3つのフックを提案します。最も驚くべき数字、結果、または矛盾から始め、4～8語を使用し、見返りを1つの大きな単語にします。各フックをフック構文でフォーマットし、AskUserQuestion で「フックなし」を含む3つのフックオプションをユーザーに提示します（ユーザーが自分で入力することもできます）。
フック構文は | ごとに1行を使用し、各行はスタイルで始まります:
s:イタリックのセリフ体導入（「どのように」「なぜ」）c:白いコンデンス大文字のセットアップb:大きなリング付きの見返りとなる単語または数字（1～2語）l:ライム色の大文字のひねりr:小さなイタリックのタグ
例: s:どのように|c:私は達成した|b:30万+|l:広告なしで|r:再生回数。フックは動画の最初の10秒で提供される内容と一致している必要があります。
4b. ポリッシュ（提案する。ユーザーがグレーディング、音声のクリーンアップ、トリミング、音楽を依頼した場合に実行する）
python3 "$K/polish.py" <name> [--grade clean|cinematic|none] [--music calm|none] [--music-level 1.0] [--denoise 100]
- トリミング: 最初の単語の前と最後の単語の後の無音部分をカットし（0.3秒と0.9秒を保持）、文字起こしをそれに合わせてシフトします。
- グレーディング:
clean（デフォルト）で温かく健康的な肌、穏やかなコントラストとソフトなビネット効果を提供します。cinematicはより深くクールです。選択する前に、各設定の1フレームをオリジナルと比較して確認してください。 - 音声: DeepFilterNet3ノイズ除去（
~/.venvs/dfn、setup.shで作成。グローバルにインストールしないでください。numpy<2が必要です）、その後ハイパスフィルター、プレゼンスブースト、デエッサー、軽いコンプレッション。 - 音楽: 合成された落ち着いたピアノとパッドのベッド。レベル1では、無音部分で音声より約20dB下、話している間は約25dB下に位置します。静かにするには
--music-level 0.6、より目立たせるには1.5を使用します。 - オリジナルは
source_orig.mp4/transcript_orig.jsonとして保存されるため、任意の設定でポリッシュを再実行できます。ポリッシュ後、buildとrenderを再度実行します。 - 冒頭での言い間違いや言い直し（「現時点では、現時点では…」など）に言及します。それらをカットすると小さなジャンプカットが発生するため、実行前に確認してください。
5. ビルド、チェック、レンダリング
python3 "$K/caption.py" build <name> --style <キー> [--hook "…"] [--hot "単語,単語"] [--fix "a=b"]
cd "videos/captions/<name>" && npx --yes [email protected] check
python3 "$K/caption.py" render <name>
--hotでアクセントカラーを維持する単語を指定します。見返りとなる単語を2～5個選びます。数字は自動的にホットになります。checkのコントラスト警告は、フックのフェードアウト時点では想定内です。レンダリング前に実際のエラーを修正してください。- フックをレンダリングする前に、スナップショットを撮り（
npx --yes [email protected] snapshot . --at 1.6 --no-end --describe false）、顔を覆っていないことを確認します。顔がフレームの上部にある場合（座っているかミッドショット）、--hook-y 0.43でフックを胸の位置に移動します。シェーディングは自動的に追従します。 - 送信前に、
out/captions/<name>.mp4から3～4フレームを取得して確認します。キャプションが口や目を覆っていてはいけません。覆っている場合は、--cap-y（数字が大きいほど画面の下に表示）で再ビルドします。 - 横向きに撮影された映像（カメラが横向きで、回転メタデータがない場合）は、コンタクトシートで人物が横向きに寝ているように表示されます。最初に回転させ（
ffmpeg -vf transpose=2= 反時計回り90度、transpose=1= 時計回り。1フレーム確認）、videos/_caption-inputs/に配置してから、そのファイルに対してnewを実行します。 - MP4を
SendUserFileで送信し、そのパスをリンクとして表示します。
6. 修正
設定は videos/captions/<name>/caption.json に保持されるため、修正は build <name> --<オプション> … の後に render <name> を実行するだけです。よくあるリクエスト:
- スタイル変更:
--style。 - サイズ変更:
--size 1.2。 - 上下調整:
--cap-y 0.7。 - キャプションあたりの単語数:
--words 2。 - 色変更:
--accent "#FF4D3D"。 - フック変更:
--hook。--hook ""で削除。 - フック長:
--hook-dur 3.5。
ユーザーは自分で cd videos/captions/<name> && npm run dev を実行してHyperFrames Studioで開くこともできます。
セットアップ情報（何かが壊れた場合）
- 文字起こしは
~/.claude/skills/embedded-captions/scripts/transcribe.cjsをHYPERFRAMES_ROOT=~/.hyperframes-rootで呼び出します。HyperFrames CLI 0.8.147がインストールされ、packages/cli/dist/cli.jsへのシンボリックリンクがある必要があります。どちらかが欠けている場合は、再インストール:npx hyperframes skills update embedded-captions、その後~/.hyperframes-rootを再ビルドします（[email protected]をnpmインストールし、node_modules/hyperframes/dist/cli.jsをpackages/cli/dist/cli.jsにシンボリックリンクします）。 - フォントは
kit/fonts/にあります（すべてSIL OFLライセンス）。各プロジェクトにコピーされます。 setup/doctor.shですべてのコンポーネントをチェックし、setup/setup.shで修復します。- 人物の背後に表示されるキャプションは
/embedded-captionsワークフローで可能ですが、非常に遅く（10秒あたり約4分）、HYPERFRAMES_ROOTの設定が必要です。リクエストがあった場合のみ提案してください。