Communitygithub.com

HyperFrames 核心合約

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

HyperFrames 核心合約 是什麼?

此技能定義了 HyperFrames 組合合約,這是一套用於建立可渲染 HTML 影片專案的技術規範。它說明了如何透過 `data-*` 屬性與 GSAP 時間軸,將一個 HTML 檔案建構成一個可播放、可回溯時間的組合。技能重點在於避免常見的代理陷阱,例如 CSS `transform` 與 GSAP 動作的衝突、或是在剪輯元素上使用 `autoAlpha`。此外,它詳細說明了獨立組合與模板式子組合兩種結構的差異,並強制一系列不可妥協的規則,以確保渲染結果具確定性、可重現性。技能同時整合了 HyperFrames CLI 工具(如 `check`、`timeline`、`preview` 和 `render`),並建議在處理現有專案時,先執行 `npx hyperframes timeline` 來了解時間軸狀態,而不是直接閱讀 HTML。此技能是 HyperFrames 生態系統中其他領域技能(如動畫、創意、媒體與 CLI)的基礎。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/samyakiasonline-ctrl/hyperframe/tree/HEAD/.claude/skills/hyperframes-core

在你喜歡的 AI 中提問

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

說明文件

外掛安裝注意事項: 在執行設定或重新整理指令之前,請先遵循 外掛執行規則(當此技能位於 HyperFrames 外掛中時)。獨立安裝則保留下方的更新說明。

HyperFrames 核心

代理陷阱(請優先閱讀):

  • 使用 flex/inset 進行居中,不要在一個節點上使用 CSS transform: translate(-50%,-50%) 後又對其進行 GSAP x/y 動畫。檢查事項:gsap_css_transform_conflict。請改用 fromTo 或 xPercent/yPercent。
  • 不要在場景結束時加入 tl.set(..., {visibility:"hidden"})。執行環境會自動隱藏已結束播放的剪輯。為內部節點設定透明度淡出(或為 .clip 設定 opacity)就已足夠。字幕硬性終止則屬於不同規則。
  • window.__timelines["id"] 必須與根元素的 data-composition-id 相符。
  • 執行 render 後,請閱讀摘要的第二行:beginframe 與 screenshot、GPU 模式、階段時間。screenshot + software gpu 在 Linux 上是較慢的路徑。

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選擇單體架構或模組化架構;組織模組化 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。

建立組合

兩種根形式(不可互換)

  • 獨立組合(頂層 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。

一個暫停的時間軸

每個組合在 window.__timelines["<id>"] 註冊剛好一個 gsap.timeline({ paused: true })(鍵值等於根元素的 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 對相同屬性的補間動畫搭配使用 — CSS 值與補間的起始值會衝突,lint 會以 gsap_css_transform_conflict 拒絕它。請使用 gsap.fromTo(el, { x: -40 }, { x: 0 }) 在補間內部設定初始狀態,而不是使用 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> 永遠不會被混音器選取,因此渲染會是靜音的。
  • 永遠不要對 .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>;經過 transform 的元素必須是區塊級別 + 已設定尺寸;脈衝式絕對定位裝飾元素需要預留峰值間距。→ determinism-rules.md
  • <video>/<audio> 是透過平面的文件查詢找到的,因此框架可以在任何巢狀深度(包含在子組合 <template> 或包裝器內)進行搜尋和解碼。一個硬性限制:如果一個有 data-start 的 <video> 位於另一個同樣有 data-start 的普通元素內,lint 會報錯,且失敗是真實的(錯誤的來源影格,然後剪輯在時段中間消失),因此請將時間設定在包裝器或影片上,但絕不能兩者都設。子組合宿主則例外:子組合內部的媒體可以正確渲染。另一個需要注意的是時間軸,而非位置:子組合時間軸無法動畫化宿主根元素。→ 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、變數、媒體路徑。
  • 若要了解專案時間軸上的內容(音軌、剪輯、開始、結束、播放的內容),請執行 npx hyperframes timeline [--json],而不是去閱讀 index.html 和每個子組合檔案。
  • 匹配現有的組合 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 個發現項目,涵蓋 lint、執行時期、佈局、運動和對比度)
  • 包含子組合的專案:npx hyperframes snapshot --at <midpoints> 並目視檢查每個影格
  • npx hyperframes preview --background 用於審查(使用者可以在 Studio 的時間軸中編輯任何內容,且伺服器在觸發指令後持續運作)
  • 僅在使用者批准後才執行 npx hyperframes render

Individual skills in this repo

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

samyakiasonline-ctrl/hyperframe

Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet `anchor` rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.

samyakiasonline-ctrl/hyperframe

Turn arbitrary text — an article, notes, a topic, a brief — into a faceless explainer video: there is no site or footage to capture, so the visuals are invented per scene (typography, abstract graphics, diagrams, data-viz). Use for topic explainers, concept breakdowns, how-tos, listicles. Not a video built from a website (/product-launch-video — promo or tour). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Import Figma content into a HyperFrames composition — rendered assets, brand tokens, components, storyboard sections → reconstructed motion (frames read as states, not slides) (REST/CLI), connector-assisted motion when available, and shaders from a connector or native export. Use when the user pastes a figma.com link or asks to bring a Figma design, frame, logo, brand, or animation into a video/composition.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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`.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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`.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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).

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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`.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

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.

samyakiasonline-ctrl/hyperframe

Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Site tours / showcases of a website route here too — the brief carries the show-it-as-is intent. Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Turn a GitHub pull request (a PR URL, owner/repo#N, or 'this PR' in a checked-out repo) into a code-change explainer video — changelog, feature reveal, fix, or refactor walkthrough built from the diff, commits, and files: the input is a code change, not a website. Not a product promo (/product-launch-video) or a no-PR topic explainer (/faceless-explainer). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Port an existing Remotion (React) composition''s source to HyperFrames HTML. Use ONLY on an explicit ask to port/convert/migrate/translate a Remotion source — one-way, Remotion-only. A passing Remotion mention, reference-only code, or "make something like my Remotion video" is a fresh build (/general-video). Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Author a HyperFrames slideshow — a presentation, pitch deck, or interactive deck with discrete slides, fragment reveals, branching, hotspot navigation, and built-in presenter mode with speaker notes; also converts an existing page into a deck. Output is a navigable deck, not a rendered MP4. If the user didn't explicitly ask for a slideshow, confirm before authoring. Unclear → /hyperframes.

samyakiasonline-ctrl/hyperframe

Package an existing talking-head / interview / podcast video with timed, designed GRAPHIC OVERLAY cards — kinetic titles, lower-thirds, data callouts, quotes, side panels, picture-in-picture — synced to the transcript, on a 16:9 / 9:16 / 4:5 canvas of your choice; the clip plays untouched underneath. Trigger on "graphic overlays", "on-screen graphics", "package / dress up my video". Not plain subtitles (/embedded-captions). Unclear → /hyperframes.

相關技能