nexu-io/html-video · 上手攻略
- 仓库：nexu-io/html-video
- 链接：https://github.com/nexu-io/html-video
- 分类：ai-workflow
- 作者：Tom
- 更新：2026-07-14
是什么
html-video 是 Open Design 团队出品的"AI 视频生成 meta-layer"：你跟本地 coding agent 说一句话（或丢一个链接），它把 HTML/CSS/数据变成真实 MP4 视频，全程在你电脑上渲染，不需要云端、不收单次渲染费。
它不绑定某个特定渲染引擎，而是一套适配器接口，render(input, ctx) 契约，任何后端满足即可接入。目前唯一完整接通的是 Hyperframes 引擎（无头 Chromium + ffmpeg），可渲染出真实 MP4。Remotion、Motion Canvas / Revideo、Manim 在路线图上，接口已设计好但适配器尚未构建。
姊妹项目是 Open Design（设计 agent meta-layer）和 HTML Anything（静态 HTML 交付）。
解决什么问题
市面上海外→视频工具（Remotion、Motion Canvas、Heygen Hyperframes）各有各的创作模型，学一个就要折腾一阵。多数团队挑一个忍着它的局限，缺乏统一抽象。
html-video 的核心价值： - 统一入口：跟 agent 对话说"给我做个解读视频"，不用学任何视频工具 - 可插拔引擎：换渲染引擎不重写工作流，加新引擎全模板/全 agent 自动受益 - 本地渲染：不依赖云渲染农场，不按次收费 - 许可清晰：21 个模板全部附带 SPDX 许可信息，可用于商业作品 - 支持文章/仓库直接转视频：微信公众号文章（服务端渲染，无需登录）、GitHub 仓库均可抓取真实内容
快速安装
依赖要求
| 依赖 | 最低版本 | 检查命令 |
|---|---|---|
| Node.js | 20+ | node --version |
| pnpm | 9+ | pnpm --version |
| ffmpeg | 任意较新 | ffmpeg -version |
| Chromium | Playwright 内置即可 | npx playwright install chromium |
⚠️ Chromium/Playwright 依赖：如果没有系统 Chromium，执行
npx playwright install chromium（约 200MB）。Node 20+ 和 pnpm 9+ 是官方明确要求。
安装步骤
# 1. 克隆仓库
git clone https://github.com/nexu-io/html-video.git
cd html-video
# 2. 安装依赖
pnpm install
# 3. 构建所有包
pnpm -r build
# 4. 启动本地 Studio（浏览器界面）
node packages/cli/dist/bin.js studio
# 打开 http://127.0.0.1:3071
CLI 工具（无需浏览器）
# 诊断：探测已安装的 agent + 引擎
node packages/cli/dist/bin.js doctor
# 按意图搜索模板
node packages/cli/dist/bin.js search-templates --intent "github stars race" --top 3
核心用法
工作管线全貌
prompt / 链接 / 仓库
① 来源抓取 → 扁平成 Markdown（文章/仓库均可）
② agent 循环 → 读素材 + 模板风格 → 输出 content-graph（故事板）+ 逐帧 HTML
③ content-graph → 节点（实体/数据/文本）+ 边（顺序/依赖/对比），拓扑排序
④ 逐帧 HTML → 磁盘上的自包含动画 HTML 帧
⑤ Hyperframes 渲染 → 无头 Chromium 录制 → webm 每帧
⑥ ffmpeg → webm → MP4（libx264），可混入 MiniMax 配乐/旁白
→ 你的 MP4
用法一：丢链接给 agent（最常用）
# 在 Studio 里直接粘贴微信文章/GitHub 仓库链接
# Studio 在服务端抓取真实内容，agent 自动生成视频
# 示例对话：
你：做一个解读视频 https://mp.weixin.qq.com/s/...
Agent：好，我读完了《...》这篇文章——这就基于它生成。
→ 多帧解说视频，每一句都能追溯回原文要点
用法二：描述视频主题（无需任何素材）
# 在 Studio 里直接用自然语言描述
# agent 从零生成内容，挑选最合适模板
你：做一个讲 AI 代码库导航的短视频
→ 多帧视频，基于 agent 理解自动生成
用法三：命令行单帧快速导出
对于单帧视频，走快速路径，跳过 content-graph，直接一个模板 + 一个 HTML → 渲染：
# Studio 内操作：选模板 → 填内容 → 导出 MP4
# 无需 agent，UI 操作即可完成
配置 AI 配乐（可选）
# 1. 在 Settings → Audio 填入 MiniMax API key
# 2. 在每个项目的 Soundtrack 面板：
# - 背景音乐：描述情绪（如"舒缓的电影感氛围"），MiniMax 生成器乐
# - 旁白：输入文案，MiniMax TTS 朗读
# 3. 导出时自动混合（音乐压低到人声下，可选淡入淡出）
# 没配 key 的话，studio 其余部分照常工作
支持的 Coding Agent（14 个，自动探测）
| 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，prompt 走 stdin |
| Cursor Agent | cursor-agent |
cursor-agent --print |
| Gemini CLI | gemini |
prompt 走 stdin |
| Grok Build | grok |
grok -p <prompt> |
| Anthropic API | BYOK | 直连，不装 CLI 也能用 |
| 其他（Qwen Code, OpenCode, Copilot CLI, Aider, Hermes, Codex CLI） | PATH 探测 | 各自标准方式 |
💡 什么都没装时，配一个
ANTHROPIC_API_KEY，Studio 直接走 Messages API。
21 个模板分类
| 类别 | 代表模板 | 用途 |
|---|---|---|
| 数据可视化 | frame-data-chart-nyt | 纽约时报风格折线图 |
| 标题/VFX | frame-glitch-title, vfx-text-cursor | 故障风标题、打字机光标 |
| 主视觉 | frame-liquid-bg-hero | 极光渐变大标题 |
| 电影感 | frame-light-leak-cinema | 暖色胶片颗粒、漏光 |
| 片尾 | frame-logo-outro | Logo 动画结束卡 |
| 多场景 | 15+ 个 | 产品宣传、解说、决策树等 |
每个模板由 template.html-video.yaml 清单描述，包含 category、tags、best_for、inputs JSON schema、许可信息，agent 可无脑驱动。
典型适用场景
- 内容创作者/自媒体：把公众号文章、博客一键转成带动画的解说视频
- AI 工具开发者：给 GitHub 仓库生成项目介绍视频
- 产品宣传：快速做产品发布短片、数据可视化视频
- 企业内部沟通：把报告、数据一键做成演示视频
- 开发者/技术文档：代码演示、CLI 功能展示（vfx-text-cursor 模板）
坑与注意
- ⚠️ 只支持单引擎生产：目前唯一稳定可用的是 Hyperframes（真实 MP4）。Remotion/Motion Canvas/Revideo 适配器尚未构建，别被 roadmap 迷惑——README 里明确写了"In html-video"列才是唯一权威。
- ⚠️ Chromium 依赖：没有 headless Chromium 就没法渲染，
npx playwright install chromium是必须步骤。 - ⚠️ MiniMax API Key 需要单独申请：配乐功能可选，但配置路径较深（Settings → Audio），新手可能找不到。
- ⚠️ Agent 需要本地已安装：14 个 agent 都是本地 CLI，Studio 在 PATH 上探测。没装任何一个时需要配
ANTHROPIC_API_KEY作为 fallback。 - ⚠️ 微信公众号文章：需要服务端渲染页面能访问（无需登录），国内环境可能受网络限制。
- 模板许可不等于随意商用：每个模板都有明确 SPDX ID，需核实
NOTICE.md确保适合你的商业场景。
与同类对比
| 工具 | 渲染方式 | 费用 | Agent 集成 | 学习成本 |
|---|---|---|---|---|
| html-video | 本地 Chromium + ffmpeg（Hyperframes） | 免费（Apache-2.0） | 原生 14 个 agent | 低（自然语言交互） |
| Remotion | React 组件 → 视频 | 4 人以上收费 | 无原生 | 高（需写 React） |
| Motion Canvas | TypeScript 生成器 on canvas | 免费 | 无原生 | 高（TypeScript） |
| Heygen | 云端 | 按次收费 | API | 中（但贵） |
| Pika/Luma | 云端 AI 生成 | 订阅制 | 无 | 低（但效果不可控） |
核心差异：html-video 是 meta-layer，其他是具体引擎。它不重复造轮子，而是通过统一适配器接口让你自由切换渲染引擎，同时把 AI agent 作为默认前端。Remotion 等要你写代码；html-video 让你用自然语言"指挥" agent 写。
一句话推荐结论
把"用嘴剪视频"变成现实——全程本地渲染、支持任意 coding agent、Apache-2.0 零费用，适合想用 AI agent 做内容自动化的团队或个人。不过目前只有 Hyperframes 引擎完整可用，Remotion 等多引擎路线图尚未落地，生产场景建议先确认功能是否满足再上车。