HyperFrames
HTMLがビデオの信頼できる情報源です。コンポジションは、タイミングのための data-* 属性、アニメーションのためのGSAPタイムライン、および外観のためのCSSを持つHTMLファイルです。フレームワークは、クリップの可視性、メディア再生、タイムライン同期を処理します。
アプローチ
HTMLを書く前に、高いレベルで考えてください:
- 何 — 視聴者は何を体験すべきか? ナラティブアーク、重要な瞬間、感情的なビートを特定します。
- 構造 — いくつのコンポジションが存在するか、そのうちどれがサブコンポジションか、インラインか、どのトラックが何を運ぶか(ビデオ、オーディオ、オーバーレイ、キャプション)。
- タイミング — どのクリップが持続時間を決定するか、どこにトランジションが配置されるか、ペーシングはどうか。
- レイアウト — まず最終状態を構築します。以下の「アニメーションの前にレイアウト」を参照してください。
- アニメート — 次に、以下のルールを使用して動きを追加します。
小さな編集(色の修正、タイミングの調整、1つの要素の追加)の場合は、ルールに直接進んでください。
視覚的アイデンティティゲート
次の順序で確認してください:
- プロジェクトにDESIGN.mdが存在しますか? → それを読みます。その正確な色、フォント、モーションルール、「やってはいけないこと」の制約を使用します。
- visual-style.mdが存在しますか? → それを読みます。その
style_prompt_fullと構造化フィールドを適用します。(注:visual-style.mdはプロジェクト固有のファイルです。visual-styles.mdは8つの名前付きプリセットを持つスタイルライブラリです — 別のファイルです。) - ユーザーがスタイルを指定しましたか(例:「スイスパルス」、「ダークでテクニカル」、「高級ブランド」)? → visual-styles.md を読み、8つの名前付きプリセットを確認します。最小限のDESIGN.mdを生成します:
## Style Prompt(1段落)、## Colors(役割付きの3~5個の16進数値)、## Typography(1~2のフォントファミリー)、## What NOT to Do(3~5のアンチパターン)。 - 上記のいずれでもない場合? → HTMLを作成する前に3つの質問をします:
- ムードは?(爆発的/シネマティック/流動的/テクニカル/混沌/温かみ)
- 明るいキャンバスか暗いキャンバスか?
- 特定のブランドカラー、フォント、視覚的参照はありますか? 次に、回答から最小限のDESIGN.mdを生成します。
すべてのコンポジションは、そのパレットとタイポグラフィをDESIGN.md、visual-style.md、または明示的なユーザー指示に遡らなければなりません。#333、#3b82f6、または Roboto に手を伸ばしている場合 — このステップをスキップしています。
モーションのデフォルト、サイジング、エントランスパターン、イージングについては、house-style.md に従ってください。ハウススタイルは物事がどのように動くかを処理します。DESIGN.mdは物事がどのように見えるかを処理します。
アニメーションの前にレイアウト
すべての要素を、その最も見える瞬間 — 完全に入り、正しく配置され、まだ退出していないフレーム — に配置します。これをまず静的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の位置が真実であり、トゥイーンはそこに到達するための経路を説明します。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をアニメーションする
- メディアの再生/一時停止/シークを呼び出す — フレームワークが再生を所有します
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つでも違反すると、壊れたコンポジションになります。
- シーン間では常にトランジションを使用します。 ジャンプカットは禁止です。例外はありません。
- すべてのシーンで常にエントランスアニメーションを使用します。 すべての要素は
gsap.from()を介してINアニメーションします。要素が完全に形成された状態で現れてはいけません。シーンに5つの要素がある場合、5つのエンタランヌトゥイーンが必要です。 - 最終シーン以外ではエグジットアニメーションを決して使用しないでください。 つまり:トランジションが発火する前に、透明度を0、yを画面外、スケールを0にアニメーションする
gsap.to()や、その他の「アウト」アニメーションは許可されません。トランジション自体がエグジットです。発信シーンのコンテンツは、トランジションが開始する瞬間に完全に表示されている必要があります。 - 最終シーンのみ: 最後のシーンでは要素をフェードアウトしてもかまいません(例:フェードトゥブラック)。これが
gsap.to(..., { opacity: 0 })が許可される唯一のシーンです。
間違い — トランジション前のエグジットアニメーション:
// 禁止 — トランジションが使用できる前にシーンを空にします
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// トランジションは空のフレームで発火します
正しい — エントランスのみ、トランジションがエグジットを処理:
// シーン1 エントランスアニメーション
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// エグジットトゥイーンなし — 7.2秒でのトランジションがシーンチェンジを処理します
// シーン2 エントランスアニメーション
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);
アニメーションガードレール
- 最初のアニメーションを0.1-0.3秒オフセットします(t=0ではありません)
- エントランヌトゥイーン全体でイージングを変える — シーンごとに少なくとも3つの異なるイージングを使用します
- シーン内でエントランスパターンを繰り返さない
- 暗い背景に全画面の線形グラデーションを避ける(H.264バンディング — ラジアルまたはソリッド+局所的なグローを使用)
- レンダリングされたビデオでは60px+の見出し、20px+の本文、16px+のデータラベル
- 数字列には
font-variant-numeric: tabular-nums
visual-style.md またはアニメーションの指示がない場合、美的デフォルトについては house-style.md に従ってください。
タイポグラフィとアセット
- フォント: CSSで必要な
font-familyを記述するだけで、コンパイラがサポートされているフォントを自動的に埋め込みます。フォントがサポートされていない場合、コンパイラは警告します。 - 外部メディアには
crossorigin="anonymous"を追加します - SVGフィルターIDはグローバルに一意である必要があります — プレフィックスを付けてください(例:
glow-filter-1)
サンプルテンプレート
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>最小構成</title>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<style>
body { margin: 0; overflow: hidden; }
</style>
</head>
<body>
<div data-composition-id="root" data-width="1920" data-height="1080" data-start="0" data-duration="5">
<div class="scene-content">
<h1 id="title">こんにちは世界</h1>
<p id="subtitle">HyperFramesのご紹介</p>
</div>
<style>
[data-composition-id="root"] .scene-content {
display: flex; flex-direction: column; justify-content: center; align-items: center;
width: 100%; height: 100%; box-sizing: border-box; background: #1a1a2e;
}
[data-composition-id="root"] h1 { color: #e94560; font-size: 80px; font-family: sans-serif; }
[data-composition-id="root"] p { color: #fff; font-size: 32px; font-family: sans-serif; }
</style>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
tl.from("#title", { y: 50, opacity: 0, duration: 0.8, ease: "power3.out" }, 0.2);
tl.from("#subtitle", { y: 30, opacity: 0, duration: 0.6, ease: "power2.out" }, 0.5);
window.__timelines["root"] = tl;
</script>
</div>
</body>
</html>
CLIスキル
コマンドライン操作(init、lint、preview、render、transcribe、tts)については、hyperframes-cliスキルを参照してください。