Communitygithub.com

samyakiasonline-ctrl/hyperframe

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

hyperframe 是什么?

HyperFrames 是一个通过 HTML 实现视频渲染的框架核心技能。它定义了如何构建一个可渲染的 HyperFrames 项目,本质上是开发者与框架之间的技术合约。该技能主要面向使用 HyperFrames 构建视频合成的开发者,涵盖从基础骨架(最小可渲染合成)到复杂模块化结构的所有内容。关键特性包括:使用 `data-*` 属性声明 DOM 元素的播放时间、通过 `class="clip"` 定义剪辑片段、使用 `data-track-index` 管理轨道和层级顺序、支持子合成(通过 `data-composition-src` 加载)、变量系统、以及框架控制的媒体播放(`<video>`/`<audio>`)。其核心优势在于打造可确定性渲染的 HTML 项目——渲染结果可精确复现,支持进度条拖拽,且不受渲染环境随机性影响。平台支持方面,该技能服务于 HyperFrames CLI、HyperFrames 注册表等工具。工作原理上,化合脚本读取 HTML 文件,利用 GSAP 时间线(`window.__timelines["id"]`)控制精确播放,并通过编译阶段的验证规则确保无冲突(如 GSAP 与 CSS transform 冲突、场景退出隐藏问题等)。在写入合成 HTML 前,务必先阅读此技能下的引用文件以了解最佳实践和避免常见陷阱。

兼容平台~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 核心

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 与 screenshot、GPU 模式、阶段计时。Linux 上的 screenshot + 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 回读中。没有豁免。
  • 永远不要给 <video data-start> 一个同样带有 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> 或包装器内部)查找并解码它们。一个硬性限制:lint 会在 <video data-start> 位于另一个也带有 data-start 的普通元素内部时报错,并且失败是真实的(错误的源帧,然后剪辑在中间消失),因此请将时间放在包装器或视频上,永远不要放在两者上。子合成宿主是例外的:子合成内部的媒体可以正确渲染。另一个注意事项是时间线,而不是位置:子合成时间线不能动画宿主根元素。→ 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.

相关技能