Communitygithub.com

nastechresearch/nastech-agent

从 HTML 合成渲染 MP4/WebM 视频。

nastech-agent 是什么?

HyperFrames 是一个 AI 智能体技能,用于将 HTML 合成渲染为 MP4 或 WebM 格式的视频文件。它将 HTML 视为视频的“单一事实来源”,通过在一个 HTML 文件中使用 `data-*` 属性来控制时序、使用 GSAP 时间线来控制动画、使用 CSS 来控制外观。该引擎会逐帧捕获浏览器页面,并利用 FFmpeg 编码输出最终视频。该技能支持多种视频类型,包括动态图形、带字幕的旁白、产品导览、社交平台覆盖、着色器转场以及任何由真实视频或音频驱动的视觉内容。它不适用于纯数学/方程动画或图像生成。本技能为开发者提供了完整的命令行工具链,用于项目初始化、预览、验证和渲染,并特别强调了视觉设计规范(通过生成的 `DESIGN.md` 文件)和避免常见陷阱(如 `<br>` 标签导致的双重换行、异步构建时间线等),以确保视频渲染的确定性和高质量。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nastechresearch/nastech-agent/tree/HEAD/optional-skills/creative/hyperframes

在你喜欢的 AI 中提问

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

文档

HyperFrames

HTML 是视频的单一事实来源。一个合成是一个 HTML 文件,其中包含用于时序控制的 data-* 属性、用于动画的 GSAP 时间线以及用于外观的 CSS。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                      # 诊断环境问题

preview 是一个长期运行的 Next.js 服务器,它会保持 Chrome 渲染进程处于打开状态。完成后务必停止它(参见清理)——一个被遗忘的预览进程会保持空闲的 chrome-headless-shell 进程,在无 GPU 的主机(WSL、容器、CI)上,这些进程会通过软件 WebGL(swiftshader)无限占用每个 CPU 核心。

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

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

设置(一次性)

bash "$(dirname "$(find ~/.nastech/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 之前先规划

在接触代码之前,请从高层次阐述:

  • 内容 —— 叙事弧、关键时刻、情感节拍
  • 结构 —— 合成、轨道(视频/音频/覆盖层)、时长
  • 视觉标识 —— 颜色、字体、运动特征(爆发式 / 电影感 / 流畅 / 技术风格)
  • 关键帧 —— 对于每个场景,大多数元素同时可见的时刻。这是您将首先构建的静态布局。

视觉标识门(硬性门控)。 在编写任何合成 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 <name> 选择一个,传递 --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() 出场动画(从 CSS 位置动画离开)。

有关完整的数据属性模式(data-attribute schema)和合成规则,请参阅 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() 或系统时钟逻辑。如果需要伪随机性,请使用带种子的伪随机数生成器(seeded 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. 代码检查、验证、检查、预览、渲染

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 是布局方面的配套工具 —— 它在多个时间点运行页面,并标记静态代码检查无法看到的问题(一个字幕在 4.5 秒时才包裹到安全区域之外、一张卡片在其标题为最长变体时溢出、一个元素最终位于转场着色器后面)。特别要对包含对话气泡、卡片、字幕或紧凑排版的合成运行 inspect。

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

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

清理

render 是一次性的(工作进程在完成后退出)。preview 不是 —— 它会运行一个后台 Next.js 服务器,使 Chrome 工作进程保持驻留状态,直到您停止它。永远不要让它保持运行:在无 GPU 的主机上,每个空闲工作进程的 swiftshader 进程会占用一个 CPU 核心,并且一个预览进程如果保持打开数天会积累多个。

当用户完成审查后(或在开始新的预览之前),停止预览:

pkill -f "hyperframes.*preview"     # Studio 服务器(释放端口 3002)
pkill -f chrome-headless-shell      # 其渲染工作进程;仅在无其他工具使用它们时才安全

如果不确定其他工具是否使用 chrome-headless-shell,请先检查:pgrep -af chrome-headless-shell。以相同方式恢复一个被卡住的主机(许多空闲工作进程占用 CPU)—— 请参阅 references/troubleshooting.md。

陷阱

  • 让 preview 保持运行 —— 它是一个长期运行的服务器,持有 Chrome 工作进程;在 WSL/容器/CI 上,这些空闲工作进程会各占用一个 CPU 核心(软件 WebGL)。完成后停止它 —— 请参阅清理。

  • 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(同时处理 visibility 和 opacity)。

  • 调用 video.play() 或 audio.play() —— 框架控制播放。永远不要自己调用这些方法。

  • 异步构建时间线 —— 捕获引擎在页面加载后同步读取 window.__timelines。永远不要将时间线构建包裹在 async、setTimeout 或 Promise 中。

  • 独立的 index.html 包裹在 <template> 中 —— 将所有内容对浏览器隐藏。只有通过 data-composition-src 加载的子合成才使用 <template>。

  • 使用视频来播放音频 —— 始终使用静音的 <video> 加独立的 <audio>。

验证

在渲染前后:

  1. 代码检查 + 验证 + 检查通过: npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes 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_e

相关技能