kinyias/hyperframes-templates | Embedded Captions

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

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

埋め込み字幕 (Embedded Captions)

1つのカタログ、最初に選択 (CATALOG.md — 35のアイデンティティ; その背後にあるエンジンはバックエンドの詳細です)。Standard (デフォルト) は、クリーンな逐語 レール (ほとんどのテキストを表示する下部3分の1の字幕) + クライマックスで被写体の背後に合成された 埋め込み を構築します。Cinematic は純粋な埋め込み — レールはなく、すべてのキャプションが被写体の背後に合成されます (ヒーロータイポグラフィ、蓄積、オクルージョン効果)。Theme は完全なテーマ構成 — ボディパラダイム × ヒーローセットピース × フロントFX × プレートリアクション で、レジストリから合成されます (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/ターミナルを通じてキャンセルしてください。キャプションヘルパーは強制終了したり、プロセススナップショットからレンダリングを復旧したりしません。

運用フロー (TL;DR)

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

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

1. 決定ゲート (不良クリップを拒否) → CATALOG.md から 1つのアイデンティティを選択 (35のアイデンティティ; エンジン/コンパイラはルックアップで導出 — モード/カテゴリの質問を表面化しないでください)
2. hyperframes init (プロジェクトディレクトリが既にビデオと共に存在する場合はスキップ — matte.cjs/transcribe.cjs はディレクトリ内の任意のビデオを source.mp4 として採用します) → bash scripts/prepare.sh <project> (マット ∥ 文字起こし ∥ オーディオエンベロープを並列実行、次にシーンパレット/光学/照明を使用したセーフゾーン v2 — 1つのコマンドで、何も忘れません)
3. クリエイティブな選択の小さなJSONを作成 (最初に safe-zones.json を読む): Cinematic → cinematic.json → make-cinematic.cjs ( plan.json を導出してコンパイルします); Theme → 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 (被写体の背後に合成された頂点の単語)。Standardモードは両方を行い、頂点のみを埋め込みます。§ キャプションモデル を参照してください。
• 映像は未加工のまま提供されます (Standard/Cinematic; ThemeモードのPLATE予算は唯一許可された例外です — テーマDNAごとに定義されたレジスターゲートのリアクションビート (チャージディム、パンチ、シェイク、グレイン) で、マット合成の 後 に適用されるため、被写体+テキスト+プレートは1つのフレームとして移動します) — 追加されるのはキャプションのみで、マットは被写体が埋め込みトラックを遮蔽できるようにするだけです。映像のグレーディング/リカラー/スキャンラインは決して行わないでください。
• 2つのルールブック: レール → references/rail.md (薄い), 埋め込みクラフト → references/composition-craft.md (リッチ、埋め込みのみ)。必要に応じて読み飛ばしてください。

---

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

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

	何か	どのように表示されるか
ドロップ	フィラー — えーと/あの、どもり、自己訂正	表示されない
レール	デフォルト — 通常の話し言葉 (逐語)	クリーンな下部3分の1の字幕、前面、読みやすい。パンチワードにはインラインの 強調 ハイライト (アクセントカラー / アクティブワードポップ) を付けることができます — レール上に残ります。
埋め込み	昇格した頂点 — 見出しビート	被写体の 背後 に合成された1つの大きな単語 (マットオクルージョン)、デザインされた入場 + 退場

レールはほとんどのテキストを表示します。埋め込みは希少で価値のある頂点です。 希少性は クリップごとではなく、ビート/ブロックごと です: ブロック (思考) あたり ≤1 ヒーロー、2つが同時に表示されることはなく、ヒーローウィンドウの間には最低1ビートの間隔があります (コンパイラは0.6秒未満で警告します)。短いクリップ → 通常1–2個。長い解説 → セクションあたり約1個。複数のヒーローの中で、最も大きく作成されたものがAPEX です (それだけが完全なロックアップ埋め込み + 幅フィットレイズを取得します)。より小さいものは MINORな頂点 で、そのカラムを特大の強調行 (fg、減衰モーション) として乗ります — すべてのビートがマットショーケースを必要とするわけではなく、それがまさにAPEXをイベントとして保つ理由です。すべての単語を埋め込むことは、今でも一般的な間違いです。

レール表面のアイデンティティは、まさにこれを構築します (レール = rail.html、埋め込み = index.html 内のクライマックス)。カラムフローアイデンティティはレールを廃止し、すべてを埋め込みスタイルにします — これらは、言葉が読める必要がある解説/ナレーションには決して推奨せず、ムード重視の要求に対してのみ推奨します (CATALOG.md はアイデンティティごとにこれをエンコードしています)。

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

1つのフロントエンド、3つのバックエンド。 ユーザーは CATALOG.md からアイデンティティ (IDENTITY) を選択します (35エントリ: 10クラシック + 25テーマ)。エンジン、コンパイラ、オーサリングファイルはカタログ行のルックアップで導出されます。「Standard vs Cinematic vs Theme」を質問として表面化しないでください — これらはバックエンド名です (製品は複数のエンジンがあっても1つのUXを持ちます)。カタログはルーティングに必要なものをすべてエンコードしています: 読み上げ面、声、推奨対象、シーン要件、本当に近いペア (loud↔ordnance、neon↔neonsign、cream↔stardust) の隣接性ノート。

アイデンティティの選択は 嗜好ゲート です (../hyperframes/references/brief-contract.md § 1): 自律モード (「びっくりさせて」/「決めて」) では、自分でショートリストから選択し、理由を1行で述べてください。質問しないでください。

手順: クリップをプローブ → カタログから2～3のアイデンティティをショートリスト → 1つを推奨し、理由を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。

• Cinematic → ロックされたテンプレート用に cinematic.json を作成し、make-cinematic.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 を1回試し、それでもダメなら拒否します (作り上げられた単語の逐語レールは、キャプションがないより悪いです)。
• 速い動きを伴う手持ち撮影の忙しい映像 (マットがちらつきます)

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

1. ショットカットプローブ。 20%、50%、80% の位置でフレームをサンプリングします。異なる被写体/シーンが表示された場合は、カットの前で クリップをトリミング します。
2. レターボックス/ピラーボックスプローブ。 最初のフレームに黒いバーがありますか？安全なコンテンツ矩形を計算し、キャプションの配置をその内側に制限します。
3. 輝度プローブ。 キャプション領域の平均輝度をサンプリングします — 60未満 → 明るいテキストはそのまま読める、60-180 → グリフスリムを追加、180以上 → 不透明テキスト + スリム (裸の明るいテキストは絶対に禁止)。Cinematicテンプレートはクリーム色+スクリーンでロックされています — このプローブを使用して、適合するアイデンティティを選択します (明るいシーン → 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を作成; モードに応じて以下を参照
   Cinematic: cinematic.json を作成 → node scripts/make-cinematic.cjs <project>
   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 は既にコンパイル + レンダリングアンドコンポジット
    + _postfx.sh を実行します。成果物は final_fx.mp4 で、final.mp4 はプレートリアクション前のものです)

ステップ1の init は、インストールされているスキルをGitHub上の最新と比較し、いずれかが古くなっている場合はグローバルセットを更新します。

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

ステップ 3 — Cinematic モード (純粋な埋め込み)

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