HyperFrames
HTML がビデオの信頼できる情報源です。コンポジションは、タイミング用の data-* 属性、アニメーション用の GSAP タイムライン、および外観用の CSS を備えた HTML ファイルです。フレームワークは、クリップの可視性、メディア再生、タイムラインの同期を処理します。
包括的な範囲と吸収された狭いワークフロー
このスキルは、HyperFrames オーサリングのクラスレベルの包括的なものです。コンポジションの構造、タイミング、アニメーション、ビジュアルアイデンティティ、キャプション、オーディオリアクティブビジュアル、プロダクション品質のシーン構築をカバーします。コマンドリファレンスには hyperframes-cli スキルを、ソースマテリアルが既存のウェブサイトである場合には website-to-hyperframes を使用してください。1 セッションのプロダクション/デバッグに関する狭いメモは、ここではサポートリファレンスに格下げされました。
サブセクション: プロダクションワークフローの落とし穴
過去のプロダクションノートでは、いくつかの環境トラップが依然として有用であることが強調されていました:
- レンダリング時には、ASCII のみのプロジェクト/出力パスを推奨します。非 ASCII パスは、ヘッドレス Chrome またはレンダラサブプロセスを壊す可能性があります。
- Conda FFmpeg で MP4 エンコードが失敗した場合は、
export PATH=/usr/bin:$PATHでシステム FFmpeg を強制するか、フォールバックとして WebM をレンダリングします。 - カスタムタイムラインオブジェクトが GSAP の代わりに使用される場合、それらは GSAP 互換の
duration()、pause()、およびseek(time)メソッドを公開する必要があります。 - 最終的なビデオが黒または空に見える場合は、まず、タイミング設定された
.clipコンテナが、その子要素のみがアニメーション化されている間に非表示になっていないかを確認します。シーンのラッパーでの.hidden { display: none; }のようなユーティリティクラスは、古典的な失敗モードを生成します: 音声はレンダリングされ、背景はレンダリングされますが、親シーンがレイアウト/ペイントに入ることがないため、テキスト/カードは決して表示されません。タイミング設定されたシーンラッパーの場合は、display: noneの代わりにopacity: 0またはタイムライン制御の不透明度を使用して非表示にします。 - GSAP などのクリティカルなランタイム JS については、レンダリング中のライブ CDN フェッチに依存するよりも、プロジェクト内でローカルコピーをベンダリングする(例
assets/gsap.min.js)ことを推奨します。 - スタンドアロンコンポジションに
<link rel="icon" href="data:,">を追加して、プロジェクトの一部としてファビコンがない場合の、ヘッドレスブラウザのファビコン 404 ノイズを抑制します。 - レンダリングの成功終了コードだけを信頼するのではなく、FFmpeg でフレームを抽出しスクリーンショットを検査して、視覚的に確認します。
格下げされたサポートリファレンス
references/hyperframes-video-production.mdreferences/hyperframes-workflow.md
アプローチ
HTML を書く前に、ハイレベルで考えてください:
- 何を — 視聴者は何を体験すべきか? ナラティブアーク、キーモーメント、感情的なビートを特定します。
- 構造 — いくつのコンポジションがあるか、どれがサブコンポジションでどれがインラインか、どのトラックが何を運ぶか(ビデオ、オーディオ、オーバーレイ、キャプション)。
- タイミング — どのクリップが期間を決定するか、トランジションはどこに配置されるか、ペーシングはどうか。
- レイアウト — 最初にエンドステートを構築します。「アニメーションの前のレイアウト」を参照してください。
- アニメート — 次に、以下のルールを使用してモーションを追加します。
小さな編集(色の修正、タイミングの調整、1 つの要素の追加)の場合は、ルールに直接スキップします。
ビジュアルアイデンティティゲート
この順序で確認してください:
- プロジェクトに DESIGN.md が存在しますか? → それを読んでください。その正確な色、フォント、モーションルール、および「やってはいけないこと」の制約を使用します。
- visual-style.md が存在しますか? → それを読んでください。その
style_prompt_fullと構造化フィールドを適用します。(注:visual-style.mdはプロジェクト固有のファイルです。visual-styles.mdは 8 つの名前付きプリセットを持つスタイルライブラリです — 別のファイルです。) - ユーザーがスタイルを指定しましたか(例:「Swiss Pulse」、「ダークでテクニカル」、「ラグジュアリーブランド」)? → 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: それらの位置に INTO アニメーション
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: それらの位置から OUT アニメーション
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/compositions に必須 | 秒数。ビデオ/オーディオはメディアの長さにデフォルト設定されます。 |
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」)。
シーントランジション(交渉不可)
すべてのマルチシーンコンポジションは、これらのルールのすべてに従わなければなりません。それらのいずれかに違反すると、コンポジションは壊れます。
- シーン間では常にトランジションを使用します。ジャンプカットは禁止です。例外はありません。
- すべてのシーンで常にエントランスアニメーションを使用します。すべての要素は
gsap.from()を介して IN アニメーションします。完全に形成された状態で表示される要素はありません。シーンが
…
[翻訳のために切り詰められました]