embedded-captions

プラグインのインストール： セットアップや最新状態の確認コマンドを実行する前に、このスキルが HyperFrames プラグイン内にある場合は、プラグインの実行ルールに従ってください。スタンドアロンでインストールした場合は、以下の更新手順をそのまま使用します。

まず、このスキルを最新の状態に保ってください。実行前にユーザーに確認します： npx hyperframes skills update embedded-captions。すべて最新であればすぐに何もせず終了します。それ以外の場合は、このスキルと依存するコアドメインスキルを更新してから利用します。

埋め込みキャプション

カタログは1つ、最初に選択します（CATALOG.md — 35種類。背後で動作するエンジンはバックエンドの詳細です）。Standard（デフォルト）では、内容をそのまま伝えるすっきりしたレール（テキストの大半を担う下部字幕）と、クライマックスで被写体の背後にあるシーンに合成される埋め込みを作成します。Cinematicは埋め込みのみで、レールはなく、すべてのキャプションが被写体の背後に合成されます（ヒーロータイポグラフィ、蓄積、オクルージョンが演出効果になります）。Themeは、完全にテーマ化された構成で、ボディのパラダイム × ヒーローのセットピース × 前景エフェクト × プレートの反応をレジストリから組み合わせます（themes/README.md）：ordnance terminal neonsign stardust stomp。解説動画やナレーションの大半にはStandardが適しています。埋め込みは貴重な、ふさわしい場面に限るピーク演出です。すべての単語を埋め込むのはよくある間違いです。ThemeはVFX品質を求める依頼（「炸」、「特效」、「像 AE 做的」）に適しています。

---

ランタイムの前提条件

プラグインのインストールでは、マッティング、文字起こし、レンダリングにマニフェストでバージョンが固定された同梱のCLIを使用するため、ソースチェックアウトは不要です。ローカルプレビューとキャプション計測ヘルパーには、Sharp、Puppeteer（Chromiumブラウザーを含む）、GSAPも必要です。これらは読み取り専用プラグイン内ではなく、キャプションプロジェクトにインストールしてください。

npm install --prefix <project> --save-dev --save-exact [email protected] [email protected] [email protected]

プロジェクトのロックファイルは保持してください。これらの依存関係がすでにある場合は、上書きせず、ロックされているバージョンを使用してください。BashとFFmpeg/ffprobeがPATH上にある必要があります。マッティングと文字起こしでは、初回使用時に独自のモデルをダウンロードする場合があります。

レンダリングでは、合成を行う前にCLIが正常終了するまで待機します。旧式のHF_TIMEOUT_Sシェルウォッチドッグは使用されなくなりました。大きな部分ファイルがあるからといって、レンダリングが完了した証拠にはなりません。ビルド済みチェックアウトの明示的な引数、またはHYPERFRAMES_ROOTを指定すると、プラグインで固定されたCLIではなく、コントリビューター向けCLIが選択されます。停止したレンダリングは、CLIまたはターミナルから通常の方法でキャンセルしてください。キャプションヘルパーはプロセススナップショットからレンダリングを強制終了したり、復旧したりしません。

運用フロー（概要）

/hyperframes 経由でルーティングされる場合、インテント層が確認するのは入力（どのクリップか）だけです。また、アイデンティティの選択は後回しにすると伝えます。候補を絞り込むにはクリップのプローブが必要なため、以下のステップ1で行います。レイヤーの実行形式に関する質問は該当しません（映像素材には手を加えず、レビューするストーリーボードもありません）。BRIEF.md がある場合は、確認済みの入力とユーザーのメモが記載されているため、最初に読みます。

以下の制作に関する説明は長いですが、パイプライン自体は短く、決定論的な処理はすべて計算またはコンパイルで行い、手書きはしません。

1. 判定ゲート（不適切なクリップを拒否）→ CATALOG.md からアイデンティティを1つ選択（アイデンティティは35種類。エンジン／コンパイラーは参照によって導出されます。モード／カテゴリーに関する質問は決して表示しません）
2. hyperframes init（プロジェクトディレクトリがすでに存在し、その中に動画がある場合は省略します。matte.cjs／transcribe.cjs はディレクトリ内の動画を source.mp4 として採用します）→ bash scripts/prepare.sh <project>（matte ∥ transcribe ∥ 音声エンベロープを並列処理し、その後、シーンのパレット／光学特性／ライティングを使って safe-zones v2 を実行します。コマンドは1つだけで、抜けはありません）
3. クリエイティブな選択を小さな JSON に記述（最初に safe-zones.json を読みます）。Cinematic → cinematic.json → make-cinematic.cjs（plan.json を導出してコンパイルします）。Theme → theme.json → make-theme.cjs（rail／panel／poem／takeover の各パラダイム。anchor は控えめな rail のデフォルトです）
4. ビジュアル QA：node scripts/preview-frames.cjs <project> → 合成プレビューを忠実に再現（1フレーム約2秒、レンダリングなし）。レンダリングを実行する前に「§ ビジュアル QA」を確認してください。
5. render-and-composite.sh → ゲート（タイミング／オクルージョン＋ヒーロー／はみ出し／引き継ぎ）→ final.mp4

見落とされやすい重要なルール：

• rail（デフォルト）＋embed（昇格）。 drop（フィラー。表示しない）／rail（字幕をそのまま表示する下部テロップ。手前に表示され、ほとんどのテキストを担います）／embed（被写体の背後に合成するピークワード）。標準モードでは両方を使い、ピークのみを embed にします。「§ キャプションモデル」を参照してください。
• 動画はそのまま納品します（Standard／Cinematic。Theme モードの PLATE 予算だけは認められた例外です。テーマの DNA ごとに定義された、レジスターで制御するリアクションのビート（charge-dim、punch、shake、grain）を、マット合成の後に適用するため、被写体＋テキスト＋プレートが一体となってフレーム内で動きます）**。追加するのはキャプションだけです。マットは被写体で embed トラックを遮蔽できるようにするだけです。映像素材のカラーグレーディング／色変更／走査線処理は決して行いません。
• ルールブックは2つです。rail → references/rail.md（簡潔）、embed の制作技法 → references/composition-craft.md（詳しい説明。embed 専用）。必要に応じて目を通してください。

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

話されたフレーズは、すべて次の3種類のいずれかです。

	内容	表示方法
drop	フィラー — えーと、あのー、言いよどみ、言い直し	表示しない
rail	デフォルト — 通常の話し言葉（逐語）	読みやすい、画面下部の字幕。手前に表示します。強調したい語には、インラインのemphasisハイライト（アクセントカラー／アクティブな語のポップ表示）を付けられます。レール上に表示されます。
embed	昇華されたピーク — 見出しとなる瞬間	大きな単語を1つ、合成して被写体の背後に表示します（マットによるオクルージョン）。演出を加えた登場と退場を設計します。

ほとんどのテキストを担うのはレールで、embedは希少で、獲得されたピークです。 希少性はクリップ単位ではなく、ビート／ブロック単位です。1ブロック（思考）につきヒーローは最大1つで、同時に2つ表示されることはなく、ヒーローの表示ウィンドウの間には少なくとも1ビート分の間隔を空けます（0.6秒未満の場合、コンパイラーが警告します）。短いクリップなら通常1〜2つ、長い解説動画ならセクションごとに約1つです。複数のヒーローのうち、制作者が設定した最大のものがAPEXです（フルロックアップの埋め込み＋幅に合わせた引き上げが適用されるのはこれだけです）。小さいものはMINORピークとして、列に沿って特大の強調行（前景、抑えた動き）で表示します。すべてのビートにマットを使った見せ場が必要なわけではありません。それこそが、APEXを特別なイベントに保つ方法です。すべての単語を埋め込むのは、今でもよくある間違いです。

レール面のアイデンティティでは、まさにこの構成を採用します（レールはrail.html、埋め込みはindex.htmlのクライマックスです）。列フロー型のアイデンティティではレールをなくし、すべてを埋め込み型にします。これらは、言葉を逐語的に伝える必要がある解説／ボイスオーバーではなく、逐語性よりムードを重視する依頼にのみ推奨します（各アイデンティティでの扱いはCATALOG.mdに記載されています）。

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

フロントエンドは 1 つ、裏側には 3 つのエンジン。 ユーザーは CATALOG.md（全 35 項目：クラシック 10 項目＋テーマ 25 項目）からアイデンティティを選びます。エンジン、コンパイラー、作成ファイルは、カタログの行を照合して決まります。「Standard と Cinematic と Theme のどれにしますか？」とは決して尋ねないでください — これらはバックエンドの名称です（エンジンが複数あっても、製品の UX は 1 つです）。カタログには、ルーティングに必要なすべての情報が含まれています。視聴面、声、推奨対象、シーンの要件、そして本当に似ている組み合わせ（loud↔ordnance、neon↔neonsign、cream↔stardust）の隣接メモです。

アイデンティティの選択は好みを確認するゲートです（../hyperframes/references/brief-contract.md § 1）。自律モード（「おまかせ」／「決めて」）では、候補リストから自分で選び、質問する代わりに、理由を一文で述べてください。

手順：クリップを確認 → カタログからアイデンティティを 2〜3 個に絞る → 理由を一文添えて 1 つを推奨 → ユーザーが選択（自律モードでは、理由を述べて自分で選択）→ そのアイデンティティのファイルを作成します。アイデンティティはエンジンに固定されています（エンジンをまたぐ組み合わせは不可。開くことは検証イベントです。dna/README.md を参照してください）。

作成に入る前に、必ずおすすめを提示してユーザーに選んでもらってください。 黙ってデフォルトを選ばないでください。

（アイデンティティの一覧は CATALOG.md にあります。ルーティングの唯一の信頼できる情報源です。以下のエンジンのドキュメントでは、各バックエンドの作成仕様を説明します。）

ここでの選択肢は CATALOG.md の内容がすべてです。このワークフローでは HyperFrames のコンポーネントレジストリを検索しません。 構成ワークフローでは、名前付きのルックを作成する前に npx hyperframes catalog を実行しますが、このワークフローでは実行してはいけません。各エンジンは固定されたコンパイラーで、cinematic.json／theme.json を読み込み、構成を自ら出力します。そのため、レジストリ項目（caption-* ブロックも含む）を配置する場所はありません。レジストリのブロックはデザイン済みのキャンバス上のテキストにスタイルを適用しますが、このスキルはマットを使って人物の映像に字幕を焼き込みます。要望に合うアイデンティティがない場合は、カタログ外のものを探さず、そう伝えたうえで最も近いものを選んでください。

おすすめの判断基準：CATALOG.md の「候補を絞るためのヒューリスティクス」を使ってください。基準はアイデンティティ単位です（例：「炸」なら ordnance／stomp／terminal／loud が候補になり、何を爆発させるべきかで選びます）。カテゴリ単位ではありません。迷った場合は anchor を選んでください。

• Cinematic → 固定テンプレート用に cinematic.json を記述し、make-cinematic.cjs でコンパイルします。
• Theme → themes/README.md を読み、theme.json を作成して、scripts/render-theme.sh を実行します（コンパイル＋レンダリング＋プレートリアクション → final_fx.mp4）。

---

判断ゲート — 最初に実行

どちらのモードに進む前にも、動画を確認してシーンを分類します。

ffprobe <video.mp4>                    # specs
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png   # at 20/50/80%

サンプルを確認します。次の場合は受け付けないでください。

• 複数の話者がいる／ハードカットがある（ショットごとに分割してレンダリングするか、受け付けないでください）
• 人物が映っていない（このスキルはトーキングヘッド向けです）
• 3 秒未満、音声がない、または顔が一度もはっきり見えない — 音声がほぼ無音の場合、transcribe.cjs は警告を出します（Whisper は無音の上に「Thank you.」のような語句を幻聴することがあります）。警告に従い、受け付けないでください。 作り上げた言葉に字幕を付けてはいけません
• ソース動画に字幕／キャプション／目立つテキストグラフィックがすでに焼き込まれている — 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％の位置でフレームをサンプリングします。異なる被写体やシーンが現れた場合は、カットの前でクリップをトリミングしてください。
2. レターボックス／ピラーボックス検出プローブ。 最初のフレームに黒帯がありますか？ コンテンツのセーフ領域を計算し、字幕の配置をその内側に制限します。
3. 輝度プローブ。 字幕領域の平均輝度をサンプリングします — under 60 → 明るい文字はそのままで読み取れます。60-180 → 字形のスクリーンを追加します。180+ → 不透明な文字＋スクリーン（明るい文字をそのまま使うのは不可）。シネマティックテンプレートはクリーム色＋screenで固定されています — このプローブは 適したアイデンティティを選ぶ ために使います（明るいシーンでは ink、または不透明なレールの anchor テーマ）。色の変更には使いません。
4. トーンに基づくアイデンティティの推奨（推奨するのはあなた、選ぶのはユーザー — Step 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 (parallel) → safe-zones. One command.
                                           #   → frames_fg/ transcript.json safe-zones.json
3. [AGENT STEP — the only creative step] author a small JSON; see below by mode
   Cinematic: author cinematic.json → node scripts/make-cinematic.cjs <project>
   Theme:     author theme.json → bash scripts/render-theme.sh <project>   (compiles + renders + plate fx)
4. node scripts/preview-frames.cjs <project>   # ~2s/frame composite previews → § Visual QA (BEFORE the render)
5. bash scripts/render-and-composite.sh <project>  # gates → final.mp4 + history/ snapshot
   (Theme mode: SKIP steps 3b/5 — render-theme.sh already runs compile + render-and-composite
    + _postfx.sh; the deliverable is final_fx.mp4, final.mp4 is pre-plate-reaction)

Step 1 の init は、インストール済みスキルを GitHub 上の最新バージョンと照合し、古いものがあればグローバルセットを更新します。

Step 3 はモードによって異なります。

Step 3 — シネマティックモード（純粋な埋め込み）

1. まず safe-zones.json を読みます。 ナレーション面は zones.hugLeft／hugRight に配置します — シルエットに隣接する空いた帯です（身体から離れたテキストは埋め込まれず、浮いて見えます。遠くの隅は代替位置であり、デフォルトではありません）。ヒーローはデフォルトで heroAnchor／heroBands.best に配置されます（被写体の中央に重なり、約30〜55％が隠れます）。recommendation:"fg" は読みやすさのためナレーションを前面に移動します。heroBands.feasible の場合、ヒーローは常に埋め込んだままにします — hero-fg は最後の手段です。
2. DNA は Step 0 で選んだアイデンティティ（CATALOG.md）です — ここで選び直してはいけません。シーンに合っているか確認します（ヒーロー帯の輝度が150を超える場合は ink が適しています。ネオン／グリッチ／クローム／速度感を含む10種類すべての詳細な選択ガイダンスはカタログにあります）。選んだものと理由を説明し、決定はユーザーに委ねます。DNA はタイポグラフィ／パレット／ブレンド／モーション＋ヒーローの三幕構成を固定します。safe-zones v2（palette／optics／lighting）が、それをこのシーンに合わせて自動的にパラメーター化します。
3. <project>/cinematic.json を作成します — "dna": "<name>" と、raw groups ではなく thought-BLOCKS を記述します。各ブロックは、言葉の行（節の区切りに沿って2〜5語をまとめたもの）＋積み重ねる面＋行ごとの css（サイズ／ウェイト／スタイルのみ — 位置は指定しません）で構成し、"hero": true とマークする行は最大1行（強調する語。表示形式には "text" を指定）です。スキーマは scripts/make-cinematic.cjs のヘッダーを参照してください。
4. コンパイルします：node scripts/make-cinematic.cjs <project> — ブロックを plan.json → index.html に変換します。次の要素は自動生成されます：トランスクリプト順のタイミング、ブロック内での累積表示、ブロック間のページ切り替え、ヒーローのロックアップ（ヒーローブロックの前置きコンテキスト、HERO、後置きコンテキストが、被写体を中心に配置された1つの結合構成として積み重なります — 上から下への読み順は、構造上、発話順になります。コンテキストは前面に浮かび、ヒーローは背後に埋め込まれます＝深度のサンドイッチです。質量ルールにより、ヒーローがコンテキストより目立ちます）、頂点／小規模なヒーローの分割、構造によって保証される読み順、safe-zones に基づく前景へのフォールバック。その後、通常どおりゲートを実行します。(デザインで表現できない場合は、plan.json を直接手作業で作成することもできます。その場合は、自分で fill-timings.cjs ＋ fit-fonts.cjs ＋ make-composition.cjs を実行してください。)

ステップ 3 — テーマモード（テーマ化された構成）

最初に themes/README.md を読んでください — パラダイム／セットピースのレジストリ、関連付け、厳守ルール、正確な theme.json スキーマを確認します。

1. テーマの DNA を選びます。コンテンツの文体に合わせてください（各 themes/<name>.json には voice と when があります）。選んだテーマと理由を伝え、ユーザーに決定してもらいます。
2. <project>/theme.json を作成します — dna、lines（原文どおり、トランスクリプトの順序で、各 1～5 語 — takeover の場合、各行は 1 枚の CARD）、minors（強調する語）、hero:{match}（クライマックスとなる語句。埋め込み型セットピースでは lines に含めず、インライン型セットピースと panel+redact では lines に含めます）。
3. レンダリング：bash scripts/render-theme.sh <project> — コンパイル時に原文完全性ゲートを適用してコンパイルし、両方のレイヤーをレンダリングして合成し、プレートのリアクションを適用して final_fx.mp4 を生成します。ビジュアル QA には、コンパイル後、レンダリング前に preview-frames.cjs を使用します。

---

ビジュアル QA — レンダリング前にプレビューする

node scripts/preview-frames.cjs <project> [t…] は、忠実なプレビューフレームを約 2 秒で合成します（シーク時点の字幕レイヤーのスクリーンショット + 実際の動画フレーム + マットによるオクルージョン + レールオーバーレイ = その時点で最終合成がどのように見えるか）。既定のサンプルは各グループ／クライマックスの区間です。フルレンダリングには数分かかります。レイアウトの問題を見つけるために使ってはいけません。

プレビュー（<project>/preview/sheet.png）を次のリストと照合してください。これらは幾何学的なゲートでは検出できない問題です。

1. 白飛び — 明るい領域（窓／看板／空）に明るい文字を重ねると、読めなくなります → 平面を移動するか DNA／モードを変更します（明るいシーン → ink）。
2. 文字同士の重なり — シーン内の文字／グラフィックの上に字幕が重なる、または 2 つの字幕グループが衝突する。
3. 読み順 — 画面上の上下の順序は話された順序と一致させます。ヒーローが後続の語より下に来てはいけません。
4. ヒーローの存在感 — クライマックスは大きく、被写体の背後に見える状態（約 30～55% が隠れる）にします。余白に浮かぶラベルにしてはいけません。
5. バランス — 断片を散らすのではなく、まとまりのある列／帯にします。余白にゆとりを持たせ、何も切れないようにします。

次に、references/reference-bar.md の5 つのポジティブチェック（ポスターテスト · 控えめすぎないかのテスト · 一目でわかる階層 · シーンとの調和 · 無音区間の監査）を行います。失敗チェックリストはレンダリングが破綻するのを防ぎ、ポジティブチェックリストはデザインとしての完成度を高めます。両方に合格したら納品できます。

新鮮な目でのレビュー（ユーザー向けの成果物では推奨）： 自分のレイアウトには確証バイアスがかかります。サブエージェントを起動できる場合は、プレビューシートとこのチェックリストだけを渡して、フレームごとに PASS／FIX の判定を求めます（「この字幕プレビューを 5 項目のチェックリストに照らしてレビューし、各フレームについて PASS または具体的な修正点を回答してください」）。修正を cinematic.json／theme.json に適用し、再コンパイルして再プレビューします。各ループは数秒です。プレビューに合格してから、一度だけレンダリングします。

DNA レジストリ — 10 種類のビジュアル言語（テンプレートカタログを置き換え）

どちらのモードも dna/ を参照します。シーンごとにパラメーターを設定する、アートディレクション済みの 10 種類のビジュアル言語です（映像からサンプリングしたアクセントカラー、測定した光の方向に沿った接触影、深度に合わせたぼかし、RMS に連動したヒーローの振幅）。

DNA	レジスター	シーンへの適合性	表現
cream	プレミアム・ウォーム	暗め／中間調の暖色系シーン	Inter ＋ 暖かみのあるクリーム色 ＋ スクリーン合成。光りながら現れるヒーロー（cinematic-cream の後継）
ink	プレミアム	明るいシーン（luma > 150）	ほぼ黒の乗算合成 — 壁に直接印字された文字。明るいシーン向けの選択肢
editorial	エディトリアル・ラグジュアリー	内省的／ファッション／詩的	Bodoni Moda、ヒーローは小文字のイタリック — 雑誌のような優雅さ
keynote	テック・プレミアム	製品／ローンチ	不透明な白の Inter 800、中央に静止
documentary	フォーマル	インタビュー／シリアス	焼き付け表示で文字が現れる。ヒーローなし — 重厚さそのものがスタイル
loud	ラウド	ハイプ／スポーツ／ソーシャル	Anton ＋ シーンからサンプリングしたアクセントカラー、単一ユニットの強打と波紋。本文は前景に表示（bodyLayer: fg）
neon	ラウド・ネオン	ネオンノワール／ナイトライフ／テックノワール（暗いシーン）	エレクトリックシアンのサイン、点火時のちらつき、サインのようにヒーローが点灯
glitch	ラウド・ネオン	デジタル／ハッカー／AI	着地時に RGB 分離した残像が一つに重なる。機械的なパーカッシブなタイミング
chrome	ラウド・ラグジュアリー	Y2K／ファッションテック／音楽	液体金属のグラデーションを施したヒーロー ＋ ホールド中に一度だけ光沢が走る
velocity	ラウド・スポーツ	スポーツ／自動車／フィットネス	各単語が動きのベクトルに沿って登場（残像＋傾斜）。ヒーローはスピードトレイルを伴って通過

safe-zones.json（heroAnchor.bandLuma、palette.temperature）× コンテンツのレジスターを基準に選びます。選択ルールは dna/README.md をご覧ください。作成時は cinematic.json に "dna": "<name>" を指定します。

エンジンは DNA からヒーローの三幕構成を生成します（作成者による設定は不要です）。同時に表示される字幕が暗くなり（導入）、音量に比例した振幅で文字ごとに登場し（インパクト）、退出するまで呼吸するように輝きます（余韻）。

（レガシー：plan.template:"cinematic-cream" は自動的に dna:"cream" にマッピングされます。廃止された 54 種類のテンプレートライブラリはこのリポジトリの外にアーカイブされており、このスキルには同梱されていません。_motion.md は、モーションを表す動詞のリファレンスカタログとしてスキル内に残っています。）

美的判断 — トーン × ショット × プラットフォーム（カタログの候補選定への入力であり、2つ目のルーターではありません）

3つの軸でクリップを分類し、その結果をCATALOG.mdの候補選定に反映します。このセクションだけでモード／エンジンを選択することはありません。

トーン（コンテンツはどのような雰囲気ですか？）

• ドキュメンタリー | 対話的 | エネルギッシュ | 詩的 | 基調講演 | 調査報道 | ミュージックビデオ

ショット（フレーミングはどのようなものですか？）

• クローズアップ（頭部＋肩） | ミディアムショット（胴体以上） | ワイド（全身以上） | カットモンタージュ（複数のショット）

プラットフォーム（どこで再生しますか？）

• 9:16 縦向き（TikTok/IG/Shorts） | 16:9 横向き（YouTube/web） | 1:1 正方形 | 放送用書き出し

演出に関する用語は、references/direction-catalog.md § Classification matrixを参照してください。その後、CATALOG.mdに戻って候補となるアイデンティティを絞り込みます（このマトリックスは候補選定に役立つものであり、ルーティングを行うのはカタログのみです）。

コンポジションの技法（埋め込みトラック）— 埋め込みの前にお読みください

embed-trackのプレイブック全文は**references/composition-craft.mdにあります。文字起こしの役割注釈、フレーズのグループ化、平面とクリーンゾーンの固定、ゾーンの一貫性、クライマックスの強調と可読性、エッジの余白、遮蔽に関する3段階の判断、蓄積と持続について説明しています。これは、_昇格した_フレーズをシーンにどう配置するかを定めるものです。埋め込みを作成する前にお読みください（Cinematic cinematic.json または Standard index.html）。デフォルトのrail**トラックには、よりシンプルな独自仕様があります → references/rail.md。

---

共通ナレッジ

ドキュメント	内容
references/rail.md	レールトラック — 標準の下部テロップ仕様（デフォルト。テキストの大部分を表示します）。
references/composition-craft.md	埋め込みトラックの実践ガイド — グループ化、プレーン、クライマックス時のポップ、オクルージョンの判断、蓄積／持続性。埋め込む前にお読みください。
dna/README.md	DNA レジストリ — シーンごとにパラメーター化された10種類のビジュアル言語と、その選び方。
references/reference-bar.md	品質基準 — 各レジスターの世界水準の参考例と、5つのポジティブチェック。
references/aesthetic-principles.md	18のルール。 センスでVeed AIを上回るためのものです。まずお読みください。
references/motion-vocabulary.md	名前付きモーションプリミティブ10種と、トーンからタイミングを引く早見表
references/direction-catalog.md	すぐに使える美学10種と、トーン×ショット×プラットフォームのマトリクス
references/anti-patterns.md	すでに排除済みのバグ（CoreML、letter-spacingによるリフローなど）
references/scene-types.md	壁面を使用できる条件（4つ）
references/layout-heuristics.md	プレーンの配置、クリーンゾーンの選定、クラウンの3条件、ピラーボックスの計算
references/typography-presets.md	フォントサイズ×カラム幅のマトリクス（初期値）
references/caption-grouping.md	単語からグループへのルール（間、文の区切り）
references/failure-modes.md	開発時に注意すべき、見落とされがちな問題
references/bespoke-vs-presets.md	プリセットがうまくいかない場合がある理由と、複製して調整するパターン

美学の原則とディレクションカタログを最初にお読みください。 それ以外はすべて実装の詳細です。

---

絶対条件

• 顔が常に 100% 覆われてはいけない — 0.3 秒ごとのウィンドウで、顔の bbox は 30% 以上が覆われていないこと。
• WCAG コントラスト — 最終レンダーでリントします。失敗したらパレットを修正してください。
• 決定論的 — Math.random()、Date.now()、repeat:-1 は使わないでください。
• 動画をグレーディング/再着色してはいけません。 映像はそのまま出荷されます — キャプションだけが唯一の追加要素です。a-roll の上に全画面のスキャンライン / デュオトーン / 暗転 / ビネットを重ねないでください。neon-noir/CRT テクスチャはフレーム全体の上ではなく、キャプション要素の 内側 に属します。
• トーキングヘッド / 解説ではレール優先。 文字起こし全体を埋め込まないでください — テキストの大半はレールであり、埋め込むのはピークだけです。すべてを埋め込むのはデフォルトの間違いです。
• 埋め込みは希少かつ間隔を空ける。 1 文/ビートあたり埋め込みは ≤1 で、隣接したり同時に表示されたりしないこと、少なくとも 1 ビート以上離すこと、apex は最大 1 つです。クライマックス = ビートごとのピークであり、決して「クリップ全体の唯一の見せ場」ではありません。
• マット = 人物（hyperframes remove-background、u2net_human_seg、Apache-2.0）。 人間のセグメンテーションは意図によるものですが、外科的ではありません。細いオフセット備品（マイクブームアーム）は通常除外されます — キャプションはその上、人物の背後にレンダリングされます — 一方、被写体の NEAR にある大きな顕著なオブジェクト（望遠鏡、デスクリグ）はマットに漏れ込み、キャプションを遮蔽する可能性があります。被写体が HELD するオブジェクト（製品、電話）は断続的に抜け落ち、キャプションが前面を通過することがあります。決して仮定しないでください。hero を配置する前に 2〜3 のタイムスタンプで frames_fg/ をサンプリングし、漏れ出た備品を避けた hero 位置を優先してください（heroAnchor は漏れによって歪む可能性があります — frames_bg とクロスチェックしてください）。
• safe-zones は備品に盲目です — 使用するすべてのバンドを目視確認してください。 ゾーン/heroBands は 被写体 の遮蔽 + 輝度のみをスコアリングします。「クリーン」なゾーン内にマイク、望遠鏡、スクリーンがあってもそれらには見えません（そしてマットに漏れ込む備品は heroAnchor.centerXPct を人物からずらします）。作成前に、使用する予定の各バンドのフレームを 1 枚抽出してください。そこに備品があれば、その bbox を測定し、プレーンを移動/縮小してください。2 つの実際のケースは、エージェントがまさにこれを実行したからこそクリーンに出荷されました。（自動備品顕著性は既知のギャップです。ゾーンの peakLuma は 動く 明るいオブジェクトしか捉えません。）
• キャプションはフレーム内に留まる。 シネマティックモードはフレームオーバーフローをハードゲートします。標準モードは check-overflow.cjs を WARNING として実行します（意図的なブリードだけが唯一の例外です — 警告を読んでください）。
• 各キャプションは画面に ≥ 0.5 秒 — それより短いと読めません。
• 単語のタイミングは transcript.json と 80ms 以内で一致しなければならない — キャプションが 500ms ずれて発火すると、シーンの幻想が破壊されます。シネマティックはレンダリング前に check-timing.cjs --strict を実行します（render-and-composite.sh 経由）。THEME モードは代わりにコンパイル時に同じタイミングを強制します（make-theme の逐次文字起こしマッチャー + 逐語的完全性ゲート — ドリフトはコンパイルエラーです）。複数の文字起こし単語を 1 つのエントリに詰め込まないでください（例: "FUTURE OF" や、1 つの start/end を持つ IT + 改行 + ALL のスタック） — 2 番目の単語は最初のタイムスタンプを継承し、早く発火します。同じ視覚行に配置したい場合でも、それぞれ独自のタイミングを持つ別々の単語エントリに分割してください（<br> ではなく CSS の white-space / 自然な折り返しを使用してください）。キャプションテキスト ≠ 文字起こしとなる創造的な置換（例: "fifteen percent" を "15%" で置き換える）はサポートされています — check-timing.cjs 内の CREATIVE_SUBS に登録してください。
• グループウィンドウはその単語を包み込まなければならない — すべてのグループで group.in ≤ min(word.start) かつ group.out ≥ max(word.end) です。group.in が単語の start より遅い場合、その単語はコンテナがマウントされるまでサイレントに遅延します（これにより 800ms のラグバグを出荷したことがあります）。バリデータはこれを強制します。
• 2 つのキャプショングループが時間 AND 画面領域の両方で重複してはいけない — 時間的に重複するキャプションはテキストの上にテキストが積み重なる事態を生みます。選択肢: (a) 空間的分離 — 各グループを重複しない垂直バンドに配置して共存させる（メモリーウォールカスケードスタイル）、(b) ハンドオフ — 前のグループの out を次のグループの in 以下に設定し、画面に 1 つだけ表示されるようにする、(c) 意図的なレイヤードタイポグラフィ — いずれかのグループに "allow_overlap": true を追加してバリデータを黙らせる。バリデータは各グループの垂直 bbox を CSS から推定し、衝突をフラグします。デフォルトでは (a) を選んでください — これが cinematic-cream を、字幕トラックが自らを置き換えるのではなく、詩が積み重なっていくように感じさせるものです。
• スクリーンブレンドは明るい背景（輝度 >180）で失敗します。 シネマティックテンプレートはクリーム + screen であり、その DNA はロックされています（プランはそれらを再着色できません） → 明るい背景では白飛びするため、見た目を上書きするのではなく、ink（明るい表面のために作られた活版印刷）または anchor テーマ（不透明なレール表面）を選んでください。
• 単語の登場時に letter-spacing や filter:blur をアニメーションさせないでください — inline-block のリフローが行ジャンプを引き起こします。
• マッティングに CoreML は禁止 — onnxruntime CoreML EP の混合精度パーティショニングが顔のアルファを破壊しました（以前の RVM エンジンで観測済み。再試行しないでください）。マッティングは CPU のみです（約 2 fps @1080p ≈ 10 秒クリップあたり 2〜3 分。長いクリップではこれを予算に組み込んでください）。

---

依存関係

• HyperFrames CLI： プラグインのインストールでは、マニフェストでバージョンが固定された同梱ランチャーを使用します。ソースへのコントリビューターは、ビルド済みのチェックアウト（packages/cli/dist/cli.js）を HYPERFRAMES_ROOT 経由で使用するか、スキルのソースツリー、または ~/Downloads/hyperframes を使用できます。
• Node が中心。Python を使う箇所は uvx 経由の 2 か所（手動インストール不要）： 文字起こしでは uvx 経由で WhisperX を実行します（単語単位のタイミングを取得し、既存の単語単位の transcript.json があればフォールバックします）。また、Theme の drawon セットピースでは、コンパイル時に python3 scripts/gen-stroke-path.py をシェルから実行します。それ以外はすべて、hyperframes に同梱されているツールチェーンで実行します。マッティングには hyperframes CLI の remove-background（u2net_human_seg。重みは ~/.cache/hyperframes/ に一度だけ自動ダウンロード、約 168 MB）、画像／アルファ演算には sharp、レイアウト／オクルージョン／オーバーフローには puppeteer、さらに ffmpeg を使用します。上記の ランタイムの前提条件 に記載のとおり、キャプションプロジェクトに Sharp、Puppeteer、GSAP をインストールしてください。ヘルパーはまずそのプロジェクトを確認し、ソースへのコントリビューター向けにチェックアウトの依存関係の検索も維持します。
• 文字起こし = uvx 経由の WhisperX（単語単位のタイミングとアラインメント。手動インストール不要 — transcribe.cjs が uvx whisperx を実行します）。既存の単語単位の transcript.json があれば、そちらにフォールバックします。
• ソース動画 — matte.cjs／transcribe.cjs は source.mp4 を自動で解決するため（クリップを glob で検索するか、hyperframes.json を読み取ります）、hyperframes init --video X.mp4 の実行時に手動で名前を変更する必要はありません。
• fps — matte.cjs はソースのネイティブなフレームレートで抽出し、matte.fps に記録します。render-and-composite.sh はその値を使用し、マットとフレームの同期を保ちます。
• マッティングの重みは同梱されていません。matte.cjs は hyperframes CLI の remove-background をシェルから実行し、u2net_human_seg（約 168 MB、Apache-2.0）を ~/.cache/hyperframes/background-removal/models/ に一度だけダウンロードします。新しいマシンで初回の準備を行う際は、このダウンロードのためにネットワーク接続が必要です。

必須の依存関係が見つからない場合は、手順を黙って省略せず、停止してユーザーに確認してください。