HyperFrames
HTMLがビデオの信頼できる唯一の情報源です。コンポジションは、タイミングのための data-* 属性、アニメーションのための GSAP タイムライン、および外観のための CSS を含む HTML ファイルです。フレームワークは、クリップの可視性、メディアの再生、およびタイムラインの同期を処理します。
属性API、コンポジション/テンプレート構造、変数、およびメディアルール: references/authoring.md。セッションで最初のコンポジションHTMLを作成する前に読んでください。
アプローチ
発見 (探索的なリクエストのみ)
ユーザーが方向性を決めていない自由形式のリクエスト(「製品ローンチビデオを作って」)の場合、色を選ぶ前に意図を理解します: 視聴者、プラットフォーム、優先事項(モーション品質 vs 正確性 vs スピード)、およびバリエーションが必要かどうか。バリエーションが必要な場合、ペースや構造が異なる2~3のオプション(1つは安全、1つは野心的)を提供します。色の交換ではありません。
具体的なリクエスト(「タイトルカードを追加して」、「シーン3のタイミングを修正して」)の場合は、発見をスキップします。
ステップ 1: デザインシステム
design.md または DESIGN.md が存在する場合、最初にそれを読んでください(大文字小文字の両方 - Linuxでは別のファイルです)。ブランドカラー、フォント、制約の信頼できる唯一の情報源であり、その正確な値を使用します。フォント名が指定されているが、fonts/ に対応する .woff2 ファイルがなく、組み込みの一致もない場合は、HTMLを書く前にユーザーに警告します。
design.md が存在しない場合、選択肢を提供します:
- ユーザーがスタイルやムードを指定した? visual-styles.md (8つの名前付きプリセット)を読み、最も近いものを選びます。
- 視覚的にブラウズする? デザインピッカーを実行します - references/design-picker.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: 計画
- What - 物語のアーク、重要な瞬間、感情のビート。
- Structure - コンポジションの数、サブコンポジション vs インライン、各トラックが何を担うか。
- Rhythm - 実装前にシーンのリズムを宣言します(fast-fast-SLOW-fast-SHADER-hold)。テンプレート: references/beat-direction.md。
- Timing - どのクリップが持続時間を決定し、トランジションがどこに配置されるか。
- Layout - 最初に最終状態を構築します(次のセクション)。
- Animate - 次にモーションを追加します。
依頼されたものだけを構築します。 「タイトルカード」は「タイトルカード + 3つの補助シーン + 音楽 + キャプション」ではありません。追加を提案することはできますが、自動的に追加してはいけません。
小さな編集の場合は、ルールに直接進みます。
アニメーションの前にレイアウト
すべての要素を最も見える瞬間にあるべき位置に配置します - 完全に入力され、正しく配置され、まだ退出していない状態。最初に静的なHTML + CSSとして記述します。まだGSAPは使わないでください。
理由: 要素をアニメーションの開始状態(画面外、不透明度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を決して使用しないでください(コンテンツが増えるとオーバーフローします)。絶対位置は装飾用に予約します。 gsap.from()による入力 - 画面外からCSSの位置へアニメーションします。CSSが基本真実であり、トゥイーンはその旅路です。(data-composition-src経由でロードされるサブコンポジション:gsap.fromTo()を推奨 - references/motion-principles.md を参照)。- 最終シーンのみ:
gsap.to()による退出。 他のすべてのシーンは完全に表示された状態で終了します - トランジション自体が退出です(以下のトランジションルール3)。
要素Aが要素Bが同じ領域に入る前に退出する場合、両方に自身のヒーローフレームに対する正しいCSS位置を与えます - タイムラインがそれらを共存させないようにし、レイアウトステップでタイミングエラーによる偶発的な重なりをキャッチします。意図的なレイヤリング(テキストの後ろのグロー、カードスタック)は問題ありません。このステップは偶発的な重なり(2つの見出しの衝突、ラベルを覆う統計情報、フレーム外のコンテンツ)をキャッチするために存在します。
タイムライン契約
- すべてのタイムラインは
{ paused: true }で開始します - プレーヤーが再生を制御します - すべてのタイムラインを登録します:
window.__timelines["<composition-id>"] = tl - フレームワークがサブタイムラインを自動的にネストします - 手動で追加しないでください
- 持続時間はGSAPタイムラインの長さではなく
data-durationから取得します - 持続時間を設定するために空のトゥイーンを作成しないでください
ルール (譲歩不可)
決定論的: 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を使用する - タイムラインを非同期に構築する
- 後のシーンのクリップ要素に
gsap.set()を使用する - それらはページロード時にDOMに存在しません。クリップのdata-start以降でtl.set(selector, vars, timePosition)を使用します。 - コンテンツテキストで
<br>を使用する - 自然な折り返しと重なり、オーバーフローの原因になります。代わりにmax-widthを使用します。例外: 意図的に1行に1単語の短い表示タイトル。
シーン遷移 (譲歩不可)
すべてのマルチシーンコンポジションは、以下の4つすべてに従わなければなりません。1つでも違反すると、壊れたコンポジションになります。
- シーン間では常にトランジションを使用します。 ジャンプカットは禁止です。
gsap.from()を使用してすべての要素を入力アニメーション化します。 完全に形成された状態で表示されるものはありません。5つの要素は5つの入力トゥイーンを意味します。- 最終シーン以外では出口アニメーションを決して使用しません。 トランジションの前に不透明度をフェードアウト、画面外に移動、または0にスケーリングする
gsap.to()は禁止です。トランジション自体が出口であり、トランジションが発火するとき、出ていくシーンは完全に見えている必要があります。トランジション前の出口トゥイーンは、トランジションに空のフレームを渡します。 - 最終シーンのみ要素をフェードアウトしてもよい。
トランジションの選択と実装: references/transitions.md。
アニメーションガードレール
- 最初のアニメーションは0.1~0.3秒オフセットします(t=0ではない)
- イージングを変化させます - シーンごとに少なくとも3種類の異なるイージング、シーン内で繰り返される入力パターンは禁止
- 暗い背景での全画面リニアグラデーションは避けます(H.264バンディング) - ラジアルまたはソリッド + 局所的なグロー
- 見出しは60px以上、本文は20px以上、データラベルは16px以上
- 数値列には
font-variant-numeric: tabular-numsを使用します
既存のコンポジションの編集
- 実際のファイルを読み込み、推測しないでください。 コンポジション自体が仕様です - ソースから正確な16進コード、フォント、イージングパターンを抽出します(記憶からではない)。
- リクエストされたもののみ変更し、無関係なクリップのタイミングは保持します。
出力チェックリスト
高速(即座に実行、結果をブロック):
-
npx hyperframes lintとnpx hyperframes validateの両方がパスする - design.md が存在する場合、デザイン準拠が確認されている
低速(プレビュー表示中に並行して実行):
-
npx hyperframes inspectがパスするか、報告されたすべてのオーバーフローが意図的にマークされている - コントラスト警告が対処されている
- アニメーションの振り付けが確認されている(アニメーションマップスクリプト)
各チェックの実行方法と修正方法: references/quality-checks.md。
リファレンス一覧
新しいコンポジションでは常に読むこと:
| ファイル | 内容 |
|---|---|
| references/authoring.md | data属性、テンプレート構造、変数、ビデオ/オーディオ、フォント/アセット |
| references/video-composition.md | ビデオメディアルール - これらはWebの直感を上書きします |
| references/typography.md | フォントペアリング、OpenType、暗い背景の調整 |
| references/motion-principles.md | モーションデザイン、画像モーション、重要なGSAPルール |
マルチシーンコンポジションでも常に読むこと:
| ファイル | 内容 |
|---|---|
| references/beat-direction.md | リズムテンプレート、振り付け動詞、深度レイヤー |
| references/transitions.md | トランジション選択; カタログ は実装へのルートを提供; シェーダートランジションは @hyperframes/shader-transitions npmパッケージにあります(node_modules 内のソースを読むこと) |
タスクが必要とする場合に読むこと:
| ファイル | 読むタイミング |
|---|---|
| references/quality-checks.md | inspect/contrast/design/animation-mapチェックの実行時 |
| references/cli.md | 任意のCLIコマンド; ビルド/レンダリングのトラブルシューティング |
| references/captions.md | オーディオタイミングに同期されたテキスト |
| references/transcript-guide.md | キャプション側のトランスクリプト処理(CLI呼び出しはmedia.mdにあります) |
| references/dynamic-techniques.md | 動的キャプションアニメーション(カラオケ、スラム、スキャッター) |
| references/audio-reactive.md | 音楽/音声に反応するビジュアル |
| references/css-patterns.md | マーカーハイライト(ハイライト、サークル、バースト、スクリブル) |
| references/techniques.md | ビートごとの計画手法(コード付き11パターン) |
| references/narration.md | ナレーション/TTSのペーシングとスクリプト構造 |
| references/media.md | TTS(Kokoro)、文字起こし(Whisper)、背景除去 |
| references/prompt-expansion.md | アプローチのステップ2 |
| references/design-picker.md | design.md を視覚的に作成する |
| references/from-website.md | ウェブサイトをビデオに変換する |
| references/registry.md | レジストリブロックのインストール/コントリビュート(hyperframes add) |
| visual-styles.md | ユーザーがスタイルを指定した場合; design.md の生成 |
| house-style.md | design.md がない場合の美的デフォルト |
| patterns.md | PiP、タイトルカード、スライドショー |
| data-in-motion.md | データ、統計、インフォグラフィック |
ランタイムアダプター(コンポジションがGSAPの代わりにそのランタイムを使用する場合に読むこと): waapi、lottie、three、animejs、css-animations、typegpu。