Communitygithub.com

sairam0424/MindForge

使用 HyperFrames 创建基于 HTML 的视频合成、动画标题卡、社交覆盖层、带字幕的讲话人视频、音频响应式视觉效果和着色器过渡。HTML 是视频的来源真相。当用户想要从 HTML 合成中渲染 MP4/WebM、想要动画化文本/标志/图表覆盖在媒体上、需要与音频同步的字幕、想要 TTS 叙述、或者想要将网站转换为视频时使用。

MindForge 是什么?

HyperFrames 是一个 AI 技能,允许开发者和代理将 HTML/CSS/JS 动画渲染为高质量的视频(MP4/WebM)。它将 HTML 作为视频的单一事实来源,利用 GSAP 进行基于时间线的动画,并通过 FFmpeg 进行帧捕获和编码。该技能提供了一整套工具,包括项目脚手架、实时预览、视频渲染、TTS(文本转语音)生成、音频转录、图像字幕生成以及音频响应式可视化。它严格适用于非数学动画,如动态图形、产品演示、讲话人视频、社交覆盖层和网站转视频工作流。关键约束包括视觉标识定义、确定性动画(无随机或异步时序)、以及广泛的 lint/验证/检查功能以确保最终视频没有视觉或结构问题。HyperFrames 与常见的 AI 编程代理(如 Claude Code)以及基于终端的编辑器(如 Cursor 或 Codex)配合良好,指导用户完成从规划、设计到渲染的完整视频创作流程。

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

在你喜欢的 AI 中提问

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

文档

超帧(HyperFrames)

HTML 是视频的唯一真理来源。一个合成文件是一个带有 data-* 属性用于时序控制、一个 GSAP 时间线用于动画、以及 CSS 用于外观的 HTML 文件。HyperFrames 引擎逐帧捕获页面,并使用 FFmpeg 编码为 MP4/WebM。

manim-video 的补充: 对于数学/几何解释器(方程式、3B1B 风格),请使用 manim-video。对于动态图形、讲话人头像带字幕、产品导览、社交覆盖层、着色器过渡以及任何由真实视频/音频媒体驱动的内容,请使用 hyperframes。

何时使用

  • 用户请求从文本、脚本或网站生成渲染视频
  • 动画标题卡片、下三分之一部分或排版介绍
  • 带字幕的叙事视频(TTS + 字幕与波形同步)
  • 音频响应式视觉效果(节拍同步、频谱条、脉冲辉光)
  • 场景间过渡(淡入淡出、擦除、着色器变形、闪白)
  • 社交覆盖层(Instagram/TikTok/YouTube 风格)
  • 网站到视频流程(捕获 URL,生成推广视频)
  • 任何必须确定性地渲染为视频文件的 HTML/CSS/JS 动画

请不要将该技能用于:

  • 纯数学/方程动画(→ manim-video)
  • 图像生成或表情包(→ meme-generation、图像模型)
  • 实时视频会议或流媒体

快速参考

npx hyperframes init my-video               # 脚手架空项目
cd my-video
npx hyperframes lint                        # 在预览或渲染前验证
npx hyperframes preview                     # 实时重载浏览器预览(端口 3002)
 npx hyperframes render --output final.mp4   # 渲染为 MP4
npx hyperframes doctor                      # 诊断环境问题

渲染标志:--quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker(可重现) · --strict。

完整的 CLI 参考: references/cli.md。

设置(一次性完成)

bash "$(dirname "$(find ~/.agent/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"

该脚本:

  1. 验证 Node.js >= 22 和 FFmpeg 是否已安装(如果未安装,则打印修复说明)。
  2. 全局安装 hyperframes CLI(npm install -g hyperframes@>=0.4.2)。
  3. 通过 Puppeteer 预缓存 chrome-headless-shell — 对于通过 Chrome 的 HeadlessExperimental.beginFrame 捕获路径获得最佳质量渲染是必需的。
  4. 运行 npx hyperframes doctor 并报告结果。

如果设置失败,请参阅 references/troubleshooting.md。

步骤

1. 在编写 HTML 之前进行规划

在接触代码之前,请在高层次上阐明:

  • 内容 — 叙事弧线、关键时刻、情感节拍
  • 结构 — 合成、轨道(视频/音频/覆盖层)、持续时间
  • 视觉标识 — 颜色、字体、运动特性(爆炸性 / 电影感 / 流畅 / 技术感)
  • 主角帧(Hero Frame) — 对于每个场景,最多元素同时可见的时刻。这是您将首先构建的静态布局。

视觉标识关卡(硬关卡)。 在编写任何合成 HTML 之前,必须定义视觉标识。请不要使用默认或通用颜色编写合成(#333、#3b82f6、Roboto 是跳过此步骤的标志)。按顺序检查:

  1. 项目根目录下的 DESIGN.md? → 使用其确切的颜色、字体、运动规则和“不要做的事”约束。

  2. 用户指定了样式(例如“瑞士脉冲”、“暗黑科技”、“奢侈品牌”)? → 生成一个最小的 DESIGN.md,包含 ## Style Prompt、## Colors(3-5 个十六进制颜色及其角色)、## Typography(1-2 个字体族)、## What NOT to Do(3-5 个反模式)。

  3. 以上都不是? → 在编写任何 HTML 之前,先问 3 个问题:

    • 情绪是什么? (爆炸性 / 电影感 / 流畅 / 技术感 / 混乱 / 温暖)
    • 亮色还是暗色画布?
    • 是否有任何品牌颜色、字体或视觉参考?

    然后根据答案生成一个 DESIGN.md。每个合成必须将其调色板和排版追溯到 DESIGN.md 或用户明确的指示。

2. 脚手架搭建

npx hyperframes init my-video --non-interactive

模板: blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。传递 --example <名称> 选择一个,传递 --video clip.mp4 或 --audio track.mp3 以媒体作为种子。

3. 先布局,后动画

首先为主角帧编写静态 HTML+CSS — 现在还没有 GSAP。.scene-content 容器必须填充场景(width:100%; height:100%; padding:Npx),使用 display:flex + gap。使用内边距将内容向内推 — 永远不要在内容容器上使用 position: absolute; top: Npx(当内容高于剩余空间时会溢出)。

只有当主角帧看起来正确后,添加 gsap.from() 入场效果(动画到 CSS 位置)和 gsap.to() 出场效果(动画从该位置开始)。

有关完整的数据属性模式和合成规则,请参阅 references/composition.md。

4. 使用 GSAP 进行动画

每个合成必须:

  • 注册其时间线: window.__timelines["<composition-id>"] = tl
  • 以暂停开始: gsap.timeline({ paused: true }) — 播放器控制播放
  • 使用有限的 repeat 值(没有 repeat: -1 — 会破坏捕获引擎)。计算: repeat: Math.ceil(duration / cycleDuration) - 1。
  • 是确定性的 — 没有 Math.random()、Date.now() 或时钟逻辑。如果您需要伪随机性,请使用种子化的 PRNG。
  • 同步构建 — 时间线构建期间没有 async/await、setTimeout 或 Promise。

有关核心 GSAP API(补间、缓动、交错、时间线),请参阅 references/gsap.md。

5. 场景间的过渡

多场景合成需要过渡。规则:

  1. 始终在场景之间使用过渡 — 没有跳切。
  2. 始终在每个场景元素上使用入场动画(gsap.from(...))。
  3. 除了最后一个场景外,绝不使用出场动画 — 过渡本身就是出场。
  4. 最后一个场景可以淡出。

使用 npx hyperframes add <transition-name> 安装着色器过渡(flash-through-white、liquid-wipe 等)。完整列表: npx hyperframes add --list。

6. 音频、字幕、TTS、音频响应式、高亮标记

  • 音频: 始终是一个单独的 <audio> 元素(视频是 muted playsinline)。
  • TTS: npx hyperframes tts "文字稿" --voice af_nova --output narration.wav。使用 --list 列出声音。声音 ID 的第一个字母编码语言(a/b=英语、e=西班牙语、f=法语、j=日语、z=普通话等)— CLI 会自动推断音素化器区域设置;仅传递 --lang 进行覆盖。非英语音素化需要系统范围内安装 espeak-ng。
  • 字幕: npx hyperframes transcribe narration.wav → 逐词转录稿。根据转录稿的语气选择样式(激情 / 企业 / 教程 / 故事讲述 / 社交 — 请参阅 references/features.md 中的表格)。语言规则: 除非音频确认是英语,否则永远不要使用 .en Whisper 模型 — .en 会对非英语音频进行翻译而不是转录。每个字幕组在其出场补间后必须有硬性的 tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) 销毁 — 否则组会泄露到后面的组中可见。
  • 音频响应式视觉效果: 预先提取音频频段(低音 / 中音 / 高音)并在时间线内部使用 for 循环的 tl.call(draw, [], f / fps) 逐帧采样 — 一个长的补间不会响应音频。将低音映射到 scale(脉冲)、高音映射到 textShadow/boxShadow(辉光)、整体振幅映射到 opacity/y/backgroundColor。避免均衡器条俗套 — 让内容指导视觉,音频驱动其行为。
  • 标记式高亮: 高亮、圆形、爆发、涂写、草图效果等文本强调效果是确定性的 CSS+GSAP — 请参阅 references/features.md#marker-highlighting。完全可寻址,没有动画 SVG 滤镜。
  • 场景过渡: 每个多场景合成必须使用过渡(没有跳切)。从 CSS 基元(推拉滑动、模糊淡入淡出、放大穿过、交错块)或着色器过渡(flash-through-white、liquid-wipe、cross-warp-morph、chromatic-split 等)中选择,通过 npx hyperframes add 安装。情绪和能量表位于 references/features.md#transitions。不要在同一合成中混合 CSS 和着色器过渡。

7. Lint、验证、检查、预览、渲染

npx hyperframes lint              # 捕获缺失的 data-composition-id、重叠轨道、未注册的时间线
npx hyperframes validate          # 在 5 个时间戳处进行 WCAG 对比度审计
npx hyperframes inspect           # 视觉布局审计 — 溢出、帧外元素、被遮挡的文本
npx hyperframes preview           # 实时浏览器预览
npx hyperframes render --quality draft --output draft.mp4    # 快速迭代
npx hyperframes render --quality high --output final.mp4     # 最终交付

hyperframes validate 对每个文本元素背后的背景像素进行采样,并在对比度低于 4.5:1(或大文本低于 3:1)时发出警告。hyperframes inspect 是布局方面的伴侣 — 在多个时间戳运行页面,并标记静态 lint 无法看到的问题(一个字幕仅在 4.5 秒时超出安全区域、一个卡片在其标题是最长变体时溢出、一个元素最终位于过渡着色器后面)。特别在包含对话气泡、卡片、字幕或紧凑排版的合成上运行 inspect。

8. 网站转视频(如果用户提供 URL)

使用 references/website-to-video.md 中的 7 步捕获转视频工作流:捕获 → DESIGN.md → SCRIPT.md → 故事板 → 合成 → 渲染 → 交付。

陷阱

  • HeadlessExperimental.beginFrame' wasn't found — Chromium 147+ 移除了此协议。确保您使用的是 hyperframes@>=0.4.2(自动检测并回退到截图模式)。逃生舱: export PRODUCER_FORCE_SCREENSHOT=true。请参阅 hyperframes#294 和 references/troubleshooting.md。
  • 系统 Chrome(不是 chrome-headless-shell) — 渲染会挂起 120 秒然后超时。运行 npx puppeteer browsers install chrome-headless-shell(setup.sh 会执行此操作)。hyperframes doctor 会报告将使用哪个二进制文件。
  • 任何地方的 repeat: -1 — 破坏捕获引擎。始终计算有限的重复次数。
  • 在稍后进入的剪辑元素上使用 gsap.set() — 元素在页面加载时不存在。在时间线内部使用 tl.set(selector, vars, timePosition),在或在该剪辑的 data-start 之后。
  • 内容文本中的 <br> — 强制换行不知道渲染的字体宽度,因此自然换行 + <br> 会双倍换行。使用 max-width 让文本换行。例外情况:每个单词故意独占一行的短显示标题。
  • 动画化 visibility 或 display — GSAP 无法补间这些。使用 autoAlpha(同时处理可见性和不透明度)。
  • 调用 video.play() 或 audio.play() — 框架拥有播放所有权。永远不要自己调用这些。
  • 异步构建时间线 — 捕获引擎在页面加载后同步读取 window.__timelines。永远不要将时间线构建包装在 async、setTimeout 或 Promise 中。
  • 独立的包装在 <template> 中的 index.html — 将所有内容隐藏在浏览器之外。只有通过 data-composition-src 加载的子合成才使用 <template>。
  • 使用视频作为音频 — 始终是静音的 <video> + 单独的 <audio>。

验证

在渲染前后:

  1. Lint + validate + inspect 通过: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect(lint 捕获结构性问题,validate 捕获对比度,inspect 捕获视觉布局/溢出问题 — 如果出现警告,请参阅 troubleshooting.md)。
  2. 动画编排 — 对于新的合成或重大动画更改,运行动画映射。npx hyperframes init 将技能脚本复制到项目中,因此路径是项目本地路径:
    node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
      --out <composition-dir>/.hyperframes/anim-map
    
    输出一个单一的 animation-map.json,包含每个补间的摘要、ASCII 甘特时间线、交错检测、死区(>1秒无动画)、元素生命周期和标志(offscreen、collision、invisible、paced-fast <0.2s、paced-slow >2s)。扫描摘要和标志 — 修复或证明每个。小编辑可跳过。
  3. 文件存在且非零大小: ls -lh final.mp4。
  4. 持续时间与 data-duration 匹配: ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4。
  5. 视觉检查: 提取合成中间帧: ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png。
  6. 如果预期音频存在: ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1。

如果 hyperframes render 失败,运行 npx hyperframes doctor 并在报告时附上其输出。

参考资料

  • composition.md — 数据属性、时间线合同、不可协商的规则、排版/资产规则
  • cli.md — 每个 CLI 命令(init、capture、lint、validate、inspect、preview、render、transcribe、tts、doctor、browser、info、upgrade、benchmark)
  • gsap.md — HyperFrames 的 GSAP 核心 API(补间、缓动、交错、时间线、matchMedia)
  • features.md — 字幕、TTS、音频响应式、标记高亮、过渡(按需加载)
  • website-to-video.md — 7 步捕获到视频工作流
  • troubleshooting.md — OpenClaw 修复、环境变量、常见渲染错误

相关技能