Node API

Everything the CLI does is a function you can call. Import from volito, find an item, render it.

import { findItem, renderVideo } from "volito";

const item = findItem("essentials/lower-third");
const result = await renderVideo(item, {
  props: { name: "Priya Sharma", role: "Product designer" },
  style: "ember",                 // a style name, DESIGN.md text, or a style object
  colors: { accent: "#00A86B" },  // overrides on the style
  aspect: "9:16",
  motion: { name: { in: "typewriter" }, "*": { ease: "bouncy" } },
  out: "priya.mov",
});
console.log(result.file, result.frames, result.ms, result.warnings);

Finding items

Function	What it does
`findItem(ref)`	An item by id (`lower-third`) or `pack/id`. Throws with the nearest matches when there is none.
`searchItems(query?)`	Items matching `{ search, category, pack, placement }`: words, one of the categories, a pack id, or `overlay` / `full`.
`library(extraDirs?)`	Every pack and item: the built-in packs plus the folders in `VOLITO_PACKS` and `extraDirs`.
`loadPack(dir)`	One pack from a folder holding a `pack.json` (see Write your own).
`customItem(code, options?)`	An item from your own program text, so it renders like any other. Options: `placement` (`overlay` or `full`), `duration`, `id`, `description`.

Rendering

Function	Returns
`renderVideo(item, options)`	`{ file, format, width, height, fps, frames, drawn, duration, bytes, ms, warnings }`. Takes `format` (`mov` by default, or `hevc`, `webm`, `mp4`, `gif`, `png`), `out` or `outDir`. Needs ffmpeg except for `png`.
`renderStill(item, options)`	`{ data, format, width, height, t, warnings, file? }`: one frame at `t` as PNG bytes (alpha kept) or an SVG document. Takes `t`, `format` (`png` or `svg`) and `out`.
`renderSheet(item, options)`	`{ png, times, warnings, width, height }`: frames across time in one PNG. Takes `times`, `cols` and `tileWidth`.
`checkItem(item, options)`	A report per aspect: errors, warnings and the slowest frame, with `ok` overall. Takes `aspects` to check only some. `describeReport(report)` prints it.

Options

Every render and check takes the same build options:

Option	What it is
`props`	The item's props by name (volito info lists them).
`style`	A built-in style name, the text of a DESIGN.md, or a style object.
`colors`	Overrides on the style: `accent`, `accent2`, `ink`, `paper`, `surface`, `mode` (`"dark"` or `"light"`), and the faces `display`, `text`, `mono` as `"Family:weight"`.
`aspect`	`"16:9"`, `"9:16"`, `"1:1"`, `"4:5"`, or `{ width, height }` in px.
`duration`	Seconds; the item's default when omitted.
`media`	Image props as `data:` URLs, by prop name. `loadImage(pathOrUrl)` turns a file or URL into one; `loadMedia(item, props)` does it for every image prop.
`words`	Words spoken over the graphic, `[{ w, s, e }]` in clip seconds. `readWords(file, offset)` reads a transcript or Whisper JSON.
`beats`	Named moments to move, like `{ in: 0.4, out: -0.6 }`; negative counts from the end.
`motion`, `mood`, `seed`, `speed`	How the parts move; see Motion.

Renders add:

Option	What it is
`fps`	Frames per second, 30 by default.
`width`	Output width in px; the height follows the aspect.
`background`	A colour under the graphic, or `"transparent"` (the default where the format has alpha).
`concurrency`	Frames rasterised at once; the machine's cores by default.
`frameTimeoutMs`	The longest one frame's program may run.
`onProgress(done, total)`	Called as frames finish.

Your own program

import { readFileSync } from "node:fs";
import { customItem, renderVideo } from "volito";

const item = customItem(readFileSync("promo-card.js", "utf8"), { placement: "overlay", duration: 4 });
await renderVideo(item, { style: "cobalt", props: { title: "Hello" }, out: "promo.mov" });

The program runs in the same sandbox, with the same faces and the same renderer as the built-in items.

Also exported

parseDesignMd(text) and composeDesignMd(style): a DESIGN.md (or Google design.md tokens, CSS variables, prose) to a style and back.
BUILTIN_STYLES, the 36 styles; EDITOR_STYLES, the MONARC PRO subset; PATTERN_NAMES, the sixteen patterns.
MOVES, EASES, IDLES, HITS, MOODS and MOVE_NOTES: the motion vocabulary.
probeFfmpeg() tells you whether ffmpeg is reachable; video renders without it throw FfmpegMissing.
ProgramRunner, to run a program yourself one frame at a time in the sandbox.