nexu-io/html-video: an HTML to MP4 meta-layer for coding agents

The problem html-video addresses: every HTML-to-video engine wants its own authoring model

The README frames the category honestly. Hyperframes wants HTML plus CSS plus GSAP driven by an agent skill. Remotion wants React components. Motion Canvas and Revideo want TypeScript generators drawing on a canvas. Manim is math and 3D first. Each one is opinionated, and the README says picking the right engine per use case, learning each model and stitching them into one workflow costs real engineering time, so most teams pick one and live with its limits.

html-video positions itself as the meta-layer above those engines. You talk to your agent, and according to the README the agent picks the engine, picks a template, fills in your content and renders the video. The engine becomes an implementation detail behind a single adapter interface, described as one `render(input, ctx)` contract that any backend can satisfy. The audience is developers who already run a local coding agent and want a video file, not a new animation DSL. The README lists 14 supported agent backends, auto-detected on your `PATH` and switchable from the top bar.

How the render path actually works: headless Chromium, ffmpeg, and one adapter contract

The shipped pipeline is narrow and concrete. The README states that the Hyperframes engine is the default and renders real MP4 by recording the animated HTML frame-by-frame in headless Chromium, then encoding with ffmpeg using libx264. Templates are single-file animated HTML documents, and the gallery shows 21 of them, including frame-data-chart-nyt for editorial line charts, frame-glitch-title for title cards, frame-liquid-bg-hero, frame-light-leak-cinema, vfx-text-cursor and frame-logo-outro.

The architectural claim is that the engine sits behind the adapter interface, so adding a new engine would give every template, every agent and the studio workflow access to it. That claim is not yet tested in practice. The README's own status note says the pluggable-engine architecture is in place and Hyperframes is fully wired up, while Remotion, Motion Canvas / Revideo and Manim are roadmap items whose adapters are not built. The repository's package.json does list `@remotion/bundler`, `@remotion/renderer` and `remotion` as root dependencies, so Remotion code is present in the monorepo, but the README is explicit that its adapter is not runnable. Treat the engine table's "In html-video" column as the source of truth.

There is also a soundtrack path. The README advertises an optional AI soundtrack with music and narration, and one badge labels it "AI music + narration". The README excerpt does not describe which service or model produces it, so budget time to read the docs folder before you promise narration in a deliverable.

Installing html-video and rendering a first MP4

The root package.json declares the runtime requirements: Node `>=20` and pnpm `>=9`, with `packageManager` pinned to `pnpm@9.15.0`. The monorepo uses pnpm workspaces covering `packages/*` and `templates/*`. The README advertises a three-command quickstart, but the excerpt does not spell the commands out, so the steps below come from the root scripts in package.json rather than from a quickstart section.

Clone the repository and install dependencies with pnpm. The workspace layout means a single install covers the packages and the templates.

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

Build every workspace package. The root `build` script fans out with `pnpm -r build`.

pnpm build

Run the CLI smoke test. This is the closest thing the repository offers to a first real render, and it targets the CLI package directly.

pnpm --filter @html-video/cli smoke

If the smoke run succeeds, you have a working Chromium plus ffmpeg chain. If it fails, check for a headless Chromium binary and an ffmpeg build with libx264 before touching the templates. The README does not document a rollback path or a way to pin a specific Chromium build, so treat the first successful smoke run as your baseline and record the versions you used.

Where html-video is the wrong tool

The engine gap is the first limitation. If your team has already invested in Remotion compositions, html-video cannot render them today: the README states the Remotion adapter is planned and not built. You would be adopting a wrapper whose advertised value (engine choice) is not yet available, and paying the cost of learning the Hyperframes authoring model anyway.

Second, the project assumes a local coding agent. The README's whole interaction model is "you talk to your agent". If you want a deterministic CI job that renders a fixed template from a fixed data file with no agent in the loop, the README does not describe that path, and nothing in the excerpt suggests a headless batch mode. For scheduled, unattended rendering you would be building that layer yourself.

Third, the render stack is heavy by nature. Headless Chromium plus ffmpeg is a large dependency footprint for a build agent, and the README does not document container images, resource limits or memory requirements. On a constrained CI runner, frame-by-frame capture is the part most likely to fail, and the README does not describe partial-render recovery or resume. Finally, the README does not document rollback, version pinning for templates, or how a template update interacts with an in-flight render.

Hyperframes versus Remotion: two different answers to the same question

The README's comparison table is the most useful part of the document because it states the tradeoff for each engine. Hyperframes is HTML plus CSS plus GSAP, agent-skill driven, with a single rendering paradigm. Remotion is React components, and the README flags it as source-available with paid licensing above four developers. That licence difference matters more than the API difference for a small team: with Remotion you write compositions as React components and get a mature React ecosystem, but you inherit a commercial threshold. With Hyperframes you keep plain HTML and CSS, which is easier for an agent to generate and edit, and you stay inside Apache-2.0 for the html-video layer itself.

Motion Canvas and Revideo take a third route, TypeScript generators drawing on a canvas, which the README calls best for explainers and code-first work. Manim is math and 3D first and the README calls it niche. The practical difference for an adopter is where your content lives. If your content is already structured data bound to HTML, Hyperframes is the shorter path. If your content is already React, Remotion fits better, but html-video will not render it yet.

Maintenance status, licence and upgrade cost

The repository is not archived, and the last push was on 2026-06-21. That is roughly three months before today, so the project is within the six-month window, but the README does not publish a release cadence and no releases were retrieved. There is no changelog in the top-level entries, so upgrade cost is hard to estimate from the repository alone. The files you would read to judge it are `CONTRIBUTING.md`, `CLAUDE.md` and the `notes/` and `research/` directories, none of which the README summarises.

The licence is Apache-2.0, declared both in the README badge and in the root package.json `license` field. For the html-video layer that means permissive use with a patent grant and no per-render fee, which is the README's explicit selling point. Two caveats follow from the comparison table rather than from legal analysis. Remotion is described as source-available with paid licensing above four developers, so if a future Remotion adapter ships, the licence of the engine you select still governs your use. And the render chain pulls in Chromium and ffmpeg, whose own licences and build flags you should confirm for your distribution model. The repository carries an `ATTRIBUTIONS.md` file, which is where third-party notices appear to be collected.

What to check before you commit a production pipeline to it

Verify the render chain first. Run the smoke script, then render one of the 21 templates with your own data and inspect the output for frame drops and audio sync. The README does not state a maximum duration, resolution or frame rate, so establish those limits yourself before a client asks.

Verify the agent path second. The README lists 14 backends detected on your `PATH`, and auto-detection is the kind of feature that behaves differently under a different shell or a container. Confirm that your chosen agent is picked up and that switching it from the top bar does what you expect.

Verify the template contract third. Templates are described as single-file animated HTML, and the gallery shows what they look like, but the README excerpt does not document the variables an agent fills in. Read the `templates/` directory and the `docs/` folder to learn the actual substitution points. If the template contract is thin, your content pipeline will be brittle regardless of which engine renders it.

Editorial conclusion

Adopt html-video if you already drive a coding agent from the terminal and want MP4 output without per-render fees, and accept that only the Hyperframes engine renders today. Skip it if you need a stable engine-selection API or a documented upgrade path; the README does not cover either. Before committing, run `pnpm --filter @html-video/cli smoke` on your machine and confirm that headless Chromium plus ffmpeg with libx264 actually produce a playable file on your OS.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. nexu-io/html-video on GitHub
4. Project website
5. README