nexu-io/html-video

二〇二六年八月二十六日·★ 1,499·⑂ 158·HTML·Apache-2.0 · GitHub 原仓库

摘要

html-video 是一个开源项目（Apache-2.0），允许用户通过本地编码 agent（如 Open Design、Windsurf CLI、Claude Code 等 14 种后端）将 HTML 描述、文章链接或 GitHub 仓库转化为真实 MP4 视频。项目采用可插拔引擎架构，当前集成 Hyperframes 引擎，通过无头 Chromium 逐帧录制动画 HTML 并使用 ffmpeg（libx264）编码。提供 21 个许可清晰的模板，支持多帧故事板、AI 配乐（MiniMax）及本地渲染，无按次费用或供应商锁定。由 nexu-io 的 Open Design 团队构建。

html-video

HTML 变成视频——就在你的笔记本上。 带上你的本地编码 agent（Open Design · Windsurf CLI · Trae CLI · Claude Code · Cursor · Codex · Gemini · Grok · Qwen · OpenCode · Copilot · Aider · Hermes · 或 Anthropic API）。描述一个视频，或粘贴一篇文章链接 / GitHub 仓库，agent 会将其转化为多帧、全动画视频——然后直接在你的机器上渲染成真正的 MP4。一个 agent 循环、可插拔的渲染引擎、精选模板库、可选的 AI 配乐。Apache-2.0 许可，无按次渲染费用，无供应商锁定。

展示

以下每个模板都是一个真实的、动画化的单文件 HTML 视频——这些是实时渲染，而非模拟图。放入一个模板，让 agent 用你的内容填充它，然后导出为 MP4。

……还有 15 个以上，包括多场景产品宣传片、动态文字、瑞士网格和 Vignelli 数据卡片、决策树解释器、Takram 有机动感，以及温暖颗粒的编辑风格。在工作室图库中浏览全部 21 个实时模板。

为什么存在这个项目

HTML→视频是一个真实的类别——但每个引擎都有自己的主张，并且每个都希望你学习它的创作模型：

引擎	范式	权衡	在 html-video 中
Hyperframes	HTML + CSS + GSAP，agent 技能驱动	单一渲染范式	✅ 已集成——默认引擎；通过无头 Chromium + ffmpeg 渲染真实 MP4
Remotion	React 组件	源码可用，超过 4 名开发者需付费	🗺️ 计划中
Motion Canvas · Revideo	基于 canvas 的 TypeScript 生成器	最适合解释器，代码优先	🗺️ 计划中
Manim 及同类	数学 / 3D 优先	小众	🗺️ 研究中

为每个用例选择正确的引擎、学习每个模型、并将它们拼接成一个工作流，需要花费真正的工程时间。大多数团队选择一个并忍受其限制。

html-video 是位于所有这些引擎之上的元层。 你与你的 agent 对话；它选择引擎、选择模板、填充你的内容，并渲染视频。引擎是一个实现细节，位于一个单一的 adapter 接口之后——一个任何后端都能满足的 render(input, ctx) 契约。添加一个新引擎，每个模板、每个 agent 以及整个工作室工作流都能免费使用它。无需学习新的 DSL，切换引擎时也无需重写。

同样的理念在设计领域驱动了 Open Design——一个覆盖多种工具的 agent 元层。html-video 是来自同一团队的动效对应项目。

状态： 可插拔引擎架构已就位，Hyperframes 引擎已完全连接并可渲染真实 MP4——无头 Chromium 逐帧录制动画 HTML，ffmpeg 编码（libx264）。Remotion、Motion Canvas / Revideo 和 Manim 在路线图上：adapter 接口已为它们设计，但它们的 adapter 尚未构建。上面的“在 html-video 中”列是当前实际可运行内容的唯一真实来源。

概览


编码 Agent（14 个）	Open Design (Vela) · Windsurf CLI · Trae CLI · Claude Code · Cursor Agent · Codex CLI · Gemini CLI · Grok Build · Qwen Code · OpenCode · GitHub Copilot CLI · Aider · Hermes · Anthropic Messages API —— 自动检测你的 `PATH`，可从顶部栏切换。
真实 MP4 渲染	无头 Chromium 录制动画 HTML，ffmpeg 编码（libx264）——本地运行，无云端渲染，无按片段费用。
文章 / 仓库 → 视频	粘贴 URL 或 GitHub 仓库；工作室在服务端获取内容（支持微信公众号文章）并基于真实内容构建视频。
21 个模板	精选、许可清晰的模式：数据可视化、产品宣传片、社交媒体短视频、解释器、动态文字、转场——在图库中实时预览。
多帧故事板	内容图驱动多场景视频；内联编辑每帧文本、重新排序、重新渲染。
AI 配乐	通过 MiniMax 提供的可选背景音乐 + 旁白，在导出时混入 MP4。
工作室 + CLI	本地浏览器工作室和可脚本化的 `html-video` CLI。
许可	Apache-2.0 —— 无按次渲染费用、无座位限制、无贡献者协议。

工作原理

输入一句话（或一个链接）；输出一个真实的 MP4。无论你是从提示词、文章还是仓库开始，流程都是一样的：

  prompt / link / repo
        │
        ▼
  ① 源获取        工作室在服务端拉取 URL 或仓库，将其扁平化为 Markdown
        │
        ▼
  ② agent 循环    你的 agent 读取素材 + 所选模板的风格，并输出
        │          一个内容图（故事板）+ 每帧一个 HTML 块
        ▼
  ③ 内容图        多帧 IR——节点（实体 / 数据 / 文本）+ 边（序列 /
        │          依赖 / 对比）；拓扑排序为帧顺序和时间
        ▼
  ④ 每帧 HTML     每个节点成为磁盘上一个自包含的动画 HTML 帧
        │
        ▼
  ⑤ Hyperframes 渲染  无头 Chromium 加载每帧，录制（自动延长以覆盖
        │               帧自身的动画），→ 每帧一个 webm
        ▼
  ⑥ ffmpeg        每个 webm → mp4（libx264），然后拼接成一个视频；
        │          可选 MiniMax 音乐 + 旁白混入
        ▼
      your.mp4

步骤 ②–④ 是“元层”所在：agent 决定故事板，引擎决定如何绘制它，两者互不干扰。步骤 ⑤ 是引擎特定的——稍后替换为 Remotion 或 Motion Canvas 只会替换那个框，而故事板和 agent 循环保持不变。一切都在你的机器上运行；唯一的网络调用是可选的源获取和可选的配乐。

单帧视频走一条快速路径，跳过内容图——一个模板、一个 HTML，直接渲染。

将链接变成视频

这是大多数人会用的功能：给你的 agent 一个链接，拿回一个视频。Agent 作为本地 CLI 运行，本身没有网络访问权限，因此工作室在服务端获取源内容，并将真实内容输入生成提示词——无需复制粘贴文章正文，并且像微信公众号这样无需登录的服务端渲染页面也能正常工作。

你:   做一个解读视频  https://mp.weixin.qq.com/s/…
Agent: 好，我读完了《用嘴剪视频的时代来了？…》这篇文章 — 这就基于它生成。下一步选风格。
→      多帧解释器，基于文章的实际要点构建

网页文章 → 获取并扁平化为 Markdown。像微信公众号文章这样的服务端渲染页面开箱即用。
GitHub 仓库 → 通过公共 API 拉取描述、顶层结构和 README——非常适合“解释这个开源项目”的视频。
仅提示词 → 描述主题，agent 从头开始编写内容。

无论来源是什么，它都成为视频实际构建的素材——而不是围绕预制模板的装饰。Agent 读取获取的内容，决定需要多少场景，并编写一个内容图故事板：关键点成为帧，它们之间的关系（这个跟随那个，这个与那个对比）成为边，所选模板的视觉风格应用于每帧。因此，一篇 1500 字的文章会变成一个节奏分明的多场景解释器，其每一行都追溯到源内容中的某处；一个仓库会变成一个结构化的项目实际介绍。

快速开始

前提条件

要求	最低版本	检查
Node.js	20+	`node --version`
pnpm	9+	`pnpm --version`
ffmpeg	任何较新版本	`ffmpeg -version`
Chromium（或 Playwright 浏览器）	—	`npx playwright install chromium`

默认渲染引擎在无头 Chromium 浏览器中录制动画 HTML，然后使用 ffmpeg（libx264）编码 MP4。如果你没有系统安装的 Chromium，请安装 Playwright 的 Chromium：

npx playwright install chromium

安装与运行

pnpm install
pnpm -r build
node packages/cli/dist/bin.js studio    # 在 http://127.0.0.1:3071 打开工作室

在工作室中：选择一个模板（或直接描述一个视频 / 粘贴一个链接），与你的 agent 对话，编辑每帧文本，添加配乐，然后导出 MP4。

CLI 工具：

node packages/cli/dist/bin.js doctor                 # 检测已安装的 agent + 引擎
node packages/cli/dist/bin.js search-templates --intent "github stars race" --top 3

支持的 Agent

自动检测你的 PATH；从工作室顶部栏切换活动 agent。工作室首选 Open Design (Vela)——一次登录，多种模型，成本更低——然后回退到第一个可用的 agent，这样新项目总是有一个可工作的后端。

Agent	检测方式	调用方式
Open Design (Vela)	`vela` / 捆绑在 Open Design 应用中	通过 stdio 的 ACP——在 Open Design 中一次登录，选择任意模型
Windsurf CLI	`windsurf`	`windsurf --yolo`，通过 stdio 的 ACP
Trae CLI	`traecli`	`traecli acp serve --yolo`，通过 stdio 的 ACP
Claude Code	`claude`	`claude --print`，通过 stdin 的提示词
Cursor Agent	`cursor-agent`	`cursor-agent --print`
Codex CLI	`codex`	`codex exec`，通过 stdin 的提示词
Hermes	`hermes`	Hermes ACP CLI
Gemini CLI	`gemini`	通过 stdin 的提示词
Grok Build	`grok`	`grok -p <prompt>`
Qwen Code	`qwen`	通过 stdin 的提示词
OpenCode	`opencode`	`opencode run`，通过 stdin 的提示词
GitHub Copilot CLI	`copilot`	`copilot --allow-all-tools`，通过 stdin 的提示词
Aider	`aider`	`aider --message <prompt>`
Anthropic API	BYOK	直接 Messages API——无需安装 CLI

什么都没安装？设置一个 Anthropic 密钥，工作室直接与 Messages API 通信。

配乐

为完成的视频赋予声音。在设置 → 音频中，添加一个 MiniMax API 密钥，然后在每个项目的配乐面板中：

背景音乐——描述一种情绪（calm cinematic ambient, slow build）；MiniMax 生成一段器乐音轨。
旁白——输入脚本；MiniMax 朗读它（TTS）。

两者都会在导出的 MP4 中混入（音乐在语音下自动降低音量，可选淡入/淡出），通过 ffmpeg 实现。没有配置密钥？工作室的其余部分照常工作。

模板库

这 21 个模板并非随机拼凑——每个都是一个自包含、agent 可读的单元，由工作室启动时扫描的 template.html-video.yaml 清单描述。一个清单携带了 agent 选择和使用模板所需的一切，而无需打开 HTML：

用途——category、tags 和一个 best_for 列表（例如 "Corporate slide"、"Minimal report card"），search-templates 会根据你的意图匹配这些。
输出——支持的分辨率、宽高比、fps、时长范围、是否有 alpha 通道或音频。
输入——一个 inputs JSON schema，因此 agent 确切知道要填充哪些文本/数据槽位。
许可来源——一个 SPDX ID，加上明确的 attribution_required / redistribution_allowed / commercial_use 标志，以及一个指向上游来源 URL 的 assets_attribution 块。

最后一部分是刻意的。每个模板在结构上都是许可清晰的：分支保留其原始许可，仓库根目录的 NOTICE.md 记录了每个来源和 SPDX，没有明确宽松许可的内容不会发布。因此，你可以将其中任何一个用于商业作品而无需审计。模板涵盖数据可视化（NYT 风格图表、瑞士/Vignelli 网格）、标题与特效（故障、动态文字、打字机光标）、主视觉与电影感（液态渐变、漏光、温暖颗粒）、产品宣传片（15 秒 / 30 秒多场景）以及解释器框架（决策树）——并且格式是开放的，因此社区模板可以以相同方式加入。

架构

packages/
├── core/                  Project / Asset / ContentGraph 类型、注册表、编排器、
│                          MiniMax 提供者 + ffmpeg 音频混音
├── content-graph/         多帧故事板 IR（节点 + 边，拓扑排序）
│ runtime/               Agent 运行时——检测 / 生成 / 流式传输
│                          (Open Design/Vela · Windsurf CLI · Trae CLI · Claude · Cursor · Codex · Gemini · Grok · Qwen · OpenCode · Copilot · Aider · Hermes · Anthropic API)
├── adapter-hyperframes/   Hyperframes 引擎 adapter——通过 Chromium + ffmpeg 的真实渲染
├── cli/                   `html-video` 命令 + 工作室 HTTP 服务器 + 源获取
└── project-studio/        浏览器工作室 UI（聊天、模板库、帧、配乐、导出）
templates/                 21 个精选、许可清晰的视频模板
research/                  RFC（引擎 adapter / 模板元数据 / agent 技能 / 内容图）

路线图

引擎 adapter 规范——一个接口，N 个后端
模板元数据格式——许可优先，agent 可读
多帧故事板工作流（内容图）
工作室：实时模板库、agent 切换器、每帧文本编辑
源素材：文章 / GitHub 仓库 → 视频
AI 配乐（MiniMax 音乐 + 旁白），在导出时混入
真实 MP4 渲染——通过无头 Chromium + ffmpeg 的 Hyperframes 引擎
Agent 模型选择——Open Design (Vela) 后端，实时模型目录
Remotion / Motion Canvas / Revideo 的 adapter
Agent 技能包 + 模板市场

参考与传承

项目	在此的角色
Open Design	姊妹项目——设计 agent 元层；同一团队，共享理念
HTML Anything	姊妹项目——用于静态交付物的 HTML；html-video 是动效方面
Hyperframes	已集成的引擎 adapter；HTML+CSS+GSAP 渲染范式，以及多个 Apache-2.0 模板的来源

许可

Apache-2.0

构建者

nexu-io —— Open Design 背后的团队。加入 Discord · 关注 @nexudotio。

译自 GitHub · 项目涌现 · 录于二〇二六年八月二十六日