Communitygithub.com

s2530786-cell/ION-DEX

使用 HyperFrames HTML 创建视频合成、动画、标题卡、叠加层、字幕、画外音、音频驱动视觉效果和场景过渡。用于任何基于 HTML 的视频内容构建,包括添加与音频同步的字幕、生成文字转语音旁白、创建音频响应式动画(节拍同步、发光、脉冲)、添加动画文本高亮(标记扫过、手绘圆圈、爆发线条、涂鸦、素描轮廓)或场景过渡(交叉淡出、擦除、揭示、着色器过渡)。涵盖从合成创作、时间轴到媒体、完整视频制作工作流程。

ION-DEX 是什么?

ION-DEX 是一个 HyperFrames 技能,专注于通过 HTML 驱动的高效工作流进行视频生成和编辑。它将 HTML 文件作为视频合成的唯一真相来源,使用 `data-*` 属性控制时间轴、GSAP 动画和 CSS 外观。该技能支持广泛的功能:从基本的标题卡、叠加层和字幕(包括与音频同步的文字转语音旁白),到复杂的音频响应式动画(如节拍同步发光和脉冲效果),以及各种场景过渡(交叉淡出、擦除、翻转和着色器效果)。它适用于任何需要生成、编辑或优化基于 HTML 的视频内容的场景,特别适合需要动态、可定制且脚本化视频生产流程的开发者。ION-DEX 集成了完整的工作流,包括设计系统加载(从 project 中的 `design.md` 文件读取品牌规范)、意图驱动的提示扩展、以及详细的布局优先动画策略(即先构建最终状态的静态 CSS 布局,然后通过 GSAP `from()` 和 `to()` 添加运动和退出动画)。它还支持参数化合成(通过 `data-composition-variables` 传递变量)和子合成加载(`data-composition-src`),使视频元素可复用且可配置。技能强调“布局优先于动画”的原则,通过先构建视觉最终状态来避免意外重叠和布局缺陷。

兼容平台~Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/s2530786-cell/ION-DEX/tree/HEAD/.cursor/skills/hyperframes

在你喜欢的 AI 中提问

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

文档

HyperFrames

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

方法

发现(仅限探索性请求)

对于开放式请求(“给我制作一个产品发布视频”、“为我们的品牌创建一些内容”),在用户未确定方向之前,先了解意图,然后再选择颜色:

  • 受众 — 谁观看此视频?开发者?高管?普通消费者?
  • 平台 — 在何处播放?社交媒体(15 秒)、网站主页、产品演示、内部使用?
  • 优先级 — 什么最重要?运动质量?内容准确性?品牌忠实度?速度?
  • 变体 — 用户需要多个选项,还是一个最佳方案?

对于具体请求(“添加标题卡”、“修复场景 3 的时间”),跳过发现步骤。

对于探索性请求,考虑提供 2-3 个有实质性差异的变体 — 不仅是颜色替换,而是不同的节奏、能量水平或结构方法。一个保守/预期方案,一个激进方案。不要强制要求 — 这是一个在适当时可用的工具。

步骤 1:设计系统

如果项目根目录存在 design.md 或 DESIGN.md,先读取它(检查两种大小写 — 它们在 Linux 上是不同的文件)。它是品牌颜色、字体和约束的唯一真理来源。使用其精确值 — 不要发明颜色或替换字体。任何格式都可以(YAML 前言、散文、表格 — 只需提取值)。

如果它指定的字体找不到(本地没有 fonts/ 目录包含 .woff2 文件,也不是内置字体),则在编写 HTML 之前警告用户:“design.md 指定了 [字体名称] 但未找到字体文件。请将 .woff2 文件添加到 fonts/,否则我将回退到 [最接近的内置替代方案]。”

如果不存在 design.md,向用户提供选择:

  1. 用户指定了风格或氛围? → 阅读 visual-styles.md 了解 8 个命名预设。选择最匹配的。
  2. 想通过视觉浏览选项? → 运行设计选择器:阅读 references/design-picker.md 了解完整工作流程。它会提供视觉选择器页面。用户在浏览器中配置氛围、调色板、排版和运动,然后复制生成的 design.md 并粘贴回对话。
  3. 想跳过快速进行? → 询问:氛围、浅色或深色、任何品牌颜色/字体?然后从 house-style.md 中选择调色板。

design.md 定义品牌。它不定义视频合成规则。 这些规则来自 references/video-composition.md 和 house-style.md。使用适合于视频规模的品牌颜色 — 而非网页 UI 的不透明度。

步骤 2:提示扩展

始终对每个合成执行(但单场景片段和微不足道的编辑除外)。此步骤将用户的意图与 design.md 和 house-style.md 结合起来,产生一个所有下游代理都能一致读取的中间表示。

阅读 references/prompt-expansion.md 了解完整过程和输出格式。

步骤 3:计划

在编写 HTML 之前,先进行高层思考:

  1. 什么 — 观众应该体验什么?识别叙事弧线、关键时刻和情感节奏。
  2. 结构 — 有多少个合成,哪些是子合成或内联合成,哪些轨道承载什么(视频、音频、叠加层、字幕)。
  3. 节奏 — 在实现之前声明场景节奏。哪些场景是快速点击,哪些是停留,着色器在哪里放置,能量峰值在哪里。命名模式:快速-快速-慢速-快速-着色器-停留。阅读 references/beat-direction.md 了解节奏模板。
  4. 时间 — 哪些片段驱动持续时间,过渡在哪里,节奏是什么。
  5. 布局 — 先构建最终状态。参见下面的“布局优于动画”。
  6. 动画 — 然后使用下面的规则添加运动。

仅构建被要求的内容。 对“标题卡”的请求不是“标题卡 + 3 个支持场景 + 背景音乐 + 字幕”的请求。每个场景、每个元素、每个补间都应争取自己的位置。如果额外的场景或元素能真正提升作品质量,可以建议它们 — 但不要擅自添加。

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

布局优于动画

将每个元素放置在其最显眼时刻应处的位置 — 即它完全进入、正确放置且尚未退出的帧。将其编写为静态 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 位置是基础事实;补间描述了到达那里的过程。(在通过 data-composition-src 加载的子合成中,优先使用 gsap.fromTo() — 参见 references/motion-principles.md 中的关键 GSAP 规则。)
  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-durationimg/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-variable-values否子合成主元素上每个实例的变量覆盖 JSON 对象

在根 <html> 元素上:

属性必需值
data-composition-variables否已声明变量的 JSON 数组(id/type/label/default)— 驱动 Studio 编辑 UI 并为 getVariables() 提供默认值

合成结构

通过 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>

变量(参数化合成)

使用不同内容渲染同一合成 — 标题、主题色、价格、字幕 — 无需编辑源 HTML。

三步模式:

  1. 声明 在合成 <html> 根元素上使用 data-composition-variables 声明变量。每个条目需要 id、type(string、number、color、boolean、enum 之一)、label 和 default。枚举条目还需要 options: [{value, label}, ...]。
  2. 读取 合成脚本中使用 window.__hyperframes.getVariables() 读取解析后的值。返回声明默认值 + 每个实例覆盖 + CLI 覆盖的合并结果。
  3. 覆盖 渲染时使用 npx hyperframes render --variables '{...}'(顶层)或主元素上的 data-variable-values='{...}'(子合成的每个实例)。
<!doctype html>
<html
  data-composition-variables='[
  {"id":"title","type":"string","label":"Title","default":"Hello"},
  {"id":"theme","type":"enum","label":"Theme","default":"light","options":[
    {"value":"light","label":"Light"},
    {"value":"dark","label":"Dark"}
  ]}
]'
>
  <body>
    <div data-composition-id="root" data-width="1920" data-height="1080">
      <h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
      <script>
        const { title, theme } = window.__hyperframes.getVariables();
        document.getElementById("hero").textContent = title;
        document.body.dataset.theme = theme;
      </script>
    </div>
  </body>
</html>
# 开发预览使用声明的默认值
npx hyperframes preview

# 使用覆盖渲染
npx hyperframes render --variables '{"title":"Q4 Report","theme":"dark"}' --output q4.mp4

# 或从 JSON 文件
npx hyperframes render --variables-file ./vars.json

子合成每个实例的值: 相同的 getVariables() 适用于通过 data-composition-src 加载的子合成。每个主元素传递自己的值:

<div
  data-composition-id="card-pro"
  data-composition-src="compositions/card.html"
  data-variable-values='{"title":"Pro","price":"$29"}'
></div>
<div
  data-composition-id="card-enterprise"
  data-composition-src="compositions/card.html"
  data-variable-values='{"title":"Enterprise","price":"Contact us"}'
></div>

规则

合成规则

  1. 始终包含 <body> 样式 — margin: 0; overflow: hidden; width: 100vw; height: 100vh;
  2. 每个合成必须有 data-composition-id 在根内容 div 上,以及 data-width 和 data-height。
  3. data-duration 在每个合成上是必需的 — 它优先于 GSAP 时间轴时长。
  4. 根合成的时间轴必须挂载到 window.__timelines["root"]。
  5. 所有时间轴使用 let,并用 paused: true 创建。框架调用 play()。
  6. 不要调用 tl.play() — 框架自动播放。
  7. 所有片段需要 data-track-index — 同一轨道上的片段不能重叠。
  8. 组合轨道片段 用于不重叠的元素(标题、字幕、画外音分别使用不同轨道)。
  9. 叠加轨道用于重叠元素 — 每个叠加元素独立轨道。
  10. 音频不是片段 — 使用 <audio> 标签。data-start 和 data-duration 在父片段上定义。
  11. 服务端往返可能会导致旧的片段恢复 — 避免不必要的重新渲染。
  12. 保持补间简单 — GSAP 处理插值。使用 from() 和 to()。
  13. 删除元素,不隐藏 — 如果用户要求删除元素,也删除其补间。将元素从 HTML 中移除。如果片段被隐藏并重新出现,其补间可能以意外顺序播放。

参考

相关技能