@vosso/voila-cli

The Voila product-video pipeline as a CLI — record a scripted browser flow into a take, plan zoom/cursor effects with the same planner the Voila studio uses, and render a polished video headlessly. Designed to be driven by AI agents (Claude Code, Codex) as well as humans; invoked as vos voila … when @vosjs/cli is installed, or directly as voila-cli.

vos voila record --actions actions.json --out take   # drive the page, synthesize the cursor track, encode + plan
# … edit take/doc.json (zoom spans, trims, speed, styling) — or let your agent …
vos voila render take out.webm                       # deterministic polished render

The take directory

take/
  recording.webm   encoded footage (CFR WebM)
  frames/          raw screencast JPEGs (kept for re-encode)
  cursor.json      synthesized CursorTrack (exact coords, element rects)
  meta.json        RecordingMeta (producer: "cli")
  actions.json     the script that produced it — the replay recipe
  doc.json         ProjectDoc — the agent-editable surface

doc.json is the product's superpower: zoom/pan is zoom: [{in, out, level, cx, cy, source}], trims are segments, pacing is speed — all plain JSON. Edit and re-render; nothing re-runs the browser. plan honors the wand contract: source:"manual" spans are preserved, only source:"auto" suggestions regenerate.

Actions

{
  "url": "https://your-app.example",
  "viewport": { "width": 1280, "height": 720 },
  "steps": [
    { "do": "wait", "ms": 700 },
    { "do": "hover", "selector": "a[href='/pricing']", "ms": 700 },
    { "do": "click", "selector": "#signup" },
    { "do": "type", "selector": "input[name=email]", "text": "[email protected]" },
    { "do": "scroll", "dy": 400 },
    { "do": "move", "x": 640, "y": 320 }
  ]
}

Verbs: wait · hover · click · type · scroll · move. Because the CLI issues every input itself, the cursor track is synthesized — exact coordinates, exact timing, fresh element rects — which is what powers element-aware auto-zoom and click effects downstream. vos voila validate checks a script (or a take) without running anything.

For scripts and agents

Logs on stderr, results on stdout; --json = NDJSON events ending with {"event":"done",…}; exit codes 0/1/2/3 (3 = no browser). Requires a Chromium-family browser (system Chrome is used automatically; npx playwright install chromium or VOS_BROWSER_PATH otherwise) and network access (render pages load three/mediabunny from the CDN).