Vistaro

vistaro.dev: the website, with the demos and a live tour of every animation.

A command-line tool for the AI coding agents that run on your machine: Claude Code, Codex, Antigravity. Ask your agent for a demo video, a help article or a marketing clip of your web app. The agent writes two text files, a mockup of the screen and a timeline of what happens on it, and the CLI turns them into the video and the guide. When the interface changes, you run it again. Agents: start with AGENTS.md, the manual with every file format.

Under the hood, the CLI drives a headless browser through the timeline. It moves a cursor, clicks, types and zooms, and records what it sees. You get an MP4 with subtitles and chapters, a numbered guide with a screenshot for every step, and the same again in each language you add. None of this needs an API key.

In: the two files of the sample in demo/. index.html is the screen and vistaro.config.json is the timeline.

Out: a 21-second MP4 with subtitles and chapters (watch it on vistaro.dev),

and a guide with one numbered frame per step, cropped to whatever the reader has to click:

Both come out of one command: npx vistaro export demo -o demo.mp4 --guide (see Quick start).

Because the recording is out of date the day the product changes. Then you record it again by hand, in one language, and nobody can review what changed. Here a demo is two text files in your repository, so:

• The UI moved? Run the command again. build-all --changed-only rebuilds only what changed and tells you which guides' screenshots drifted.
• The video and the written guide come from the same timeline, so they can't disagree.
• A new language is a translated strings file. The clicks, timings and camera moves are shared.
• The timeline is JSON, so it goes through a pull request like any other change, and the whole pipeline runs headless in CI.
• Marketing clips work the same way. A homepage animation is a timeline that gets reviewed and regenerated, not a video file someone re-cuts by hand. It usually gets its own mockup, since a marketing shot frames the product to make a point while a guide follows the real screens, but it uses the same tool, the same actions and the same translation path.

• Video: an MP4 (or GIF) with a moving cursor, a spotlight and a click ripple on every interaction, plus typing, camera pushes and screen transitions. Subtitles are drawn on the frame at about 4% of its height and move out of the way of the cursor and whatever is highlighted on their own (meta.subtitleScale resizes them, a step's subtitlePlace pins one). You also get a .vtt file, MP4 chapters per step and, optionally, narration (OpenAI TTS or macOS say).
• Step guide: guide.json, guide.md and guide.html, with a numbered frame and a crop per step, the video inline, and the measured timings.
• Languages: localize scaffolds locales/<code>/ with a strings.<code>.json. Only the text changes between languages.
• Batch builds: help.catalog.json plus build-all builds every guide in every language into one output tree with an index.json, skipping what hasn't changed and flagging guides whose frames drifted.
• Live pages: record drives your real app from the same timeline, with real navigation, waits for async loads, and a saved login.
• Marketing reels: set "kind": "reel" in the timeline. The spotlight, ripple and subtitles switch off, the clip is silent, and export gives you an MP4, a WebM, a poster and a GIF. If you turn subtitles back on ("reel": { "subtitles": true }), they render as a solid caption bar that stays readable in a muted autoplay clip. build --embed writes a self-contained embed-<device>.html that starts playing when scrolled into view and loops, plus the snippet for the page that hosts it. One responsive mockup covers desktop and phone, with per-device overrides in the timeline.

A step in the generated guide.md looks like this:

## 2. Check what is left

![Step 2](assets/step-02.crop.png)

> Two of five sections are drafted.

In your project:

npm install --save-dev vistaro
npx playwright install chromium      # one time: the browser Vistaro records with
npx vistaro --help

Or once for the whole machine with npm install -g vistaro (then vistaro --help), or without installing anything with npx vistaro@latest <command>. Run the Chromium line in every case: npm 12 and pnpm skip install scripts by default, so the download usually does not happen on its own. If it is missing, the CLI stops and prints the command to run. The same npm skips ffmpeg's download too; the first export fetches it on its own before recording.

Node >= 20.6, macOS or Linux (Windows is untested). The manual is installed with the package at node_modules/vistaro/AGENTS.md. Optional keys in .env or the environment: OPENAI_API_KEY (narration; falls back to macOS say), GEMINI_API_KEY / ANTHROPIC_API_KEY (only for the standalone extract and animate commands).

Open your project in Claude Code, Codex or Antigravity and paste this. The agent installs Vistaro if needed and learns the rest from its manual:

Install vistaro as a dev dependency (npm install --save-dev vistaro, then npx playwright install chromium), read node_modules/vistaro/AGENTS.md, and create a product demo of the main screen of the app. Explore what vistaro offers and use the appropriate animations and transitions. Display a cursor as needed.

It writes the screen and the timeline, checks them, looks at the frames, fixes what is off, and renders the video and the guide. Review the result like any other change.

From source, to contribute or to run unreleased code:

git clone https://github.com/clarido/Vistaro.git
cd Vistaro
npm install
npx playwright install chromium

In a clone, every npx vistaro in this README is npx tsx cli.ts (the generated CLI reference and the CLI's own hints print the npm form).

3.0 renamed everything to vistaro, with no fallback. In each demo directory, and in anything that embeds Vistaro output:

A directory that still has only anim.config.json stops with an error naming both files. Rebuild the embeds and tours you host (build --embed, tour --embed) and replace the snippets you pasted, since their element and message names changed.

Run the sample in demo/. It lives in the repository, not in the npm package: copy its index.html and vistaro.config.json into a demo folder in your project, or run these from a clone.

npx vistaro check demo                # schema, timing, and every target in a headless browser
npx vistaro build demo                # demo/animated.html: a self-playing page to open in a browser
npx vistaro preview demo              # demo/preview.png: one labelled frame per step
npx vistaro export demo -o demo.mp4 --guide

export writes demo.mp4, demo.vtt, the chapters and demo/guide/ (guide.json, guide.md, guide.html, assets/step-NN.png). The video is as long as the timeline. Add --narration for a spoken track (OPENAI_API_KEY, or macOS say). animated.html is a generated file, so run build again after you edit index.html. export doesn't use it: it records index.html directly, which keeps the video identical to what check and preview saw.

For your own screen, put its index.html in a new folder, run npx vistaro init-config <folder> to scaffold a timeline next to it, then run the same commands on that folder.

A timeline is a list of timed interactions on CSS selectors:

{
  "meta": { "title": "Create your first report", "cursor": "mac" },
  "steps": [
    { "id": "intro", "time": "0s", "action": "fadeIn", "target": "body", "title": "Overview", "subtitle": "Welcome to the dashboard." },
    { "id": "open",  "time": "2s", "action": "click", "target": ".btn-primary", "title": "Open the report builder", "narration": "Click the primary button." },
    { "id": "zoom",  "time": "4s", "action": "camera", "target": ".btn-primary", "scale": 1.3, "duration": 2 }
  ]
}

Paste your screenshots into the agent's chat and ask for the demo:

"Here are the three screens of our onboarding. Recreate them, write a timeline that walks through signing up, and export the video with a guide, in English and French."

The agent writes index.html and vistaro.config.json, runs check, build and preview, looks at the preview PNG and fixes the timeline, exports with --guide, then runs localize and exports each language.

An agent can't watch a video, so everything about motion is also reported as text. check describes where each camera step lands: the visible window, what's in frame and what the frame edge cuts off. A zoom aimed at the wrong element shows up as a finding the agent can read and fix. preview --motion puts frames from a real playback on one sheet, check --trace logs where the cursor, spotlight, subtitle and camera were at every step, and filmstrip turns the exported MP4 into a labelled grid of frames, with an optional JSON report of what moved and when. The full workflow and every file format are in AGENTS.md.

npx vistaro localize ./demo fr        # ./demo/locales/fr/ + strings.fr.json, pre-filled
# translate strings.fr.json and the visible text of locales/fr/index.html
npx vistaro export ./demo/locales/fr -o demo-fr.mp4 --guide

npx vistaro build-all                 # every guide x locale of help.catalog.json -> help-out/
npx vistaro build-all --changed-only --diff
npx vistaro build-all --help          # catalog schema

npx playwright codegen --save-storage auth.json https://app.local/login   # sign in once
npx vistaro record ./guides/save --url https://app.local/save --storage-state auth.json -o save.mp4 --guide

npx vistaro extract screenshot.png ./demo --provider gemini      # screenshot -> index.html
npx vistaro animate ./demo "Fade in, then click the primary button" --provider claude
npx vistaro export ./demo -o demo.mp4

Node.js + TypeScript through tsx (no build step), commander, Playwright Chromium, ffmpeg-static (libx264 crf 18, VP9 for WebM), pixelmatch for the staleness diff. Desktop exports record at 1920x1080, mobile at 390x844; --width/--height override.

The video is exactly as many pixels as the CSS viewport. Playwright's screencast paints one CSS pixel per video pixel and ignores deviceScaleFactor, so the only way to get more pixels is a bigger viewport. --scale N multiplies the viewport and zooms the page back with :root { zoom: N }: at --scale 2 a phone clip is 780x1688 while its layout is still 390x844. Guide screenshots aren't affected and stay at 2x.

Contributing: npm test runs the suite (serial, with browser tests; SKIP_BROWSER=1 to skip them); npm run docs regenerates the CLI reference below from cli.ts, and npm run docs:check fails when it is stale.

Generated from cli.ts by npm run docs; do not edit by hand. npx vistaro <command> --help prints the same, plus the usage guide (--help) and the catalog schema (build-all --help).

init-config · extract · animate · build · check · preview · export · record · guide · filmstrip · verify · studio · demos · build-all · tour · localize

npx vistaro init-config <output_dir> [options]

Scaffold an vistaro.config.json timeline file in the target directory

npx vistaro extract <image_path> <output_dir> [options]

Extract an HTML/CSS essence from a screenshot (needs an LLM API key)

npx vistaro animate <output_dir> <prompt> [options]

Write vistaro.config.json + animated.html from a prompt (needs an LLM API key; agents write the timeline themselves and run build)

npx vistaro build <output_dir> [options]

Build animated.html from index.html + vistaro.config.json (no LLM, no API key)

npx vistaro check <output_dir> [options]

Validate vistaro.config.json: schema, timing, strings, and (unless --static/--live) every target selector in a headless browser; each camera step also reports its framing as facts (window, what is in frame, what is cut)

npx vistaro preview <output_dir> [options]

Render one labelled frame per step to <output_dir>/preview.png (or a single full-size frame with --step N)

npx vistaro export <output_dir> [options]

Record the timeline to an MP4/GIF (plus .vtt subtitles, chapters, optional narration and step guide); the length comes from the timeline

npx vistaro record <output_dir> [options]

Record the timeline against a live page (URL) instead of a local mockup: real navigations, waitFor, storage state

npx vistaro guide <output_dir> [options]

Write a Scribe-style step guide (guide.json, guide.md, guide.html + assets/) from index.html + vistaro.config.json; links the last exported video when present

npx vistaro filmstrip <video> [options]

Turn an exported video into one labelled contact strip (and optional --diff motion facts): review the clip without watching it

npx vistaro verify <output_dir> [options]

Build and audit a demo in one command: run the export pipeline (verify.mp4 + verify.vtt beside it), then the filmstrip pass (verify.strip.png), and write verify.json (ok, durationMs, steps, chapters, issues); exit 1 when any step failed

npx vistaro studio [output_dir] [options]

Open a local web editor over the timeline: with no directory it serves the project picker (every demo in the workspace, recents first); with one it opens that screen directly. Edit steps with a seekable live preview, pick targets by clicking, apply effect presets, retime steps by dragging them on the timeline ruler, run check/export, and save vistaro.config.json (the editor is a view over the file, never a second source of truth). Running the CLI with no command at all boots the same server on the hub page (/hub: the ask for your agent, the manual at /agents.md) and opens your browser

npx vistaro demos [options]

List every demo project in the workspace (screens, scenario stories, catalog entries), newest first, with the studio command that opens each -- the terminal twin of the picker

npx vistaro build-all [catalog] [options]

Build every guide x locale of help.catalog.json (check, build, export|record --guide) into /// and merge index.json + index.md; exit 1 on any failure

npx vistaro tour [catalog] [options]

Build an interactive tour site from tour.catalog.json: a scenario rail plus a canvas that plays any scenario step by step (no capture, no encoding)

npx vistaro localize <source_dir> <locale> [options]

Scaffold <source_dir>/locales// with index.html, vistaro.config.json, media and a pre-filled strings..json; the choreography is reused as is