プラグインインストール: セットアップやフレッシュネスコマンドの前に、このスキルが HyperFrames プラグイン内にある場合は プラグイン実行ルール に従ってください。スタンドアロンインストールは以下の更新手順を保持します。
HyperFrames Core は何をしますか?
エージェントの落とし穴(最初に読んでください):
- flex/
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行目(beginframeとscreenshot、GPUモード、ステージタイミング)を読んでください。screenshot+ Linux でのsoftware gpuは低速パスです。
HyperFrames はHTMLからビデオをレンダリングします。コンポジションは、data-* 属性でタイミングを宣言するDOMを持つ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 が キャッチする ルールですが、事後的にのみです。最初から正しく記述してください。
- 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(エラー)で無条件に拒否します。キャンバス/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は、ハードコードされた1920px/1080pxではなく、width/height: 100%(またはinset: 0)を使用します。キャンバスサイズはdata-width/data-heightです。
リンターの エラー は、レイアウトとコントラストの監査もオフにします。check はその後 0 sample(s) と 0/0 text checks を報告します。これはクリーンなファイルのように見えますが、何も実行されなかったことを意味します。これらの数値を信頼する前に、リンターエラーをクリアしてください。
非交渉ルール(自動ゲートが見逃す可能性のある静的なバグ)
ここに表示されます。完全な根拠はリンク先のリファレンスにあります。違反しないでください。
- レンダリング時のクロック/シードされていない
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がパスする(リンター、ランタイム、レイアウト、モーション、コントラスト全体で0件の検出) - サブコンポジションを含むプロジェクト:
npx hyperframes snapshot --at <midpoints>を実行し、各フレームを目視確認 - レビュー用に
npx hyperframes preview --background(ユーザーはStudioのタイムラインで何でも編集でき、サーバーは呼び出しコマンド後も存続します) - ユーザーの承認後にのみ
npx hyperframes render