html-video:在笔记本电脑上把 HTML 变成视频的 Agent 元层
项目地址:github.com/nexu-io/htm… · 协议:Apache-2.0 · Stars:2,289 · Forks:264 · 最新提交:2026-06-08(Remotion 引擎适配器落地 便携包：yunyingmenghai.feishu.cn/wiki/Fjcmwn…)
当 AI 写代码、写文章、写设计稿成为常态,让 AI 写视频成了下一个被盯上的场景。但 HTML→Video 引擎是各说各话的——Hyperframes 要你学 HTML/CSS/GSAP,Remotion 要写 React,Motion Canvas/Revideo 是 TypeScript 画布,Manim 主打数学动画。
nexu-io/html-video 的思路是:别学了,让 Agent 来选。它是一个视频生成的元层(Meta-Layer):你说一句"把那个 GitHub 仓库做成 60 秒视频"或者粘一篇公众号文章,Agent 自己挑引擎、挑模板、填内容、渲染出真 MP4,整个流程跑在你本机的 Chromium + ffmpeg 上,没有云端渲染费、没有供应商锁定。
一句话定位
html-video = Agent + 模板库 + 引擎适配器 + 本地渲染,把"内容→多帧动画→MP4"做成单一
render(input, ctx)契约。
先看数据
| 指标 | 数值 |
|---|---|
| Stars | 2,289 |
| Forks | 264 |
| Open Issues | 18 |
| 主语言 | HTML(4.14 MB)+ TypeScript(412 KB) |
| 仓库大小 | 9.6 MB |
| 创建时间 | 2026-05-27 |
| 协议 | Apache-2.0 |
| 最新里程碑 | Remotion 适配器(RFC-08)合入 main |
⚠️ 这是个不到 2 周岁的项目,但发布密度高(2 周内连发 Hyperframes 适配 + Remotion Phase 2),Roadmap 上还有 Motion Canvas / Revideo / Manim 三家待集成。
它在解决什么问题
HTML→Video 工具链当前的核心痛点是:写动画 ≠ 写视频。一份好看的 GitHub 项目介绍短视频,需要:
- 选引擎(每个引擎有不同范式)
- 拆脚本成多帧 storyboard
- 写每帧的 HTML/CSS/GSAP/React
- 在浏览器里逐帧录屏
- ffmpeg 合成 + 加音轨
第 1、2 步是产品决策,3-5 步是机械劳动。html-video 把这五步压成一句话 → MP4。
4 大子系统
packages/
├── core/ 项目 / 素材 / ContentGraph 类型 + 编排器 + MiniMax 音视频
├── content-graph/ 多帧故事板 IR(节点+边,拓扑排序)
├── runtime/ Agent 运行时:检测 / 生成 / 流式输出(14 个后端)
├── adapter-hyperframes/ Hyperframes 引擎适配器(Chromium + ffmpeg)
├── cli/ html-video CLI + Studio HTTP 服务 + 源抓取
└── project-studio/ 浏览器 Studio UI(聊天 / 模板库 / 帧编辑 / 导出)
| 子系统 | 职责 | 关键点 |
|---|---|---|
| runtime | 调起本地 Coding Agent | 14 个 agent 后端自动检测(Vela / Claude Code / Codex / Hermes / Aider / Copilot…) |
| content-graph | 多帧编排 | 节点 + 边,自动拓扑排序到帧顺序与时长 |
| adapter-* | 引擎适配器 | 统一 render(input, ctx) 接口,目前 Hyperframes 已 shipped,Remotion Phase 2 已合入 |
| studio | 浏览器交互 | http://127.0.0.1:3071,聊天 + 画廊 + 帧编辑器 + 导出 |
一次完整循环
prompt / link / repo
↓
① source fetch → 服务端拉取,扁平化到 Markdown(支持微信公众号)
↓
② agent loop → 读素材 + 模板风格,产出 content-graph + 每帧 HTML
↓
③ content-graph → 节点+边,拓扑排序到帧顺序 & 时长
↓
④ per-frame HTML → 自包含的动画 HTML 帧
↓
⑤ Hyperframes render → headless Chromium 录每帧 → webm
↓
⑥ ffmpeg → webm → mp4(libx264);可选 MiniMax 配乐 + 配音
↓
your.mp4
单帧视频可以跳过 content-graph。
引擎对比
| 引擎 | 范式 | html-video 状态 |
|---|---|---|
| Hyperframes | HTML + CSS + GSAP | ✅ Shipped,默认引擎 |
| Remotion | React 组件 | 🟡 Phase 2 合入(RFC-08) |
| Motion Canvas / Revideo | TypeScript 画布 | 🗺️ Planned |
| Manim | 数学 / 3D 优先 | 🗺️ Researching |
14 个 Coding Agent 自动检测
| Agent | 检测命令 | 调用方式 |
|---|---|---|
| Open Design (Vela) | vela | ACP over stdio |
| Windsurf CLI | windsurf | windsurf --yolo |
| Trae CLI | traecli | traecli acp serve --yolo |
| Claude Code | claude | claude --print |
| Cursor Agent | cursor-agent | cursor-agent --print |
| Codex CLI | codex | codex exec |
| Gemini CLI | gemini | stdin prompt |
| Grok Build | grok | grok -p <prompt> |
| Qwen Code | qwen | stdin prompt |
| OpenCode | opencode | opencode run |
| GitHub Copilot CLI | copilot | copilot --allow-all-tools |
| Aider | aider | aider --message <prompt> |
| Hermes | hermes | Hermes ACP CLI |
| Anthropic Messages API | BYOK | 直连 API(无 CLI 也行) |
本地什么都没装?塞个
ANTHROPIC_API_KEY,Studio 直接走 Messages API,其他功能照常。
21 个模板
README 里点名的几个:
- frame-data-chart-nyt — 编辑级 NYT 风格动效折线图
- frame-glitch-title — 色差故障 + 扫描线标题卡
- frame-liquid-bg-hero — 极光液态渐变 Hero
- frame-light-leak-cinema — 暖色胶片颗粒 + 漏光电影感
- vfx-text-cursor — 终端光标打字机
- frame-logo-outro — Logo 结尾卡
剩下 15 个覆盖多场景产品推广、动效字、瑞士网格、Vignelli 数据卡、决策树解释、Takram 有机运动、暖色编辑。每个模板带 SPDX 许可证元数据(redistribution_allowed / commercial_use / attribution_required),社区模板按同样格式 drop-in。
装 & 用
前置依赖
| 要求 | 最低版本 |
|---|---|
| Node.js | 20+ |
| pnpm | 9+ |
| ffmpeg | 任意较新 |
| Chromium | npx playwright install chromium |
启动 Studio
pnpm install
pnpm -r build
node packages/cli/dist/bin.js studio # 打开 http://127.0.0.1:3071
CLI 速查
node packages/cli/dist/bin.js doctor # 检测 agents + engines
node packages/cli/dist/bin.js search-templates --intent "github stars race" --top 3
没装 Chromium?先跑
npx playwright install chromium,否则录屏步骤会跪。
配乐 + 配音
在 Settings → Audio 加 MiniMax API key,项目内可分别配置:
- 背景音乐 — 描述情绪,MiniMax 生成 instrumental
- 配音 — 输入脚本,MiniMax TTS 朗读
导出 MP4 时由 ffmpeg 混合(配乐在配音下自动 duck,可选淡入淡出)。没填 key 不影响其他功能。
Roadmap
- 引擎适配器规范
- 模板元数据格式(License-first)
- 多帧 content-graph 工作流
- Studio:模板库 / Agent 切换 / 帧编辑器
- 文章 / GitHub 仓库 → 视频
- AI 配乐(MiniMax)
- Hyperframes 引擎真 MP4 渲染
- Agent 模型选择(Vela 后端)
- Remotion 适配器 Phase 2(2026-06-08 合入)
- Motion Canvas / Revideo / Manim 适配器
- Agent skill 包 + 模板市场
踩坑记录(基于项目结构推断)
| 现象 | 根因 | 解决 |
|---|---|---|
| 启动 Studio 报 Chromium 找不到 | 没装 Playwright Chromium | npx playwright install chromium |
| 模板搜不到结果 | ContentGraph 没匹配到 category / tags | 跑 doctor 查模板索引,或换 search-templates 的 --intent 关键词 |
| 配乐 / 配音没出 | 没配 MiniMax API key | Settings → Audio 填 key;不填也跑得通,只是没声音 |
| 微信公众号文章拉不到 | 服务端 fetch 没绕登录 | 走链接自动 Markdown 化是默认行为;私域内容需要预导出 Markdown |
使用感受
✅ 优点
- 元层思路对了:让 Agent 选引擎,而不是逼用户学 4 套范式
- License-first 模板库:商用可追溯,21 个模板不算多但覆盖关键场景
- 14 个 Agent 后端自动检测,本地生态门槛低
- 端到端可跑通(
一句话 → MP4),路线图清晰
⚠️ 注意点
- 项目新(2 周岁不到),API 与目录结构可能仍在变化
- 默认引擎 Hyperframes 对 GSAP 较重,纯静态视频可能过度
- Remotion 适配器刚进 Phase 2,生产环境建议先 Hyperframes
- 配乐 / 配音需要 MiniMax 海外可达,国内网络要自备代理
🎯 推荐人群
- 有 Coding Agent,想批量出"GitHub 项目 60 秒介绍视频"的运营 / 增长
- 视频教学作者,需要把文章 / 仓库 → 视频
- 想搭"AI 视频生成平台",且不想绑单一引擎的团队
相关链接
| 资源 | 链接 |
|---|---|
| 仓库 | github.com/nexu-io/htm… |
| 姐妹项目 Open Design | github.com/nexu-io/ope… |
| 姐妹项目 HTML Anything | github.com/nexu-io/htm… |
| 默认引擎 Hyperframes | github.com/heygen-com/… |
| 项目主页 | open-design.ai/html-video |
写在最后
html-video 不是又一个"HTML 转视频"的 CLI,它把**"让 AI 选引擎 + 编排多帧 + 本地渲染"**做成了产品形态。对内容运营来说,把 GitHub 项目 / 公众号文章 → 60 秒视频,从此只剩一句话的成本。
下一步值得盯的是 Remotion Phase 3 与 Motion Canvas / Revideo 适配器——如果三家引擎都能跑同一份 content-graph,这个元层就真的成了"AI 视频生成的事实标准接口"。
GitHub:github.com/nexu-io/htm…
