onda CLI

The onda CLI is the command-line adapter for the engine: it turns a scene-graph JSON document into a rendered image or video. Run it via cargo run -p onda-cli -- <args> (or the built binary target/release/onda).

onda — render a scene-graph document to an image or video

USAGE:
    onda render <scene.json> <out.png>               Render one still
    onda export <movie.json> <out.gif|.mp4>          Render a scene + timeline
    onda export-frames <frames.json> <out.gif|.mp4>  Render pre-evaluated frames
    onda scopes <frames.json> <out.json>             Colour scopes (luma/RGB, clipping)

Commands

render

onda render <scene.json> <out.png> [--backend auto|vello|cpu] [--system-fonts]

Renders a single scene graph to a PNG. Prints the dimensions and the backend used, e.g. rendered scene.json -> out.png (640x360, vello backend).

export

onda export <movie.json> <out.gif|.mp4> [--backend ...] [--system-fonts]

Renders an animated document — { "scene": ..., "timeline": ... } — to a video. The timeline’s keyframe animations target node ids; the frame count comes from the composition’s duration_in_frames, and fps from the composition. Any <svg> nodes are expanded once on the template before the timeline is evaluated.

export-frames

onda export-frames <frames.json> <out.gif|.mp4> [--backend ...] [--system-fonts]

Encodes a JSON array of scene graphs (one per frame) to a video — exactly what @onda-engine/react’s renderFramesJSON emits. fps is read from the first frame’s composition.

pnpm --filter @onda-engine/react exec tsx examples/animated.tsx frames.json
cargo run -p onda-cli -- export-frames frames.json out.mp4

scopes

onda scopes <frames.json> <out.json> [--frame N] [--backend ...]

Renders frame N (default 0) and writes colour scopes as JSON — a deterministic, no-vision-model read of the image: Rec.709 luma + per-channel R/G/B histograms (256 bins), a per-column luma waveform, channel means, luma min/max, and the fraction of pixels crushed to black (clippedLowFrac) or blown to white (clippedHighFrac). Transparent pixels are excluded. Pure measurement (like lint) — for judging exposure, contrast, and colour balance objectively (e.g. before grading a footage shot or an AI-generated plate). Works on a whole comp, or on any image/clip wrapped in a one-node scene.

Real footage (video clips)

<Video> / VideoClip sources are decoded with ffmpeg as a per-frame pre-pass; the renderer then draws each frame like an image. This decode is on by default (build --no-default-features for a leaner binary without it). Combined with per-clip trim (startFrom/endAt), retime (playbackRate), and timeline placement, this is the engine’s NLE / video-editing path — cut, trim, and speed real clips alongside motion graphics. The engine also has a declarative timeline node (Clips on a lane) resolved to the active clip per frame.

Options

--backend auto|vello|cpu

Selects the rendering backend (default auto).

Value	Behavior
auto	Use Vello (GPU) if an adapter is available, else fall back to CPU (prints a note).
vello	Force the GPU-native vector backend; errors if no GPU adapter. (gpu is an alias.)
cpu	Force the deterministic CPU reference rasterizer.

The Vello backend does anti-aliased fills/strokes, paths, gradients, clips, and crisp text. The CPU backend is bit-identical and dependency-light but draws fills + text only (no AA/strokes/paths/gradients/clips/rounded corners). See Backends.

--system-fonts

Use the host’s installed fonts instead of the bundled default font. CPU backend only, and it makes output machine-dependent (breaks determinism). Omit it for reproducible output.

Other flags

Flag	Effect
-h, --help	Print usage.
-V, --version	Print the version.

Output formats

Extension	Encoder	Requirement
.png	Built-in (render)	None.
.gif	Pure Rust	None — always available.
.mp4	ffmpeg (libx264, yuv420p)	ffmpeg on PATH.

If ffmpeg isn’t installed, MP4 export fails with a clear error — use .gif, which needs no external tools.

SVG resolution

For all three commands, file srcs on <svg> nodes resolve relative to the input JSON’s directory. Write the scene JSON next to its SVG assets. Inline markup is self-contained. See SVG import.