プラグインのインストール: セットアップまたは更新コマンドの前に、このスキルが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>(マット処理 ∥ 文字起こし ∥ オーディオエンベロープを並列実行、次にセーフゾーン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つが同時に表示されることはなく、ヒーローウィンドウ間には少なくともビートの間隔が必要です (コンパイラは0.6秒未満で警告します)。短いクリップ → 通常1~2; 長い説明動画 → セクションごとに約1つ。複数のヒーローの中で、最も大きく作成されたものがAPEX です (それだけが完全なロックアップ埋め込み + 幅適合レイズを取得します); 小さいものは MINORピーク であり、拡大された強調行 (前景、減衰モーション) としてカラムに乗ります — すべてのビートがマットショーケースを必要とするわけではなく、まさにそれがapexをイベントに保ちます。すべての単語を埋め込むことは依然としてよくある間違いです。
レール表面のアイデンティティはこれを正確に構築します (レール = rail.html、埋め込み = index.html のクライマックス)。カラムフローのアイデンティティはレールを削除し、すべてを埋め込みスタイルにします — 言葉を読む必要がある説明動画/ナレーションには決してお勧めせず、雰囲気重視の要求にのみ推奨します (CATALOG.md はアイデンティティごとにこれをエンコードしています)。
ステップ 0 — CATALOG から1つのアイデンティティを選択
1つのフロントエンド、背後に3つのエンジン。 ユーザーは CATALOG.md から IDENTITY を選択します (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。
- シネマティック → ロックされたテンプレートのために
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は無音に対して「Thank you.」のような単語を幻覚します)。それに従い、拒否してください。 捏造された単語をキャプションしないでください。 - ソースに既に焼き込みキャプション/字幕/重いテキストグラフィックがある — 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> # マット処理 ∥ 文字起こし (並列) → セーフゾーン。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> # ~2秒/フレームの合成プレビュー → § ビジュアルQA (レンダリングの前)
5. bash scripts/render-and-composite.sh <project> # ゲート → final.mp4 + history/ スナップショット
(テーマモード: ステップ3b/5をスキップ — render-theme.sh はコンパイル + レンダリングアンドコンポジット
+ _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の場合、埋め込まれたままにしてください — ヒーロー前景は最後の手段です。 - DNAはステップ0で選んだアイデンティティです
...