Communitygithub.com

sandeshrajbhandari/hyperframes-instruct

HyperFrames 合成合約 — 建立一個可渲染的專案。用於合成結構、`data-*` 時間屬性、`class="clip"`、軌道、子合成、變數、框架擁有的媒體播放、確定性渲染規則和驗證。在撰寫合成 HTML 前閱讀。

hyperframes-instruct 是什麼?

這個技能「hyperframes-instruct」是 HyperFrames 框架的核心技術合約,它定義了如何建立一個可渲染的影片合成專案。HyperFrames 允許開發者透過宣告式 HTML 和 `data-*` 時間屬性來驅動影片渲染,其動畫運行時是可尋址的,並且媒體播放由框架本身管理。此技能涵蓋了建立合成 HTML 的所有必要規則,包括兩種根形式(獨立 vs 子合成)、確定性渲染禁令(不可使用未種子的亂數、網路請求、重複次數 -1 僅限於有限根持續時間下)、以及 `class="clip"` 元素的使用限制。它支援多種動畫運行時,包括 GSAP、Lottie 和 Three.js,並可與 Tailwind v4 整合。此技能還提供了詳細的參考文件清單,涵蓋最小合成、資料屬性、軌道與剪輯、子合成、變數與媒體、以及編輯現有合成的指南。總而言之,這份技能是任何使用 HyperFrames 建立影片合成專案的開發者或 AI Agent 的必讀文件。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sandeshrajbhandari/hyperframes-instruct/tree/HEAD/.agents/skills/hyperframes-core

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

外掛安裝: 在執行設定或更新命令前,若此技能位於 HyperFrames 外掛中,請遵循外掛執行規則。獨立安裝則保留下方更新說明。

HyperFrames 核心

AI Agent 陷阱(優先閱讀):

  • 使用 flex/inset 置中,不要用 CSS transform: translate(-50%,-50%) 在你然後用 GSAP x/y 動畫的節點上。Lint:gsap_css_transform_conflict。改用 fromTo 或 xPercent/yPercent。
  • 不要添加場景離開的 tl.set(..., {visibility:"hidden"})。執行環境已經隱藏了計時的 clips。在內部節點(或 .clip 上的 opacity)上淡化透明度就足夠了。字幕硬終止是另一條規則。
  • window.__timelines["id"] 必須與根元素的 data-composition-id 匹配。
  • 在 render 之後,閱讀摘要的第二行:beginframe vs screenshot、GPU 模式、階段時間。screenshot + Linux 上的 software gpu 是慢路徑。

HyperFrames 從 HTML 渲染影片。一個合成是一個 HTML 檔案,其 DOM 透過 data-* 屬性宣告時間,其動畫運行時是可尋址的,並且其媒體播放由框架擁有。

此技能是技術合約 — 如何建立一個 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-*(根 / clip / 子合成宿主 / 舊別名);使用 class="clip"
references/tracks-and-clips.md了解 data-track-index 控制(及不控制)的內容、z-index、相對於另一個 clip 的時間;使用 npx hyperframes timeline 列出每個軌道和 clip
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。

建立一個合成

兩種根形式(不可互換)

  • 獨立(頂層 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> 放在 <template> 內部。<link> 兩種方式都會被提升。 ⚠ 宿主 ID 慣例:給予宿主 slot、內部 template 以及 window.__timelines["<id>"] key 相同的 ID。支援不同的本地 ID(組裝器會回退到檔案中的第一個根元素),但這種不匹配是靜默的,因此除非有理由不匹配,否則請保持它們一致。

檔案形狀、宿主接線和預渲染檢查清單 → references/sub-compositions.md。

根元素必須設定大小(靜默佈局錯誤)

獨立根元素設定 width/height: 100%。畫布大小是 data-width/data-height。執行環境會將這些像素值應用到合成根元素。不要在 #root 上硬編碼 1920px/1080px。骨架 → references/minimal-composition.md。

一個暫停的時間軸

每個合成註冊恰好一個 gsap.timeline({ paused: true }) 到 window.__timelines["<id>"](key = 根元素的 data-composition-id)。在非同步回調(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 tween 配對 — CSS 值和 tween 的起始值會衝突,並且 lint 會以 gsap_css_transform_conflict 拒絕。使用 gsap.fromTo(el, { x: -40 }, { x: 0 }) 在 tween 內部設定初始狀態,而不是使用 CSS transform: translateX(-40px)。
  • 永遠不要在 <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> 永遠不會被混音器拾取,因此渲染是靜默的。
  • 永遠不要使用 autoAlpha 或 visibility 對 .clip 進行 tween — 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 下使用(匯出 clips 給它 — 否則使用有限次數)。→ determinism-rules.md
  • 永遠不要對 .clip 元素進行 display、visibility 或 autoAlpha 的 tween。框架擁有 clip 的可見性,且 lint 會拒絕它(gsap_animates_clip_element)。改為對子元素進行動畫。→ determinism-rules.md
  • 正文中沒有 <br>;已轉換的元素必須是塊級且設定大小;脈動的絕對定位裝飾元素需要峰值間距。→ determinism-rules.md
  • <video>/<audio> 是透過扁平文件查詢找到的,因此框架可以在任何嵌套深度(包括在子合成 <template> 或包裝器內部)尋找並解碼它們。一個硬性限制:如果一個 <video data-start> 位於另一個也帶有 data-start 的普通元素內部,lint 會報錯,且失敗是真實的(錯誤的來源幀,然後 clip 在插槽中間消失),因此請將時間屬性放在包裝器或影片上,絕對不要兩者都放。子合成宿主是豁免的:子合成內部的媒體可以正確渲染。另一個需要注意的是時間軸,而不是放置:子合成時間軸無法對宿主根元素進行動畫。→ variables-and-media.md
  • 在組裝後的頁面上保持每個 id 唯一(為子合成 id 添加前綴,使用組合 id #<id>-hero),以便你自己的 #id CSS 和 getElementById 呼叫能夠解析。幀注入不再依賴於此:編譯器會為每個 video[src]/audio[src]/img[src] 蓋上文件唯一的 data-hf-render-id。使用 <source> 子元素而不是 src 屬性的媒體不會被蓋章,因此獨特的 id 在那裡仍然重要。→ composition-patterns.md
  • 在正常渲染中,對合成根元素進行全螢幕填充是沒問題的。它只在分層合成路徑上被丟棄(HDR 內容,或使用著色器轉場的合成),在該路徑中引擎強制每個合成根元素透明,以便下方的圖層能夠顯示出來。如果你的合成使用著色器轉場或 HDR 媒體,請將填充放在一個全出血的子元素上(position:absolute; inset:0)。→ composition-patterns.md

編輯現有合成

  • 首先閱讀檔案。保留不相關的時間、軌道、ID、變數、媒體路徑。
  • 要了解專案時間軸上的內容(軌道、clips、開始、結束、播放內容),請執行 npx hyperframes timeline [--json],而不是讀取 index.html 和每個子合成檔案。
  • 匹配現有的合成 ID 和時間軸 key。
  • 添加一個 clip:有意識地根據周圍的 clips 設定其 data-start/data-duration。data-track-index 是 Studio 顯示通道,不是時間約束,因此不需要是空的。
  • 超出根 data-duration 結束的 clip 會被截斷:在同一編輯中將根 data-duration 擴展到 clip 的結束時間(lint 會警告 clip_ends_past_root_duration)。
  • 任何合成元素上的 data-hidden 會在預覽和渲染中隱藏它,覆蓋其時間視窗;它是非破壞性/可逆的,並由 Studio 的時間軸眼睛圖示切換。
  • 添加一個子合成:在連接宿主之前,驗證其內部的 data-composition-id。

驗證

有關命令詳情,請使用 hyperframes-cli

  • npx hyperframes check 通過(在 lint、執行時、佈局、運動和對比度檢查中均無發現問題)
  • 包含子合成的專案: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.

相關技能