raea world
A frame as one world: its layers, text, 3D parts, camera, shots, clips, cues and lines as entities, queried across media.
raea world reads a frame of a composition into one world of facts, as raea/ecs holds a world: entities with
components by name. React is stepped to the frame and nothing is drawn. The page is laid out (styles and layout,
no paint), so a run of text has its box, size, font and line count. Every medium is in the same world: the 3D
layer with its camera and parts (each measured from its triangles), the page's text, pictures and footage in their
stacking order, the Sequences as shots, the sounds as cues and the lines sung or said on the frame. Each entity
carries its Source: the file and line that wrote it and the component it was used in.
--find is one query across all of it: the entities with every component with names, none of those without
names, and each where field equal to its value.
What only a render knows joins the same world. The newest render of the composition in its project's record (or the
one --render names) adds each text's Contrast against the pixels behind it, the frame's and each shot's
Picture (light and movement), the Mix's loudness and each cue's Onset in it, and, from a render with
--layers, which layers Covers which. Each is measured on the output the first time it's asked for and kept in the
render's manifest. The Rendered resource names the render, and says stale when the composition changed after it.
With no render, or on a frame the render didn't draw, the Waits resource says what waits for one.
raea world edit.tsx --frame 120
raea world edit.tsx --at 0-29 --json > world.json
raea world edit.tsx --frame 48 --find '{"with": ["Text", "Layer"], "where": {"Layer.medium": "2d-type"}}'
raea world edit.tsx --frame 48 --find '{"with": ["Part"], "where": {"Part.kind": "text3d"}}' # the words that are 3DUsage
raea world EDIT.tsx [--composition ID] [--frame N | --at A-B|A,B] [--find JSON] [--no-layout] [--render OUT | --no-render] [--json] (a frame as one world: its layers, text, parts, camera, shots, clips, cues and lines as entities with components, each measured, with what its newest render measured (contrast, light and movement, loudness, onsets, covers) or what waits for one; --find '{"with": ["Text", "Layer"], "where": {"Layer.medium": "2d-type"}}' is one query across media)Headless: it needs nothing running and opens no window. Takes up to 1 argument besides its flags.
Flags
| Flag | Takes | What it does |
|---|---|---|
--at | A-B|A,B | Several frames, each its own world: a range (120-150) or a list (0,48,96). Not with --frame. |
--composition | ID | Which composition of the file to read, when it has more than one. |
--find | JSON | Only the entities that match: with names components each must have, without those it must not, and where maps Component.field to the value it must equal. |
--frame | N | The frame to read (0 when neither this nor --at is given). |
--json | – | Print each frame as JSON: its size, fps and every entity with its id, parent and components. |
--no-layout | – | Don't lay the page out. Faster, but text has no box, size or line count and carries needs: "render". |
--no-render | – | Join no render: the world as the composition says, with what a render would add listed in Waits. |
--render | OUT | Join this render (an output of raea render, its manifest beside it) instead of the newest one in the project's record. |
Components
| Component | On | What it holds |
|---|---|---|
Layer | each composited layer | medium (2d-type, 2d-graphic, 3d, footage, page), order from the back, opacity, blend |
Text | a run of type, 2D or 3D | words, font, size (px of a frame 1080 on its short side), box (0 to 1), extruded (metres), lines |
Part | a 3D mesh or model | kind, name, at, rotation, scale, its world box (min, max), triangles, src, material, color |
Camera | the frame's camera | eye, look, fov or ortho, near, far, velocity (m/s to the next frame) |
Shot | a Sequence on the frame | name, from, to (composition frames); the shot around it is its parent |
Clip | footage on the timeline | source, hash (SHA-256), time, in, out, at, words (TAKE.words.json's) |
Cue | a sound on the timeline | source, at (seconds), gain (dB), bus |
Line | a line sung or said now | text, from, to, words with their times (the project's words.json) |
Source | whatever was written | file, line, component, key (the layer key) |
Contrast | a run of 2D type, from a render | ratio: its colour against the pixels behind it (WCAG, 1 to 21), as raea check measures it |
Picture | a shot, and the frame as a resource, from a render | luma (0 to 1), motion (the mean change from the frame before, 0 to 1; a shot leaves out its first frame, the cut into it), frames measured on a shot |
Onset | a cue, from a video render | at: when the mix rises 6 dB where it starts, to within 10 dB of where it goes (seconds), late_ms; both empty when nothing starts there |
Covers | a layer drawn over others, from a render with --layers | each layer it covers and the share of that layer's box |
Resources belong to the frame, not to one entity: Mix (the render's lufs and true peak), Rendered (its
output, manifest, record entry and whether it is stale) and Waits (each component a render would add, and what
it waits for).
A field raea can't know without a render says so: text from a page that wasn't laid out has needs: "render", and
a <Speech> line has needs: "transcript" for its word times.