プラグインのインストール: セットアップや最新化コマンドの前に、このスキルが HyperFrames プラグイン内にある場合は、プラグイン実行ルール に従ってください。スタンドアロンインストールの場合は、以下の更新手順を維持してください。
HyperFrames Core
エージェントの落とし穴(最初に読んでください):
- 中央揃えには flex/
insetを使用し、後で GSAP のx/yでアニメーションさせるノードに CSStransform: translate(-50%,-50%)を使わないでください。 lint: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 です。ランタイムはそれらのピクセルをコンポジションルートにスタンプします。1920px/1080px を #root にハードコードしないでください。スケルトン → 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で拒否します。CSS のtransform: translateX(-40px)の代わりに、gsap.fromTo(el, { x: -40 }, { x: 0 })でトゥイーン内に初期状態を設定してください。 <video>/<audio>にcrossoriginを絶対に付けないでください。lintはmedia_crossorigin_breaks_preview(エラー)で無条件に拒否します。これにはキャンバス/WebGL/WebAudio の読み戻しも含まれます。抑制方法はありません。<video data-start>に、同じく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です。
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つのハードリミット:<video data-start>が同じくdata-startを持つ別の プレーンな 要素の内側にある場合、lintはエラーを出します。そして、その失敗は実際のものです(間違ったソースフレーム、その後クリップがスロット途中で消えます)。そのため、ラッパーまたはビデオのどちらかにタイミングを設定し、両方には決して設定しないでください。サブコンポジションホストは例外です:サブコンポジション内のメディアは正しくレンダリングされます。もう一つの注意点は配置ではなくタイムラインです:サブコンポジションのタイムラインはホストルート要素をアニメーションできません。→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を実行すること