まず、このスキルを最新の状態に保ってください。確認せずに実行します:
npx hyperframes skills update embedded-captions。すべてが最新の場合は高速なno-opです。そうでない場合は、このスキルと、依存するコアドメインスキルを、それらに依存する前に更新します。
埋め込みキャプション
1つのカタログを事前に選択（CATALOG.md — 35のアイデンティティ。背後にあるエンジンはバックエンドの詳細です）。Standard（デフォルト）は、クリーンな逐語的なレール（ほとんどのテキストを表示する下部3分の1の字幕）と、映像のクライマックスで被写体の背後に合成される埋め込みを構築します。Cinematicは純粋な埋め込みです。レールはなく、すべてのキャプションが被写体の背後に合成されます（ヒーロータイポグラフィ、蓄積、オクルージョンが効果として適用されます）。Themeは、完全なテーマ化された構成です。ボディパラダイム×ヒーローセットピース×フロントFX×プレートリアクションを、レジストリ（themes/README.md）から構成します：ordnance terminal neonsign stardust stomp。ほとんどの解説動画/ナレーションはStandardです。埋め込みは、希少で価値のあるクライマックスです。すべての単語を埋め込むのはよくある間違いです。ThemeはVFXレベルの要求（「炸」、「特效」、「AEで作ったように」）に適しています。
運用フロー（概要）
/hyperframes を介してルーティングされます。インテントレイヤーは、入力（どのクリップか）のみを確認し、アイデンティティの選択を先送りされた要求として通知します。ショートリストは調査済みのクリップを必要とするため、以下のステップ1に留まります。レイヤーの実行形状に関する質問は該当しません（映像は未編集であり、レビューするストーリーボードはありません）。BRIEF.md が存在する場合、確認された入力とユーザーノートが含まれています。最初にそれを読んでください。
以下のクラフト散文は長いですが、パイプライン自体は短いです。そして、決定論的なすべてのものは計算またはコンパイルされ、手書きされることはありません。
- 決定ゲート（不良クリップを拒否）→ ** CATALOG.md から1つのアイデンティティを選択**（35のアイデンティティ。エンジン/コンパイラはルックアップによって導出されます。モード/カテゴリの質問をユーザーに提示しないでください）
hyperframes init（プロジェクトディレクトリが既に存在し、その中にビデオがある場合はスキップ —matte.cjs/transcribe.cjsはディレクトリ内の任意のビデオを source.mp4 として採用します）→bash scripts/prepare.sh <project>（マット処理 ∥ 文字起こし ∥ オーディオエンベロープを並列実行し、その後、シーンパレット/光学/照明を用いたセーフゾーンv2を実行 — 1つのコマンドで全てをカバー）- 小さなJSONのクリエイティブな選択を作成（最初に
safe-zones.jsonを読む）：Cinematic →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs；Theme →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（被写体の背後に合成されるクライマックスの単語）。Standardモードは両方を行い、クライマックスのみを埋め込みます。§ キャプションモデル を参照してください。 - **ビデオは変更されずに配信されます（Standard/Cinematic；Themeモードの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です（それのみが完全なロックアップ埋め込み + 幅適合レイズを得ます）。小さいものはMINORなクライマックスで、列に沿って特大の強調線として表示されます（前景、減衰した動き）。すべてのビートがマットショーケースを必要とするわけではなく、それがまさにAPEXをイベントとして際立たせている理由です。すべての単語を埋め込むことは、今でもよくある間違いです。
レールサーフェスアイデンティティは、まさにこれを構築します（レール = rail.html、埋め込み = index.html 内のクライマックス）。カラムフローアイデンティティはレールを廃止し、すべてを埋め込みスタイルにします。これらのアイデンティティは、ムード重視で逐語性が重要でない場合（解説動画やナレーションのように単語が読めなければならない場合は不可）にのみ推奨します（CATALOG.md はこれをアイデンティティごとにエンコードしています）。
ステップ 0 — カタログから1つのアイデンティティを選択
1つのフロントエンド、背後に3つのエンジン。 ユーザーは CATALOG.md からアイデンティティを選択します（35エントリ：10のクラシック + 25のテーマ）。エンジン、コンパイラ、および作成ファイルは、カタログ行からのルックアップによって導出されます。「Standard vs Cinematic vs Theme」を質問として提示しないでください — これらはバックエンドの名前です（1つの製品は、複数のエンジンを持つ場合でも1つのUXを持ちます）。カタログはルーティングに必要なすべてをエンコードしています：読み取りサーフェス、ボイス、推奨対象、シーンのニーズ、および実際に近いペア（loud↔ordnance、neon↔neonsign、cream↔stardust）に関する隣接ノート。
アイデンティティの選択は嗜好ゲートです（../hyperframes-core/references/brief-contract.md § 1）：自律モード（「驚かせて」/「決めて」）の場合、自分でショートリストから選択し、なぜそれを選んだかの一文の理由を述べてください。質問はしないでください。
手順：クリップを調査 → カタログから2〜3のアイデンティティをショートリストアップ → 一文の理由とともに1つを推奨 → ユーザーが選択（自律モード：あなたが選択し、理由を述べる）→ そのアイデンティティのファイルを作成します。アイデンティティはエンジンに固定されています（クロスコンボは不可。1つを開くことは検証イベントです — dna/README.md を参照）。
常に推奨事項を提示し、作成する前にユーザーに選択させてください。 黙ってデフォルトにしないでください。
（完全なアイデンティティテーブルは CATALOG.md にあります — ルーティングのための単一の信頼できる情報源。以下のエンジンドキュメントは、各バックエンドの作成契約を説明しています。）
推奨ヒューリスティック：CATALOG.md の「ショートリスト作成ヒューリスティック」を使用してください。これらはアイデンティティレベルです（例：「炸」は ordnance/stomp/terminal/loud をショートリストアップし、何が爆発するかで選択します）。カテゴリレベルではありません。不明な場合 → anchor。
- Cinematic → ロックされたテンプレート用に
plan.jsonを作成し、make-composition.cjsでコンパイルします。 - Theme → 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を試し、それでもダメなら拒否してください（でっち上げられた単語の逐語的なレールは、キャプションがないよりも悪いです）。 - 高速な動きを伴う手ぶれの激しい映像（マットがちらつく）
事前調査プローブ（コストはかからず、最悪の障害を防ぎます）
- ショットカットプローブ。 20%、50%、80% の位置でフレームをサンプリングします。異なる被写体/シーンが現れた場合は、カットの前にクリップをトリミングします。
- レターボックス / ピラーボックスプローブ。 最初のフレームに黒いバーがありますか？安全なコンテンツ矩形を計算し、キャプションの配置をその内部に制限します。
- 輝度プローブ。 キャプション領域の平均輝度をサンプリングします —
60未満→ 明るいテキストはそのままで読めます、60-180→ グリフスクリムを追加、180+→ 不透明テキスト + スクリム（裸の明るいテキストは絶対に避ける）。Cinematicテンプレートはクリーム+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> # マット処理 ∥ 文字起こし（並列）→ セーフゾーン。1つのコマンド。
# → frames_fg/ transcript.json safe-zones.json
3. [エージェントステップ — 唯一のクリエイティブなステップ] 小さなJSONを作成します。以下のモードを参照。
Cinematic: plan.json を作成 → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
Theme: 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/ スナップショット
（Themeモード：ステップ3b/5をスキップ — render-theme.sh がコンパイルと render-and-composite + _postfx.sh を既に実行しています。
成果物は final_fx.mp4 で、final.mp4 はプレートリアクション前のものです）
ステップ1の init は、インストールされているスキルをGitHub上の最新版と比較し、いずれかが古い場合はグローバルセットを更新します。
ステップ3はモードによって異なります：
ステップ 3 — Cinematic モード（純粋な埋め込み）
- 最初に
safe-zones.jsonを読んでください。 ナレーションプレーンはzones.hugLeft/hugRightに配置されます — シルエットに隣接するクリーンなストリップ（テキストが身体から遠いと浮いて見え、埋め込まれているように見えません。遠い角はフォールバックであり、デフォルトではありません）。ヒーローはデフォルトでheroAnchor/heroBands.bestに配置されます（被写体上に中央揃え、約30〜55%がオクルードされます）。recommendation:"fg"は、読みやすさのためにナレーションを前景に移動します。ヒーローはheroBands.feasibleである限り、埋め込まれたままになります — ヒーロー前景は最後の手段です。 - DNAはステップ0で選択したアイデンティティです（CATALOG.md） — ここで選択を再開しないでください。シーンに対してそれを常識的にチェックしてください（明るいヒーローバンドの輝度 > 150 は
inkを必要とします。完全な選択ガイダンスはカタログにあり、neon/glitch/chrome/velocity を含む10個すべてをカバーしています）。選択とその理由を述べてください。ユーザーが決定します。DNAはタイプ/パレット/ブレンド/モーション + ヒーロー三部作をロックします。セーフゾーンv2（palette/optics/lighting）は、これを自動的に_この_シーンにパラメータ化します。 <project>/cinematic.jsonを作成 —"dna": "<name>"+ 思考ブロック（生のグループではありません）。各ブロック = 単語の行（節の境界で2〜5語にグループ化）+ それが積み重なるプレーン + 行ごとのcss（サイズ/ウェイト/スタイルのみ — 位置はなし）+ 多くとも1行が"hero": trueとマークされる（プロモーションされた単語。表示フォームには"text"）。スキーマ：scripts/make-cinematic.cjsヘッダー。- コンパイル：
node scripts/make-cinematic.cjs <project>— ブロックを plan.json → index.html に変換します。あなたのために生成されるもの：文字起こしにシーケンスされたタイミング、ブロック内での蓄積、ブロック間でのページフリップ、ヒーローロックアップ（ヒーローブロックの事前コンテキスト、ヒーロー、および事後コンテキストが、被写体上に中央揃えされた1つの結合コンポジションとしてスタックされます — 読み順は上→下 = 構築による発話順。コンテキストは前景に浮かび、ヒーローは背後に埋め込まれます = デプスサンドイッチ。マスルールはヒーローがそのコンテキストを支配するようにします）、APEX/マイナーヒーローの分割、構築による読み順、セーフゾーンごとの前景フォールバック。その後、通常通りゲートが実行されます。（plan.json を直接手動で作成することも可能です。その場合は、fill-timings.cjs+fit-fonts.cjs+make-composition.cjsを自分で実行してください。）
ステップ 3 — Theme モード（テーマ化された構成）
最初に themes/README.md を読んでください — パラダイム/セットピースのレジストリ、リンケージ、ハードルール、および正確な theme.json スキーマ。
- コンテンツレジスターによってテーマDNAを選択します（各
themes/<name>.jsonにはvoice+whenがあります）。選択とその理由を述べてください。ユーザーが決定します。 <project>/theme.jsonを作成 —dna、lines（逐語的、文字起こし順序。1行/行、オプションのhero/fx、俯瞰的なtimeはなし —make-theme.cjsがコンパイルします）。詳細なスキーマは themes/README.md にあります。- コンパイル+レンダリング：
bash scripts/render-theme.sh <project>— コンパイル → レンダリング → ポストエフェクト（プレートリアクション）→ 最終出力final_fx.mp4。（内部ではmake-theme.cjs→fit-fonts.cjs→make-composition.cjs、次にrender-and-composite.sh、最後に_postfx.shを実行します）。final.mp4はプレートリアクション前のマイルストーンです。
キャプションクラフト — レール（Standard）
レールは、キャプションの作業馬です。これは、前景に表示されるクリーンな逐語的な下部3分の1の字幕であり、すべての通常の話し言葉を伝達します。レールのルールブック全体は references/rail.md にあります。以下は要点です：
- 常に可視：話されている間、レール上に表示され、埋め込みの邪魔にはなりません（レールは前景にあり、埋め込みは被写体の背後にあります）。
- 逐語的：えーと、あのー、言い間違いを含む、話されたすべての単語が表示されます。
transcribe.cjsからのフィルタリングはありません。 - クリーンなタイポグラフィ：最小限のスタイリング、高い可読性。各アイデンティティのDNAに従います。
- 進行状況の強調：現在の単語がハイライトされることがあります（アクティブワードポップ）。
レールビルダースキーマ（<project>/rail.json）：
"lines": テキスト行の配列。各々が"text"（表示テキスト）、"start"（秒単位の開始時間）、"end"（秒単位の終了時間）。"style": オプションのCSSオーバーライド（フォントサイズ、色、配置）。- 注：レールJSONは、
scripts/make-cinematic.cjsまたはscripts/make-theme.cjsによって自動的に生成されます。通常は手動での作成は必要ありません。
キャプションクラフト — 埋め込み（Cinematic / Standardのクライマックス）
埋め込みキャプションは、スキルの差別化要因です。それらは被写体の背後に合成され、被写体がテキストの一部を覆い隠す（オクルードする）ことで、奥行きと没入感を生み出します。完全なクラフトガイドは references/composition-craft.md にあります。
主要な概念：
- オクルージョン：前景の被写体が、背後にある埋め込みテキストの一部を自然に覆い隠します。これにより、テキストがシーンに「属している」ように見えます。
- ロックアップ：ヒーローブロック（事前コンテキスト、ヒーローワード、事後コンテキスト）は、被写体上に中央揃えされた1つの結合コンポジションとしてスタックされます。読み順は上から下へ、話される順序と一致します。
- APEX vs マイナー：複数のヒーロービートの中で、最も大きなものだけが完全なロックアップ埋め込み（幅適合レイズ、完全なエフェクトスタック）を得ます。他のものは、同じ列内の強調された線として扱われます。
- タイミング：各ヒーワードは、明確な入場、保持、および退場のアニメーションを持ちます。保持時間は、単語の長さと音声のテンポに基づいてコンパイラによって計算されます。
- ビジュアルQA：レンダリングする前に、
node scripts/preview-frames.cjs <project>を使用してコンポジットをプレビューします。これにより、約2秒/フレームで忠実なプレビューが生成され、高価なフルレンダリングをコミットする前に結果を確認できます。
ビジュアルQA（ステップ4 — レンダリング前）
レンダリングを実行する前に、合成結果を確認することが重要です。
node scripts/preview-frames.cjs <project>
プレビューフレームを確認するために、以下の手順を実行します：
- 生成されたフレームを
<project>/preview/で確認します。 - レイアウト、タイミング、オクルージョンに問題がないかチェックします。
- 問題がある場合は、JSONファイル（
plan.jsonまたはtheme.json）を調整し、ステップ3と4を繰り返します。 - すべてが良好な場合にのみ、ステップ5に進みます。
よくある問題と修正：
- 不自然なオクルージョン：
safe-zones.jsonのヒーローバンド位置を調整するか、plan.jsonでヒーローの配置を変更します。 - テキストが小さすぎる/大きすぎる：
cinematic.jsonまたはtheme.jsonでフォントサイズを調整するか、ドメイン設定を確認します。 - タイミングが合わない：
transcript.jsonのタイムスタンプを確認します。必要に応じてfill-timings.cjsを再実行するか、タイミングを手動で微調整します。
トラブルシューティング / よくある問題
| 問題 | 診断と修正 |
|---|---|
| マットがちらつく / 被写体のエッジが粗い | scripts/prepare.sh のマット処理パラメータを増やします。詳細については scripts/matte/README.md を参照してください。 |
| 埋め込みテキストが被写体の前に表示される | safe-zones.json の heroBands 設定を確認します。テキストが前景に設定されていないか確認します (recommendation:"fg")。 |
| レールのテキストが読めない | アイデンティティを変更するか (ink は暗いシーンに適しています)、safe-zones.json で fg フォールバックを強制します。 |
| 文字起こしが不正確 / 意味不明 | 最初に WHISPER_MODEL=medium を試します。それでもダメなら、クリップを拒否します（誤ったキャプションは最悪です）。 |
render-and-composite.sh が特定のゲートで失敗する | ゲートメッセージを確認します：「TIMING」→ タイムラインを確認、「OCCLUSION」→ ヒーローが適切にオクルードされているか確認、「OVERFLOW」→ テキストが領域に収まっているか確認。 |
テーマモードで _postfx.sh がエラーを出す | テーマDNAが有効で、必要なすべてのアセットが利用可能であることを確認します。themes/<name>.json を参照してください。 |
付録：ファイル構造（<project> ディレクトリ内）
<project>/
├── source.mp4 # 元の動画ファイル（scripts/prepare.sh によってコピーされる）
├── frames_fg/ # 前景フレーム（マット処理済み、被写体を含む）
├── frames_bg/ # 背景フレーム（被写体なし）
├── transcript.json # 文字起こし結果
├── safe-zones.json # セーフゾーン、パレット、光学、照明のデータ
├── plan.json # Cinematicモード：コンパイルされたタイミングと配置（make-cinematic.cjs の出力）
├── cinematic.json # Cinematicモード：エージェント作成のブロック定義（入力）
├── theme.json # Themeモード：エージェント作成のテーマ定義（入力）
├── index.html # 埋め込みコンポジション
├── rail.html # レールコンポジション（Standardモード）
├── preview/ # ビジュアルQAプレビューフレーム
├── final.mp4 # 最終出力（Standard/Cinematicモード）
├── final_fx.mp4 # 最終出力（Themeモード、プレートリアクション後）
└── history/ # 以前のバージョンのスナップショット
付録：標準モードの動作例
- ユーザーが「この解説動画にキャプションを追加して」と要求します。
- エージェントがクリップを調査し、単一の被写体がはっきりと映っていることを確認します。
- エージェントが CATALOG.md から適切なアイデンティティ（例：
anchor）を推奨します。ユーザーが承認します。 - エージェントが
hyperframes initとscripts/prepare.shを実行します。 - エージェントが
safe-zones.jsonを読み込み、cinematic.json（Standardモードのため、1つのクライマックスブロックのみ）を作成します。 - エージェントが
scripts/make-cinematic.cjsを実行し、plan.jsonとindex.html（埋め込み）+rail.html（レール）を生成します。 - エージェントが
node scripts/preview-frames.cjsで結果をプレビューします。問題がなければレンダリングに進みます。 render-and-composite.shが最終的なfinal.mp4を生成します。すべてのキャプションが追加され、元の映像は変更されていません。