HTML in · Video out

Video, for agents.

Agents write code for a living. Video was the one output they could not. vigo renders HTML scenes into deterministic video through a JSON timeline — so a video is something an agent can edit, not a binary blob.

npm i -g vigo-video
deterministic frames JSON timelines 14 MCP tools ffmpeg + Chromium MIT
vigo-ad.mp4 · 33s · 1280×720 @30fps h.264 · aac · narrated
Rendered by vigo itself

Two deliverables, produced by the tool

Both videos below were rendered with vigo render from the projects in examples/. The scenes are HTML, the narration is mixed audio, the timeline is JSON.

Product ad · 6 scenes · 33s music bed + voiceover

The pitch

Hook, reveal, pipeline, editing, MCP, outro. Every frame comes from an HTML scene in examples/ad/scenes/.

Explainer · 10 chapters · 2m51s narrated walkthrough

How it works

Ten narrated chapters: the timeline model, deterministic seeking, compositing, the edit loop, media ops, MCP, and the architecture.

Why

Built for a machine that reads JSON

Editors produce binary project files that no agent can reason about. vigo keeps the whole video as text.

01 · Timeline

Video as data

Tracks, clips, start, duration, offset. Edits are idempotent operations on one JSON file — no database, no lock-in, no re-import.

02 · Determinism

Same input, same bytes

CSS and Web Animations are paused and seeked. Time never comes from the clock, so re-rendering a scene reproduces the exact frame.

03 · Small surface

Three runtime deps

Chromium paints, ffmpeg encodes, Node orchestrates. Frames are staged in a temp folder and cleaned up. No GPU, no editor state.

04 · Agent native

MCP from the start

14 tools and a guide resource so an agent can create, edit, render and probe a video without a human in the loop.

05 · Media in

Not just HTML

Video, image and audio clips composite over the HTML layers, with per-clip offsets, fit modes, volume and fades.

06 · Round trip

Media ops included

Convert, resize, trim, concat, extract frames and pull poster frames — then feed the result straight back into the timeline.

How it works

One pass, four stages

Nothing is captured live. The timeline is evaluated frame by frame, so a 10-minute render is 24 000 exact frames.

01

Read the timeline

Tracks stack in order. For every frame, vigo resolves which clips are active.

02

Seek the scene

Chromium opens the HTML, freezes time, and seeks CSS, WAAPI and window.vigo.seek(t).

03

Capture frames

Transparent PNG or fast JPEG layers are written per frame into a temp directory.

04

Composite + encode

ffmpeg layers the frames, fits media, mixes audio and fades, and writes H.264 MP4 or VP9 WebM.

The contract

A video is a JSON timeline

Tracks composite in array order. Clips on one track cannot overlap. Timing is half-open: start ≤ t < start + duration.

track · html
hook
reveal
pipeline
edit
track · media
broll.mp4 · offset 1.0s
logo.png
track · audio
voiceover.mp3
music.mp3 · 0.7

playhead at t = 14.2s · 4 of 4 active clips resolved

vigo.json
// every frame resolves from this file
{
  "version": 1,
  "width": 1920, "height": 1080,
  "fps": 30, "duration": 10,
  "tracks": [
    { "id": "main", "type": "html", "clips": [
      { "id": "intro", "kind": "html",
        "src": "scenes/intro.html",
        "start": 0, "duration": 5 }
    ]},
    { "id": "music", "type": "audio", "clips": [
      { "id": "bed", "kind": "audio",
        "src": "music.mp3", "volume": 0.7,
        "fadeOut": 2 }
    ]}
  ]
}
Quickstart

From nothing to an MP4

Three commands and a folder of HTML. The project file stays readable the whole way.

terminal
# one scene, straight to video
$ vigo html2video scene.html -o out/scene.mp4 --duration 6

# a project with tracks and audio
$ vigo init my-video --name demo --duration 8
$ vigo add my-video/vigo.json --track main \
      --src scenes/intro.html --duration 5
$ vigo add my-video/vigo.json \
      --src music.mp3 --volume 0.6 --fade-out 2
$ vigo render my-video/vigo.json -o out/demo.mp4

# edit the timeline, not the mp4
$ vigo trim  my-video/vigo.json intro --duration 3
$ vigo split my-video/vigo.json intro --at 1.5
scenes/intro.html
<style>
  body { margin: 0; background: #05070d;
         color: #f4f7ff; }
  h1 { font-size: 6vw;
        animation: rise 1s ease both; }
  @keyframes rise { from { opacity: 0; transform: translateY(2rem); } }
</style>

<h1>HTML in. Video out.</h1>

<script>
  // JS motion must expose a seek hook
  window.vigo = {
    seek(t) { /* set state for time t */ }
  };
</script>
For agents

One MCP server, fourteen tools

The same engine the CLI uses, exposed over stdio. A guide resource carries the schema and the seek contract, so an agent never has to guess.

Tools

What the agent gets

  • Create — project, scenes, timeline
  • Edit — add, trim, split, move, remove, set
  • Render — MP4 or WebM, any size, progress
  • Inspect — project JSON, probe, thumbnails
  • Convert — media ops and ffmpeg passthrough
  • Learn — vigo://guide resource
mcp.json
{
  "mcpServers": {
    "vigo": {
      "command": "vigo",
      "args": ["mcp"]
    }
  }
}
agent loop
create → write scenes → add clips →
edit → render → probe → iterate
CLI reference

Every command speaks JSON

Add --json to any command and stdout stays machine-readable. Progress always goes to stderr.

CommandWhat it does
vigo init <dir>Create a project folder with a timeline
vigo add <project>Add html / video / image / audio clips to a track
vigo render <project>Render the timeline to MP4 or WebM
vigo html2video <file>Render a single HTML scene straight to video
vigo inspect <project>Print the timeline and a summary
vigo trim / split / move / set / rmIdempotent edits to the timeline
vigo convert / concat / frames / thumbMedia operations via ffmpeg
vigo probe <file>Duration, codecs, dimensions, size
vigo doctorCheck ffmpeg and Chromium readiness
vigo guidePrint the full contract