HyperFrames
HTMLが動画の唯一の情報源です。コンポジションは、タイミング用のdata-*属性、アニメーション用のGSAPタイムライン、そして外観用のCSSを持つHTMLファイルです。フレームワークがクリップの表示、メディア再生、タイムライン同期を処理します。
アプローチ
探索(探索的リクエストのみ)
方向性が決まっていないオープンエンドなリクエスト(「製品ローンチ動画を作って」「ブランド用に何か作って」)に対しては、色を選ぶ前に意図を理解します。
- オーディエンス — 誰が見るのか? 開発者? 役員? 一般消費者?
- プラットフォーム — どこで再生されるのか? ソーシャル(15秒)、ウェブサイトのヒーロー、製品デモ、内部用?
- 優先順位 — 最も重要なのは何か? モーションの品質? コンテンツの正確さ? ブランドの忠実性? スピード?
- バリエーション — ユーザーは選択肢を望んでいるのか、それとも単一の最善のものを望んでいるのか?
具体的なリクエスト(「タイトルカードを追加して」「シーン3のタイミングを修正して」)の場合は、探索をスキップします。
探索的リクエストの場合は、単なる色の変更ではなく、異なるペーシング、エネルギーレベル、または構造的アプローチにおいて意味のある2〜3のバリエーションを提供することを検討します。1つは安全/予想通り、もう1つは野心的なものです。これを必須とせず、適切な場合に利用できるツールとして提供します。
ステップ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から来ます。ブランドカラーは、ウェブ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-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>
ビデオとオーディオ
ビデオは muted playsinline でなければなりません。オーディオは常に別の <audio> 要素です:
<video
id="el-v"
data-start="0"
data-duration="30"
data-track-index="0"
src="video.mp4"
muted
playsinline
></video>
<audio
id="el-a"
data-start="0"
data-duration="30"
data-track-index="2"
src="video.mp4"
data-volume="1"
></audio>
タイムライン契約
- すべてのタイムラインは
{ paused: true }で開始されます — プレーヤーが再生を制御します - すべてのタイムラインを登録します:
window.__timelines["<composition-id>"] = tl - フレームワークはサブタイムラインを自動的にネストします — 手動で追加しないでください
- 期間は
data-durationから取得され、GSAPタイムラインの長さからは取得されません - 期間を設定するために空のトゥイーンを作成しないでください
ルール(譲歩不可)
決定論的: Math.random()、Date.now()、または時間ベースのロジックは使用しないでください。擬似ランダム値が必要な場合は、シード付きPRNG(例:mulberry32)を使用してください。
GSAP: 視覚的なプロパティ(opacity、x、y、scale、rotation、color、backgroundColor、borderRadius、transform)のみをアニメーションします。visibility、display をアニメーションしたり、video.play() / audio.play() を呼び出したりしないでください。
アニメーションの競合: 複数のタイムラインから同じ要素の同じプロパティを同時にアニメーションしないでください。
repeat: -1 禁止: 無限リピートのタイムラインはキャプチャエンジンを壊します。コンポジションの期間から正確なリピート数を計算します:repeat: Math.ceil(duration / cycleDuration) - 1。
同期タイムライン構築: async / await、setTimeout、またはPromise内でタイムラインを構築しないでください。キャプチャエンジンは、ページロード後に window.__timelines を同期的に読み取ります。フォントはコンパイラによって埋め込まれるため、すぐに利用可能です — フォントのロードを待つ必要はありません。
絶対にしてはいけないこと:
window.__timelinesの登録を忘れる- オーディオにビデオを使用する — 常にミュートされたビデオ + 別の
<audio> - ビデオをタイミング付きのdiv内にネストする — タイミングなしのラッパーを使用する
data-layer(data-track-indexを使用)またはdata-end(data-durationを使用)を使用する- ビデオ要素の寸法をアニメーションする — ラッパーdivをアニメーションする
- メディアでplay/pause/seekを呼び出す — フレームワークが再生を所有します
data-composition-idなしでトップレベルのコンテナを作成する- 任意のタイムラインまたはトゥイーンで
repeat: -1を使用する — 常に有限リピートにする - タイムラインを非同期に構築する(
async、setTimeout、Promise内) - 後続のシーンからのクリップ要素に
gsap.set()を使用する — それらはページロード時にDOMに存在しません。代わりに、クリップのdata-start時間以降のタイムライン内でtl.set(selector, vars, timePosition)を使用してください。 - コンテンツテキストで
<br>を使用する — 強制改行は実際にレンダリングされたフォント幅を考慮しません。自然に折り返されるテキストに<br>を追加すると、不要な改行が発生し、重なりの原因になります。代わりにmax-widthを使用してテキストを折り返してください。例外:各単語が意図的に別々の行にある短い表示タイトル(例:130pxでの「THE\nIMMORTAL\nGAME」)。
シーントランジション(譲歩不可)
マルチシーンコンポジションは、以下のすべてのルールに従う必要があります。いずれか1つに違反すると、コンポジションは壊れます。
- **...
[翻訳のために一部省略]