1. ultrafast
  2. Docs
  3. The document

Docs

The document

A video is one JSON file. Here is its whole shape.

Shape

film.json
{
  "version": 1,
  "format": { "width": 1080, "height": 1920, "fps": 30, "duration": 10,
              "motion_blur": { "samples": 6, "shutter": 0.5 } },
  "nodes": {
    "<id>": { "op": "<op>", "params": { }, "inputs": { }, "timing": { } }
  },
  "components": { },
  "output": "<id of the node to render>"
}

Documents are plain files you can diff, template and edit. The engine reloads a document when it changes, so an agent can write it directly or through uf edit.

format

  • width, height: any size, in pixels. Change them and frame-relative layout (blocks, captions, fit, stacks) follows.
  • fps, duration: frames per second and seconds.
  • motion_blur: samples and shutter, plus max_samples for whips and fast pans. Each moving layer is blurred on its own, as a compositor does; footage and shaders hold at the frame's time.

nodes

Each node has an op, its params, its inputs (other nodes, by id, on named ports) and optional timing. Sources have no inputs; effects take a source; composites take fg and bg.

a title over footage
"clip":  { "op": "video", "params": { "src": "launch.mp4", "fit": "cover", "start": 12 } },
"grade": { "op": "grade", "inputs": { "source": "clip" }, "params": { "look": 2, "amount": 0.6 } },
"title": { "op": "block", "params": { "kind": "title", "title": "Artemis I", "kicker": "16 Nov 2022" } },
"comp":  { "op": "over", "inputs": { "fg": "title", "bg": "grade" } }

Generators (solid, gradient, noise, shaders) are infinite: crop or transform them into panels. Paths and text stay vector until they are rasterized, so a transform directly on them stays sharp at any scale. The planner fuses chains of nodes into one GPU kernel and skips what can't be seen.

Params and animation

Any param can be a constant or animated:

five ways to set a param
"size": 64
"position": { "keys": [ { "t": 0, "v": [540, 2100], "ease": "out_expo" },
                        { "t": 0.8, "v": [540, 960] } ] }
"rotation": { "keys": [ { "t": 0, "v": 0 }, { "t": 1, "v": 10 } ], "repeat": "pingpong" }
"position": { "wiggle": { "frequency": 2, "amplitude": 10, "base": [540, 960] } }
"opacity":  { "expr": "0.5 + 0.5 * sin(t * 3)" }
  • Keys: t in seconds, v the value, ease a name (in_out_cubic, out_expo, out_back, spring...) or a CSS-style bezier {"bezier": [0.16, 1, 0.3, 1]}. repeat: cycle or pingpong.
  • Drivers: wiggle, oscillate, and audio, which follows a soundtrack band so a param pulses with the music.
  • Expressions: {"expr": "..."}, a formula of t, with a list for vectors.

timing

a shot on screen from 2 s to 6 s, played at half speed
"timing": { "in": 2, "out": 6, "offset": 2, "speed": 0.5 }
  • in, out: when the node is on screen. Outside its window a composite passes its background through and an effect passes its source; neither costs anything.
  • offset: where the node's local time zero sits in its parent's time. speed: local seconds per parent second (negative plays backwards). loop: local time wraps at this duration.
  • Windows compose through nesting. For cuts between shots, prefer transition nodes (crossfade, dip, wipe, push, slide, iris, zoom, dissolve, glitch, blur); each shot renders only while it is on screen.

components

A component is a small document with its own params and inputs, used like an op. "$name" inside a component refers to one of its params. Components are flattened before planning, so they cost nothing at render time. uf import-svg and uf import-lottie write SVG artwork and Lottie animations as components with every part editable.

Assets, colour, type

  • File paths (footage, images, fonts, SVG, Lottie, audio) are relative to the document.
  • Colours are sRGB hex (#ff48b0, #ff48b080) or 0–1 arrays with straight alpha. Compositing is in linear light; set "space": "srgb" on an over, blend or gradient to blend the way CSS and Figma do.
  • Fonts: a family name (any Google Font is fetched once by name), a font file, or a bundled face (ultrafast:display, ultrafast:sans, ultrafast:serif, ultrafast:mono, ultrafast:wide). Variable fonts animate any axis with axis_<tag>.

Schema and versions

Documents carry "version": 1. The JSON Schema is published at ultrafast.mov/schema/v1.json for editor completion and validation; uf schema prints the same file, and uf ops the vocabulary with every param's type and default. Changes within a version are additive.