プラグインのインストール: セットアップまたはフレッシュネスコマンドの前に、プラグイン実行ルールに従ってください。このスキルがHyperFramesプラグイン内にある場合の手順です。スタンドアロンインストールの場合は、以下の更新手順をそのまま使用してください。
まず、このスキルを最新の状態に保ってください — 実行前にユーザーに確認してください:
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 做的」) 向けです。
ランタイムの前提条件
プラグインインストールでは、マット処理、転写、レンダリングにバンドルされたマニフェストピン留め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 が存在する場合、確認された入力とユーザーノートが含まれています — まずそれを読んでください。
以下のクラフト散文は長いですが、パイプライン自体は短いです — そして決定的なものはすべて計算またはコンパイルされ、手書きではありません:
- 決定ゲート (悪いクリップを拒否) → CATALOG.md から1つのアイデンティティを選択 (35のアイデンティティ; エンジン/コンパイラはルックアップによって導出 — モード/カテゴリの質問は決して表示しない)
hyperframes init(プロジェクトディレクトリが既に存在し、その中にビデオがある場合はスキップ —matte.cjs/transcribe.cjsはディレクトリ内の任意のビデオを source.mp4 として採用) →bash scripts/prepare.sh <project>(matte ∥ transcribe ∥ audio-envelope を並列実行し、次にセーフゾーン v2 をシーンパレット/光学/照明付きで — 1つのコマンド、何も忘れない)- クリエイティブな選択の小さなJSONを作成 (最初に
safe-zones.jsonを読む): シネマティック →cinematic.json→make-cinematic.cjs(plan.jsonを導出してコンパイル); テーマ →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つのうちの1つです:
| 内容 | 表示方法 | |
|---|---|---|
| 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/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.jsonを書き、make-cinematic.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を一度試し、それでもダメなら拒否してください (作り話の単語の逐語レールはキャプションがないよりも悪いです)。 - 速い動きを伴う忙しいハンドヘルド (マットがちらつく)
飛行前プローブ (コストはかからず、最悪の失敗を防ぎます)
- ショットカットプローブ。 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を作成; モードに応じて以下を参照
シネマティック: cinematic.json を作成 → node scripts/make-cinematic.cjs <project>
テーマ: theme.json を作成 → bash scripts/render-theme.sh <project> (コンパイル + レンダリング + プレートFX)
4. node scripts/preview-frames.cjs <project> # ~2s/フレーム コンポジットプレビュー → § ビジュアル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 — シネマティックモード (純粋な埋め込み)
- 最初に
safe-zones.jsonを読んでください。 ナレーションプレーンはzones.hugLeft/hugRightに配置されます — シルエットに隣接するクリーンなストリップ (テキストが体から遠いと浮いて見え、埋め込まれていないように見えます; 遠いコーナーはデフォルトではなくフォールバックです)。ヒーローはデフォルトでheroAnchor/heroBands.bestになります (被写体の中央、約30~55%隠れます)。recommendation:"fg"は読みやすさのためにナレーションを前に移動します。ヒーローはheroBands.feasibleである限り埋め込まれたままです — ヒーローfgは最後の手段です。 - DNAはステップ0で選択したアイデンティティです。 各
cinematic.jsonテンプレートはアイデンティティのDNAを定義します: ページ、シェイプ、トランジション、タイムカーブ。"anchor" DNAはserve: basicsとalign: railを設定し、表面は従来のテキストを埋め込みます (高く、控えめ、ロックアップエフェクトなし)。CATALOG.md の各アイデンティティはそのDNAを宣言しています。 - ペイロードキー:
text: "<埋め込みワード>"、style: "hero"または"minor"(§ キャプションモデルを参照)、at: <タイムコード>、heroAnchor: "<ゾーン>"(デフォルトはsafe-zones.jsonで推奨)。flow: "push"(左から出現) /"rise"(下から) /"cascade"(先行ワードの上のライン)。 - バリデーション:
node scripts/make-cinematic.cjs <project>がplan.jsonを出力し、preview-frames.cjsがそれをレンダリングします。
ステップ3 — テーマモード (フルテーマ)
safe-zones.jsonを読んでください。 テーマモードはzones.loud/zones.quietを使用してレイヤーを配置します。- テーマを選択しました (ステップ0)。 各テーマは
themes/<theme>.jsonを定義します:plateReaction(チャージディム、パンチ、シェイク、グレイン)、heroTypography(フォントファミリー、トラッキング、スケール)、railStyle(不透明度、カラー)。anchorテーマはすべてリアクションを無効にし、align: railでクリーンなテキストを埋め込みます。 theme.jsonのペイロード:text: "<ラインテキスト>"、role: "hero"/"rail"/"panel"、at: <タイムコード>、motion: "standard"/"subtle"/"aggressive"。- コンパイル + レンダリング:
bash scripts/render-theme.sh <project>はmake-theme.cjsを実行 (plan.jsonを導出) → レンダリング → プレートFXを適用 →final_fx.mp4を出力。
ステップ4 — ビジュアルQA
node scripts/preview-frames.cjs <project> を実行すると、各フレームの合成プレビューが各フレーム約2秒で生成されます。確認すべきこと:
- テキストオクルージョンは正しいですか? ヒーローは被写体の背後にあり、レールは前方にあります。
- 被写体の境界に沿ったハロー/フリンジはありませんか? マットエッジのアーティファクト。必要に応じて
safe-zones.jsonのerosionパラメータを調整します。 - 配置は安全ですか? テキストは黒いバーやシーンの端からはみ出していませんか。
- タイミングは適切ですか? 埋め込みは音声と同期していますか。
- テキストは読みやすいですか? コントラストが十分ですか。スクリムが必要ですか (輝度プローブ)。
納品前に複数のキーフレームを確認してください。 プレビューは約2秒で済むため、すべてを検証する余裕があります。
ステップ5 — レンダリング
bash scripts/render-and-composite.sh <project>
これは:
plan.jsonに対してゲートを実行 (タイミング、オクルージョン+ヒーロー、オーバーフロー)- 埋め込みトラックをレンダリング (被写体の背後)
- レールトラックをレンダリング (前方)
- 合成して
final.mp4を出力 history/スナップショットにアーカイブ
テーマモードはこれをスキップします — render-theme.sh は既にこれを行っています (final_fx.mp4 を出力、final.mp4 はプレートリアクション前)。
参照
- CATALOG.md — アイデンティティの選択とルーティング
- references/rail.md — レールキャプションルール (薄い)
- references/composition-craft.md — 埋め込みキャプションルール (豊富)
- themes/README.md — テーマDNAとレジスタリー
- hyperframes/references/brief-contract.md — ブリーフ契約