name: embedded-captions description: > 既存の単一被写体のトーキングヘッド動画に、フッテージを編集せずに字幕を追加します。プレーンの逐語字幕、被写体の背後に埋め込まれた映画的な字幕、VFX字幕、「炸/特效/酷炫字幕」、または35スタイルカタログの名前付きアイデンティティに対応。バックエンドエンジンではなく、視覚的アイデンティティでルーティングします。デフォルトは静かな`anchor`レールです。ユーザーが明示的に完全な映画的処理を希望する場合のみ、すべての単語を埋め込みます。ワークフローは、文字起こしと被写体マット処理を含めて、エンドツーエンドでローカルで実行されます。適用前に複数ショットのフッテージを分割してください。

まず、このスキルを最新に保つために、実行前にユーザーに確認してください: npx hyperframes skills update embedded-captions。すべてが最新の場合は高速なno-op、そうでない場合は、このスキルとそれが依存するコアドメインスキルを、それらに依存する前に更新します。

埋め込みキャプション

事前に選択する1つのカタログ (CATALOG.md — 35のアイデンティティ; 背後にあるエンジンはバックエンドの詳細です)。標準 (デフォルト) は、クリーンな逐語レール (ほとんどのテキストを保持する下部3分の1の字幕) + 被写体の背後にシーンに埋め込まれたクライマックス (ピーク時) を構築します。シネマティック は純粋な埋め込み — レールはなく、すべてのキャプションが被写体の背後に合成されます (ヒーロー書体、蓄積、遮蔽効果)。テーマ は、完全なテーマ別構成 — ボディパラダイム × ヒーローセットピース × フロントFX × プレートリアクションで、レジストリ (themes/README.md) から構成されます: ordnance terminal neonsign stardust stomp。ほとんどの説明・ナレーションは標準です; 埋め込みは希少で価値のあるピークです — すべての単語を埋め込むのがよくある間違いです; テーマはVFXグレードの要求 (「炸」、「特效」、「AEで作ったように」) 向けです。

運用フロー (TL;DR)

/hyperframes 経由でルーティングされ、インテントレイヤーは入力 (どのクリップか) のみを確認し、アイデンティティ選択を後回しの質問として告知します — ショートリストにはプローブされたクリップが必要なため、以下のステップ1に留まります; レイヤーの実行形状に関する質問は適用されません (フッテージは未編集であり、レビューするストーリーボードはありません)。BRIEF.md が存在する場合、確認された入力とユーザーノートが含まれています — 最初にそれを読んでください。

以下のクラフト散文は長いですが、パイプライン自体は短いです — そして、決定論的なものはすべて計算またはコンパイルされ、手動で作成されることはありません:

決定ゲート (不良クリップを拒否) → CATALOG.md から1つのアイデンティティを選択 (35のアイデンティティ; エンジン/コンパイラはルックアップによって導出 — モード/カテゴリの質問を表面化しない)
hyperframes init (プロジェクトディレクトリが既に存在し、その中にビデオがある場合はスキップ — matte.cjs/transcribe.cjs はディレクトリ内の任意のビデオを source.mp4 として採用) → bash scripts/prepare.sh <project> (matte ∥ transcribe ∥ audio-envelope を並列実行し、その後、シーンパレット/光学/照明を使用した safe-zones v2 — 1つのコマンドで、何も忘れません)
クリエイティブな選択の小さなJSONを作成 (最初に safe-zones.json を読んでください): シネマティック → plan.json → fill-timings.cjs → fit-fonts.cjs → make-composition.cjs; テーマ → theme.json → make-theme.cjs (レール/パネル/詩/テイクオーバーパラダイム; anchor は静かなレールのデフォルト)
ビジュアルQA: node scripts/preview-frames.cjs <project> → 約2秒/フレームで忠実なコンポジットプレビュー (レンダリングなし)。レンダリングに費用を払う前に、§ ビジュアルQAを確認してください。
render-and-composite.sh → ゲート (タイミング / 遮蔽+ヒーロー / オーバーフロー / ハンドオフ) → final.mp4

人々が見逃す重要なルール:

レール (デフォルト) + 埋め込み (プロモーション)。 drop (フィラー、表示されない) / rail (逐語的な下部3分の1の字幕、前面、ほとんどのテキストを保持) / embed (被写体の背後に合成されたピークワード)。標準モードは両方を実行し、ピークのみを埋め込みます。§ キャプションモデルを参照。
動画は手を加えずに納品されます (標準/シネマティック; テーマモードのPLATE予算は唯一許可された例外です — 各テーマDNAで定義されたレジスタゲートのリアクションビート (チャージディム、パンチ、シェイク、グレイン) は、マットコンポジット後に適用され、被写体+テキスト+プレートが1つのフレームとして動きます) — キャプションのみが追加されます; マットは被写体が埋め込みトラックを遮蔽できるようにするだけです。フッテージをグレーディング/リカラー/スキャンラインしないでください。
2つのルールブック: レール → references/rail.md (薄い)、埋め込みクラフト → references/composition-craft.md (豊富、埋め込みのみ)。必要に応じて斜め読みしてください。

キャプションモデル — レール + 埋め込み

話された各フレーズは、次の3つのいずれかです:

	内容	表示方法
drop	フィラー — えーと/あー、どもり、自己修正	表示されない
rail	デフォルト — 通常の話し言葉 (逐語)	クリーンな下部3分の1の字幕、前面、読みやすい。パンチワードはインラインの `emphasis` ハイライト (アクセントカラー / アクティブワードポップ) を取得できます — それはレールに残ります。
embed	プロモートされたピーク — 見出しのビート	被写体の背後に合成された1つの大きな単語 (マット遮蔽)、デザインされた入場 + 退場

レールはほとんどのテキストを保持します; 埋め込みは希少で価値のあるピークです。 希少性はクリップごとではなく、ビート/ブロックごとです: ブロック (思考) ごとに1つ以下のヒーロー、2つが同時に見えることはなく、ヒーローウィンドウ間には少なくとも1ビートの間隔が必要です (コンパイラは0.6秒未満を警告します)。短いクリップ → 通常1〜2; 長い説明 → セクションごとに約1つ。複数のヒーローの中で、最大の作成されたヒーローがAPEXです (それだけが完全なロックアップ埋め込み + 幅フィットの引き上げを取得します); 小さなものはマイナーピークで、その列を特大の強調行 (fg、減衰モーション) として使用します — すべてのビートがマットショーケースを必要とするわけではなく、それがまさにAPEXをイベントとして保つものです。すべての単語を埋め込むのがまだよくある間違いです。

レールサーフェスアイデンティティはこれを正確に構築します (レール = rail.html、埋め込み = index.html のクライマックス)。カラムフローアイデンティティはレールを削除し、すべてを埋め込みスタイルにします — ムード重視の要求 (逐語的でない) には推奨しますが、単語が読めなければならない説明/ナレーションには決して推奨しません (CATALOG.md はアイデンティティごとにこれをエンコードしています)。

ステップ 0 — CATALOGから1つのアイデンティティを選択

1つのフロントエンド、背後に3つのエンジン。 ユーザーは CATALOG.md からアイデンティティを選択します (35エントリ: 10クラシック + 25テーマ); エンジン、コンパイラ、および作成ファイルはカタログ行からのルックアップによって導出されます。「標準 vs シネマティック vs テーマ」を質問として表面化しないでください — これらはバックエンド名です (製品は複数のエンジンでも1つのUXを持ちます)。カタログはルーティングに必要なすべてをエンコードします: 読み込みサーフェス、声、推奨対象、シーンニーズ、真に近いペア (loud↔ordnance、neon↔neonsign、cream↔stardust) の隣接性ノート。

アイデンティティ選択はプリファレンスゲートです (../hyperframes-core/references/brief-contract.md § 1): 自律モード (「びっくりさせて」/「私に代わって決めて」) では、自分でショートリストから選び、その1行の理由を述べ、質問する代わりにそれを伝えます。

手順: クリップをプローブ → カタログから2〜3のアイデンティティをショートリスト → 1行の理由とともに1つを推奨 → ユーザーが選択 (自律モード: あなたが選択し、理由を述べる) → そのアイデンティティのファイルを作成。アイデンティティはエンジン固定です (クロスコンボ不可; 1つを開くことは検証イベントです — dna/README.md を参照)。

作成前に必ず推奨を提示し、ユーザーに選択させてください。 黙ってデフォルトにしないでください。

(完全なアイデンティティテーブルは CATALOG.md にあります — ルーティングのための唯一の真実のソース。以下のエンジンドキュメントは、各バックエンドの作成契約を説明します。)

推奨ヒューリスティック: CATALOG.md の「ショートリストヒューリスティック」を使用してください — これらはアイデンティティレベルです (例：「炸」は ordnance/stomp/terminal/loud をショートリストし、何が爆発すべきかで選択します)、カテゴリレベルではありません。不明な場合 → anchor。

シネマティック → ロックされたテンプレート用に plan.json を作成し、make-composition.cjs でコンパイル。
テーマ → themes/README.md を読み、theme.json を作成し、scripts/render-theme.sh を実行 (コンパイル + レンダリング + プレートリアクション → final_fx.mp4)。

決定ゲート — 最初に実行

どちらのモードの前に、ビデオをプローブし、シーンを分類してください。

ffprobe <video.mp4>                    # スペック
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png   # 20/50/80% で

サンプルを読み取ってください。以下の場合は拒否:

複数の話者 / ハードカット (各ショットを分割してレンダリングするか、拒否)
人間の被写体がない (このスキルはトーキングヘッド用)
3秒未満、音声なし、または顔が明確に見えない — transcribe.cjs はオーディオがほぼ無音の場合に警告します (Whisperは沈黙の上に「ありがとう」のような単語を幻覚します); それに従い、拒否してください — でっち上げの単語にキャプションを付けないでください
ソースに既に埋め込みキャプション/字幕/重いテキストグラフィックがある — 2番目のキャプションシステムを追加すると競合し、フッテージは手を加えずに出荷されます (カバー/インペイントなし)。焼き付けテキストはクリップの途中でのみ表示されることが多い: 1fpsのコンタクトシート (ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png) をサンプリングし、3つのスポットフレームを信頼しないでください。
文字起こしがガベージ — 非ネイティブ/強いアクセントの音声は、自信満々の意味不明な文字に文字起こしされる可能性があります。作成前に transcript.json を正気度チェックしてください; 言語として解析できない場合は、WHISPER_MODEL=medium を1回試し、それでもだめなら拒否してください (でっち上げの単語の逐語レールは、キャプションがないより悪いです)。
忙しいハンドヘルドで速い動き (マットがちらつく)

事前飛行プローブ (コストはかからず、最悪の失敗を防ぎます)

ショットカットプローブ。 20%、50%、80% でフレームをサンプリング。異なる被写体/シーンが現れた場合、カットの前にクリップをトリミングしてください。
レターボックス/ピラーボックスプローブ。 最初のフレームに黒いバーがありますか？安全なコンテンツ矩形を計算し、キャプションの配置をその内部に制約してください。
輝度プローブ。 キャプション領域の平均輝度をサンプリング — 60未満 → 明るいテキストはそのまま読める、60-180 → グリフスクリムを追加、180以上 → 不透明テキスト + スクリム (決して裸の明るいテキストは使わない)。シネマティックテンプレートはクリーム+screenでロックされています — このプローブを使用して、適切なアイデンティティを選択してください (明るいシーン → ink、または不透明レールの anchor テーマ)、決して色を変更しないでください。
トーンによるアイデンティティ推奨 (あなたが推奨し、ユーザーが選択します — ステップ 0 + CATALOG.md を参照)。 説明 / インタビュー / 単語を必ず読む必要がある → レール/パネルサーフェスアイデンティティ; 詩的 / ソーシャル / 「シネマティック」 → カラムフローアイデンティティ (レジスター別); 「炸 / 特效 / VFX」 / 名前付きワールド → テーマ別アイデンティティ。不明な場合 → anchor (単語が読め、シーンは安全) — ただし、ショートリストを提示し、ユーザーに選択させてください。

パイプライン — 5ステップ

1. hyperframes init <project> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <project>       # matte ∥ transcribe (並列) → safe-zones. 1つのコマンド。
                                           #   → frames_fg/ transcript.json safe-zones.json
3. [エージェントステップ — 唯一のクリエイティブステップ] 小さなJSONを作成; モードによって以下を参照
   シネマティック: plan.json を作成 → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   テーマ:     theme.json を作成 → bash scripts/render-theme.sh <project>   (コンパイル + レンダリング + プレートFX)
4. node scripts/preview-frames.cjs <project>   # 約2秒/フレームのコンポジットプレビュー → § ビジュアルQA (レンダリング前)
5. bash scripts/render-and-composite.sh <project>  # ゲート → final.mp4 + history/ スナップショット
   (テーマモード: ステップ3b/5をスキップ — render-theme.sh は既にコンパイル + render-and-composite + _postfx.sh を実行; 納品物

埋め込みキャプションスキル