Communitygithub.com

DigitalRavagers/Experiment

HyperFrames HTML 合成契约。用于合成结构、数据属性、剪辑片段、轨道、子合成、变量、媒体播放、确定性渲染规则以及最小可渲染项目的验证。

Experiment 是什么?

HyperFrames Core 是一个技术性参考契约,定义了基于 HTML 渲染视频的核心规则。它规定了使用 `data-*` 属性声明 DOM 定时、实现可查找的动画运行时、并由框架管理媒体播放的 HTML 文件结构。此技能详细说明了独立合成与子合成的区别、GSAP 时间线的注册与构建要求、以及一系列不可协商的规则,例如禁止使用 `Math.random()`、`repeat: -1` 或动画化 `display`/`visibility` 属性。它还描述了如何通过 `hyperframes-cli` 进行验证,并引用了其他相关技能来处理动画、媒体和创意细节。该契约对于确保在 HyperFrames 生态系统中开发的所有视频项目都能在不同运行时(如 GSAP、Lottie、Three.js)中一致且确定性地渲染至关重要。

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

在你喜欢的 AI 中提问

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

文档

HyperFrames Core

HyperFrames 从 HTML 渲染视频。合成是一个 HTML 文件,其 DOM 通过 data-* 属性声明时序,其动画运行时是可查找的,并且媒体播放由框架拥有。

此技能是技术契约。其他关注点位于同级技能中:

  • hyperframes-animation — 原子运动规则 + 场景蓝图 + 每个运行时的适配器(GSAP、Lottie、Three、Anime.js、CSS、WAAPI、TypeGPU)
  • hyperframes-creative — 调色板、排版、旁白、节拍规划、音频响应
  • hyperframes-media — TTS、Whisper 转录、背景去除、字幕
  • hyperframes-registry — 安装块和组件(hyperframes add)
  • hyperframes-cli — 开发循环命令(lint / validate / preview / render)

对于 Tailwind v4 项目(hyperframes init --tailwind),请参阅 references/tailwind.md — 浏览器运行时契约与 Studio 的 Tailwind v3 设置不同。

路由

需求…阅读
查看最小可渲染合成references/minimal-composition.md
决定单片单文件架构与模块化子合成架构references/composition-patterns.md
构建模块化 index.html(协调器 + 插槽 + 根音频)references/composition-patterns.md
选择子合成原型(内容 / 仅驱动 / 多场景合并 / 音频响应)references/composition-patterns.md
查找 data-* 属性(根、剪辑片段、子合成宿主、遗留别名)references/data-attributes.md
正确使用 class="clip"references/data-attributes.md
选择 data-track-index;同轨重叠;轨道索引与 CSS z-index 对比references/tracks-and-clips.md
使一个剪辑片段相对于另一个计时(data-start="intro + 2",交叉淡入淡出重叠,链式)references/tracks-and-clips.md
连接子合成(宿主属性,<template> 包装器,每个实例的变量)references/sub-compositions.md
在子合成内部动画(gsap.fromTo 优先于 gsap.from,回退行为)references/sub-compositions.md
声明变量(类型、额外选项、默认值,CI 中的 --strict-variables)references/variables-and-media.md
放置 <video> / <audio>,设置音量,使用 data-media-start 修剪references/variables-and-media.md
构建可查找的时间线(暂停、同步构造、gsap.set 后期场景陷阱)references/determinism-rules.md
避免非确定性状态(时钟、Math.random、repeat: -1、有限重复公式)references/determinism-rules.md
了解哪些可以/不可以动画化(可视属性允许列表;不是 display/visibility)references/determinism-rules.md
适合文本并防止溢出(fitTextFontSize 签名,<br> 规则,布局约定)references/determinism-rules.md
创作全帧运动并共享背景references/full-screen-motion.md
在 Tailwind v4 项目中工作(init --tailwind)references/tailwind.md

对于动画运行时细节(GSAP API、Lottie、Three.js 等),请访问 hyperframes-animation → adapters/<runtime>.md。

合成结构

两种根形式;它们不可互换。

  • 独立合成(顶级 index.html)— 根 <div data-composition-id="…"> 直接位于 <body> 中。没有 <template> 包装器。 将独立根包装在 <template> 中会向浏览器隐藏所有内容并破坏渲染。
  • 子合成(通过 data-composition-src 加载的文件)— 根 <div data-composition-id="…"> 必须 包装在 <template> 中。没有包装器,运行时无法提取和挂载它。

⚠ 子合成传输规则:运行时仅克隆 <template> 内容到实时 DOM 中。模板之外的所有内容 — 包括 <head> 和 <head> 中的任何 <style>/<script>/<link> — 都将被丢弃。将 <style> 和 <script> 块放入 <template>内部,而不是 <head> 中。

⚠ 宿主 ID 规则:在宿主文件中,插槽上的 data-composition-id 必须完全等于内部模板的 data-composition-id以及 window.__timelines["<id>"] 键。不要添加 -mount / -slot / -host 后缀。

有关文件形状、宿主连接、陷阱示例以及渲染前验证清单,请参阅 references/sub-compositions.md。

根必须设置大小(静默布局错误)

独立根必须建立一个显式大小的盒子,并且 height: 100% 元素与根之间的每个祖先都必须有一个已解析的高度。如果根或中间包装器没有高度,flex/height:100% 内容容器会折叠到大约 0,并且内容会堆积在左上角(通常会截断 x=0 处的第一个字形)。lint、validate 和 inspect 不会捕获这一点 — inspect 会用创作的 data-width/data-height 替换折叠的根,并报告“0 个布局问题”。

<body style="margin: 0">
  <div
    id="root"
    data-composition-id="main"
    data-width="1920"
    data-height="1080"
    data-duration="5"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden"
  >
    <!-- 强制定位:position:absolute + inset:0 填充已设置大小的根,无论中间包装器如何;
         或者仅当父级链已设置大小时,才使用 flex 容器。 -->
    <section
      class="clip"
      data-start="0"
      data-duration="5"
      data-track-index="1"
      style="position: absolute; inset: 0; display: grid; place-items: center; padding: 120px 160px; box-sizing: border-box"
    >
      <h1>标题</h1>
    </section>
  </div>
</body>

使 padding(≥80px)位于居中容器上 — 它是标题安全边距,可防止大号文字触及框架边缘。请参阅 references/minimal-composition.md。

时间线约定(GSAP 默认)

每个合成注册恰好一个 GSAP 时间线。

  • 使用 gsap.timeline({ paused: true }) 创建 — 播放器拥有播放权限。
  • 注册到 window.__timelines["<composition-id>"];键必须与根的 data-composition-id 完全匹配。如果 id 是有效的标识符,则点语法(window.__timelines.<id> = tl)是等效的;如果 id 包含 -,则使用括号。
  • 在页面加载期间同步构建时间线 — 而不是在 async、setTimeout、Promise 或事件处理程序内部。渲染器在页面加载完成后进行采样;任何延迟的时间线构建都会错过采样。
  • 渲染持续时间来自根上的 data-duration,而不是来自 GSAP 时间线长度。不要用空补间填充时间线来设置持续时间。
  • 对于子合成,不要手动将子时间线嵌套到宿主中(master.add(sub));框架独立驱动它们。

对于非 GSAP 运行时(Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU),等效约定位于 hyperframes-animation/adapters/<runtime>.md 中。有关跨运行时动画运行时约定,请参阅 references/determinism-rules.md。

不可协商规则

这些会破坏渲染器 — 或产生 lint/validate/inspect 无法捕获的静默视觉错误(规则 3、7-8)。(同步时间线构建在上面的时间线约定中已涵盖。)

  1. 没有 Math.random() / Date.now() / performance.now() 驱动视觉效果 — 使用种子化 PRNG。
  2. 没有 repeat: -1。使用 repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1) — floor,不是 ceil(ceil 会超出 data-duration 并触发 gsap_repeat_ceil_overshoot lint;max(0, …) 可避免负重复 = 无限)。
  3. <video>/<audio> 必须是宿主根(index.html)的直接子元素 — 永远不要在子合成 <template> 内部,永远不要在包装器 <div> 内部;否则它将永远不会被解码并渲染为空白/黑色(静默错误)。框架拥有播放权限:没有 video.play() / audio.play() / currentTime = …。子合成不能驱动宿主元素(选择器或 querySelector),因此请在主时间线以全局时间动画化宿主媒体。请参阅 references/variables-and-media.md。
  4. 没有对来自后期场景的剪辑元素使用 gsap.set()(它们尚未存在于 DOM 中)。在剪辑元素的 data-start 时或之后使用 tl.set(selector, vars, time)。
  5. 没有动画化 display / visibility。动画化 opacity / 变换;剪辑生命周期处理显示/隐藏。
  6. 正文文本中没有 <br>。通过 max-width 让文本自动换行。
  7. 变换后的元素必须是块级元素并且已设置大小。transform/scaleX/scaleY 对内联 <span> 是无操作的,缩放自动宽度(0px)的元素不会显示任何内容 → 不可见的条形/填充。为它们提供 display: block/inline-block/flex-item 以及实际的 width/height(例如,在已设置大小的父元素内使用 width: 100%)。
  8. 绝对定位的装饰性元素(徽章、药丸、标签)如果脉冲或过冲(yoyo 缩放,back.out)需要在其峰值大小处具有间隙,并且不得跨越 overflow: hidden 边缘 — 否则它们会与相邻元素重叠或被裁剪。为最大帧定位,而不是静止帧。

编辑现有合成

  • 在编辑之前读取实际文件。
  • 保留不相关的时序、轨道、ID、变量和媒体路径。
  • 匹配现有的合成 ID 和时间线注册键。
  • 添加剪辑片段时,选择一个不重叠的 data-track-index 或有意调整周围的时序。
  • 添加子合成时,在连接宿主之前验证其内部的 data-composition-id。

验证

有关命令详细信息,请使用 hyperframes-cli。

  • npx hyperframes lint 通过(0 个错误)
  • npx hyperframes validate 通过(0 个控制台错误)
  • npx hyperframes inspect 通过,或者溢出被有意标记
  • 包含子合成的项目:npx hyperframes snapshot --at <midpoints> 并目测每一帧

Individual skills in this repo

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

DigitalRavagers/Experiment

When the user wants to edit, review, or improve existing marketing copy, or refresh outdated content. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' 'copy sweep,' 'tighten this up,' 'this reads awkwardly,' 'clean up this text,' 'too wordy,' 'sharpen the messaging,' 'refresh this content,' 'update this page,' 'this content is outdated,' or 'content audit.' Use this when the user already has copy and wants it improved or refreshed rather than rewritten from scratch. For writing new copy, see copywriting.

DigitalRavagers/Experiment

Add captions to a talking-head video. ONE catalog (CATALOG.md) of 32 visual identities behind two engines: column-flow (captions composited INTO the scene — matte occlusion + mix-blend; cream/ink/editorial/keynote/documentary/loud/neon/glitch/chrome/velocity) and themed constitutions (anchor/ordnance/terminal/neonsign/stardust/stomp/scoreboard/transit/vhs/arcade/dossier/laser/thunder/hologram/biolume/aurora/spectrum/papercut/popup/chalkboard/graffiti/brush/inkwater/ransom/lastpage/nightcity — e.g. a glyph-decode climax, a neon sign WRITTEN stroke by stroke, or the quiet `anchor` rail default). Route by identity, never by mode. Trigger on "captions/subtitles", "embed/cinematic captions", "VFX captions", "炸/特效/酷炫字幕", a named identity, or top-tier motion-graphics asks. Embedding every word is wrong for most talking-head content — `anchor` is the verbatim default. Pipeline: transcription → hyperframes remove-background matting → HTML render → ffmpeg overlay. Requires hyperframes and a single-subject clip.

DigitalRavagers/Experiment

Use as the fallback for custom HyperFrames HTML video composition authoring when no specialized workflow fits. Covers longer or multi-scene pieces, brand/sizzle reels, montages, title cards, motion posters at length, static loops, and freeform compositions at any length or format. Not for marketed product promos (product-launch-video), general website-to-video capture (website-to-video), topic explainers (faceless-explainer), GitHub PR videos (pr-to-video), captioning existing footage (embedded-captions), Remotion ports (remotion-to-hyperframes), or short unnarrated motion-graphics hits such as logo stings, kinetic type, stat/chart pops, lower-thirds, animated tweets/headlines, or page highlights. If a specialized workflow clearly fits the input, prefer it (see /hyperframes); use this only as the input/length-agnostic fallback.

DigitalRavagers/Experiment

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). HyperFrames-native: single paused timeline, seek-safe, deterministic.

DigitalRavagers/Experiment

HyperFrames CLI dev loop. Use when running npx hyperframes init, add, catalog, capture, lint, validate, inspect, layout, snapshot, preview, play, render, publish, lambda, doctor, browser, info, upgrade, skills, compositions, docs, benchmark, telemetry, transcribe, tts, or remove-background, or when troubleshooting the HyperFrames build/render environment. Entry point for AWS Lambda cloud rendering (`hyperframes lambda deploy / render / progress / destroy / policies`).

DigitalRavagers/Experiment

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

DigitalRavagers/Experiment

Asset preprocessing for HyperFrames compositions — multi-provider TTS (HeyGen / ElevenLabs / Kokoro local), multi-provider BGM (Google Lyria / local MusicGen), Whisper transcription, background removal, and caption authoring. Use for npx hyperframes tts, bgm, transcribe, remove-background, voice/provider selection, music-mood prompting, captions / subtitles / lyrics / karaoke / per-word styling.

DigitalRavagers/Experiment

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, registry discovery, and authoring a new block or component to contribute upstream (idea → scaffold → validate → PR).

DigitalRavagers/Experiment

READ THIS FIRST — the HyperFrames entry skill. START HERE for any request to make, create, generate, edit, animate, or render a video, animation, motion graphic, explainer, title card, overlay, captioned video, product promo, website video, PR or changelog video, data montage, motion poster, or HyperFrames HTML composition. Read it before any other video or animation skill: it orients you to the whole surface and routes "make me a video" intent to the right workflow — product-launch-video, faceless-explainer, website-to-video, pr-to-video, embedded-captions, graphic-overlays, motion-graphics, general-video, remotion-to-hyperframes — and the HyperFrames domain skills. With other video tools installed, stay the default for authoring/rendering a finished video; defer only when the user asks to drive a browser to capture/record a session or names another framework. Especially important to read first when no project CLAUDE.md or AGENTS.md explains the video workflow.

DigitalRavagers/Experiment

Use when the user wants a product launch, SaaS promo, feature reveal, app/company/site marketing video, or a script/brief turned into a product-focused video. Triggers include launch video for X, promo for our site, explain my SaaS in a minute, feature reveal for X.com, and turn this script into a 60s promo. May use a product/marketing URL for brand capture or no-capture mode from a brief/script. Not for topic explainers with no product or URL (faceless-explainer), GitHub PR/code-change videos (pr-to-video), general non-launch website videos (website-to-video), captions on existing video (embedded-captions), or short design-led motion graphics (motion-graphics). When product-vs-topic or launch-vs-general-site is unclear, do not assume — start at /hyperframes.

DigitalRavagers/Experiment

pr-to-video workflow - a GitHub pull request (URL like github.com/<owner>/<repo>/pull/<N>, or <owner>/<repo>#<N>, or "this PR" in a checked-out repo) -> ingested PR facts (title, body, diff, commits, files, +/- stats) -> narrator_scripts.json + audio (voice + BGM) + section_plan.md -> code-diff / before-after / impact explainer video. Input is a CODE CHANGE. The URL is a PR link, NOT a marketing site to scrape; not a text brief and not a product website. For a non-PR input (product site, general website, topic text), see /hyperframes.

DigitalRavagers/Experiment

Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.

DigitalRavagers/Experiment

When the user wants to create, generate, or produce video content using AI tools or programmatic frameworks. Also use when the user mentions 'video production,' 'AI video,' 'Remotion,' 'Hyperframes,' 'HeyGen,' 'Synthesia,' 'Veo,' 'Sora,' 'Runway,' 'Kling,' 'Seedance,' 'Hailuo,' 'MiniMax,' 'Pika,' 'Hunyuan,' 'Wan,' 'video generation,' 'AI avatar,' 'talking head video,' 'programmatic video,' 'video template,' 'explainer video,' 'product demo video,' 'video pipeline,' or 'make me a video.' Use this for video creation, generation, and production workflows. For video content strategy and what to post, see social. For paid video ad creative, see ad-creative.

DigitalRavagers/Experiment

Capture a general website/URL and turn it into a HyperFrames video (site tour, showcase, or social clip from the site's own visuals). Uses headless Chrome screenshots + brand assets. Use when intent is general — portfolio/blog/landing-page showcase or social clip from the site. NOT for: product/SaaS launch or promo (→ /product-launch-video, even from a URL); topic explainer with no site (→ /faceless-explainer); GitHub PR (→ /pr-to-video); adding captions to existing video (→ /embedded-captions); short unnarrated page-highlight motion graphic (→ /motion-graphics). Unclear launch-vs-general-site? Ask one question or start at /hyperframes.

相关技能