Communitygithub.com

HyperFrames 合成技能

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

HyperFrames 合成技能 是什么?

HyperFrames 核心技能是使用 HTML 构建视频合成的技术契约。每个合成是一个 HTML 文件,通过 `data-*` 属性声明时间线,运行时支持可寻的动画和框架自有的媒体播放。合成支持两种根形式:独立式(`index.html` 中直接放置 `<div data-composition-id="...">`)和子合成式(通过 `data-composition-src` 加载,包裹在 `<template>` 中)。关键陷阱包括:不要对 GSAP `x`/`y` 动画的节点使用 CSS `transform: translate(-50%,-50%)` 居中(应使用 flex/`inset`);不要添加场景退出的 `tl.set(..., {visibility:"hidden"})`,运行时已自动隐藏定时片段;`window.__timelines["id"]` 必须匹配根元素的 `data-composition-id`。该技能与 `hyperframes-animation`、`hyperframes-creative`、`media-use`、`hyperframes-cli`、`hyperframes-registry` 等兄弟技能协同工作,并提供了 10 个参考文档(最小合成、合成模式、数据属性、轨道与片段、编辑配方、子合成、变量与媒体、确定性规则、全屏运动、Tailwind 集成)供按需阅读。通过遵循此契约,开发者可构建可预测、可验证的基于 HTML 的视频合成,适用于 HyperFrames 框架的所有平台。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

插件安装: 在执行设置或新鲜度命令之前,请遵循插件执行规则(当此技能位于 HyperFrames 插件内时)。独立安装则保留下方更新说明。

HyperFrames Core

代理陷阱(请先阅读):

  • 使用 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 + software gpu on 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>"](键值 = 根节点的 data-composition-id)处注册恰好一个 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 拒绝。使用 gsap.fromTo(el, { x: -40 }, { x: 0 }) 在补间内设置初始状态,而不是使用 CSS transform: translateX(-40px)。
  • 永远不要在 <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 使用 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、运行时、布局、动态和对比度方面没有发现任何问题)
  • 包含子合成的项目: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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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

laviedezidane/hyperframes-skill

Agent Media OS for 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. When the host app provides its own music or sound-effect tools, use those for music and sound effects; `resolve --type bgm|sfx` needs the heygen CLI. When `HEYGEN_API_BASE` is set, HeyGen calls go through that host with no CLI sign-in.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

laviedezidane/hyperframes-skill

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.

相关技能