Communitygithub.com

GanQiao1990/skills_2026

在 HyperFrames HTML 中创建视频合成、动画、标题卡、叠加层、字幕、画外音、音频响应式视觉效果和场景过渡。当需要构建任何基于 HTML 的视频内容、添加与音频同步的字幕、生成文本转语音旁白、创建音频响应式动画(节拍同步、发光、脉冲由音乐驱动)、添加动画文本高亮(标记扫过、手绘圆圈、爆发线条、涂鸦、草图轮廓)或添加场景间过渡(交叉淡入淡出、擦除、揭示、着色器过渡)时使用。涵盖合成创作、计时、媒体和完整的视频制作工作流程。对于 CLI 命令(init, lint, preview, render, transcribe, tts),请参阅 hyperframes-cli 技能。

skills_2026 是什么?

该技能是 HyperFrames 视频合成框架的权威指南,将 HTML 作为视频的“唯一真实来源”。它涵盖了从项目结构设计和视觉身份定义到详细的合成创作、动画和场景制作的全部内容。该技能强制执行严格的视觉身份门控流程(通过 DESIGN.md),确保不会使用默认或通用颜色。技术规则非常严格:需要确定性动画(无 Math.random),使用 GSAP 时的有限重复(无 repeat: -1),以及同步时间线构建(无 async/await)。该技能对于任何使用 HyperFrames 构建基于浏览器的视频、动画标题卡、音频响应式视觉效果(节拍同步、发光、脉冲)或自动字幕和语音合成的人来说都是必不可少的。它强调了环境陷阱,例如由于 display: none 导致黑屏或由于音频作为单独元素未静音而导致问题。它整合了视频制作参考并定义了平台无关的工作流(支持任何能够运行 HTML5 和 GSAP 的浏览器)。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GanQiao1990/skills_2026/tree/HEAD/openclaw-imports/hyperframes

在你喜欢的 AI 中提问

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

预览

来自技能 README

文档

HyperFrames

HTML 是视频的唯一真实来源。一个合成是一个包含 data-* 属性用于计时、一个 GSAP 时间线用于动画和 CSS 用于外观的 HTML 文件。该框架处理剪辑可见性、媒体播放和时间线同步。

总括范围和合并的狭义工作流

该技能是 HyperFrames 创作的类级总括。它涵盖合成结构、计时、动画、视觉标识、字幕、音频响应式视觉效果以及制作质量的场景构建。有关命令参考,请使用 hyperframes-cli 技能;当源材料是现有网站时,请使用 website-to-hyperframes。特定单次会话的制作/调试笔记已降级为此处的支持参考。

小节:生产工作流陷阱

历史生产笔记强调了一些仍然有用的环境陷阱:

  • 渲染时首选仅 ASCII 的项目/输出路径;非 ASCII 路径可能破坏无头 Chrome 或渲染器子进程。
  • 如果 Conda FFmpeg 下 MP4 编码失败,使用 export PATH=/usr/bin:$PATH 强制使用系统 FFmpeg 或渲染 WebM 作为回退。
  • 当使用自定义时间线对象而非 GSAP 时,它们必须公开与 GSAP 兼容的 duration()、pause() 和 seek(time) 方法。
  • 如果最终视频看起来是黑色或空的,首先检查是否有父级 display: none 的子级同时被动画化。关键在于:如果父容器被设置为 display: none,则其子级无法渲染。使用 opacity: 0 或时间线控制的透明度代替 display: none。
  • 对于关键运行时 JS(如 GSAP),首选在项目中本地复制一份(例如 assets/gsap.min.js),而不是在渲染期间依赖实时 CDN 获取。
  • 为独立合成添加 <link rel="icon" href="data:,"> 以抑制当项目中没有 favicon 时无头浏览器 favicon 404 噪声。
  • 通过使用 FFmpeg 提取帧并检查屏幕截图来验证视觉效果,而不仅仅相信成功的渲染退出代码。

降级的支持参考

  • references/hyperframes-video-production.md
  • references/hyperframes-workflow.md

方法

在编写 HTML 之前,从高层次思考:

  1. 什么 — 观众应该体验什么?确定叙事弧线、关键时刻和情感节拍。
  2. 结构 — 有多少个合成,哪些是子合成 vs 内联,哪些轨道承载什么(视频、音频、叠加层、字幕)。
  3. 计时 — 哪些剪辑驱动持续时间,过渡落在哪里,节奏如何。
  4. 布局 — 首先构建最终状态。请参见下面的“先布局后动画”。
  5. 动画 — 然后使用下面的规则添加运动。

对于小修改(修复颜色、调整时间、添加一个元素),直接跳到规则。

视觉标识门

按此顺序检查:

  1. 项目中存在 DESIGN.md? → 阅读它。使用其确切的颜色、字体、运动规则和“不要做什么”约束。
  2. 存在 visual-style.md? → 阅读它。应用其 style_prompt_full 和结构化字段。(注意:visual-style.md 是项目特定文件。visual-styles.md 是包含 8 个命名预设的风格库 — 不同文件。)
  3. 用户命名了风格(例如“Swiss Pulse”、“黑暗科技感”、“奢侈品牌”)? → 阅读 visual-styles.md 了解 8 个命名预设。生成一个最小的 DESIGN.md,包含:## Style Prompt(一段)、## Colors(3-5 个十六进制值及角色)、## Typography(1-2 个字体系列)、## What NOT to Do(3-5 个反模式)。
  4. 以上都没有? → 在编写任何 HTML 之前问 3 个问题:
    • 情绪是什么?(爆炸性 / 电影感 / 流畅 / 技术感 / 混乱 / 温暖)
    • 浅色还是深色画布?
    • 有任何特定品牌颜色、字体或视觉参考吗? 然后根据答案生成一个最小的 DESIGN.md。

每个合成必须将其调色板和排版追溯到 DESIGN.md、visual-style.md 或明确的用户指示。如果您使用 #333、#3b82f6 或 Roboto — 您跳过了此步骤。

对于运动默认值、尺寸调整、入场模式和缓动 — 请遵循 house-style.md。House style 处理事物如何移动。DESIGN.md 处理事物看起来像什么。

先布局后动画

将每个元素定位到其最可见时刻应处的位置 — 即它完全进入、正确放置且尚未退出的帧。首先将其编写为静态 HTML+CSS。还没有 GSAP。

为什么这很重要: 如果您将元素定位在其动画起始状态(屏幕外、缩放到 0、透明度 0)并过渡到您认为它们应落位的位置,您是在猜测最终布局。重叠在视频渲染之前是不可见的。通过先构建最终状态,您可以在添加任何运动之前发现并修复布局问题。

流程

  1. 为每个场景识别主角帧 — 大多数元素同时可见的时刻。这是您要构建的布局。
  2. 为该帧编写静态 CSS。.scene-content 容器必须使用 width: 100%; height: 100%; padding: Npx; 配合 display: flex; flex-direction: column; gap: Npx; box-sizing: border-box 来填充整个场景。使用内边距将内容向内推 — 绝不要在内容容器上使用 position: absolute; top: Npx。绝对定位的内容容器在内容高于剩余空间时会溢出。仅将 position: absolute 保留用于装饰性元素。
  3. 使用 gsap.from() 添加入场 — 从屏幕外/不可见动画到 CSS 位置。CSS 位置是真实依据;过渡描述到达那里的路径。
  4. 使用 gsap.to() 添加入场 — 从 CSS 位置动画到屏幕外/不可见。

示例

/* scene-content 填充场景,内边距定位内容 */
.scene-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  width: 100%;
  height: 100%;
  padding: 120px 160px;
  gap: 24px;
  box-sizing: border-box;
}
.title {
  font-size: 120px;
}
.subtitle {
  font-size: 42px;
}
/* 容器填充任何场景尺寸(1920x1080、1080x1920 等)。
   内边距定位内容。Flex + gap 处理间距。 */

错误 — 硬编码尺寸和绝对定位:

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}
// 第 3 步:动画进入这些位置
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// 第 4 步:动画离开这些位置
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);

当元素在时间上共享空间时

如果元素 A 在元素 B 进入同一区域之前退出,两者都应对其各自的主角帧具有正确的 CSS 位置。时间线排序保证它们永远不会有视觉上的共存 — 但如果您跳过布局步骤,您将无法发现它们因计时错误而意外重叠的情况。

什么算作有意重叠

分层效果(文本后的发光、阴影元素、背景图案)和 z 堆叠设计(卡片堆叠、深度层)是有意的。布局步骤是为了发现无意重叠 — 两个标题落在彼此之上、一个统计数字覆盖标签、内容溢出画面。

数据属性

所有剪辑

属性必需值
id是唯一标识符
data-start是秒数或剪辑 ID 引用("el-1"、"intro + 2")
data-duration图片/div/合成必需秒数。视频/音频默认为媒体时长。
data-track-index是整数。相同轨道的剪辑不能重叠。
data-media-start否源的修剪偏移(秒数)
data-volume否0-1(默认 1)

data-track-index 不影响视觉分层 — 使用 CSS z-index。

合成剪辑

属性必需值
data-composition-id是唯一合成 ID
data-start是开始时间(根合成:使用 "0")
data-duration是优先于 GSAP 时间线时长
data-width / data-height是像素尺寸(1920x1080 或 1080x1920)
data-composition-src否外部 HTML 文件的路径

合成结构

通过 data-composition-src 加载的子合成使用 <template> 包装器。独立合成(主 index.html)不使用 <template> — 它们将 data-composition-id div 直接放在 <body> 中。在独立文件上使用 <template> 会向浏览器隐藏所有内容并破坏渲染。

子合成结构:

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    <!-- 内容 -->
    <style>
      [data-composition-id="my-comp"] {
        /* 作用域样式 */
      }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      // 补间...
      window.__timelines["my-comp"] = tl;
    </script>
  </div>
</template>

在根目录中加载:<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

视频和音频

视频必须 muted playsinline。音频始终是一个单独的 <audio> 元素:

<video
  id="el-v"
  data-start="0"
  data-duration="30"
  data-track-index="0"
  src="video.mp4"
  muted
  playsinline
></video>
<audio
  id="el-a"
  data-start="0"
  data-duration="30"
  data-track-index="2"
  src="video.mp4"
  data-volume="1"
></audio>

时间线契约

  • 所有时间线以 { paused: true } 开始 — 播放器控制播放
  • 注册每个时间线:window.__timelines["<composition-id>"] = tl
  • 框架自动嵌套子时间线 — 不要手动添加它们
  • 时长来自 data-duration,而非 GSAP 时间线长度
  • 绝不要创建空补间来设置时长

规则(不可协商)

确定性: 没有 Math.random()、Date.now() 或基于时间的逻辑。如果需要伪随机值(例如 mulberry32),请使用种子 PRNG。

GSAP: 仅动画化视觉属性(opacity、x、y、scale、rotation、color、backgroundColor、borderRadius、变换)。不要动画化 visibility、display 或调用 video.play()/audio.play()。

动画冲突: 永远不要同时从多个时间线动画化同一元素的同一属性。

没有 repeat: -1: 无限重复的时间线会破坏捕获引擎。从合成时长计算确切重复次数:repeat: Math.ceil(duration / cycleDuration) - 1。

同步时间线构建: 永远不要在 async/await、setTimeout 或 Promise 内部构建时间线。捕获引擎在页面加载后同步读取 window.__timelines。字体由编译器嵌入,因此立即可用 — 无需等待字体加载。

绝不能做:

  1. 忘记 window.__timelines 注册
  2. 将视频用于音频 — 始终是静音视频 + 单独的 <audio>
  3. 将视频嵌套在带计时的 div 内 — 使用不带计时的包装器
  4. 使用 data-layer(使用 data-track-index)或 data-end(使用 data-duration)
  5. 动画化视频元素尺寸 — 动画化包装 div
  6. 对媒体调用 play/pause/seek — 框架拥有播放控制
  7. 创建没有 data-composition-id 的顶级容器
  8. 在任何时间线或补间上使用 repeat: -1 — 始终是有限重复
  9. 异步构建时间线(在 async、setTimeout、Promise 内部)
  10. 在来自后续场景的剪辑元素上使用 gsap.set() — 它们在页面加载时不存在于 DOM 中。替代方案是使用 tl.set(selector, vars, timePosition) 在剪辑的 data-start 时间或之后在时间线内部设置。
  11. 在内容文本中使用 <br> — 强制换行不考虑实际渲染的字体宽度。自动换行的文本加上 <br> 会产生额外的、不需要的换行,从而导致重叠。让文本通过 max-width 自动换行。例外:每个词都故意单独成行的简短显示标题(例如,130px 的 "THE\nIMMORTAL\nGAME")。

场景过渡(不可协商)

每个多场景合成必须遵循所有这些规则。违反任何一条都是无效的合成。

  1. 始终在场景间使用过渡。 没有跳切。没有例外。
  2. 始终在每个场景上使用入场动画。 每个元素通过 gsap.from() 动画进入。没有元素可以完全形成地出现。如果一个场景...

相关技能