nexu-io / html-video

nexu-io/html-video

open_in_new前往仓库

为编程代理提供程序化视频生成——在本地将HTML、CSS和数据转换为真实MP4。支持可插拔渲染引擎、21种模板及AI配乐。Apache-2.0许可，无按次渲染费用。Open Design团队官方项目。

项目概览

项目概述

html-video 是 nexu-io 旗下 Open Design 团队发布的 Apache-2.0 开源项目，定位为“面向编码智能体的程序化视频工具”：在本地把 HTML、CSS 与数据变成真实 MP4。用户可以用自然语言描述视频、粘贴文章链接或 GitHub 仓库，由本地 coding agent 生成多帧故事板与逐帧动画 HTML，再通过可插拔渲染引擎输出 MP4。项目当前已内置 Hyperframes 引擎（无头 Chromium 录制 + ffmpeg 编码），提供 21 个模板和可选 AI 配乐/旁白，无按渲染次数收费、无供应商锁定。

核心功能

  • 编码智能体驱动：支持 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 等 14 种后端，自动检测 PATH 并可在 Studio 顶栏切换。
  • 链接/仓库转视频：粘贴网页文章（含微信公众账号文章）或 GitHub 仓库链接，服务端抓取并扁平化为 Markdown，再交给 agent 生成视频。
  • 真实 MP4 本地渲染：无头 Chromium 逐帧录制动画 HTML 为 WebM，ffmpeg 以 libx264 编码并拼接为 MP4。
  • 21 个模板：涵盖数据可视化、标题/VFX、Hero、电影感、产品宣传片、解释器等多种类型，模板带 template.html-video.yaml 清单，供 agent 自动读取输入 schema 与许可信息。
  • 多帧故事板（content-graph）：以节点+边构成内容图，拓扑排序成帧顺序与时长，支持逐帧文本编辑、重排和重新渲染。
  • AI 配乐与旁白：在 Studio 设置 MiniMax API Key 后，可生成背景音乐和 TTS 旁白，导出时用 ffmpeg 混入 MP4。
  • 本地 Studio 与 CLI：浏览器界面工作室与 html-video 命令行工具（doctor、search-templates 等）。

适用与不适用场景

适用场景：

  • 想让本地 coding agent 快速把一篇文章、一个 GitHub 仓库或一段文字描述变成解说/宣传短视频。
  • 团队需要可审计、可脚本化、license-clean 的模板与本地渲染流程，避免按渲染次数付费的云服务。
  • 需要程序化批量产出视频，并把 HTML/CSS/数据作为视频源。

不适用场景：

  • 需要精细时间轴剪辑、多轨音频处理等专业视频编辑能力——本项目不是通用 NLE（非线性编辑器）。
  • 期望立即使用 Remotion、Motion Canvas、Revideo、Manim 等其它引擎：当前只有 Hyperframes 引擎已完全可用，其余在路线图上但适配器尚未实现。
  • 无法安装或使用 Node.js 20+、pnpm 9+、ffmpeg、Chromium/Playwright 的环境（例如纯浏览器在线场景，项目是本地运行）。
  • 需要完全离线的 AI 音轨：AI 配乐/旁白依赖 MiniMax API，属于可选外部服务。

技术架构与依赖

项目是 pnpm workspace monorepo，主要目录：

  • packages/core：Project/Asset/ContentGraph 等类型、注册表、编排器、MiniMax provider、ffmpeg 音频混流。
  • packages/content-graph：多帧故事板 IR（节点+边，拓扑排序）。
  • packages/runtime：agent 运行时，检测/启动/流式输出，支持 14 种 agent 后端。
  • packages/adapter-hyperframes：Hyperframes 引擎适配器（Chromium + ffmpeg 真实渲染）。
  • packages/cli：html-video 命令、Studio HTTP 服务器、来源抓取。
  • packages/project-studio：浏览器端 Studio UI（对话、模板画廊、帧编辑、配乐、导出）。
  • templates/：21 个精选、license-clean 模板。
  • research/：RFC（引擎适配器、模板元数据、agent skill、content-graph 等）。

渲染管线：prompt/链接/仓库 → 来源抓取 → agent loop（生成 content-graph + 每帧 HTML）→ 内容图排序 → 逐帧 HTML → Hyperframes 通过无头 Chromium 录制 → ffmpeg 编码拼接 MP4。

依赖（仓库写明的 Prerequisites）：

  • Node.js 20+
  • pnpm 9+
  • ffmpeg
  • Chromium（或 npx playwright install chromium）
  • 可选：MiniMax API Key（仅涉及 AI 配乐/旁白）

安装与快速开始

前置检查：

node --version
pnpm --version
ffmpeg -version
npx playwright install chromium

克隆并安装：

git clone https://github.com/nexu-io/html-video.git
cd html-video
pnpm install
pnpm -r build

启动 Studio：

node packages/cli/dist/bin.js studio
# 打开 http://127.0.0.1:3071

CLI 工具：

node packages/cli/dist/bin.js doctor
node packages/cli/dist/bin.js search-templates --intent "github stars race" --top 3

仓库资料中未提供 npm 包名、发布渠道、Docker 镜像或云部署方式；当前安装方式以 GitHub 源码与 pnpm workspace 为准。

典型使用方法

  1. 链接转视频：在 Studio 对话中粘贴文章或仓库 URL，例如“做一个解读视频 https://mp.weixin.qq.com/s/...”，agent 会抓取内容并生成基于真实内容的多帧解说视频。
  2. 纯提示词生成：直接描述视频主题，agent 从零编写内容与故事板。
  3. 模板驱动：在 Studio 模板画廊中选一个模板（如 NYT 风格数据图、故障艺术标题、液态背景 Hero），让 agent 按模板输入 schema 填内容。
  4. 配乐与旁白：在 Settings → Audio 配置 MiniMax API Key，在 Soundtrack 面板描述背景音乐情绪或输入旁白脚本，导出时混入 MP4。
  5. CLI 检查环境：node packages/cli/dist/bin.js doctor 查看已检测到的 agent 与引擎。

配置与部署要点

  • 本地优先：所有渲染发生在自己机器上；唯一的网络调用是可选的来源抓取（如网页/仓库）和可选的 AI 音轨请求。
  • Agent 配置：agent 通过 PATH 自动检测；若本机已安装多个 CLI，可在 Studio 顶栏切换；未安装任何 CLI 时可配置 Anthropic API Key 直连 Messages API。
  • Studio 地址：默认 http://127.0.0.1:3071。
  • 音频配置：MiniMax Key 仅用于可选音乐/旁白；不配置不影响其余功能。
  • 模板扩展：新增模板需遵循 RFC-07 来源规范（仅允许 MIT、Apache-2.0、BSD、CC-BY、CC-BY-SA 等宽松许可，并记录三层 provenance），并放置 template.html-video.yaml 清单。
  • 引擎扩展：新增引擎需实现 EngineAdapter 接口（validate/render/preview 等），并遵循进程隔离、进度报告、取消清理等 RFC-01 约定；核心会自动发现 packages/ 下的适配器。
  • 仓库资料未提供官方 Docker、Kubernetes、CI/CD 或云端托管配置，相关内容需参阅社区或后续发布。

限制、风险与许可证

限制：

  • 当前可运行渲染引擎只有 Hyperframes；Remotion、Motion Canvas/Revideo、Manim 均在路线图中，适配器尚未发布。
  • 需要本地 Chromium 与 ffmpeg；首次使用需安装 Playwright Chromium。
  • HTML 模板与来源内容的许可责任由使用者承担；项目模板层面有 license gate 与 provenance 记录，但用户输入的内容仍需自行确认。
  • AI 配乐/旁白依赖 MiniMax 外部服务，可能涉及网络传输与第三方条款。
  • 仓库未提供最新的 release tag 或版本号，具体版本状态需以仓库为准。

许可证：

  • 项目整体为 Apache-2.0（见仓库 LICENSE），无按渲染收费、无席位上限、无需 CLA。
  • 仓库资料声明模板逐一记录 SPDX 与归属信息，且仅纳入宽松许可来源。

官方链接

信息来源和分析时间

信息来源：GitHub 仓库元数据、README、CONTRIBUTING.md 及其中引用的 RFC 文档路径。 分析时间：仓库抓取时未标注具体时间；本摘要中的“当前”“已发布”均以抓取到的仓库快照为准。