Communitygithub.com

sandeshrajbhandari/hyperframes-instruct

HyperFrames合成契约——构建一个可渲染的项目。用于组合结构、`data-*`时间属性、`class="clip"`、轨道、子合成、变量、框架自有媒体播放、确定性渲染规则和验证。在编写合成HTML前阅读。

hyperframes-instruct 是什么?

该技能文件定义了HyperFrames框架的核心技术规范,开发者必须遵循它来构建可渲染的视频合成项目。HyperFrames允许开发者通过HTML文档的DOM结构和`data-*`属性声明视频的时间线,并使用GSAP等动画运行时实现可寻帧的播放。技能详细说明了独立合成与子合成的两种文件结构、根元素尺寸要求、单暂停时间线注册规则、lint工具会捕获的常见编码错误(如CSS transform与GSAP属性冲突),以及一系列不可协商的确定性渲染规则(禁止运行时时钟、随机数、网络请求等)。它适用于所有基于HyperFrames的项目(包括Cursor、Claude Code等AI agent开发环境),并通过`references/`目录中的专题文档、`hyperframes-cli`工具进行验证。阅读此契约是编写正确合成HTML的前提。

兼容平台~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"})。运行时已自动隐藏定时片段。在内层节点(或 .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-* 属性(根 / 片段 / 子合成宿主 / 遗留别名);使用 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。

一个暂停的时间线

每个合成注册恰好一个 gsap.timeline({ paused: true }) 在 window.__timelines["<id>"](键 = 根的 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> 永远不会被混音器拾取,因此渲染是静默的。
  • 永远不要用 autoAlpha 或 visibility 对 .clip 进行补间动画——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>;被变换的元素必须是块级且设置尺寸;脉动的绝对定位装饰元素需要峰值间隔。 → determinism-rules.md
  • <video>/<audio> 通过平面文档查询找到,因此框架在任何嵌套深度(包括在子合成 <template> 或包装器内部)都能寻址和解码。一个硬限制:如果 <video data-start> 位于另一个也带有 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 通过(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.

相关技能