最初に、このスキルを最新の状態に保つために、ユーザーに確認してから実行してください:
npx hyperframes skills update embedded-captions。すべてが最新の場合は高速なno-opです。そうでない場合は、このスキルとそれが依存するコアドメインスキルを、使用する前に更新します。
埋め込みキャプション(Embedded Captions)
1つのカタログを事前に選択(CATALOG.md — 35のアイデンティティ。背後にあるエンジンはバックエンドの詳細です)。Standard(デフォルト)は、クリーンな逐語レール(多くのテキストを表示するlower-third字幕)+ クライマックスでシーンの被写体の_背後_に合成される埋め込みを構築します。Cinematicは純粋な埋め込みです — レールなし、すべてのキャプションが被写体の背後に合成されます(ヒーロータイポグラフィ、蓄積、オクルージョン効果)。Themeは完全なテーマ別構成です — ボディパラダイム × ヒーローセットピース × フロントエフェクト × プレート反応、レジストリから構成されます(themes/README.md):ordnance terminal neonsign stardust stomp。ほとんどの解説/ナレーションはStandardです。埋め込みは、希少で価値のあるクライマックスです — すべての単語を埋め込むのはよくある間違いです。Themeは、VFXレベルの要求("炸"、"特效"、"像 AE 做的那样")向けです。
運用フロー(TL;DR)
/hyperframesを通じてルーティングされ、インテントレイヤーは入力(どのクリップか)のみを確認し、アイデンティティの選択を後回しの質問として告知します — ショートリストはプローブされたクリップを必要とするため、以下のステップ1に留まります。レイヤーの実行形状に関する質問は適用されません(映像は未編集であり、レビューするストーリーボードはありません)。BRIEF.mdが存在する場合、確認された入力とユーザーメモが含まれています — 最初にそれを読んでください。
以下のクラフト散文は長いですが、パイプライン自体は短いです — そしてすべての決定論的な処理は計算またはコンパイルされ、手書きではありません:
- 判定ゲート(不良クリップを拒否)→ カタログから1つのアイデンティティを選択(35のアイデンティティ、エンジン/コンパイラはルックアップによって導出 — モード/カテゴリの質問は絶対に表示しない)
hyperframes init(プロジェクトディレクトリが既に存在し、中にビデオがある場合はスキップ —matte.cjs/transcribe.cjsはディレクトリ内の任意のビデオをsource.mp4として採用)→bash scripts/prepare.sh <プロジェクト名>(マット || 文字起こし || オーディオエンベロープを並列実行、次にシーンパレット/光学/照明を使用したsafe-zones v2 — 1つのコマンドで、何も忘れない)- クリエイティブな選択の小さなJSONを作成(最初に
safe-zones.jsonを読む):Cinematic →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs;Theme →theme.json→make-theme.cjs(レール/パネル/ポエム/テイクオーバーパラダイム;anchorが静かなレールのデフォルト) - ビジュアルQA:
node scripts/preview-frames.cjs <プロジェクト名>→ 約2秒/フレームで忠実なコンポジットプレビュー(レンダリングする前に § ビジュアルQA を確認) render-and-composite.sh→ ゲート(タイミング / オクルージョン+ヒーロー / オーバーフロー / ハンドオフ)→final.mp4
人々が見逃す重要なルール:
- レール(デフォルト)+ 埋め込み(プロモーション)。
drop(フィラー、表示しない)/rail(逐語的なlower-third字幕、前面、ほとんどのテキストを表示)/embed(被写体の背後に合成されるクライマックスワード)。Standardモードは両方を行い、クライマックスのみを埋め込みます。§ キャプションモデルを参照。 - **ビデオは手を加えずに納品されます(Standard/Cinematic;ThemeモードのPLATE予算は唯一認められた例外です — テーマDNAごとに定義されたレジスターゲートされたリアクションビート(チャージディム、パンチ、シェイク、グレイン)で、マットコンポジットの後に適用され、被写体+テキスト+プレートが1つのフレームとして動くようにします) — キャプションのみが追加されます。マットは、被写体が埋め込みトラックを遮蔽できるようにするだけです。映像のグレーディング、リカラー、スキャンラインは絶対に行わないでください。
- 2つのルールブック:レール → references/rail.md(簡潔)、埋め込みクラフト → references/composition-craft.md(豊富、埋め込みのみ)。必要に応じて斜め読みしてください。
キャプションモデル — レール + 埋め込み
すべての話されたフレーズは、以下の3つのいずれかです:
| 内容 | 表示方法 | |
|---|---|---|
| drop | フィラー — えーっと/うーん、どもり、自己修正 | 表示しない |
| rail | デフォルト — 通常の話し言葉(逐語) | クリーンなlower-third字幕、前面、読みやすい。パンチワードはインラインのemphasisハイライト(アクセントカラー / アクティブワードポップ)を取得可能 — レール上に留まります。 |
| embed | プロモートされたクライマックス — 見出しビート | 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からアイデンティティを選択します(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 → ロックされたテンプレート用に
plan.jsonを作成し、make-composition.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を一度試し、それでもだめなら拒否してください(でっち上げの単語の逐語レールは、キャプションがないより悪いです)。 - 手ブレの激しいハンドヘルド撮影(マットがちらつく)
事前プローブ(コストはかからず、最悪の失敗を防ぎます)
- ショットカットプローブ。 20%、50%、80%の時点でフレームをサンプリング。異なる被写体/シーンが現れた場合は、カットの前でクリップをトリミングしてください。
- レターボックス/ピラーボックスプローブ。 最初のフレームに黒いバーがありますか?安全なコンテンツ矩形を計算し、キャプションの配置をその内部に制限します。
- 輝度プローブ。 キャプション領域の平均輝度をサンプリング —
60未満→ 明るいテキストはそのまま読み取れます、60-180→ グリフスクリムを追加、180以上→ 不透明テキスト+スクリム(裸の明るいテキストは絶対に避ける)。Cinematicテンプレートはクリーム+スクリーンでロックされています — このプローブを使用して_適合するアイデンティティを選択_し(明るいシーン→ink、または不透明レールanchorテーマ)、色を変更しないでください。 - トーンによるアイデンティティの推奨(あなたが推奨し、ユーザーが選択します — ステップ0 + CATALOG.mdを参照)。 解説/インタビュー/単語を読む必要があるもの → レール/パネルサーフェスアイデンティティ。詩的/ソーシャル/「シネマティック」 → レジスターによるカラムフローアイデンティティ。"炸 / 特效 / VFX" / 名前付きワールド → テーマ別アイデンティティ。不明な場合 →
anchor(単語は読め、シーンは安全)— ただし、ショートリストを提示し、ユーザーに選択させてください。
パイプライン — 5ステップ
1. hyperframes init <プロジェクト名> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <プロジェクト名> # マット ∥ 文字起こし(並列)→ 安全ゾーン。1つのコマンド。
# → frames_fg/ transcript.json safe-zones.json
3. [エージェントステップ — 唯一のクリエイティブステップ] 小さなJSONを作成。以下のモード別手順を参照。
Cinematic: plan.jsonを作成 → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
Theme: theme.jsonを作成 → bash scripts/render-theme.sh <プロジェクト名> (コンパイル+レンダリング+プレートエフェクト)
4. node scripts/preview-frames.cjs <プロジェクト名> # 約2秒/フレームのコンポジットプレビュー → § ビジュアルQA(レンダリングの前)
5. bash scripts/render-and-composite.sh <プロジェクト名> # ゲート → final.mp4 + history/ スナップショット
(Themeモード:ステップ3b/5をスキップ — render-theme.shは既にコンパイル+レンダリングアンドコンポジット
+ _postfx.shを実行しています。成果物はfinal_fx.mp4、final.mp4はプレート反応前のものです)
ステップ1のinitは、インストールされているスキルをGitHub上の最新と比較し、古いものがあればグローバルセットを更新します。
ステップ3はモードによって異なります:
ステップ 3 — Cinematicモード(純粋な埋め込み)
-
最初に
safe-zones.jsonを読んでください。 ナレーションプレーンは**zones.hugLeft/hugRight** に配置します — シルエットに隣接するクリーンなストリップ(身体から遠く離れたテキストは浮いて見え、埋め込まれているようには見えません。遠いコーナーはデフォルトではなく、フォールバックです)。ヒーローはデフォルトでheroAnchor/heroBands.best(被写体に中央揃え、約30~55%遮蔽)。recommendation:"fg"は、読みやすさのためにナレーションを前面に移動します。ヒーローは、heroBands.feasibleの場合、常に埋め込まれたままにします — ヒーローfgは最後の手段です。 -
DNAは、ステップ0で選択したアイデンティティです(CATALOG.md)— ここで選択を再オープンしないでください。シーンに対して妥当性をチェックしてください(明るいヒーローバンドの輝度 > 150 は
inkを望みます。完全な選択ガイダンスはカタログにあり、neon/glitch/chrome/velocityを含むすべての10をカバーしています)。あなたの選択と理由を述べてください。ユーザーが決定します。DNAはタイプ/パレット/ブレンド/モーション + ヒーローの3幕をロックします。safe-zones v2(palette/optics/lighting)は、それをこのシーンに自動的にパラメータ化します。 -
<プロジェクト名>/cinematic.jsonを作成 —"dna": "<名前>"+ 思考ブロック。生のグループではありません:各ブロック = 単語の行(節境界で2~5グループ化)+ それが積み重なるプレーン + 行ごとのcss(サイズ/ウェイト/スタイルのみ — 位置は不可)+ 最大1行に"hero": trueとマーク(プロモートされた単語。"text"は表示形式用)。スキーマ:scripts/make-cinematic.cjsヘッダー。 -
コンパイル:
node scripts/make-cinematic.cjs <プロジェクト名>— ブロックをplan.json → index.htmlに低レベル化。自動生成:文字起こしシーケンスタイミング、ブロック内蓄積、ブロック間ページフリップ、ヒーローロックアップ(ヒーローブロックの事前コンテキスト、HERO、および事後コンテキストが、被写体を中心とした1つの結合コンポジションとして積み重ねられます — 読み順は上から下 = 構築上の発話順。コンテキストは前面に浮かび、ヒーローは背後に埋め込まれます = 奥行きサンドイッチ。質量ルールにより、ヒーローがそのコンテキストを支配することが保証されます)、APEX/マイナーヒーロー分割、構築による読み順(1つのロックアップ内で、話された順序 = 表示順序)。全文埋め込みは、すべての単語がヒーローロックアップを取得することを意味するのではありません — それはよくある間違いです。
cinematic.jsonは、各ブロックの最大1行をhero: trueとしてマークします。ブロックの残りは、通常の埋め込み行として表示されます(fg、減衰モーション、小さいサイズ)。 -
プレビュー:
node scripts/preview-frames.cjs <プロジェクト名>。§ ビジュアルQAルールに従ってチェックしてください。 -
レンダリング:
bash scripts/render-and-composite.sh <プロジェクト名>
ステップ 3 — Themeモード
- 最初に
safe-zones.jsonを読んでください。 ナレーションプレーンは**zones.hugLeft/hugRight** に配置します。 <プロジェクト名>/theme.jsonを作成 — テーママニフェスト("theme": "<テーマ名>")、レジスター("register": "rail" | "panel" | "poem" | "takeover")、DNA(オプション、CATALOGからのエンジン識別子)、およびBRIEF.mdのドメインの言葉から直接書かれたプレーンなキャプションコンテンツ。どのテーマがどのレジスターをサポートするかについては、themes/README.mdを参照してください。anchorレジスターはrailです。- 実行:
bash scripts/render-theme.sh <プロジェクト名>— コンパイル+レンダリング+プレート反応。出力:final_fx.mp4(レンダリングされた最終的なもの)、final.mp4(プレート反応前のスナップショット) - プレビュー:
node scripts/preview-frames.cjs <プロジェクト名>。§ ビジュアルQAルールに従ってチェックしてください。
ビジュアルQAルール(レンダリング前チェック)
レンダリングを実行する前に、node scripts/preview-frames.cjs <プロジェクト名>でプレビューし、以下を確認してください:
- 埋め込みは被写体の背後にあり、遮蔽されている。前面に漏れている場合 → safe-zones v2が失敗しています。
hugLeft/hugRightプレーンにフォールバックするか、レール+埋め込みに切り替えてください。 - タイミングは発話と一致している — 特にヒーローワードの同期をスポットチェック。
- ヒーローは支配的であり、孤立していない — ロックアップには事前+事後コンテキストが含まれていますか?ヒーローは1~2秒間画面に表示され、その後フェードアウトしますか?
- オーバーフロー — テキストが両側の安全ゾーンを超えていませんか?超えている場合、
fit-fonts.cjsは縮小しますが、サイズ変更を強制する前にzonesの配置を確認してください。 - コントラスト — 明るい背景に明るいテキスト?輝度プローブが60~180の場合はグリフスクリムを追加し、180を超える場合は不透明テキスト+スクリムを追加します。
- 同時表示 — 2つのヒーローは同時に表示されません。(コンパイラはチェックしますが、目視確認してください)。
トラブルシューティングとエッジケース
マットがちらつく
- モーションブラーが大きいか、髪の毛の細かいディテール。
prepare.shに--matte-sensitivity lowを渡して、内部のマットパラメータを調整します。もしくは、zones.hugLeft/hugRightを強制して被写体を避けます。
文字起こしが信頼できない
transcript.jsonを読んでください。ナンセンスに聞こえる場合は、WHISPER_MODEL=mediumを設定してprepare.shを再実行します。それでも駄目なら、拒否します。
埋め込みワードが被写体と重ならない(オクルージョン不足)
safe-zones.jsonのheroBands.feasibleを確認してください。偽の場合、埋め込みはフォールバックプレーン(ヒーローfg)に配置されます。これは制限であり、バグではありませんが、レール+埋め込みを検討する必要があることを意味します。
テーマプレートエフェクトが強すぎる/弱すぎる
theme.jsonでplate_intensity(0.0~1.0)を調整します。デフォルトは0.5。
付録
ファイルリファレンス
| ファイル | 目的 |
|---|---|
frames_fg/ | 前景マスクフレーム(グリーンスクリーン用のアルファなし白、アルファベースの被写体用の透明) |
transcript.json | ワードレベルのタイムスタンプ付きWhisper文字起こし |
safe-zones.json | 検出されたシルエットと提案されたキャプション配置ゾーン |
audio_envelope.json | 正規化されたオーディオエンベロープ(タイミングの開始/終了の手がかり用) |
plan.json | コンパイル後のタイミング+レイアウト計画(手動編集しない) |
index.html / rail.html | コンパイルされたキャプションキャンバス(手動編集しない) |
final.mp4 | レンダリングされた出力(プレート反応前、Cinematic/Standardモードの最終的なもの) |
final_fx.mp4 | Themeモードの出力(プレート反応後) |
アイデンティティカタログクイックリファレンス
CATALOG.mdを参照してください。簡易表:
| アイデンティティ | サーフェス | 最適な用途 |
|---|---|---|
anchor | レール | デフォルト。読みやすさと安全性。 |
ink | レール | 明るいシーン、不透明テキストが必要。 |
loud | カラムフロー | エネルギッシュなソーシャルクリップ。 |
ordnance | テーマ | VFX爆発、「炸」。 |
terminal | テーマ | ハッカー/デジタル美学。 |
| ... | (完全なリストはCATALOG.mdを参照) |
このスキルはHyperFramesエコシステムの一部です。バグや機能リクエストについては、GitHubリポジトリに報告してください。