1. 一句话定位
html-video 是一个让 AI Agent 把 HTML/CSS/数据/文章/仓库内容转换成 MP4 视频的本地开源工作流。
它的核心思路不是再做一个单独的视频编辑软件，而是在多种 HTML-to-Video / code-to-video 引擎之上放一个 Agent meta-layer：
- 用户描述想要的视频，或粘贴文章/GitHub repo。
- Studio 抓取来源内容并转成 Markdown。
- Agent 阅读内容，生成 content-graph 故事板和逐帧 HTML。
- Hyperframes 引擎把每一帧 HTML 动画录制成视频片段。
- ffmpeg 编码、拼接、混音，导出 MP4。
售前可这样讲：
html-video 把“写网页”和“做视频”连接起来。对企业来说，它可以把文章、报告、仓库介绍、产品卖点、数据图表变成短视频，而且渲染在本地完成，没有云端单次渲染费用，也不被某个视频生成 SaaS 锁死。
2. 它主要能做什么
2.1 Prompt / 文章 / GitHub 仓库转视频
html-video 支持三种输入来源：
| 输入 | 官方描述 | 售前价值 |
|---|---|---|
| Prompt | 用户描述主题，Agent 从零生成内容 | 快速做创意短片、产品概念片、社媒视频 |
| Web article | 抓取网页文章并扁平成 Markdown，README 特别提到支持微信公众号文章 | 适合把公众号、博客、新闻、白皮书转解读视频 |
| GitHub repo | 拉取仓库简介、顶层结构、README | 适合把开源项目、技术产品转讲解视频 |
这对售前非常实用。你过去已经让我做了很多“开源项目售前分析笔记”，html-video 的应用场景可以进一步变成：
- 把开源项目分析变成 60 秒解读视频。
- 把技术方案变成客户演示短片。
- 把企业报告/公众号文章变成短视频素材。
- 把产品更新日志变成社媒发布视频。
2.2 多帧故事板和 content-graph
html-video 不只是把一页 HTML 录成视频。它支持 multi-frame storyboard：
- Agent 读取来源材料。
- 提取关键点。
- 形成 content-graph：节点是实体、数据、文本；边表示顺序、依赖、对比等关系。
- content-graph 被拓扑排序成视频帧顺序和时间。
- 每一帧变成一个自包含的 animated HTML frame。
这意味着一篇长文章不是简单塞到模板里，而是可以被拆成有节奏的多场景解说。
2.3 本地真实 MP4 渲染
当前已可运行的渲染路径是：
HTML + CSS + GSAP
-> Hyperframes
-> Headless Chromium 逐帧/逐段录制
-> webm per frame
-> ffmpeg libx264 编码
-> concat 成 MP4这点有两个售前价值：
- 本地渲染：不像云端视频生成 SaaS 那样按次收费，也减少素材外传。
- 真实 MP4：最终产物是可分发的视频文件，不只是网页预览。
2.4 Studio + CLI 两种使用方式
html-video 提供：
- 本地浏览器 Studio：模板库、Agent 对话、逐帧文案编辑、配乐、导出。
- CLI：适合自动化、脚本化、检查 Agent 和模板。
常用命令：
pnpm install
pnpm -r build
node packages/cli/dist/bin.js studio
node packages/cli/dist/bin.js doctor
node packages/cli/dist/bin.js search-templates --intent "github stars race" --top 3Studio 默认地址：
http://127.0.0.1:30712.5 21 个 license-clean 模板
README 强调模板不是随便拼凑，而是由 template.html-video.yaml 描述，包含：
- category / tags / best_for。
- 支持分辨率、画幅比、fps、时长范围。
- 输入 JSON schema。
- SPDX license。
- attribution_required / redistribution_allowed / commercial_use。
- assets_attribution。
模板类型包括：
- 数据可视化：NYT-style chart、Swiss/Vignelli data cards。
- 标题和视觉特效：glitch title、kinetic type、typewriter cursor。
- 主视觉和电影感：liquid background、light leak、warm grain。
- 产品宣传：15s / 30s multi-scene product promo。
- 解说框架：decision tree explainer。
- Logo outro。
模板 NOTICE 显示：
- 多个模板来自 heygen-com/hyperframes，Apache-2.0。
- 一个 30s product promo 模板来自 nateherkai/hyperframes-student-kit，MIT，替换了品牌资产。
- 还有若干 html-video 原创 Apache-2.0 模板。
售前价值：
对企业内容生产来说，模板许可是否清楚非常重要。html-video 把模板来源、SPDX 和商业使用标记写进元数据，降低后续商用审查成本。
2.6 AI 配乐和旁白
README 提到支持 MiniMax：
- 背景音乐：用文字描述 mood，生成 instrumental track。
- 旁白：输入脚本，MiniMax TTS 朗读。
- 导出时通过 ffmpeg 混入 MP4，音乐可 duck under voice，并支持淡入淡出。
售前要注意：这部分需要 MiniMax API key，是可选能力。没有 key 时，Studio 其他功能不受影响。
2.7 支持 14 类 Agent 后端
README 列出的 Agent 包括：
- 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 中自动探测已安装 Agent，并可在 Studio 顶栏切换。若本机没有 CLI，也可用 Anthropic API BYOK。
3. 当前可用能力和路线图区分
这是售前必须讲清楚的部分。
| 能力 | 状态 | 说明 |
|---|---|---|
| Engine adapter spec | 已完成 | 一个接口，未来可接多个后端 |
| Template metadata | 已完成 | license-first、agent-readable |
| Content-graph 多帧故事板 | 已完成 | 文章/repo 到多场景视频的中间表示 |
| Studio | 已完成 | 模板库、Agent 切换、逐帧编辑 |
| Source fetch | 已完成 | 文章/GitHub repo 转素材 |
| AI soundtrack | 已完成 | MiniMax 音乐 + 旁白 |
| Real MP4 render | 已完成 | Hyperframes + Chromium + ffmpeg |
| Open Design Vela 后端 | 已完成 | 模型选择和 catalog |
| Remotion adapter | 计划中 | README 明确未完成 |
| Motion Canvas / Revideo adapter | 计划中 | README 明确未完成 |
| Manim | 调研中 | 数学/3D 方向，尚未适配 |
| Agent skill packages | 计划中 | 尚未完成 |
| Template marketplace | 计划中 | 尚未完成 |
售前表达建议：
当前可以把它当作 Hyperframes 驱动的本地 HTML-to-MP4 视频生成 Studio 使用；可插拔引擎架构已经设计好，但多引擎适配还不能作为当下交付承诺。
4. 适用场景
4.1 技术内容转短视频
非��适合：
- GitHub 开源项目解读视频。
- 技术博客解读。
- 产品更新说明。
- API/SDK 使用教程。
- 技术方案亮点短片。
你当前的 Obsidian 开源项目笔记就可以形成一条内容生产链：
GitHub 项目 -> 售前分析笔记 -> html-video -> 技术解读短视频 -> 客户沟通/社媒发布4.2 企业市场部内容自动化
适合：
- 产品发布短视频。
- 数据报告动态图。
- 品牌片头/片尾。
- 社媒竖版短视频。
- 活动预热视频。
- 客户案例解读视频。
优势：
- 模板统一风格。
- 本地批量生成。
- 可修改 HTML/CSS/模板。
- 无单次渲染费用。
4.3 数据报告和可视化视频
模板包含 NYT-style data chart、Swiss/Vignelli 数据卡等，适合：
- 周报/月报亮点。
- 销售数据变化。
- 行业趋势解读。
- 投融资/市场规模图表。
售前话术：
客户很多报告沉在 PPT 和 PDF 里，html-video 可以把关键数据变成动态短视频，用于内部汇报、销售赋能或社媒传播。
4.4 企业内部知识传播
适合：
- 把制度公告转成视频。
- 把培训材料转成短视频。
- 把项目周报转成动态摘要。
- 把研发变更日志转成面向业务的解释视频。
优势不是“电影级视频”，而是低成本、高频、可模板化的视频生产。
4.5 Agent 视频生产工作台
对正在做 Agent 平台的客户，html-video 可以作为一个“内容生产 Agent 工具”：
- Agent 读取素材。
- Agent 选择模板。
- Agent 生成帧内容。
- 用户在 Studio 中调整。
- 本地渲染导出。
这比纯文本 Agent 更容易形成可交付成果。
5. 不太适合的场景
| 不适合场景 | 原因 | 建议 |
|---|---|---|
| 电影级实拍/真人视频生成 | html-video 主要是 HTML/CSS/模板化动效，不是扩散视频模型 | 用 Runway、可灵、Pika、Sora 类视频模型 |
| 复杂时间线专业剪辑 | 不是 Premiere/DaVinci 替代品 | 生成素材后交给专业剪辑工具 |
| 高度写实 3D / 数学动画 | Manim/3D 仍是调研方向 | 直接使用 Manim、Blender 或专门引擎 |
| 非技术用户完全零配置 | 需要 Node、pnpm、ffmpeg、Chromium、Agent 或 API key | 需要产品化封装或集成服务 |
| 对 Remotion/Motion Canvas 有强需求 | 适配器还在路线图 | 不应承诺已支持 |
6. 架构理解
6.1 官方管线整理
URL/repo -> Markdown"] Fetch --> Agent["Agent Loop
读取素材 + 模板风格"] Agent --> Graph["Content Graph
nodes + edges + timing"] Graph --> HTML["Per-frame HTML
self-contained animated frames"] HTML --> Render["Hyperframes Render
Headless Chromium -> WebM"] Render --> FFmpeg["ffmpeg
libx264 concat + audio mux"] FFmpeg --> MP4["Final MP4"] Templates["21 License-clean Templates"] --> Agent Templates --> HTML Audio["MiniMax Music / TTS"] --> FFmpeg
6.2 Monorepo 模块
| 模块 | 作用 |
|---|---|
packages/core | Project / Asset / ContentGraph 类型，registry，orchestrator，MiniMax provider，ffmpeg audio mux |
packages/content-graph | 多帧故事板 IR，节点、边、拓扑排序 |
packages/runtime | Agent runtime，探测、启动、流式通信 |
packages/adapter-hyperframes | Hyperframes 引擎适配器，Chromium + ffmpeg 渲染 |
packages/cli | html-video 命令、Studio HTTP server、source fetching |
packages/project-studio | 浏览器 Studio UI |
templates | 21 个许可清晰的视频模板 |
research | RFC：engine adapter、template metadata、agent skill、content-graph |
7. 怎么用
7.1 前置条件
| 依赖 | 最低版本 |
|---|---|
| Node.js | 20+ |
| pnpm | 9+ |
| ffmpeg | 较新版本即可 |
| Chromium / Playwright browser | 用于 Headless Chromium 渲染 |
安装 Chromium：
npx playwright install chromium7.2 启动 Studio
pnpm install
pnpm -r build
node packages/cli/dist/bin.js studio打开：
http://127.0.0.1:30717.3 CLI 工具
node packages/cli/dist/bin.js doctor
node packages/cli/dist/bin.js search-templates --intent "github stars race" --top 37.4 推荐演示流程
- 启动 Studio。
- 输入一个 GitHub 仓库链接。
- 让 Agent 生成 5-8 帧解读视频。
- 选择数据可视化或 explainer 模板。
- 逐帧修改标题和文案。
- 可选添加 MiniMax 旁白。
- 导出 MP4。
8. 售前可以怎么讲
8.1 面向市场/内容团队
html-video 可以把文章、报告、产品卖点和开源项目自动变成短视频。它不是替代专业剪辑，而是解决高频、模板化、数据化内容的视频化问题，让团队用更低成本生产更多可传播素材。
8.2 面向技术团队
它用 HTML/CSS/GSAP 表达画面，用 Headless Chromium 和 ffmpeg 本地渲染 MP4。模板有 JSON schema 和 license 元数据，Agent 能理解模板输入，生成逐帧 HTML。整体可扩展、可改模板、可接本地 Agent。
8.3 面向管理层
这是一个开源、本地运行、无单片渲染费用的视频生产工具。适合作为企业内容自动化的 PoC：先选固定模板和固定内容来源，把一类文档或文章稳定转成短视频，再考虑产品化集成。
9. 常见客户问题
| 客户问题 | 回答建议 |
|---|---|
| 它是 AI 视频生成模型吗？ | 不是扩散视频模型。它是 Agent + HTML/CSS 动效 + 本地渲染工作流，更适合信息型、数据型、模板化视频。 |
| 现在支持哪些渲染引擎？ | 当前已完整可用的是 Hyperframes。Remotion、Motion Canvas、Revideo、Manim 在路线图或调研中。 |
| 能不能商用模板？ | README 和 NOTICE 强调模板 license-clean；许多模板来自 Apache-2.0 / MIT 来源，元数据记录 SPDX 和商业使用标志。具体商用仍建议按企业流程复核。 |
| 是否需要联网？ | 本地渲染不需要云端渲染；但抓取文章/repo、调用 Agent API、MiniMax 配乐/旁白会产生网络请求。 |
| 能不能做中文视频？ | README 中文示例包含微信公众号文章解读；文案生成取决于所选 Agent/模型，模板本身是 HTML，可承载中文。 |
| 能否批量生成？ | 有 CLI 和本地架构，理论上适合自动化；但生产级批量要补任务队列、失败重试、模板管理和素材审核。 |
| 可以接我们自己的品牌模板吗？ | 可以。模板是自包含 HTML + YAML manifest，适合做企业品牌模板库。 |
10. PoC 建议
10.1 PoC 选题
建议选一个明确内容类型：
- 一篇企业公众号文章转 60 秒解读视频。
- 一个 GitHub 项目转 90 秒技术介绍视频。
- 一份月报数据转 30 秒动态图表视频。
- 一个产品功能更新转社媒短视频。
10.2 验收指标
| 指标 | 说明 |
|---|---|
| 内容准确性 | 视频文案是否忠于原文/仓库 README |
| 生成耗时 | 从输入链接到导出 MP4 的时间 |
| 人工修改量 | 逐帧需要改多少文字和排版 |
| 视觉一致性 | 是否符合企业品牌和模板风格 |
| 渲染稳定性 | Chromium/ffmpeg 是否稳定导出 |
| 成片质量 | 分辨率、fps、字幕、音轨、转场是否可用 |
| 模板复用性 | 同一模板能否套不同内容 |
| 合规性 | 文章、图片、音乐、字体、模板许可是否清楚 |
10.3 售前演示脚本
- 准备一个客户行业相关 URL。
- 打开 Studio，粘贴链接。
- 让 Agent 生成多帧 storyboard。
- 选择一个 explainer 或 data-viz 模板。
- 在 Studio 中修改 2-3 帧文字。
- 可选生成旁白。
- 导出 MP4。
- 解释本地渲染、模板许可、后续品牌模板定制路径。
11. 风险和注意事项
11.1 产品成熟度
html-video 还处在较早期阶段。虽然 README 显示核心路线已经跑通，但未来引擎、skill packages、模板市场仍在路线图中。
售前不要把它包装成成熟商业视频平台，而应定位为：
可 PoC、可二次开发、适合内部内容自动化探索的开源本地视频生成底座。
11.2 Agent 输出质量不稳定
视频内容由 Agent 生成，质量依赖：
- 输入材料质量。
- 模型能力。
- 模板约束。
- prompt。
- 人工审核。
企业应用必须保留人工审核环节，尤其是市场发布和客户交付材料。
11.3 渲染环境依赖
需要 Node.js、pnpm、ffmpeg、Chromium/Playwright。客户环境如果是内网、Windows、无 GUI、无浏览器依赖，部署前要验证。
11.4 版权和素材合规
虽然模板许可清晰，但最终视频仍可能包含：
- 文章原文内容。
- GitHub README 内容。
- 客户上传图片。
- 字体。
- AI 音乐/旁白。
这些都需要按企业发布流程审核。
12. 我的售前判断
html-video 的价值在于把 Agent、模板、HTML 动效和本地渲染串成了一个可操作的视频生产工作台。
它最适合的不是“替代所有视频制作”，而是“让大量信息型内容快速视频化”：
- 技术解读。
- 数据报告。
- 产品介绍。
- 企业公告。
- 开源项目介绍。
- 社媒短视频素材。
适合推进的客户：
- 市场部需要高频短视频内容，但预算和人力有限。
- 技术团队想把文档/仓库/报告自动转成可传播内容。
- 企业 Agent 平台想增加“视频生成”工具能力。
- 对云端视频生成费用、素材外传、厂商锁定敏感的客户。
不建议承诺：
- 完全取代专业剪辑。
- 已支持所有主流 video-as-code 引擎。
- 自动生成无需审核的商业成片。
13. 参考资料
- GitHub 仓库：nexu-io/html-video
- 英文 README：README.md
- 中文 README：README.zh-CN.md
- 模板 NOTICE：templates/NOTICE.md
- package.json：package.json
- Hero 图：hero.png
- 模板示例：
- frame-data-chart-nyt
- frame-glitch-title
- frame-liquid-bg-hero
- frame-logo-outro
信息核查日期：2026-06-30。由于 GitHub API 匿名访问触发限流，本笔记未写入实时 stars/forks；项目能力、路线图、安装方式和模板许可主要基于官方 README、中文 README、NOTICE 和 package.json 整理。