HyperFrames
HyperFrames は HTML → MP4 レンダラー(Apache 2.0)です。コンポジションは平易な HTML ファイルで、data-start、data-duration、data-track-index 属性を持ちます。レンダラーはヘッドレス Chrome でタイムラインをフレーム正確に駆動し、フレームを FFmpeg にパイプします。スキル hyperframes-prompt-builder がマーケティングエンジンのディスパッチャエントリポイントであり、このスキルはオーサリングルールを担います。
呼び出すタイミング
- ピースが(
PROVIDERS.mdまたはフロントマターのprovider_override.video: hyperframesを介して)HyperFrames プロバイダにルーティングされた場合。 - タスクが
motion-typography、data-viz-reel、programmatic-short、または宣言された変数から決定論的な出力を必要とするコンポジション(例:新しい数値で再レンダリングしても変わらない週次 KPI リール)の場合。 - 承認済みの静止画(クォートカード、カルーセルスライド)をタイポグラフィシステムを変更せずに短いモーションピースに昇格する必要がある場合。
- オーケストレータが再レンダリング可能なアーティファクトを必要とする場合:同じコンポジション、異なる
--variables、バイト同一のベースライン。
入力
composition_id: 文字列。プロジェクトディレクトリとdata-composition-idに使用する短いスラッグ。aspect:9:16|1:1|16:9|4:5。duration_seconds: 整数。コンポジションの全長。scenes: 配列。各{ id, start_s, duration_s, role: "hook" | "body" | "cta", copy?, asset_ref? }。design_tokens: オブジェクト。ブランドカラー、プライマリ/セカンダリのフォントファミリ、スペーシングスケール。存在する場合はclients/<slug>/design.mdから取得。variables: 配列、省略可能。呼び出し元がレンダリング時にオーバーライドできる宣言パラメータ{ id, type, label, default }。assets: オブジェクト、省略可能。{ video?, audio?, images[] }— プロジェクト下のローカルパス。output_dir: 文字列。レンダラーが MP4 を書き込む場所(デフォルトはoutputs/<client>/<date>/<piece-id>/)。
プロセス
- まずブランドコンテキストを読み取る。
clients/<active-client>/design.md(または渡されたデザイントークン)をロードする。トークンがわかるまでは HTML のオーサリングを拒否する — クライアントにトークンがない場合のみ、リポジトリ内のデフォルトにフォールバックする。 - ナラティブアークを声に出して計画する(シーン、リズム、トランジション、ビート)前にマークアップを書く。フックを最初の 1.5 秒に、ボディ、CTA を末尾に配置。
- アニメーションの前にレイアウトを決める。 最終的なオンスクリーンレイアウトを最初に書く — 要素が最終的に配置される位置に配置する。それらの位置に
gsap.from()でアニメーションする;最終シーンのみgsap.to()による退出が許可される。 - HTML を作成する。 ルート
<html>はdata-composition-id、data-width、data-heightを持つ。各クリップはid、data-start、data-duration、data-track-indexを持つ。data-composition-variables(<html>上の JSON 配列)でパラメータ化する;実行時にwindow.__hyperframes.getVariables()で読み取る。 - すべてのタイムラインを一時停止状態で登録する。
const tl = gsap.timeline({ paused: true }); window.__timelines["<id>"] = tl;— フレームワークが再生を駆動する。無限ループ、Math.random()、時間ベースのロジック、非同期タイムライン構築は禁止。 - すべてのシーン間にトランジションを設定する。 ジャンプカットは禁止。上流の
references/transitions.mdにリストされているカタログ化されたトランジション(フェード、ワイプ、マスク、シェーダー)を使用する。 - ビデオとオーディオ。
<video>はミュート必須;オーディオは別の<audio>要素に、独自のトラックとして配置する。 - ローカルで検証する 最初に
npx hyperframes lintを実行し、次にnpx hyperframes inspect(テキストオーバーフロー、コンテナクリッピング)を実行する。両方がパスしてからのみレンダリングする。hyperframes-cliスキルに委任される。 - マニフェストを出力する。 MP4 の横に
manifest.jsonを書き込む。内容:{ composition_id, aspect, duration_seconds, variables_resolved, lint_pass, inspect_pass, render_settings }。CLAUDE.mdの完了定義で必須。
出力
project_path: 文字列。HyperFrames プロジェクトディレクトリへのパス。composition_html: 文字列。作成されたindex.htmlの内容(またはproject_path下のそのパス)。render_args: オブジェクト。npx hyperframes renderに渡すフラグ(--fps、--quality、--variables、--strict)。expected_artifact: 文字列。レンダリング後にoutput_dir下に現れる MP4 のパス。cost_estimate_usd: 数値。ローカルレンダリング — 計算時間のみ;DRY_RUN の場合は 0 を報告し、それ以外は--workers× 時間から見積もる。
譲れないルール
- すべての要素に開始アニメーション(
gsap.from())があること。 - すべてのタイムラインは一時停止状態で開始し、
window.__timelinesに登録されること。 - コンポジションロジック内で
Math.random()、Date.now()、setTimeout 駆動のアニメーションは禁止。 - ビデオトラックはミュート;
<video>にオーディオを埋め込まない。 - クライアントのコピーを直接マークアップに焼き付けず、可能な場合は変数として宣言し
data-composition-variablesに配置すること。これにより、同じコンポジションを新しいピースで再レンダリングできる。 outputs/下のレンダリング済み MP4 を編集せず、代わりにhyperframes renderを再実行すること。
例
例1: 週次 KPI リール(programmatic-short)
入力: { composition_id: "kpi-weekly-w21", aspect: "9:16", duration_seconds: 12, scenes: [{ id: "hook", start_s: 0, duration_s: 2, role: "hook", copy: "Semana 21" }, { id: "metric", start_s: 2, duration_s: 8, role: "body" }, { id: "cta", start_s: 10, duration_s: 2, role: "cta", copy: "Veja o detalhamento" }], variables: [{ id: "leads", type: "number", label: "Novos leads", default: 0 }, { id: "delta_pct", type: "number", label: "Variação %", default: 0 }] }
出力: outputs/<client>/<date>/kpi-weekly-w21/ 下のプロジェクト。index.html が 2 つの数値変数を読み取りアニメーション化する;render_args.--variables がピースごとにそれらを解決する。
例2: モーションクォートカード(motion-typography)
入力: { composition_id: "quote-marcos-2026-05", aspect: "1:1", duration_seconds: 6, scenes: [{ id: "main", start_s: 0, duration_s: 6, role: "body", copy: "Coloque a sua marca onde os olhos já estão." }] }
出力: アクティブなクライアントのタイポグラフィペアリングを尊重するキネティックタイプのコンポジション。マスクテキストのエントランスと、最終フレームでのソフトホールドを伴う。
障害モード
design.mdがなく、デザイントークンも渡されていない:停止して尋ねる。パレットを独自に作成しない。npx hyperframes lintがエラーを報告する(data-composition-idの欠落、トラックの重複、未登録のタイムライン):修正されるまでレンダリングをブロックする。npx hyperframes inspectが任意のシーンでテキストオーバーフローを報告する:システム最小値以下にタイプを縮小するよりも、レイアウトのリフローを優先する。- オーディオトラックがコンポジションの
duration_secondsより長い:オーディオをトリミングし、duration_secondsを拡張して合わせない。 - コンポジションが
Math.random()またはウォールクロック時間をどこかで使用している:レンダリング前に、宣言された変数またはシード指定の決定論的ジェネレーターにリファクタリングする。
関連スキル
hyperframes-cli: lint、inspect、preview、render コマンド。オーサリング後は常に呼び出される。hyperframes-prompt-builder: マーケティングエンジンのスペシャリストで、ピースのブリーフをこのスキルが期待する入力形状に変換する。マトリックスがhyperframesと解決したときにvideo-prompt-builderによって呼び出される。video-prompt-builder: 汎用ディスパッチャ。qa-tech-specs: レンダリングされた MP4 をプラットフォーム仕様(アスペクト、長さ、セーフエリア)に対して検証する。compliance-<active client>: レンダリング後に、レンダリングされたアーティファクトと変数から解決されたオンスクリーンコピーに対して実行される。
上流リファレンス
完全な上流スキル(コンポジションパターン、トランジションカタログ、オーディオリアクティブ、キャプション、データインモーション):https://github.com/wesleysimplicio/hyperframes/tree/main/skills/hyperframes