HyperFrames
HTMLは動画の唯一の真実のソースです。コンポジションは、タイミングのためのdata-*属性、アニメーションのためのGSAPタイムライン、外観のためのCSSを持つHTMLファイルです。フレームワークがクリップの可視性、メディア再生、およびタイムライン同期を処理します。
アプローチ
発見(探索的なリクエストのみ)
ユーザーが方向性を確定していない、オープンエンドなリクエスト(「プロダクトローンチ動画を作って」「ブランド用に何か作って」など)の場合、色を選ぶ前に意図を理解します。
- オーディエンス — 誰が見るのか? 開発者? 経営幹部? 一般消費者?
- プラットフォーム — どこで再生されるのか? ソーシャルメディア(15秒)、ウェブサイトヒーロー、製品デモ、社内向け?
- 優先事項 — 最も重要なものは? モーションの品質? コンテンツの正確性? ブランドの忠実性? 速度?
- バリエーション — ユーザーはオプションを望んでいるのか、それとも単一の最良の案を望んでいるのか?
具体的なリクエスト(「タイトルカードを追加して」「シーン3のタイミングを修正して」)の場合は、発見をスキップします。
探索的なリクエストの場合、意味のある違いを持つ2〜3のバリエーションを検討します。単なる色の変更ではなく、異なるペース、エネルギーレベル、または構造的なアプローチを提供します。一つは安全/期待どおりのもの、もう一つは野心的なもの。これは必須ではありません — 適切な場合に利用できるツールです。
ステップ1: デザインシステム
プロジェクトにdesign.mdまたはDESIGN.mdが存在する場合、まずそれを読みます(両方の大文字小文字を確認してください — Linuxでは別のファイルです)。ブランドカラー、フォント、および制約のための唯一の真実のソースです。その正確な値を使用してください — 色を発明したり、フォントを代用したりしないでください。どのような形式でも機能します(YAMLフロントマター、散文、テーブル — 単に値を抽出します)。
ローカルで見つけられないフォントが指定されている場合(fonts/ディレクトリに.woff2ファイルがなく、組み込みフォントでもない場合)、HTMLを書く前にユーザーに警告します:「design.mdで[フォント名]が指定されていますが、フォントファイルが見つかりません。fonts/に.woff2ファイルを追加してください。追加がない場合は、最も近い組み込みの代替フォントにフォールバックします。」
design.mdが存在しない場合、ユーザーに選択肢を提供します。
- ユーザーがスタイルやムードを指定した場合? → visual-styles.mdを読み、8つの名前付きプリセットから最も近いものを選びます。
- 視覚的にオプションを閲覧したい場合? → デザインピッカーを実行します:references/design-picker.mdを読み、完全なワークフローを確認します。これにより、視覚的なピッカーページが提供されます。ユーザーはブラウザ上でムード、パレット、タイポグラフィ、モーションを設定し、生成されたdesign.mdをコピーして会話に貼り付けます。
- スキップして速く進みたい場合? → 質問:ムード、ライトまたはダーク、ブランドカラー/フォントは? その後、house-style.mdからパレットを選びます。
design.mdはブランドを定義します。動画コンポジションのルールは定義しません。 それらのルールはreferences/video-composition.mdとhouse-style.mdにあります。ブランドカラーは、Web UIの不透明度ではなく、動画に適したスケールで使用します。
ステップ2: プロンプト拡張
すべてのコンポジションで常に実行します(単一シーンの作品や些細な編集は除く)。このステップは、design.mdとhouse-style.mdに対してユーザーの意図を具体化し、すべてのダウンストリームエージェントが同じように読む一貫した中間表現を生成します。
完全なプロセスと出力形式については、references/prompt-expansion.mdを読んでください。
ステップ3: 計画
HTMLを書く前に、ハイレベルで考えます。
- 何を — 視聴者は何を体験すべきか? ナラティブアーク、キーモーメント、感情的なビートを特定します。
- 構造 — コンポジションはいくつか、どのコンポジションがサブコンポジションかインラインか、どのトラックが何を運ぶか(ビデオ、オーディオ、オーバーレイ、キャプション)。
- リズム — 実装前にシーンリズムを宣言します。どのシーンがクイックヒットか、どれがホールドか、シェーダーはどこに配置されるか、エネルギーがどこでピークに達するか。パターンに名前を付けます: fast-fast-SLOW-fast-SHADER-hold。リズムテンプレートについてはreferences/beat-direction.mdを読んでください。
- タイミング — どのクリップが期間を決定するか、トランジションはどこに配置されるか、ペースはどうか。
- レイアウト — まず最終状態を構築します。下記の「アニメーションの前にレイアウト」を参照してください。
- アニメート — 次に、以下のルールを使用してモーションを追加します。
依頼されたものを構築します。 「タイトルカード」のリクエストは、「タイトルカード + 3つのサポートシーン + 環境音楽 + キャプション」のリクエストではありません。すべてのシーン、すべての要素、すべてのトゥイーンは、その存在を正当化する必要があります。追加のシーンや要素が作品を真に向上させる場合は、提案します — 追加しません。
小さな編集(色の修正、タイミング調整、1要素の追加)の場合は、ルールに直接スキップします。
アニメーションの前にレイアウト
すべての要素を、最も見える瞬間 — 完全に入力され、正しく配置され、まだ終了していないフレーム — に配置します。これを最初に静的なHTML+CSSとして記述します。まだGSAPは使用しません。
これが重要な理由: 要素をアニメーションの開始状態(画面外、スケール0、不透明度0)に配置し、それらが最終的に配置されるべき位置に向かってトゥイーンする場合、最終的なレイアウトを推測していることになります。重なりはビデオがレンダリングされるまで見えません。まず最終状態を構築することで、モーションを追加する前にレイアウトの問題を確認して修正できます。
プロセス
- 各シーンのヒーローフレームを特定します — 最も多くの要素が同時に表示される瞬間。これが構築するレイアウトです。
- そのフレームの静的CSSを記述します。
.scene-contentコンテナは、width: 100%; height: 100%; padding: Npx;、display: flex; flex-direction: column; gap: Npx; box-sizing: border-boxを使用して、シーン全体を埋める必要があります。パディングを使用してコンテンツを内側に押し込みます — コンテンツコンテナにposition: absolute; top: Npxを決して使用しないでください。絶対配置されたコンテンツコンテナは、コンテンツが残りのスペースより高い場合にオーバーフローします。position: absoluteは装飾用にのみ予約してください。 gsap.from()を使用してエントランスを追加します — 画面外/非表示からCSSの位置へアニメーションします。CSSの位置が真実のソースです。トゥイーンはそこに到達するまでの経路を記述します。(data-composition-srcを介して読み込まれたサブコンポジションでは、gsap.fromTo()を優先します — references/motion-principles.mdの耐荷重GSAPルールを参照してください。)gsap.to()を使用してエグジットを追加します — CSSの位置から画面外/非表示へアニメーションします。
例
/* scene-contentがシーンを埋め、パディングがコンテンツを配置 */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title {
font-size: 120px;
}
.subtitle {
font-size: 42px;
}
/* コンテナは任意のシーンサイズ(1920x1080、1080x1920など)に適合します。
パディングがコンテンツを配置します。Flex + gapが間隔を処理します。 */
誤り — ハードコードされた寸法と絶対配置:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// ステップ3: それらの位置にアニメーション
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// ステップ4: それらの位置からアニメーションアウト
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
要素が時間とともにスペースを共有する場合
要素Aが要素Bが同じ領域に入る前に終了する場合、両方ともそれぞれのヒーローフレームに対して正しいCSS位置を持つ必要があります。タイムラインの順序により、それらが視覚的に共存することはありません — しかし、レイアウトステップをスキップすると、タイミングエラーによって誤って重なるケースを捕捉できません。
意図的な重なりと見なされるもの
レイヤードエフェクト(テキストの背後にあるグロー、シャドウ要素、背景パターン)とzスタックデザイン(カードスタック、奥行きレイヤー)は意図的です。レイアウトステップは、意図しない重なり — 2つの見出しが互いに重なる、統計がラベルを覆う、コンテンツがフレームからはみ出す — を捕捉することです。
データ属性
すべてのクリップ
| 属性 | 必須 | 値 |
|---|---|---|
id | はい | 一意の識別子 |
data-start | はい | 秒数またはクリップID参照 ("el-1", "intro + 2") |
data-duration | img/div/コンポジションに必須 | 秒数。動画/音声はメディアの長さがデフォルト。 |
data-track-index | はい | 整数。同じトラックのクリップは重複できません。 |
data-media-start | いいえ | ソースへのトリムオフセット(秒数) |
data-volume | いいえ | 0-1(デフォルト 1) |
data-track-indexは視覚的なレイヤリングに影響しません — CSS z-indexを使用してください。
コンポジションクリップ
| 属性 | 必須 | 値 |
|---|---|---|
data-composition-id | はい | 一意のコンポジションID |
data-start | はい | 開始時間(ルートコンポジション:"0"を使用) |
data-duration | はい | GSAPタイムラインの長さよりも優先 |
data-width / data-height | はい | ピクセル寸法(1920x1080 または 1080x1920) |
data-composition-src | いいえ | 外部HTMLファイルへのパス |
data-variable-values | いいえ | サブコンポジションホスト上のインスタンスごとの変数オーバーライドのJSONオブジェクト |
ルートの<html>要素:
| 属性 | 必須 | 値 |
|---|---|---|
data-composition-variables | いいえ | 宣言された変数のJSON配列(id/type/label/default) — Studio編集UIを駆動し、getVariables()のデフォルトを提供します |
コンポジション構造
data-composition-srcを介して読み込まれるサブコンポジションは、<template>ラッパーを使用します。スタンドアロンコンポジション(メインのindex.html)は<template>を使用しません — data-composition-id divを直接<body>に配置します。スタンドアロンファイルで<template>を使用すると、すべてのコンテンツがブラウザから隠され、レンダリングが壊れます。
サブコンポジション構造:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- コンテンツ -->
<style>
[data-composition-id="my-comp"] {
/* スコープ付きスタイル */
}
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// トゥイーン...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
ルートで読み込み: <div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>
変数(パラメータ化されたコンポジション)
ソースHTMLを編集せずに、同じコンポジションを異なるコンテンツ(タイトル、テーマカラー、価格、キャプション)でレンダリングします。
3ステップのパターン:
- 宣言 コンポジションの
<html>ルートにdata-composition-variablesを使用して変数を宣言します。各エントリにはid、type(string、number、color、boolean、enumのいずれか)、label、defaultが必要です。列挙型エントリにはoptions: [{value, label}, ...]も必要です。 - 読み取り コンポジションのスクリプト内で
window.__hyperframes.getVariables()を使用して解決された値を読み取ります。宣言されたデフォルト + インスタンスごとのオーバーライド + CLIオーバーライドのマージ結果を返します。 - オーバーライド レンダリング時に
npx hyperframes render --variables '{...}'(トップレベル)またはホスト要素のdata-variable-values='{...}'(サブコンポジションのインスタンスごと)でオーバーライドします。
<!doctype html>
<html
data-composition-variables='[
{"id":"title","type":"string","label":"タイトル","default":"こんにちは"},
{"id":"theme","type":"enum","label":"テーマ","default":"light","options":[
{"value":"light","label":"ライト"},
{"value":"dark","label":"ダーク"}
]}
]'
>
<body>
<div data-composition-id="root" data-width="1920" data-height="1080">
<h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
<script>
const { title, theme } = window.__hyperframes.getVariables();
document.getElementById("hero").textContent = title;
document.body.dataset.theme = theme;
</script>
</div>
</body>
</html>
# 開発プレビューは宣言されたデフォルトを使用
npx hyperframes preview
# オーバーライドを使用してレンダリング
npx hyperframes render --variables '{"title":"Q4レポート","theme":"dark"}' --output q4.mp4
# またはJSONファイルから
npx hyperframes render --variables-file ./vars.json
サブコンポジションのインスタンスごとの値: 同じgetVariables()がdata-composition-srcを介して読み込まれたサブコンポジション内で動作します。各ホスト要素は独自の値を渡します:
<div
data-composition-id="card-pro"
data-composition-src="compositions/card.html"
data-variable-values='{"title":"Pro","price":"$29"}'
></div>
<div
data-composition-id="card-enterprise"
data-composition-src="compositions/card.html"
...
[翻訳のため省略]