@openvideo/cli (openvideo)

The command-line interface for OpenVideo.
Render hardware-accelerated MP4 videos, snapshot still frames for AI visual inspection, validate frame determinism in milliseconds, and launch the live interactive Studio.

⚡ Installation

Install as a project dependency:

# Using pnpm
pnpm add -D @openvideo/cli

# Using npm
npm install --save-dev @openvideo/cli

# Using yarn / bun
yarn add -D @openvideo/cli
bun add -d @openvideo/cli

Or run directly via npx / pnpx:

pnpm exec openvideo --help
npx @openvideo/cli --help

🚀 Commands Overview

| Command | Alias | Description | | :--- | :--- | :--- | | openvideo export <file> | render | Headless bit-exact MP4 video export with multi-track audio. | | openvideo still <file> | snapshot | Capture a single frame at time $t$ to PNG/JPEG for visual inspection. | | openvideo check [path] | validate | Static determinism linter + frame-stepping validator in milliseconds. | | openvideo list [path] | compositions | Discover and display composition metadata and props schema. | | openvideo dev [dir] | studio, preview | Start the live interactive Studio development server with HMR. | | openvideo mcp | — | Run the Model Context Protocol (MCP) server for AI agents. |

🎬 1. Headless Video Export (openvideo export)

Renders any TypeScript defineVideo composition directly into a high-bitrate MP4 file using headless Chromium and WebCodecs hardware acceleration:

# Render to default <name>.mp4
openvideo export ./src/projects/my-intro.video.ts

# Specify output destination
openvideo export ./src/projects/my-intro.video.ts -o ./dist/intro.mp4

# Override FPS and bitrate
openvideo export ./src/projects/my-intro.video.ts --fps 60 --bitrate 12000000

# Pass custom props
openvideo export ./src/projects/my-intro.video.ts --props '{"title": "Custom Launch", "accent": "#ff007f"}'

# Machine-readable output for AI agents and CI
openvideo export ./src/projects/my-intro.video.ts --json

Options:

• -o, --output <path>: Destination path for the .mp4 file.
• --fps <number>: Frame rate override (defaults to composition FPS).
• --bitrate <number>: Video bitrate in bps (defaults to 8000000 / 8 Mbps).
• --props <json|file>: Custom props as a JSON string or path to a .json file.
• --no-headless: Run Chromium in headed mode for debugging.
• --json: Emit a structured JSON summary on completion.
• -q, --quiet: Suppress terminal progress bar.

📸 2. Single-Frame Snapshot (openvideo still)

Captures a high-resolution still frame at a specific timestamp or frame count:

# Snapshot at 1.5 seconds
openvideo still ./src/projects/my-intro.video.ts --time 1.5s -o preview.png

# Snapshot at frame 45
openvideo still ./src/projects/my-intro.video.ts --frame 45 -o frame45.png

# Output as JPEG or WebP
openvideo still ./src/projects/my-intro.video.ts --time 2s --format jpeg -o frame.jpg

# Structured JSON response for AI agents
openvideo still ./src/projects/my-intro.video.ts --time 2s --json

🤖 The AI Feedback Loop:

Multimodal AI agents (Claude Code, opencode, ChatGPT Codex) cannot watch full MP4 videos in a terminal. With openvideo still, agents can:

1. Render a still frame at any beat: openvideo still my-video.video.ts --time 1.2s -o preview.png
2. Read the image with their visual tool.
3. Identify layout overlaps, clipping, or contrast defects.
4. Autonomously adjust code and re-verify.

🔍 3. Headless Validator (openvideo check)

Runs discrete frame-stepping slices through Vite SSR in milliseconds without launching a full browser. Checks for NaN transforms, unhandled exceptions in setup() or onFrame(), and verifies timeline tracks:

# Validate a specific file
openvideo check ./src/projects/my-intro.video.ts

# Validate all compositions in a directory
openvideo check ./src/projects/

# Sample more timeline slices
openvideo check ./src/projects/ --samples 30

# Output structured JSON report for CI or agents
openvideo check ./src/projects/ --json

📋 4. List Compositions (openvideo list)

Discovers all video compositions, printing duration, dimensions, FPS, and configurable props schema:

openvideo list ./src/projects/

# Machine-readable output for programmatic inspection
openvideo list ./src/projects/ --json

🖥️ 5. Live Studio (openvideo dev)

Spawns the live interactive OpenVideo Studio development server with multi-track timeline, visual viewport stage, and live PropsInspector:

# Start Studio on port 5173
openvideo dev

# Custom port
openvideo dev --port 3000

🤖 6. Model Context Protocol (MCP) Server (openvideo mcp)

Run OpenVideo as an official Model Context Protocol server over standard input/output (stdio), providing native structured tool-calling for Claude Code, Cursor, Windsurf, and OpenCode:

openvideo mcp

Cursor / Claude Desktop Setup:

Add to .cursor/mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "openvideo": {
      "command": "npx",
      "args": ["@openvideo/cli", "mcp"]
    }
  }
}

Registered Tools:

1. openvideo_list_compositions(path): Discovers compositions in the workspace, their duration, dimensions, and props schema.
2. openvideo_check_composition(path, samples, props): Runs static linting and frame-stepping validation, returning structured diagnostics.
3. openvideo_render_still(path, time, output, format, props): Snapshots a frame at time $t$ to PNG for multimodal visual inspection.
4. openvideo_export_video(path, output, fps, bitrate, props): Renders a bit-exact MP4 video with multi-track audio.

📄 License

MIT © OpenVideo Contributors