Shape
{
"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:samplesandshutter, plusmax_samplesfor 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.
"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:
"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:
tin seconds,vthe value,easea name (in_out_cubic,out_expo,out_back,spring...) or a CSS-style bezier{"bezier": [0.16, 1, 0.3, 1]}.repeat:cycleorpingpong. - Drivers:
wiggle,oscillate, andaudio, which follows a soundtrack band so a param pulses with the music. - Expressions:
{"expr": "..."}, a formula oft, with a list for vectors.
timing
"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
transitionnodes (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 anover,blendorgradientto 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 withaxis_<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.