html-video

# html-video **HTML becomes video — on your laptop.** html-video is a programmatic video tool that lets coding agents (Open Design, Windsurf CLI, Trae CLI, Claude Code, Cursor, Codex, Gemini, Grok, Qwen, OpenCode, Copilot, Aider, Hermes, or the Anthropic API) turn HTML, CSS, and data into real MP4 files. Describe a video, paste an article link, or a GitHub repo, and the agent generates a multi-frame animated video, rendered locally with pluggable engines. Apache-2.0 licensed, no per-render fees, no vendor lock-in. ## Key Features - **14 Agent Backends**: Auto-detects and supports 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, and Anthropic Messages API. - **21 Curated Templates**: License-clean, animated HTML templates covering data viz (NYT-style charts, Swiss/Vignelli grids), titles & VFX (glitch, kinetic type, typewriter cursor), heroes & cinematics (liquid gradients, light-leak, warm grain), product promos (15s/30s multi-scene), and explainer scaffolds (decision trees). - **Real MP4 Rendering**: Headless Chromium records animated HTML, ffmpeg (libx264) encodes to MP4 locally — no cloud render, no per-clip fee. - **Link-to-Video**: Fetches web articles (including WeChat 公众号) or GitHub repos server-side, flattens to Markdown, and feeds real content into the generation prompt. - **AI Soundtrack**: Optional background music and narration via MiniMax, mixed into the MP4 at export (music ducked under voice, fade-in/out). - **Studio + CLI**: A local browser studio (chat, template gallery, frames, soundtrack, export) and a scriptable `html-video` CLI. - **Pluggable Engine Architecture**: One `render(input, ctx)` adapter interface; swapping engines (e.g., Remotion, Motion Canvas) replaces only the render step, leaving storyboard and agent loop untouched. - **License-Clean by Construction**: Templates carry original licenses, with a `NOTICE.md` recording sources and SPDX; no unclear permissive licenses ship. ## How It Works 1. **Source Fetch**: Studio pulls URL or repo server-side, flattens to Markdown. 2. **Agent Loop**: Agent reads material + template style, emits a content-graph (storyboard) + one HTML block per frame. 3. **Content-Graph**: Multi-frame IR with nodes (entity/data/text) and edges (sequence/transition). 4. **Per-Frame HTML**: Each node becomes a self-contained animated HTML frame on disk. 5. **Render**: Each frame → webm (via headless Chromium), then ffmpeg encodes to MP4 (libx264) and concatenates. 6. **Soundtrack**: Optional MiniMax music + narration mixed in via ffmpeg. Single-frame videos take a fast path skipping the content-graph. ## Getting Started Requires Node.js 20+ and ffmpeg. Install Playwright's Chromium if not present. Build with `pnpm -r build`. CLI utilities: - `node packages/cli/dist/bin.js doctor` — detect installed agents + engines - `node packages/cli/dist/bin.js search-templates --intent "github stars race" --top 3` In the studio: pick a template (or describe a video / paste a link), chat with your agent, edit per-frame text, add a soundtrack, and export MP4. ## Project Structure - `runtime/` — Agent runtime (detect/spawn/stream) for all 14 backends - `cli/` — `html-video` command, studio HTTP server, source fetching - `project-studio/` — Browser studio UI (chat, template gallery, frames, soundtrack, export) - `templates/` — 21 curated, license-clean video templates ## Related Projects - [Open Design](https://github.com/nexu-io/open-design) — Sister project, design-agent meta-layer - [HTML Anything](https://github.com/nexu-io/html-anything) — Sister project for static HTML deliverables ## License Apache-2.0 — no per-render fees, no seat caps, no contributor agreements. An official project by the Open Design team (nexu-io).