プラグインインストール: セットアップやアップデートコマンドの前に、このスキルがHyperFramesプラグイン内にある場合はプラグイン実行ルールに従ってください。スタンドアロンインストールの場合は、以下の更新手順をそのまま使用します。
まず、このスキルを最新の状態に保つため、ユーザーに確認してから実行:
npx hyperframes skills update embedded-captions。すべてが最新の場合は高速で何も行いません。そうでない場合は、このスキルと、それが依存するコアドメインスキルを更新してから使用します。
埋め込みキャプション (Embedded Captions) は何をしますか？
カタログは一つ、最初に選択します (CATALOG.md — 35のアイデンティティ; 背後にあるエンジンはバックエンドの詳細です)。標準 (Standard) (デフォルト) は、クリーンな逐語レール (rail) (ほとんどのテキストを表示する lower-third 字幕) と、クライマックスで被写体の背後に合成される埋め込み (embed) を構築します。シネマティック (Cinematic) は純粋な埋め込み — レールなし、すべてのキャプションが被写体の背後に合成されます (ハイロタイポグラフィ、累積、オクルージョン効果)。テーマ (Theme) は、完全なテーマ別構成 — ボディパラダイム × ヒーローセットピース × 前面エフェクト × プレート反応、をレジストリ (themes/README.md) から構成します: ordnance terminal neonsign stardust stomp。ほとんどの解説 / ナレーションは標準 (Standard) です;埋め込み (embed) は希少で価値のあるピークです — すべての単語を埋め込むのはよくある間違いです。テーマは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 が存在する場合、確認された入力とユーザーノートが記載されています — 最初に読んでください。
以下のクラフト散文は長いですが、パイプライン自体は短いです — そして決定論的なものはすべて計算またはコンパイルされ、手書きされることはありません:
- 判断ゲート (不良クリップを拒否) → CATALOG.md から1つのアイデンティティを選択 (35のアイデンティティ; エンジン/コンパイラはルックアップによって導出 — モード/カテゴリの質問を決して表面化させない)
hyperframes init(プロジェクトディレクトリが既に存在し、その中にビデオがある場合はスキップ —matte.cjs/transcribe.cjsはディレクトリ内の任意のビデオを source.mp4 として採用します) →bash scripts/prepare.sh <project>(マット ∥ 文字起こし ∥ オーディオエンベロープを並列実行、その後セーフゾーン v2 をシーンパレット/光学/照明と共に — 一つのコマンドで、何も忘れません)- クリエイティブな選択を小さな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(逐語 lower-third 字幕、前面、ほとんどのテキストを運ぶ) /embed(被写体の背後に合成されるピークワード)。標準モードは両方を行い、ピークのみを埋め込みます。§ キャプションモデル を参照。 - ビデオは未編集のまま納品されます (標準/シネマティック; テーマモードのPLATE予算は唯一認められた例外です — テーマDNAごとに定義され、マット合成の後に適用される、レジスターでゲートされたリアクションビート (チャージディム、パンチ、シェイク、グレイン)。これにより、被写体+テキスト+プレートが1つのフレームとして動きます) — キャプションのみが追加されます。マットは、被写体が埋め込みトラックを隠すことを可能にするだけです。フッテージのグレーディング、リカラー、スキャンラインは決して行わないでください。
- 2つのルールブック: レール → references/rail.md (薄い)、埋め込みクラフト → references/composition-craft.md (豊富、埋め込みのみ)。必要に応じて読み飛ばしてください。
キャプションモデル — レール + 埋め込み
話されるすべてのフレーズは、次の3つのいずれかです:
| 説明 | 表示方法 | |
|---|---|---|
| drop | フィラー — えーと/あー、言い間違い、自己訂正 | 表示されない |
| rail | デフォルト — 通常の話し言葉 (逐語) | クリーンな lower-third 字幕、前面、読みやすい。強調ワードはインラインの emphasis ハイライト (アクセントカラー / アクティブワードポップ) を取得できます — レール上に留まります。 |
| embed | 昇格されたピーク — 見出しとなるビート | 被写体の背後に合成された大きな単語 (マットオクルージョン)、デザインされた出入り |
レールはほとんどのテキストを運びます。埋め込みは希少で価値のあるピークです。 希少性はクリップ単位ではなく、ビート/ブロック単位: ブロック (思考) あたり ≤1 ヒーロー、2つが同時に見えることはなく、ヒーローウィンドウ間に最低1ビートの間隔 (コンパイラは0.6秒未満で警告)。短いクリップ → 通常1～2個。長い解説 → セクションあたり約1個。複数のヒーローの中で、最も大きく記述されたものがAPEX (それのみが完全なロックアップ埋め込み + 幅フィット引き上げを取得)。小さいものはマイナーピークで、そのカラムを特大の強調線 (前景、減衰モーション) として乗ります — すべてのビートがマットショーケースを必要とするわけではなく、まさにそれがAPEXをイベントとして際立たせます。すべての単語を埋め込むことは、依然としてよくある間違いです。
レールサーフェスアイデンティティはこれを正確に構築します (レール = rail.html、埋め込み = index.html 内のクライマックス)。カラムフローアイデンティティはレールをドロップし、すべてを埋め込みスタイルにします — ムードが逐語読み取りよりも優先される要求にのみ推奨し、単語が読める必要がある解説 / ナレーションには決して推奨しません (CATALOG.md はこれをアイデンティティごとにエンコードしています)。
ステップ 0 — CATALOG から1つのアイデンティティを選択
一つのフロントエンド、背後に3つのエンジン。 ユーザーは CATALOG.md から IDENTITY を選択します (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。
- シネマティック →
make-cinematic.cjsによってコンパイルされるロックされたテンプレートのためにcinematic.jsonを記述。 - テーマ → 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で固定されています (LOCKED) — このチェックを使用して_適合するアイデンティティを選択_し (明るいシーン →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> # マット ∥ 文字起こし (並列) → セーフゾーン。一つのコマンド。
# → 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 が既にコンパイル + 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"は可読性のために NARRATION を前面に移動します;ヒーローはheroBands.feasibleである限り埋め込まれたままにします — hero-fg は最後の手段です。 - DNAはステップ0で選択したアイデンティティです — その
dna.jsonがタイポグラフィ、カラー、モーションをエンコードします。cinematic.jsonは単純にタイミングの選択を記述します: 各ヒーローとナレーションブロックの開始/終了キーフレーム、テキストコンテンツ、およびsafe-zones.jsonからのゾーン割り当て (hugLeft/hugRight、heroAnchor+ バンド)。オーサリング後、make-cinematic.cjsを実行してplan.jsonを導出し、レンダリング用にコンパイルします。 - ステップ4 — プレビューフレーム。
render-and-composite.shの前に、これらが期待通りに見えることを確認してください。
ステップ 3 — テーマモード (VFX/ワールドビルディング)
- 最初に
safe-zones.jsonを読んでください。 シネマティックモードと同じゾーンを使用しますが、テーマはplateReactionフィールドも読みます。 - テーマレジストリ (themes/README.md) からテーマ DNA を選択します。 各テーマ (
ordnance,terminal,neonsign,stardust,stomp) は、ボディパラダイム (テキストが体とどのように相互作用するか)、ヒーローセットピース、前面エフェクト、プレート反応を定義します。 theme.jsonをオーサリングします:cinematic.jsonと同じタイミング構造ですが、themeフィールドと、オプションでplate(リアクションビート用) が追加されます。オーサリング後、bash scripts/render-theme.sh <project>を実行します。これがコンパイル、レンダリング、プレート反応 (_postfx.sh) を処理し、final_fx.mp4 を生成します。- ビジュアルQA:
render-theme.shは内部でプレビューフレームを生成できます。それらを確認し、問題があればtheme.jsonを調整して再実行してください。
ビジュアルQA
レンダリングに時間とリソースを費やす前に、常にプレビューを確認してください。node scripts/preview-frames.cjs <project> は、低解像度の合成フレームを約2秒/フレームで生成します。以下を確認してください:
- テキストが読みやすいか (特にレール上で)
- 埋め込みテキストが被写体の背後で正しく隠れているか (マットが機能しているか)
- オクルージョンが自然か (テキストが不自然に浮いていないか)
- ヒーロー間の間隔が適切か (コンパイラの警告を確認)
- プレート反応 (テーマモード) が意図した効果を生んでいるか
問題がある場合は、オーサリングされたJSONを調整してプレビューを再生成してください。満足できるまで繰り返します。
レンダリングと合成
最終レンダリングは bash scripts/render-and-composite.sh <project> によって実行されます。このスクリプトは以下を実行します:
- タイミングの検証 (ギャップ、オーバーラップ)
- オクルージョン + ヒーローの合成
- オーバーフローチェック (テキストが安全ゾーンを超えていないか)
- ハンドオフ (プレート反応がある場合)
final.mp4の生成
テーマモードでは、render-theme.sh がこのステップをラップし、追加のポストエフェクト (_postfx.sh) を適用して final_fx.mp4 を生成します。final.mp4 はプレート反応が適用される前の状態で、デバッグ目的で保持されます。
歴史的スナップショットは history/ ディレクトリに保存され、以前のバージョンにロールバックできます。
トラブルシューティングとよくある間違い
- すべての単語を埋め込まないでください。 デフォルトの標準モードは、ほとんどのテキストをレールに配置し、強調したいキーワードのみを埋め込みます。すべてを埋め込むと、可読性が低下し、効果が薄れます。
- アイデンティティを尋ねる前にクリップをプローブしてください。 ショートリストにはクリップの特性 (輝度、構図、動き) が必要です。先にプローブせずにアイデンティティを尋ねないでください。
- エンジンの質問を表面化させないでください。 ユーザーに「標準、シネマティック、テーマのどれにしますか？」と尋ねないでください。代わりに、CATALOG.md からアイデンティティを提示し、選択させてください。エンジンはルックアップによって決定されます。
- マットが機能しない場合: 被写体が明確に分離されていないか、動きが速すぎる可能性があります。事前チェックセクションを参照してクリップを検証してください。
- 文字起こしが間違っている場合:
transcript.jsonを確認し、Whisper モデルをmediumまたはlargeに変更してみてください。それでもダメな場合は、クリップを拒否してください。