Communitygithub.com

HyperFrames 视频创作技能

使用 HyperFrames HTML 创建视频合成、动画、标题卡片、覆盖层、字幕、画外音、音频响应式视觉效果和场景过渡。适合构建基于 HTML 的视频内容、添加与音频同步的字幕、生成文本转语音叙述、创建音频驱动动画(节拍同步、发光、脉冲)等。

HyperFrames 视频创作技能 是什么?

HyperFrames 是一个以 HTML 为视频创作核心的专业技能,允许开发者通过 HTML 文件、GSAP 动画时间线和 CSS 样式来精确控制视频合成。它支持完整的视频制作工作流:从设计系统建立(通过 `design.md` 或预设视觉风格)、提示扩展(将用户意图转化为结构化指南),到规划视频结构、节奏和动画。该技能强调“先布局后动画”的原则,要求先构建元素在“英雄帧”中的最终静态布局,再添加进入和离开动画,以避免意外重叠。它支持子合成、参数化变量(允许同一合成根据变量输出不同内容)、音频响应式动画(如节拍同步、发光、脉冲)、字幕同步、文本动画高亮(如记号笔扫过、手绘圆圈)以及场景过渡(交叉溶解、擦除、显示、着色器过渡)。该技能适用于 Claude Code、Cursor、Codex 等 AI 代理工具,主要面向需要创建基于 HTML 的视频内容的开发者和内容创作者,通过数据属性和 GSAP 时间线实现精确时序控制,替代传统视频编辑软件。

兼容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/LingoJack/jcli/tree/HEAD/.jcli/skills/hyperframes

在你喜欢的 AI 中提问

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

预览

来自技能 README

HyperFrames 视频创作技能 preview

文档

HyperFrames

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

方法

探索(仅限探索性请求)

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

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

对于具体请求(“添加一个标题卡片”、“修复场景3的时序”),跳过探索步骤。

对于探索性请求,考虑提供2-3个有意义的变体——不仅仅是颜色切换,而是不同的节奏、能量水平或结构方法。一个安全/预期方案,一个大胆方案。不要强制要求——这只是适合时使用的工具。

步骤 1:设计系统

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

如果它指定了你本地找不到的字体(没有包含 .woff2 文件的 fonts/ 目录,也不是内置字体),请在编写 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。使用适合视频规模的品牌颜色——而不是像 Web 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":"标题","default":"你好"},
  {"id":"theme","type":"enum","label":"主题","default":"light","options":[
    {"value":"light","label":"浅色"},
    {"value":"dark","label":"深色"}
  ]}
]'
>
  <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 报告","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":"专业版","price":"$29"}'
></div>
<div
  data-composition-id="card-enterprise"
  data-composition-src="compositions/card.html"
  data-variable-values='{"title":"企业版","price":"$99"}'
></div>

时间线注册

每个合成脚本必须将其 GSAP 时间线注册到 window.__timelines 中,使用其 data-composition-id 作为键:

window.__timelines = window.__timelines || {};
window.__timelines["my-comp"] = gsap.timeline({ paused: true });

框架使用这个来暂停、播放、查找和同步合成。不注册会导致合成不响应时间控制。

片段类型

<div> 片段

标准容器用于分组动画元素、装饰覆盖层和布局结构。将 data-duration 设置为 0 使其持续整个场景。

<img> 片段

标准图像元素。必须设置 data-duration——默认为 3 秒。

<img data-start="0" data-duration="4" src="assets/logo.png" class="clip" />

<video> 片段

标准视频元素。如果省略则 data-duration 默认为视频持续时间。

<video data-start="0" src="assets/clip.mp4" class="clip"></video>

<audio> 片段

标准音频元素。如果省略则 data-duration 默认为音频持续时间。

<audio data-start="0" src="assets/music.mp3" class="clip"></audio>

<canvas> 片段

用于着色器效果、数据可视化、粒子系统和自定义绘制。

子合成

通过 data-composition-src 加载的独立 HTML 文件。使用变量实现可重用性。

场景过渡

通过场景边界处的 GSAP 时间线处理过渡:

// 从场景 A 过渡到场景 B
// 场景 A 退出,场景 B 进入
// 时间线确保正确的顺序
tl.to("#scene-A", { opacity: 0, duration: 0.5 }, "transitionStart");
tl.from("#scene-B", { opacity: 0, duration: 0.5 }, "transitionStart");

过渡类型

  • 交叉溶解:两个场景重叠并渐变
  • 擦除:一个场景从另一个场景上扫过
  • 显示:场景 B 在场景 A 下方或上方揭示
  • 着色器过渡:使用 <canvas> 进行基于 WebGL 的过渡

字幕与文本动画

字幕

使用 GSAP 时间线将文本元素与音频同步:

const captions = [
  { text: "欢迎使用 HyperFrames", start: 0, duration: 2 },
  { text: "HTML 就是视频", start: 2.5, duration: 2 },
  // ...
];

captions.forEach((caption) => {
  tl.from(".caption-text", { opacity: 0, duration: 0.3 }, caption.start);
  tl.to(".caption-text", { opacity: 0, duration: 0.3 }, caption.start + caption.duration);
  // 在补间之间更新文本——需要编辑 DOM
});

文本动画高亮

  • 记号笔扫过:一个彩色矩形在文本上动画
  • 手绘圆圈:SVG 圆圈围绕文本元素绘制
  • 爆发线条:线条从文本中心向外辐射
  • 涂鸦:手绘线条动画
  • 轮廓绘制:SVG 路径笔画动画

音频响应式动画

将动画与音频属性同步:

// 从 Web Audio API 或其他来源获取音频数据
const audioData = getAudioData(); // 假设有函数返回频率/幅度数组

// 在时间线或 requestAnimationFrame 循环中使用
tl.to(".beat-element", { scale: 1 + audioData.amplitude * 0.5, duration: 0.1 }, "beat");

常见模式包括:

  • 节拍同步:元素随音乐节拍缩放/跳动
  • 发光脉冲:元素发光随音频幅度变化
  • 粒子反应:粒子系统随着音乐节奏移动

参考

本技能依赖于以下参考文档(位于 references/ 目录和根目录中):

相关工作流

对于开发循环 CLI 命令(init、lint、inspect、preview、render),请参阅 hyperframes-cli 技能。有关素材预处理命令(tts、transcribe、remove-background),请参阅 hyperframes-media 技能。

相关技能