Communitygithub.com

assafkip/claude-video-editor

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

claude-video-editor 是什么?

此技能提供了一套完整的视频制作工作流程,基于 HyperFrames 框架,将 HTML 作为视频创作的唯一真实来源。它允许用户通过编写带有特定 `data-*` 属性的 HTML 文件来定义视频合成,并使用 GSAP 时间线进行动画控制,同时使用 CSS 定义视觉样式。该技能强制要求在进行任何 HTML 编写之前必须定义视觉标识(通过 DESIGN.md 或 visual-style.md),并强调“布局优先于动画”的原则,即先构建元素的最终静态布局,再添加入场和退场动画,以避免意外的元素重叠。它支持视频、音频、字幕、场景过渡(如淡入淡出、擦除)以及音频响应式动画,但设定了严格的规则,例如禁止使用 `Math.random()` 确保确定性、禁止在多个时间线中同时动画同一元素的相同属性、禁止无限循环动画、禁止异步构建时间线等。该技能适用于 Claude Code、Cursor、Codex 等 AI 代理平台,通过遵循其详细的规则和结构,可以生成高质量、可预测的视频合成。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/assafkip/claude-video-editor/tree/HEAD/skills/hyperframes

在你喜欢的 AI 中提问

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

预览

来自技能 README

文档

HyperFrames

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

方法

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

  1. 内容 — 观众应该体验什么?确定叙事弧线、关键时刻和情感节拍。
  2. 结构 — 有多少个合成?哪些是子合成,哪些是内联的?哪些轨道承载什么内容(视频、音频、叠加层、字幕)?
  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 个字体系列)、## 禁止事项(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-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-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() 或基于时间的逻辑。如果需要伪随机值,请使用种子 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、将元素移出屏幕、缩放到 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 9 individual skills — each has its own dedicated page.

assafkip/claude-video-editor

Build videos from stills when there is nothing to cut — narration first (ElevenLabs v3 with audio tags), then still keyframes from ANY source (AI image tools, screenshots, photos, HyperFrames-rendered HTML), animated deterministically with the animate-stills recipe (HyperFrames camera moves + GSAP atmosphere). Use when the user wants an explainer, documentary-style video, or any video built from generated or collected visuals instead of recorded footage.

assafkip/claude-video-editor

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.

assafkip/claude-video-editor

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

assafkip/claude-video-editor

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.

assafkip/claude-video-editor

Beginner-friendly end-to-end video creator for HyperFrames. Use when the user says "make a video", "create a video", "new video", "build a video", "video from scratch", "I want to make a video", "help me create a video", or when someone who's never used HyperFrames before arrives with a concept, script, or rough idea and wants a finished MP4. Interviews the user in one pass, then builds the full video with mandatory preview and visual-verification gates.

assafkip/claude-video-editor

Build and iterate short-form vertical (9:16) videos in Hyperframes — TikTok/Reels/Shorts style. Use when Nate says "short-form video", "vertical video", "TikTok/Reels/Shorts", "make a short", "talking-head + motion graphics", or when the target is a 1080x1920 composition with face video + synced scene overlays + karaoke captions. Encodes the full May Shorts 19 playbook: face-mode choreography, audio-synced scene timing, karaoke captions, and the 10-rule quality checklist.

assafkip/claude-video-editor

Edit any video by conversation — the orchestrator for the bundled video pipeline. Use when the user wants to edit, cut, caption, grade, or add motion graphics to footage; drops a folder of clips and says "edit this"; or asks to make a promo/teaser/tutorial/short. Routes to video-use (the cut engine) and HyperFrames (motion-graphics overlays), with a motion-craft library for taste.

assafkip/claude-video-editor

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.

assafkip/claude-video-editor

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.

相关技能