embedded-captions — ミュート配信層

プラグインのインストール: セットアップや更新コマンドの前に、このスキルがHyperFramesプラグイン内にある場合はプラグイン実行ルールに従ってください。スタンドアロンインストールの場合は、以下の更新手順に従ってください。

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

埋め込みキャプション

1つのカタログ、最初に選択 (CATALOG.md — 35のアイデンティティ; その背後にあるエンジンはバックエンドの詳細です)。標準 (デフォルト) は、クリーンな逐語レール (大部分のテキストを表示する下部3分の1の字幕) と、ピーク時に被写体の背後に合成される埋め込みのクライマックスを構築します。シネマティック は純粋な埋め込み — レールはなく、すべてのキャプションが被写体の背後に合成されます (ヒーロー書体、集積、オクルージョンが効果として機能)。テーマ は完全なテーマ別構成 — ボディパラダイム × ヒーローセットピース × 前面エフェクト × プレートリアクションで構成され、レジストリ (themes/README.md): ordnance terminal neonsign stardust stomp から登録されます。ほとんどの解説/ナレーションは標準です; 埋め込みは希少で価値あるピークです — すべての単語を埋め込むのはよくある間違いです。テーマは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/ターミナルを通じてキャンセルしてください。キャプションヘルパーはプロセススナップショットからレンダリングを強制終了したり回復したりしません。

操作フロー (要約)

/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 ∥ audio-envelope を並列で実行し、その後 safe-zones v2 をシーンパレット/光学/照明と共に実行 — 1つのコマンドで完了)
3. 小さなJSONのクリエイティブな選択を記述する (最初に safe-zones.json を読む): シネマティック → plan.json → fill-timings.cjs → fit-fonts.cjs → make-composition.cjs; テーマ → theme.json → make-theme.cjs (レール/パネル/ポエム/テイクオーバーパラダイム; anchor は静かなレールのデフォルトです)
4. ビジュアルQA: node scripts/preview-frames.cjs <project> → 約2秒/フレームで忠実なコンポジットプレビュー (レンダリングなし)。レンダリングに費用を払う前に § ビジュアルQA を確認してください。
5. render-and-composite.sh → ゲート (タイミング / オクルージョン+ヒーロー / オーバーフロー / ハンドオフ) → final.mp4

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

• レール (デフォルト) + 埋め込み (昇格)。 drop (フィラー、表示されない) / rail (逐語的な下部3分の1字幕、前面、大部分のテキストを表示) / embed (被写体の背後に合成されるピークワード)。標準モードは両方を行い、ピークのみを埋め込みます。§ キャプションモデル を参照。
• ビデオは未編集のまま提供されます (標準/シネマティック; テーマモードのPLATE予算は唯一の認可された例外です — テーマDNAごとに定義されたレジスターゲート付きリアクションビート (チャージディム、パンチ、シェイク、グレイン) で、マットコンポジットの後に適用され、被写体+テキスト+プレートが1つのフレームとして動きます) — キャプションのみが追加されます。マットは被写体が埋め込みトラックを隠すことを可能にするだけです。映像をグレーディング/リカラー/スキャンラインしないでください。
• 2つのルールブック: レール → references/rail.md (薄い)、埋め込みクラフト → references/composition-craft.md (豊富、埋め込みのみ)。必要に応じて斜め読み。

---

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

すべての話されたフレーズは次の3つのうちの1つです:

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

レールはテキストの大部分を表示します; 埋め込みは希少で価値あるピークです。 希少性はクリップごとではなくビート/ブロックごとです: ブロック (思考) あたり ≤1ヒーロー、同時に表示されることはなく、ヒーローウィンドウ間には少なくとも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/references/brief-contract.md § 1) です: 自律モード ("驚かせて" / "私の代わりに決めて") では、自分でショートリストから選び、理由を一言で述べてください。質問しないでください。

手順: クリップをプローブする → カタログから2～3のアイデンティティをショートリストする → 理由を一言で述べて1つを推奨する → ユーザーが選択する (自律モード: あなたが選び、理由を述べる) → そのアイデンティティのファイルをオーサリングする。アイデンティティはエンジンにロックされています (クロスコンボはありません。1つを開くことは検証イベントです — dna/README.md を参照)。

常に推奨を提示し、オーサリングする前にユーザーに選択させてください。 静かにデフォルトにしないでください。

(完全なアイデンティティテーブルは CATALOG.md にあります — ルーティングのための単一の情報源。以下のエンジンドキュメントは、各バックエンドのオーサリング契約を説明しています。)

CATALOG.md がここでの答えのすべてです。このワークフローはHyperFramesコンポーネントレジストリを検索しません。 コンポジションワークフローは、名前付きルックをオーサリングする前に npx hyperframes catalog を実行します。これは実行してはいけません。そのエンジンは cinematic.json / theme.json を消費し、コンポジション自体を出力するロックされたコンパイラであるため、レジストリアイテム — 含まれる caption-* ブロック — はマウントするものがありません。レジストリブロックはデザインされたキャンバスにテキストをスタイルします。このスキルは、マットを通して誰かの映像にキャプションを焼き付けます。どのアイデンティティもリクエストに適合しない場合は、カタログの外に手を伸ばすのではなく、そう言って最も近いものを選択してください。

推奨ヒューリスティック: 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回試し、それでもダメなら拒否してください (作り話の単語の逐語レールは、キャプションがないよりも悪いです)。
• 速い動きのある忙しい手持ちカメラ (マットがちらつく)

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

1. ショットカットプローブ。 20%、50%、80% でフレームをサンプリング。異なる被写体/シーンが現れた場合、カットの前にクリップをトリミングします。
2. レターボックス/ピラーボックスプローブ。 最初のフレームに黒いバーがあるか？安全なコンテンツ矩形を計算し、キャプションの配置をその内部に制約します。
3. 輝度プローブ。 キャプション領域の平均輝度をサンプリング — 60未満 → 明るいテキストはそのまま読める、60-180 → グリフスクリムを追加、180以上 → 不透明テキスト + スクリム (裸の明るいテキストは決して使わない)。シネマティックテンプレートはクリーム+screen でロックされています — このプローブを使用して適切なアイデンティティを選択し (明るいシーン → ink、または不透明レール anchor テーマ)、色を変更しないでください。
4. トーンによるアイデンティティ推奨 (あなたが推奨し、ユーザーが選択 — ステップ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をオーサリング。モードについては以下を参照。
   シネマティック: plan.json をオーサリング → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   テーマ:     theme.json をオーサリング → bash scripts/render-theme.sh <project>   (コンパイル + レンダリング + プレートエフェクト)
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 を実行します。成果物は final_fx.mp4 で、final.mp4 はプレートリアクション前です)

ステップ1の init は、インストールされたスキルをGitHubの最新版と照合し、古いものがあればグローバルセットを更新します。

ステップ3はモードによって異なります:

ステップ3 — シネマティックモード (純粋な埋め込み)

1. 最初に safe-zones.json を読んでください。 ナレーションプレーンは zones.hugLeft/hugRight に配置されます — シルエットに隣接するクリーンなストリップ (テキストが体から遠いと浮いて見え、埋め込まれていないように見えます。遠いコーナーはデフォルトではなくフォールバックです)。ヒーローはデフォルトで heroAnchor/heroBands.best (被写体に中央揃え、〜30～55% オクルージョン) になります。recommendation:"fg" は読みやすさのためにナレーションを前面に移動します。ヒーローは heroBands.feasible の場合に埋め込まれたままになります — hero-fgは最後の手段です。
2. DNAはあなたが選択したアイデンティティです