Communitygithub.com

Zuhair-01/claude-skills-and-systems

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

claude-skills-and-systems 是什么?

HyperFrames 是一个从 HTML 渲染视频的框架,它通过 `data-*` 属性在 DOM 中声明时序,提供可寻的动画运行时,并由框架管理媒体播放。此技能文档(SKILL.md)定义了构建 HyperFrames 项目的技术合约,涵盖组合结构、时序属性、子组合以及变量等核心概念。它详细说明了两种根形式(独立组合和子组合),强调了关键的开发者注意事项,如避免 CSS `transform` 与 GSAP 动画的冲突、不要手动嵌套子时间线、以及确保根元素正确设置尺寸。此外,文档还包含了全面的验证步骤(`npx hyperframes check`、`npx hyperframes preview` 等),并链接到多个参考文件,供开发者按需深入特定主题。该技能支持 Claude Code 等 AI 代理平台,帮助开发者编写符合框架规范且无错误的组合 HTML。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Zuhair-01/claude-skills-and-systems/tree/HEAD/skills/hyperframes-core

在你喜欢的 AI 中提问

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

文档

HyperFrames 核心

AI 代理陷阱(请先阅读):

  • 使用 flex/inset 居中,而不是在随后用 GSAP x/y 动画的节点上使用 CSS transform: translate(-50%,-50%)。Lint 检查:gsap_css_transform_conflict。请改用 fromTo 或 xPercent/yPercent。
  • 不要添加场景退出时的 tl.set(..., {visibility:"hidden"})。运行时已经隐藏了计时剪辑。内层节点上的透明淡出(或 .clip 上的 opacity)已足够。字幕硬终止是另一条规则。
  • window.__timelines["id"] 必须与根元素的 data-composition-id 匹配。
  • 渲染后,读取摘要的第二行: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 指定。运行时将这些像素值应用到组合根元素。不要硬编码为 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(使用有限次数)。→ determinism-rules.md
  • 永远不要在 .clip 元素上补间 display、visibility 或 autoAlpha。框架拥有剪辑可见性,并且 lint 会拒绝(gsap_animates_clip_element)。改为对子元素进行动画。→ determinism-rules.md
  • 正文中无 <br>;变换后的元素必须是块级且已设置尺寸;脉动的绝对定位装饰元素需要峰值间隙。→ determinism-rules.md
  • <video>/<audio> 通过平面文档查询找到,因此框架可以在任何嵌套深度(包括在子组合 <template> 或包装器内部)查找和解码它们。一个硬性限制:如果带有 data-start 的 <video> 位于另一个也带有 data-start 的普通元素内部,lint 会报错,并且故障是真实的(错误的源帧,然后剪辑在插槽中间消失),因此请将时序放在包装器或视频上,永远不要同时放。子组合宿主除外:子组合内部的媒体可以正确渲染。另一个注意事项是时间线,而不是放置:子组合时间线不能动画宿主根元素。→ variables-and-media.md
  • 保持每个 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-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 9 individual skills — each has its own dedicated page.

Zuhair-01/claude-skills-and-systems

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Zuhair-01/claude-skills-and-systems

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Zuhair-01/claude-skills-and-systems

Edit existing videos using AI — remix style, upscale, remove background, and add audio via fal.ai's hosted video models.

Zuhair-01/claude-skills-and-systems

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Zuhair-01/claude-skills-and-systems

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.

Zuhair-01/claude-skills-and-systems

Read-only queue dashboard for workspace-aware ship. (gstack)

Zuhair-01/claude-skills-and-systems

Generate HeyGen presenter videos via the v3 Video Agent pipeline — handles Frame Check (aspect ratio correction), prompt engineering, avatar resolution, and voice selection. Required for any HeyGen video generation. Replaces deprecated endpoints with v3. Use when: (1) generating any HeyGen video (via API or otherwise), (2) sending a personalized video message (outreach, update, announcement, pitch, knowledge), (3) creating a HeyGen presenter-led explainer, tutorial, or product demo with a human face, (4) "make a video of me saying...", "send a video to my leads", "record an update for my team", "create a video pitch", "make a loom-style message", "I want to appear in this video", "generate a HeyGen video", "make a talking head video". Accepts avatar_id from heygen-avatar for identity-first HeyGen videos, or uses a stock presenter. Returns video share URL + HeyGen session URL for iteration. Chain signal: when the user wants to create/design an avatar AND make a video in the same request, run heygen-avatar f...

Zuhair-01/claude-skills-and-systems

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.

Zuhair-01/claude-skills-and-systems

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

相关技能