Communitygithub.com

视频编辑工具包

使用 HyperFrames HTML 创建视频合成、动画、标题卡片、叠加层、字幕、配音、音频响应式视觉效果和场景过渡。当需要构建任何基于 HTML 的视频内容、添加与音频同步的字幕、生成文本转语音旁白、创建音频响应式动画(节拍同步、发光、脉冲驱动),添加动画文本高亮(标记扫描、手绘圆圈、爆发线条、涂鸦、素描)或添加场景之间的过渡(淡入淡出、擦拭、揭示、着色器过渡)时使用。涵盖合成编写、时间控制、媒体和完整视频制作工作流。对于 CLI 命令(初始化、检查、预览、渲染、转录、文字转语音),请参见 HyperFrames CLI 技能。

视频编辑工具包 是什么?

视频编辑工具包是一个专业化 AI 代理技能,旨在基于 HyperFrames 框架,在 HTML 中直接构建完整的视频合成。它将 HTML 作为视频的唯一真实来源,利用 `data-*` 属性进行时间控制,GSAP 时间线进行动画,CSS 进行样式。该技能强制执行一套严格的视觉身份检查(DESIGN.md)和布局优先方法(布局优先于动画),以确保所有合成在最终渲染前具有一致的样式和无重叠的布局。此技能支持多种平台(如 Claude Code, Cursor, Codex, Cline),并且必须与 HyperFrames CLI 技能配合使用,以便通过命令行执行渲染、字幕和文本转语音等任务。该工具包涵盖了整个视频制作工作流:从叙事规划、场景结构、媒体时间控制,到管理子合成、视频/音频元素、场景过渡(规则要求每个多场景合成必须有过渡,不能有跳切),以及动画防护措施(例如,不要使用 `repeat: -1`、异步时间线构建或对非最终场景使用退出动画)。重要的是,合成是确定性的(禁止使用 `Math.random()`),并且关键时间线必须注册在 `window.__timelines` 下。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/govindgoel2001/video-editing-toolkit/tree/HEAD/vendor/hyperframes-skills/hyperframes

在你喜欢的 AI 中提问

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

预览

来自技能 README

文档

HyperFrames

HTML 是视频的唯一真实来源。一个合成是一个 HTML 文件,带有用于时间控制的 data-* 属性、用于动画的 GSAP 时间线以及用于样式的 CSS。框架处理剪辑可见性、媒体播放和时间线同步。

方法

在编写 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. 用户命名了样式(例如,“瑞士脉冲”、“黑暗科技风”、“奢侈品牌”)?→ 阅读 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 来填充整个场景。使用 padding 将内容向内推——永远不要对内容容器使用 position: absolute; top: Npx。绝对定位的内容容器在内容高于剩余空间时会溢出。保留 position: absolute 仅用于装饰元素。
  3. 使用 gsap.from() 添加进入动画——从屏幕外/不可见 动画到 CSS 位置。CSS 位置是真实依据;补间描述了到达那里的路径。
  4. 使用 gsap.to() 添加退出动画——从 CSS 位置 动画到屏幕外/不可见。

示例

/* scene-content 填充场景,padding 定位内容 */
.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 等)。
   Padding 定位内容。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对于 img/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["<合成-id>"] = tl
  • 框架自动嵌套子时间线——不要手动添加它们
  • 时长来自 data-duration,而不是 GSAP 时间线长度
  • 永远不要创建空的补间来设置时长

规则(不可协商)

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

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 中。相反,在剪辑的 data-start 时间或之后,在时间线内部使用 tl.set(selector, vars, timePosition)。
  11. 在内容文本中使用 <br>——强制换行不考虑实际渲染的字体宽度。自然换行的文本加上一个 <br> 会产生额外的意外换行,导致重叠。通过 max-width 让文本自然换行。例外:短显示标题,其中每个单词有意单独成行(例如,130px 字号的 "THE\nIMMORTAL\nGAME")。

场景过渡(不可协商)

每个多场景合成必须遵循所有这些规则。违反其中任何一条都会导致合成损坏。

  1. 始终在场景之间使用过渡。 没有跳切。没有例外。
  2. 始终对每个场景使用进入动画。 每个元素通过 gsap.from() 动画进入。没有元素可以完整出现。如果一个场景有 5 个元素,它需要 5 个进入补间。
  3. 绝不使用退出动画,除了最终场景。这意味着:在过渡触发之前,没有 gsap.to() 将透明度动画化为 0、y 移出屏幕、缩放为 0 或任何其他“退出”动画。过渡本身就是退出。正在退出的场景的内容在过渡开始时必须完全可见。
  4. 仅最终场景: 最后一个场景可以淡出元素(例如,淡出到黑色)。这是唯一允许使用 gsap.to(..., { opacity: 0 }) 的场景。

错误——退出动画出现在过渡之前:

// 禁止——这会在过渡使用场景之前清空场景
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// 过渡在空帧上触发

正确——仅进入,过渡处理退出:

// 场景 1 进入动画
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// 没有退出补间——7.2 秒处的过渡处理场景切换
// 场景 2 进入动画
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);

动画防护措施

  • 第一个动画偏移 0.1-0.3 秒(不是 t=0)
  • 在进入补间中变化缓动——每个场景至少使用 3 种不同的缓动
  • 不要在一个场景内重复进入模式
  • 避免在深色背景上使用全屏线性渐变(H.264 条带——使用径向或纯色 + 局部发光)
  • 对于渲染视频,标题 60px+,正文 20px+,数据标签 16px+
  • 在数字列上使用 font-variant-numeric: tabular-nums

当没有提供 visual-style.md 或动画方向时,遵循 house-style.md 以获取美学默认值。

排版和资源

  • 字体: 只需在 CSS 中编写您想要的 font-family——编译器会自动嵌入支持的字体。如果不支持某个字体,编译器会发出警告。
  • 为外部媒体添加 crossorigin="anonymous"
  • 对于……

[……截断以供翻译]

Individual skills in this repo

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

govindgoel2001/video-editing-toolkit

GSAP animation reference for HyperFrames. Covers gsap.to(), from(), fromTo(), easing, stagger, defaults, timelines (gsap.timeline(), position parameter, labels, nesting, playback), and performance (transforms, will-change, quickTo). Use when writing GSAP animations in HyperFrames compositions.

govindgoel2001/video-editing-toolkit

HyperFrames CLI tool — hyperframes init, lint, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, compositions, docs, benchmark. Use when scaffolding a project, linting, validating, inspecting visual layout in compositions, previewing in the studio, rendering to video, transcribing audio, generating TTS, or troubleshooting the HyperFrames environment.

govindgoel2001/video-editing-toolkit

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, and registry discovery.

govindgoel2001/video-editing-toolkit

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

govindgoel2001/video-editing-toolkit

Edit any video by conversation. Transcribe, cut, color grade, generate overlay animations, burn subtitles — for talking heads, montages, tutorials, travel, interviews. No presets, no menus. Ask questions, confirm the plan, execute, iterate, persist. Production-correctness rules are hard; everything else is artistic freedom.

govindgoel2001/video-editing-toolkit

Production pipeline for mathematical and technical animations using Manim Community Edition. Creates 3Blue1Brown-style explainer videos, algorithm visualizations, equation derivations, architecture diagrams, and data stories. Use when users request: animated explanations, math animations, concept visualizations, algorithm walkthroughs, technical explainers, 3Blue1Brown style videos, or any programmatic animation with geometric/mathematical content.

相关技能