Programmatic API

The CLI is a thin shell over a server-side, importable API. A backend can do NL → eDSL → IR → (preview + diff) without shelling out or re-implementing the evaluator. Three subpath exports of the reframe-video npm package:

import	what
`reframe-video`	the core eDSL + IR — `scene`, `compileScene`, `composeScene`, `evaluate`, `sceneManifest`, `lintScene`, `validateScene`
`reframe-video/compile`	load + validate + determinism — `loadScene`, `loadSceneFromCode`, `loadModule`, `checkDeterminism`, `SceneLoadError`, `ValidationIssue`
`reframe-video/renderer`	`DisplayList` → Canvas 2D — `renderFrame`, `drawDisplayList`, `ImageRegistry`, `VideoRegistry`, `coverRect`

reframe-video/compile executes the scene module in-process. Treat untrusted or model-authored source as code: bound it with a timeout and run it where a misbehaving module can’t do harm. True sandboxing is a separate concern.

Load & validate a scene

import { loadScene, loadSceneFromCode, SceneLoadError } from "reframe-video/compile";

try {
  const compiled = await loadScene("scene.ts");        // bundle + validate → CompiledScene
  // or: await loadSceneFromCode(sourceString)          // no file on disk
} catch (err) {
  if (err instanceof SceneLoadError) {
    err.kind;     // "bundle" | "eval" | "validation" — which stage failed
    err.issues;   // ValidationIssue[] on a validation failure
  }
}

A ValidationIssue is structured, not prose — so a UI can point at the exact broken node:

interface ValidationIssue {
  code: string;     // stable category, e.g. "unknown-blend", "duplicate-node-id"
  path: string;     // locator, e.g. "nodes.box", "timeline.beat(intro)[0]", "camera.zoom"
  message: string;  // the human-readable line
}

The CLI mirrors this: reframe compile --json returns { ok: false, error, kind, issues } on failure.

Check determinism

import { checkDeterminism } from "reframe-video/compile";

const { deterministic, findings } = await checkDeterminism("scene.ts");
// compiles the source twice and diffs the IR; `findings` pins the first
// differing address when a Math.random() / Date leaked into a prop.

This is what reframe lint runs for the source-purity half of its gate.

Render a frame

import { renderFrame } from "reframe-video/renderer";
import { compileScene, evaluate } from "reframe-video";

const ctx = canvas.getContext("2d")!;        // any Canvas 2D context
renderFrame(ctx, compiled, t);                // draw the scene at time t

renderFrame evaluates the compiled scene at t and paints the resulting DisplayList; pass an ImageRegistry / VideoRegistry to supply raster sources for image / video nodes. This is the same path the live browser preview uses.

Spatial query — where things are on screen

sceneManifest answers what you can edit (addresses); the spatial query answers where it is and what’s under a point at time t — the other half an editor needs. Pure functions over the DisplayList (each op carries its source id + final scene-space transform), with canvas-free Inter metrics, so no canvas is required:

import { compileScene, sceneGeometry, hitTest } from "reframe-video";

const g = sceneGeometry(compiled, 1.5);
// g.nodes:   { id, corners: [x,y][], bounds: {x,y,w,h} }[]   (rotated quad + AABB, scene coords)
// g.groups:  { id, bounds }[]                                 (union of descendants)
// g.waypoints: { label, target, index, x, y }[]               (motionPath control points → timeline.<label>.points)
const id = hitTest(g, 960, 540); // topmost node under the point, or null

On the CLI: reframe geometry <scene> --t <sec> --json.

Embedded editor — `player --edit`

reframe player <scene> --edit -o editor.html builds an embedded-editor variant: no autoplay, seek-driven, exposing a live API + a host↔iframe postMessage channel, so a host (e.g. a desktop or web editor) can click-to-select, draw aligned handles, and preview overlay edits without rebuilding the HTML:

// inside the player iframe:
window.__reframe = {
  seek(t), play(), pause(),
  hitTest(x, y),     // → nodeId | null   (scene coords)
  bounds(),          // → { nodes, groups, waypoints }
  waypoints(),       // → motionPath handles
  setOverlay(doc),   // re-compose + re-render IN-BROWSER, no reload
};
// host → player:  { type: "seek", t } | { type: "setOverlay", doc } | { type: "hitTest", x, y } | { type: "bounds" }
// player → host:  { type: "ready", size } | { type: "pick", nodeId, sceneXY } | { type: "bounds", … }

setOverlay(doc) runs composeScene(baseIR, doc) → compileScene → redraw, so a dragged node or motionPath waypoint round-trips as a regen-stable overlay patch (nodes.<id>.x, timeline.<label>.points). --edit-origin <origin> restricts event.origin (default *).

Getting started

Reference

Showcase

Programmatic API

Load & validate a scene

Check determinism

Render a frame

Spatial query — where things are on screen

Embedded editor — `player --edit`

​Load & validate a scene

​Check determinism

​Render a frame

​Spatial query — where things are on screen

​Embedded editor — player --edit

Load & validate a scene

Check determinism

Render a frame

Spatial query — where things are on screen

Embedded editor — `player --edit`