Communitygithub.com

sandeshrajbhandari/hyperframes-instruct

HyperFramesコンポジション契約 — 単一のレンダリング可能なプロジェクトを構築するためのものです。コンポジション構造、`data-*`タイミング属性、`class="clip"`、トラック、サブコンポジション、変数、フレームワーク管理のメディア再生、決定論的レンダリングルール、およびバリデーションに使用します。コンポジションHTMLを記述する前にお読みください。

hyperframes-instruct とは?

HyperFramesはHTMLからビデオをレンダリングするフレームワークです。このスキルは「技術契約」として機能し、単一のHyperFramesプロジェクトを構築するためのすべてのルールと構造を定義します。コンポジションはHTMLファイルであり、そのDOMは`data-*`属性を使用してタイミングを宣言し、アニメーションランタイムはシーク可能で、メディア再生はフレームワークが管理します。このスキルでは、独立したルート形式とサブコンポジション形式の2つのルート形式、`gsap.timeline({ paused: true })`を使用した正確に1つの一時停止タイムラインの登録、トラックとクリップの管理方法、決定論的レンダリングのルールなどをカバーしています。また、クリエイター向けの編集レシピ、バリアブルとメディアの操作、フルスクリーンモーションの作成に関する詳細なリファレンスも提供されています。AIエージェントや開発者がこのスキルを使用する際には、CSSのtransformとGSAPのx/yの競合を避けることや、シーン終了時のvisibility非表示設定を行わないなど、特定の落とし穴に注意する必要があります。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sandeshrajbhandari/hyperframes-instruct/tree/HEAD/.agents/skills/hyperframes-core

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

プラグインのインストール: セットアップやfreshnessコマンドの前に、このスキルがHyperFramesプラグイン内にある場合はプラグインインストールルールに従ってください。スタンドアロンインストールの場合は、以下の更新手順をそのまま使用します。

HyperFrames Core

エージェントの落とし穴(最初に読んでください):

  • 中央揃えは flex/inset で行い、後でGSAPの x/y を適用するノードにCSSの transform: 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 vs screenshot、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.mddata-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.mdTailwind 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 で拒否します。代わりに、CSSの transform: 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 です。

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)。これにより、自身の #id CSS および 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 を実行

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

sandeshrajbhandari/hyperframes-instruct

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

sandeshrajbhandari/hyperframes-instruct

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

sandeshrajbhandari/hyperframes-instruct

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), automation envelopes drawn on a track's volume or any effect parameter, or one submix bus carrying a chain, a fader and an automation clock for several tracks at once (`<hf-audio-group>`). Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

sandeshrajbhandari/hyperframes-instruct

Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, timeline, history, clean, docs, benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.

sandeshrajbhandari/hyperframes-instruct

Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use `hyperframes-animation`.

sandeshrajbhandari/hyperframes-instruct

Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe, Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe 2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths, masks, SVG morph/draw, text trails, 3D depth, or `hyperframes keyframes` diagnostics. Don't use for broad scene strategy, brand design, media sourcing, captions, or general video planning.

sandeshrajbhandari/hyperframes-instruct

Search, install, and wire registry blocks and components into HyperFrames compositions. Use BEFORE hand-building any named visual — whenever a brief, a user, or a storyboard names a look, effect, treatment, or transition such as CRT scanlines, glitch, chromatic aberration, film grain, a shimmer sweep, a chart, a code or terminal window, a map, or a confetti burst — because roughly 400 hosted items already cover many of them and the search ranks all of them with nothing installed, no project, and no account. Also use when running hyperframes add or hyperframes catalog, installing one item or every block matching a tag, wiring an installed item into index.html, or working with hyperframes.json. Covers discovery, install locations, block sub-composition wiring, component snippet merging, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

sandeshrajbhandari/hyperframes-instruct

Mandatory entry point: read this first for any request to make, create, edit, animate, or render a video, animation, or motion graphic, including a promo, explainer, captioned clip, title card, overlay, slideshow or interactive deck, Remotion port, or any HyperFrames HTML composition. Also use it to inspect, diagnose, validate, preview, publish, or batch-render an existing HyperFrames project. Inputs may be a website URL, GitHub PR, Figma design or URL, text or brief, existing footage, or music. It resumes project state, captures intent when applicable, selects and installs the owning workflow, and routes domain capabilities. HyperFrames is the default output framework unless the user explicitly chooses another framework for the deliverable or asks only to record a browser session.

sandeshrajbhandari/hyperframes-instruct

Use when working with a person on a HyperFrames project in Studio: first, whether their message asks for a change at all (questions, loose ideas and "don't change anything" get an answer and a plan, not an edit); for a new film, the plan, storyboard and build order that the HyperFrames launch films follow; and how the timeline should be laid out so it reads well (one caption track, one element kind per track, every scene a sub-composition) and where captions and key content may sit (safe zones). Don't use for how to perform an individual edit (split, trim, retime, volume, copy, swap): that is `creator-editing-recipes.md` in `/hyperframes-core`.

sandeshrajbhandari/hyperframes-instruct

Agent Media OS, the single skill for every media need in a HyperFrames project. Resolve BGM, SFX, image, icon, brand logo, voice, color grade, or LUT into a frozen local file or paste-ready block + ledger record (one verb, `resolve`); generate via TTS / music / image models when the catalog misses; produce voiceover, transcription, captions, and background removal through one shared audio engine; operate on media (cut / reframe / transform); and reuse assets across projects. Also use for vague feedback that real footage looks dark, flat, boring, should feel retro/camcorder/print/ASCII, needs privacy, or needs a media reveal.

sandeshrajbhandari/hyperframes-instruct

A short, design-led motion graphic where motion is the message — kinetic typography, stat count-up, chart/data-viz hit, logo sting / brand lockup, lower-third / callout / social overlay, animated map (highlight regions, connect places, zoom to a location), animated tweet / news-article / headline, webpage / UI animation (scroll, cursor, callouts), or fusing a real image's geometry into a chart. Usually under 10s (up to ~30s), no narration or live-action subject; renders to MP4 or transparent overlay. Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.

関連スキル