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.
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.
Hook, reveal, pipeline, editing, MCP, outro. Every frame comes from an HTML scene in examples/ad/scenes/.
Ten narrated chapters: the timeline model, deterministic seeking, compositing, the edit loop, media ops, MCP, and the architecture.
Editors produce binary project files that no agent can reason about. vigo keeps the whole video as text.
Tracks, clips, start, duration, offset. Edits are idempotent operations on one JSON file — no database, no lock-in, no re-import.
CSS and Web Animations are paused and seeked. Time never comes from the clock, so re-rendering a scene reproduces the exact frame.
Chromium paints, ffmpeg encodes, Node orchestrates. Frames are staged in a temp folder and cleaned up. No GPU, no editor state.
14 tools and a guide resource so an agent can create, edit, render and probe a video without a human in the loop.
Video, image and audio clips composite over the HTML layers, with per-clip offsets, fit modes, volume and fades.
Convert, resize, trim, concat, extract frames and pull poster frames — then feed the result straight back into the timeline.
Nothing is captured live. The timeline is evaluated frame by frame, so a 10-minute render is 24 000 exact frames.
Tracks stack in order. For every frame, vigo resolves which clips are active.
Chromium opens the HTML, freezes time, and seeks CSS, WAAPI and window.vigo.seek(t).
Transparent PNG or fast JPEG layers are written per frame into a temp directory.
ffmpeg layers the frames, fits media, mixes audio and fades, and writes H.264 MP4 or VP9 WebM.
Tracks composite in array order. Clips on one track cannot overlap. Timing is half-open: start ≤ t < start + duration.
playhead at t = 14.2s · 4 of 4 active clips resolved
// 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 } ]} ] }
Three commands and a folder of HTML. The project file stays readable the whole way.
# 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
<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>
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.
vigo://guide resource{
"mcpServers": {
"vigo": {
"command": "vigo",
"args": ["mcp"]
}
}
}
create → write scenes → add clips → edit → render → probe → iterate
Add --json to any command and stdout stays machine-readable. Progress always goes to stderr.
| Command | What 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 / rm | Idempotent edits to the timeline |
| vigo convert / concat / frames / thumb | Media operations via ffmpeg |
| vigo probe <file> | Duration, codecs, dimensions, size |
| vigo doctor | Check ffmpeg and Chromium readiness |
| vigo guide | Print the full contract |