プラグインインストール: セットアップまたはフレッシュネスコマンドの前に、このスキルがHyperFramesプラグイン内にある場合はプラグイン実行ルールに従ってください。スタンドアロンインストールの場合は、以下の更新手順を保持してください。
HyperFrames コア
エージェントの落とし穴(最初にお読みください):
- フレックス/
insetで中央揃えにし、後でGSAPのx/yを適用するノードにCSStransform: translate(-50%,-50%)を使用しないでください。リンター:gsap_css_transform_conflict。fromToまたはxPercent/yPercentを使用してください。 - シーン終了時に
tl.set(..., {visibility:"hidden"})を追加しないでください。ランタイムはすでにタイミング設定されたクリップを非表示にします。内部ノード(または.clipのopacity)での不透明フェードで十分です。キャプションのハードキルは別のルールです。 window.__timelines["id"]はルートのdata-composition-idと一致している必要があります。render後、サマリーの2行目を読んでください:beginframevsscreenshot、GPUモード、ステージタイミング。Linux上のscreenshot+software gpuは低速パスです。
HyperFrames はHTMLからビデオをレンダリングします。コンポジションとは、DOMが data-* 属性でタイミングを宣言し、アニメーションランタイムがシーク可能で、メディア再生がフレームワークによって所有されるHTMLファイルです。
このスキルは技術的契約です — 1つのhyperframesプロジェクトを構築する方法です。以下の本文はビルドガイドです;トピックごとの詳細は references/(次の目次)にあり、必要に応じて読んでください。プロセスドキュメント(ブリーフ、ストーリーボード、レビュー、プロダクション、ディスパッチ、フレームワーカー)は /hyperframes → references/ にあります。その他の関心事は、兄弟ドメインスキル — hyperframes-animation、hyperframes-creative、media-use、hyperframes-cli、hyperframes-registry にあります。 /hyperframes のケイパビリティマップに、各スキルがカバーする内容が示されています。
リファレンス
| ファイル | 読む目的… |
|---|---|
references/minimal-composition.md | 最小のレンダリング可能なコンポジションスケルトンから始める |
references/composition-patterns.md | モノリシック vs モジュラーを選択する;モジュラーな index.html を構造化する;サブコンポジションのアーキタイプを選ぶ |
references/data-attributes.md | 任意の data-*(ルート/クリップ/サブコンポジションホスト/レガシーエイリアス)を調べる;class="clip" を使用する |
references/tracks-and-clips.md | data-track-index が制御するもの(および制御しないもの)、z-index、別のクリップに対する相対タイミングを理解する;npx hyperframes timeline ですべてのトラックとクリップを一覧表示する |
references/creator-editing-recipes.md | 真実のカット/トリム/並べ替え/リタイム/フリーズ/カメラ/マスク/クロスフェード/オーディオ編集レシピとその制限をコピーする |
references/sub-compositions.md | サブコンポジション(ホスト属性、<template>、インスタンスごとの変数)を配線し、その内部でアニメーションさせる |
references/variables-and-media.md | 変数を宣言する;<video>/<audio> を配置し、ボリュームを設定し、トリムする |
references/determinism-rules.md | シーク可能なタイムラインを構築する;決定論性の禁止事項;レイアウト / テキストフィット |
references/full-screen-motion.md | 共有背景で全フレームモーションを作成する |
references/tailwind.md | Tailwind v4 プロジェクトで作業する(init --tailwind;ランタイム契約は Studio の v3 とは異なる) |
アニメーションランタイムの詳細(GSAP API、Lottie、Three.js 等)については、hyperframes-animation → adapters/<runtime>.md を参照してください。
コンポジションの構築
2つのルート形式(互換性なし)
- スタンドアロン(トップレベルの
index.html):ルート<div data-composition-id="…">は<body>に直接配置され、<template>ラッパーはありません。スタンドアロンルートをラップするとすべてのコンテンツが非表示になり、lintはそれを拒否します(standalone_composition_wrapped_in_template、エラー)。 - サブコンポジション(
data-composition-src経由でロード):ルートを<template>でラップします。これが記述する形式です:ローダーはプレーンな完全ドキュメントも受け入れ、その<body>にフォールバックしますが、テンプレート形式が例とツールが想定するものです。
⚠ 転送ルール:テンプレート化されたサブコンポジションの場合、アセンブラはファイル自身の
<head>の<style>/<script>を破棄します(packages/core/src/compiler/compositionAssembly.ts、hasTemplateゲート)ので、<style>/<script>はテンプレート内部に配置してください。<link>はどちらの場合も引き上げられます。 ⚠ ホストID規則:ホストスロット、内部テンプレート、およびwindow.__timelines["<id>"]キーに同じIDを指定してください。異なるローカルIDもサポートされています(アセンブラはファイル内の最初のルートにフォールバックします)が、不一致はサイレントであるため、特別な理由がない限り一致させてください。
ファイル形状、ホスト配線、およびプリレンダーチェックリスト → references/sub-compositions.md
ルートはサイズ指定が必要(サイレントレイアウトバグ)
スタンドアロンルートは width/height: 100% を作成します。キャンバスサイズは data-width/data-height です。ランタイムはそれらのピクセルをコンポジションルートにスタンプします。#root に 1920px/1080px をハードコードしないでください。スケルトン → references/minimal-composition.md
1つの一時停止タイムライン
各コンポジションは、window.__timelines["<id>"](キー = ルート data-composition-id)に正確に1つの gsap.timeline({ paused: true }) を登録します。非同期コールバック(document.fonts.ready)内で構築することもサポートされていますが、重要なのは構築完了後にのみ登録することです。レンダリング長はルートの data-duration であり、タイムラインの長さではありません:タイムラインがそれを超えて実行された場合は切り捨てられ、早く終了した場合は最後のフレームを保持します。ルートの data-duration を省略すると、長さは代わりに推測されます(タイムライン、メディアウィンドウ、またはアダプター)。window.__timelines = window.__timelines || {} は必要ありません:ランタイムはインラインスクリプトが実行される前にレジストリを作成し、lint はもはやそれを要求しません。サブタイムラインを手動でホストにネストしないでください;ランタイムは登録された子タイムラインを自動的にネストします。完全な契約(非GSAPランタイムを含む) → references/determinism-rules.md + hyperframes-animation/adapters/
最初のパス lint の落とし穴(最初のビルド失敗が保証されています)
lint が確かにキャッチするルールですが、事後にのみです。最初から正しく記述してください:
- CSS の初期
transformを GSAP トゥイーンと同じプロパティでペアにしないでください — CSS 値とトゥイーンの開始値が競合し、lintはgsap_css_transform_conflictで拒否します。CSStransform: translateX(-40px)の代わりに、gsap.fromTo(el, { x: -40 }, { x: 0 })でトゥイーン内に初期状態を設定してください。 <video>/<audio>にcrossoriginを絶対に付けないでください。lintはmedia_crossorigin_breaks_preview(エラー)で無条件に拒否します。これには canvas/WebGL/WebAudio の読み戻しも含まれます。抑制はありません。data-startを持つ<video>に、data-startも持つ祖先を与えないでください。lintはvideo_nested_in_timed_element(エラー)で拒否します。ラッパーまたはビデオのどちらか一方にのみタイミングを設定してください。両方には設定しないでください。- すべての
<audio>にはidが必要です。lintはmedia_missing_idで拒否し、id のない<audio>はミキサーにピックアップされないため、レンダリングは無音になります。 .clipをautoAlphaまたはvisibilityでトゥイーンしないでください —lintはgsap_animates_clip_elementで拒否します。代わりに子要素をアニメーションさせてください。- 名前付きCSS
font-familyには、出荷されたローカルファイルへのインライン@font-faceが必要です。そうしないとlintがfont_family_without_font_faceを発火します。 - サブコンポジションの
#rootはwidth/height: 100%(またはinset: 0)を使用し、1920px/1080pxをハードコードしないでください。キャンバスサイズはdata-width/data-heightです。
lint エラーは、レイアウトとコントラストの監査もオフにします:check はその後 0 sample(s) および 0/0 text checks を報告しますが、これはクリーンファイルのように読み取れますが、何も実行されていないことを意味します。それらの数値を信頼する前に、lint エラーをクリアしてください。
非交渉ルール(自動ゲートが見逃す可能性のあるサイレントバグ)
ここに示します;完全な根拠はリンクされたリファレンスにあります。違反しないでください:
- レンダリング時のクロック / 非シード
Math.random/ ネットワーク / 入力状態は禁止;repeat: -1は有限のルートdata-durationの下でのみ許可(これにクリップをエクスポート — そうでない場合は有限カウントを使用)。→determinism-rules.md .clip要素でdisplay、visibility、またはautoAlphaをトゥイーンしないでください。フレームワークがクリップの可視性を所有し、lintはそれを拒否します(gsap_animates_clip_element)。代わりに子をアニメーションさせてください。→determinism-rules.md- 本文テキストに
<br>を使用しないでください;変形された要素はブロックレベルでサイズ指定されている必要があります;パルスする絶対配置の装飾要素にはピーククリアランスが必要です。→determinism-rules.md <video>/<audio>はフラットなドキュメントクエリで検出されるため、フレームワークは任意のネスト深さ(サブコンポジションの<template>またはラッパーの内部を含む)でそれらをシークおよびデコードします。1つの厳しい制限:data-startを持つ<video>が、data-startも持つ別のプレーンな要素の内部にある場合、lintはエラーを出し、実際に失敗します(間違ったソースフレーム、その後クリップがスロット途中で消えます)。そのため、タイミングはラッパーかビデオのどちらか一方にのみ設定し、両方には設定しないでください。サブコンポジションホストは例外です:サブコンポジション内のメディアは正しくレンダリングされます。もう1つの注意点は配置ではなくタイムラインです:サブコンポジションのタイムラインはホストルート要素をアニメーションさせることができません。→variables-and-media.md- アセンブルされたページ全体で各
idを一意に保ってください(サブコンポジションの id にはコンポジション id を接頭辞として付け、#<id>-heroのようにする)これにより、自身の#idCSS およびgetElementById呼び出しが解決されます。フレームインジェクションはもはやそれに依存しません:コンパイラはすべてのvideo[src]/audio[src]/img[src]にドキュメント一意のdata-hf-render-idをスタンプします。src属性の代わりに<source>子を使用するメディアはスタンプされないため、そこで一意の id が依然として重要です。→composition-patterns.md - コンポジションルートへの全画面塗りつぶしは、通常のレンダリングでは問題ありません。これはレイヤードコンポジットパス(HDRコンテンツ、またはシェーダートランジションを使用するコンポジション)でのみドロップされます。この場合、エンジンはすべてのコンポジションルートを透明にして、下のレイヤーが透けて見えるようにします。コンポジションがシェーダートランジションまたはHDRメディアを使用する場合は、塗りつぶしを全画面表示の子(
position:absolute; inset:0)に配置してください。→composition-patterns.md
既存のコンポジションの編集
- 最初にファイルを読んでください。無関係なタイミング、トラック、ID、変数、メディアパスは保持してください。
- プロジェクトのタイムライン(トラック、クリップ、開始、終了、再生内容)を把握するには、
index.htmlとすべてのサブコンポジションファイルを読む代わりに、npx hyperframes timeline [--json]を実行してください。 - 既存のコンポジションIDとタイムラインキーを一致させてください。
- クリップの追加:その周囲のクリップに対して意図的に
data-start/data-durationを設定してください。data-track-indexはStudioの表示レーンであり、タイミング制約ではないため、空いている必要はありません。 - ルートの
data-durationを超えて終了するクリップは切り捨てられます:同じ編集でルートのdata-durationをクリップの終了まで拡張してください(lintはclip_ends_past_root_durationを警告します)。 - 任意のコンポジション要素の
data-hiddenは、プレビューとレンダリングの両方で非表示にし、その時間ウィンドウをオーバーライドします;これは非破壊的/可逆的であり、Studioのタイムライン目のアイコンで切り替えられます。 - サブコンポジションの追加:ホストを配線する前に、その内部の
data-composition-idを確認してください。
検証
コマンドの詳細については hyperframes-cli を使用してください
-
npx hyperframes checkが合格する(lint、ランタイム、レイアウト、モーション、コントラストにわたって0件の検出) - サブコンポジションを含むプロジェクト:
npx hyperframes snapshot --at <midpoints>を実行し、各フレームを目視確認する - レビュー用に
npx hyperframes preview --backgroundを実行する(ユーザーはStudioのタイムラインで何でも編集でき、サーバーは呼び出し元のコマンドを生き残ります) - ユーザーの承認後にのみ
npx hyperframes renderを実行する