html-video 是一个将 HTML 内容转化为视频的工具

📌 项目简介

html-video 是一个将 HTML 内容转化为视频的工具。它允许你通过本地编程代理（如 Open Design、Claude Code 等）或直接描述，将文章链接、GitHub 仓库或纯文本提示，自动生成包含动画、多场景的 MP4 视频。渲染过程完全在本地进行，无需支付按次渲染费用。

⚙️ 系统要求与准备

在开始前，请确保你的系统已安装以下依赖：

依赖项	最低版本	检查命令
Node.js	20+	`node --version`
pnpm	9+	`pnpm --version`
ffmpeg	任何较新版本	`ffmpeg -version`
Chromium (或 Playwright 浏览器)	—	见下方安装说明

安装 Playwright 的 Chromium (推荐，若系统无 Chromium)：

1	npx playwright install chromium

🚀 快速部署与启动 (本地运行)

第 1 步：克隆或下载项目

1 2	git clone https://github.com/nexu-io/html-video.git cd html-video

第 2 步：安装依赖
项目使用 pnpm 管理依赖，在项目根目录执行：

1	pnpm install

第 3 步：构建项目

1	pnpm -r build

此命令会构建项目中的所有子包（packages）。

第 4 步：启动本地工作室 (Studio)

1	node packages/cli/dist/bin.js studio

成功启动后，终端会显示本地访问地址，通常是 http://127.0.0.1:3071。在浏览器中打开该地址即可使用图形化界面。

🎬 首次使用：从链接生成视频

这是项目最核心的功能，可以通过一个网页链接或 GitHub 仓库直接生成视频。

打开工作室：访问 http://127.0.0.1:3071。
选择或描述视频：
- 粘贴链接：在输入框中粘贴一个网页文章链接（如微信公众号文章）或 GitHub 仓库地址。
- 直接描述：直接输入文字提示，如“做一个关于太阳系行星的科普短片”。
选择代理 (Agent)：工作室顶部可以切换不同的本地 AI 代理（如 Open Design、Claude Code 等）。如果没有安装任何代理，你可以设置 Anthropic API 密钥，让工作室直接调用 API。
选择模板：从 21 种内置模板中挑选一种风格（如数据可视化、标题动画、电影感开场等）。
生成与编辑：
- 代理会读取你提供的内容，生成一个 内容图谱 (content-graph) 故事板，将内容分解为多个场景/帧。
- 你可以在界面上逐帧编辑文本，调整顺序。
添加音轨（可选）：在 设置 → 音频 中配置 MiniMax API 密钥，然后可为视频添加背景音乐或 AI 旁白。
导出 MP4：点击导出按钮。项目会使用 Hyperframes 引擎（基于 Chromium + ffmpeg）在本地渲染并生成最终的 MP4 视频文件。

🛠️ CLI 命令行工具

除了图形化工作室，你也可以使用命令行工具进行辅助操作：

环境检测：
1
node packages/cli/dist/bin.js doctor
这会检测你系统中已安装的代理和渲染引擎。

搜索模板：

1	node packages/cli/dist/bin.js search-templates --intent "数据图表" --top 3

根据意图搜索匹配的模板。

📁 项目架构简介

了解项目结构有助于后续开发和自定义：

html-video/
├── packages/                 # 核心功能包
│   ├── core/                 # 核心类型、资源管理、编排器、音频处理
│   ├── content-graph/        # 多帧故事板的数据结构（节点、边、排序）
│   ├── runtime/              # 各类 AI 代理的检测、启动和流式交互
│   ├── adapter-hyperframes/  # 默认的 Hyperframes 渲染引擎适配器
│   ├── cli/                  # CLI 命令、Studio 服务器、源内容抓取
│   └── project-studio/       # 浏览器端 Studio UI
├── templates/                # 21 个内置的、许可证清晰的视频模板
└── research/                 # 设计文档和 RFC

⚠️ 重要须知

当前可用的渲染引擎：项目架构支持多种引擎，但目前 默认且唯一能实际渲染 MP4 的是 Hyperframes 引擎（通过 Chromium + ffmpeg）。Remotion、Motion Canvas 等引擎的适配器仍在规划中。
所有操作在本地完成：除了可选的“源内容抓取”和“AI 音轨生成”外，视频渲染、编码等所有计算都在你的笔记本电脑上执行，无云端渲染费用。
模板许可证：所有内置模板都经过许可审查，明确标注了商用、署名等要求，可安全用于商业项目。
代理 (Agent) 依赖：要获得最佳的自动化生成体验，建议安装并配置至少一个支持的 AI 代理（如 Open Design 的 vela 或 Claude Code）。纯 API 模式也可工作。

💎 总结

部署 html-video 的流程非常直接，核心步骤是：确保 Node.js、pnpm、ffmpeg 环境 → 克隆项目 → 安装并构建 → 启动 Studio。之后，你就可以通过友好的网页界面，利用本地 AI 代理的能力，将文章或想法自动转化为带有动画、配乐的专业视频。整个流程强调本地化、开源免费和灵活性。