Make video, motion graphics, games and 3D scenes with raea, the Render Anything Engine: the raea skill, and hooks that run raea's quick check on a composition after it's saved and show media in the raea app instead of the Mac's viewer.
- GitHub stars
- 20
Install
/plugin install raea@raeaRun it inside Claude Code after adding the marketplace with /plugin marketplace add shinyobjectz/raea-skills.
Contents
Discovered from sourceSkills 2
raea
raea renders compositions written in TypeScript and React with a GPU engine built on Bevy. A composition is a function of the frame: give it frame N and it draws frame N. The same file renders to video, plays live as a game, or renders single frames to check.
Each step below says where it runs. HEADLESS: the raea CLI alone, in any shell. HOST: needs the raea app
running on this machine (its host answers). PAGE: needs the person's feed open in the app. PERSON: only the
person can do it. Every PAGE step says what a headless agent does instead.
0. First, every time: which workspace, which project — HEADLESS
Before you write, render or generate anything, settle where the work belongs, and keep it all there. Agents most often go wrong by starting to make things first and finding a home for them later, or never.
- The workspace.
raea workspace --jsonsays which one you're in. The workspaces are the folders under raea.root (git config --global raea.root). If you're in none, or not the one this work is for (the studio or client it's for), pick the right one, and ask the person when it isn't clear.raea workspace init NAMEonly when they want a new one. - The project.
raea workspace --jsonlists the workspace's projects and their folders, andraea project --jsonsays which one you're in. Pick the one the request belongs to. When none fits, say which project you'd make and make it (raea project new NAME) before any file of the work; ask when it's unclear which one is meant. - Name it by id. A project's id is its folder's name, as
raea workspace --jsonlists it. Titles repeat and drift, and agents that go by them post to the wrong project; ids don't. So name a project byWORKSPACE/IDeverywhere (raea show --project WORKSPACE/ID, your notes, what you tell the person). When the person pastes a line from the app's Copy reference (a line that reads raea feed item "Hero cut" (i-acp-1) in project "Launch" (launch), workspace "Acme": /path/..., naming no command), it names exactly the thing they mean: that item, in that project. - Say it, then go there. One line before you start: "Working in WORKSPACE / PROJECT (WORKSPACE/ID)." Then
cdinto the project's folder and read its context (section 3). Everything you make goes in it: compositions incompositions/, footage and media inassets/, renders inout/. Never in the home folder, the Desktop, a temp folder or wherever the shell happened to start. - Plan before you make.
plan.orgat the top of the project's folder is its to-do list, the one the person sees in the app. Read it, find the task this work is (or add it), and for work of more than one step write the steps as tasks first. Notes from the person (a round of comments, a list of fixes) are planned first too: the work they ask for as tasks in your own words, each linked to the notes it answers, never the notes pasted in. Keep it as you go: mark tasks as you start them, close them with what you made, add what's left. In the app, the plan tools; anywhere else, the file as Org text. plan.md says how.
In the raea app, a chat opened from a project's feed is already in its workspace and project: work there. If the person's request turns out to be for another project partway through, stop, say so, and move to it before going on.
1. Install (once) — HEADLESS
- macOS (Apple Silicon) or Linux (x86_64):
curl -fsSL https://raea.io/install | sh. Windows 10 or 11, in PowerShell:irm https://raea.io/install.ps1 | iex. Either putsraeaunder~/.raea, puts it on your PATH, and adds this skill to~/.claude/skills. Run it again to update.raea helplists every verb. Linux needs ALSA and fontconfig (apt install libasound2t64 libfontconfig1on Ubuntu 24.04). - Another agent:
raea skills install --agent claude|codex|kimi|geminiputs this skill where that agent reads skills.--pin quieter(any move) adds a/quieterthat loads one move. It also adds raea's hooks to that agent (after a composition is saved,raea check --quickruns and hands you what it finds; media opened in the Mac's viewer goes toraea showinstead, once) and the Blender MCP server;--no-hooksand--no-mcpleave them out. In Claude Code the skill and hooks also come as a plugin:/plugin install raea --marketplace shinyobjectz/raea-skills. - This file's front matter names the raea it shipped with (
version:). Ifraea --versionprints another, readraea skillinstead: it is this skill as your raea ships it. - From a checkout of the repository:
cargo build --release -p raea-cli; the binary istarget/release/raea. - Optional settings live in
~/.raea/env(docs/settings.md). Rendering needs none of them.
Reference
Generated from the code by tools/skills.sh gen, so they're current. Read the one you need instead of guessing a flag:
- reference/cli.md: every
raeaverb, its flags and where it runs (raea helpprints the same). - reference/feed.md: the raea app's tools for an agent it launches, and which need its page.
- reference/files.md: a workspace's and a project's files, what lives in
~/.raea, and each spec's fields (brief.ts, NAME.script.ts, taste.ts, plan.ts, controllers/ID.ts). - reference/sdk.md: what each
raeaimport gives a composition. - reference/app.md: driving the raea app's window over MCP, as a person would (HOST).
- reference/platforms.md: each network the app publishes to: shapes, lengths, file and caption limits, and where its interface covers the frame.
The guides, by what you're making
raea's craft guides travel with this skill: each file under motion/, 3d/ and craft/ is a copy of the guide
raea guide NAME prints, so either works. Open the router for what you're making; it says which one or two files the
task needs.
| Making... | Open |
|---|---|
| a cut of real footage: takes cut by words, faces framed, captions, cuts to a song | footage.md |
| motion graphics and type: cards, stats, logos, end cards | graphics.md |
| a short product film (a launch, a demo, a brand film) made like a good film of its kind, or one you were handed ("make me one like this") | the video-decompiler skill, installed beside this one by raea's installer and plugin (not in the plugin directory's edition) |
| sound: voice, beds, foley, music for picture, the mix | sound.md |
| a 3D scene: lights, materials, models, people, rooms, splats; three.js or React Three Fiber work | 3d.md |
| a game, 2D or 3D | games.md |
| an app's interface (web or native) | apps.md |
| generated images, video, sound or meshes | gen.md |
| the export, the share copy, platform specs, posting a deliverable | delivery.md |
| working with the person in the raea app: the feed, controllers, the editor, boards | collaborate.md |
| planning the work and keeping its tasks: the project's plan.org, the person's to-do list | plan.md |
| checking a cut against the person's taste and rules, reading their notes on a sound, or teaching their fingerprint | fingerprint.md |
Across all of them, craft/: craft/ROUTER.md is how to decide what to make (the order of work and
reading notes); craft/floor.md is read right before every edit; craft/modes/ says what a pitch,
an explain, a story, a game or a tool has to do; craft/verbs/ has one file per move a note asks for;
craft/rubric.md is how a critique is judged and ranked.
2. The workspace and its projects — HEADLESS
Work lives in a workspace: a git repo under raea.root (git config --global raea.root; unset, ~/Studio where
workspaces already are, else ~/Documents/raea, or ~/raea when iCloud keeps Documents), one per studio or client,
holding projects and controllers. In the raea app a project shows as a channel.
raea workspace init NAMEmakes one;raea workspace adopt DIRmakes an existing folder one.raea workspaceshows it (--jsonfor the projects and their paths).raea project new NAMEadds a project: its folder withbrief.ts,AGENTS.md,compositions/,components/,controllers/,assets/,artifacts/andout/. The workspace'sshared/has the same five folders, which any project imports from as@shared/components/NAME. A project can live inline or as its own repo (raea project split NAME,raea project join NAME); both keep its history.- Work in the project's folder. Footage and other media go in
assets/(media/in a project made before the layout), renders inout/.
3. Read before you make — HEADLESS
raea context .in the project prints everything to read first, in order: the person's taste (~/.raea/taste/taste.ts; a line there beats any guide's default), the workspace's taste, the brief, the look, the workspace's controllers, the craft floor and each of the brief's modes' guides. Read all of it. In the raea app,rules_readlists every rule the work follows, the project's owntaste.tsfirst (collaborate.md).- Run it once a session. If it refuses, say so in one line ("raea context failed: its message; reading the brief and
controllers directly") and read
brief.ts, any*.script.ts,~/.raea/taste/taste.tsandraea controller lsyourself. ACONTEXT_STALEline meansraea doctorfinds files from another version: runraea doctor --fix. - With no request in hand,
raea nextlists the two or three useful next steps from the brief, the compositions, the renders and their checks. Offer them; never run one unasked. - The controllers (
raea controller ls,raea controller get PATH) are the workspace's settings and workflows: delivery specs, who reviews what, the tools every agent gets. Work to them. Change one only when the person asks:raea controller set PATH VALUE(each change is a commit). - A controller is not a feed item. A feed item is one piece of work (a render, a still, a question): the person
reviews it once and a note on it is answered by its next version. A controller is a standing decision every agent
reads before it starts, so changing it changes all the work after. If the person would say it again on the next
piece ("always 9:16", "Grade checks every cut"), it belongs in a controller; if it's about this piece only, it's a
note. When the work needs such a decision from the person, put the controller in front of them with the feed's
controller_post(its id, the fields as group.field, a line on what you need decided) rather than asking in prose; a controller you make withcontroller_writereaches their feed on its own. Fields are typed (toggle, choice, number, text, list, agents, channels, workflow, servers, skills, rule; reference/files.md), so put what they'll adjust in fields, one controller per concern. A style preference with no fields to set ("words never cover the action") is a rule instead:rule_addin the app, or a line in the project'staste.ts. - A
rulefield is a line every piece is held to and the check that holds it: one of raea's by name with its values, or a.tscheck written withraea/check(craft/ROUTER.md, step 7).raea check PROJECTruns every rule that applies, with raea's floor and the person's taste, and says what waits for a render. - If the brief isn't shaped (no
believe, nomode), shape it before making anything: ask who it's for and the one thing they should believe, or write your best guess and add its field to the brief'sassumedlist. - For a pitch, an explain or a story, plan first: write the deliverable's storyboard as
NAME.script.tsbeside the brief (export default script({...})from "raea/brief": scenes of beats, what's on screen and what each scene must land; its fields are in reference/files.md), name it on the deliverable, and add a task "storyboard approved" taggedgate.raea spec NAME.script.tschecks it. Render nothing until the person approves it (PERSON). - Show a plan as what it will be, in this order: previz (a rough, fast raea render of the blocking, timing and
camera: grey shapes, placeholder type, no polish; it is the plan, not the piece, so the gate allows it), else a
storyboard (key frames as one
feed_postlook withfilesin order), else the script itself (feed_postread with itsNAME.script.ts: the feed shows it as a screenplay and as an A/V table, timed from each beat'sseconds). People judge a picture faster than a description. A whiteboard maps how ideas, options and references connect; it isn't the plan. - The person's footage and files:
raea library search "WORDS"finds them by meaning across the libraries they've indexed (HEADLESS once indexed; adding a folder waits for the person's yes, PERSON). - Right before any edit to a composition, even a one-line change, read the floor:
raea guide craft. Readraea guide routeronce for the order of work.
4. Make an item — HEADLESS
One .tsx file whose root registers compositions (raea init in a footage project writes the files to start from):
import { AbsoluteFill, Composition, Sequence, interpolate, registerRoot, useCurrentFrame } from "raea";
function Card({ text }: { text: string }) {
const f = useCurrentFrame();
const opacity = interpolate(f, [0, 12], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
return <AbsoluteFill style={{ background: "#000", color: "#fff", justifyContent: "center", alignItems: "center", fontSize: 96 }}><span style={{ opacity }}>{text}</span></AbsoluteFill>;
}
registerRoot(() => (
<Composition id="piece" width={1080} height={1920} fps={30} durationInFrames={90} component={() => (
<><Sequence from={0} durationInFrames={45}><Card text="One" /></Sequence><Sequence from={45} durationInFrames={45}><Card text="Two" /></Sequence></>
)} />
));
Rules that keep renders right (raea guide motion has all ten, under "The core rules"; every file needs these):
- Frame-pure. Everything that moves reads
useCurrentFrame();useState,useEffectand timers don't animate a render.Math.random()is seeded per frame, so seed what should hold still from an index. - Clamp every interpolate. Do it unless you mean the line to run on past its ends.
- Cue on words, not on guessed frames.
word("phrase")is the frame where it's said, so cues follow the cut. - Footage:
<Video>and<Audio>. Games:useGameState(initial, step)with a purestep, keys fromuseInput(). - Brand: the kit's
--brand-*variables inbrand/brand.css(raea brand DOMAINreads them from a site), thenimport { css } from "./styles.gen"and Tailwind classes likebg-brand-bg. - 3D: read 3d.md first; it routes to one file per topic in
3d/. An asset to fix first (scale, pivot, FBX to .glb) goes through Blender (raea setup blender, then 3d/blender.md); a step can be TypeScript (raea/blender). A Godot project is scripted from TypeScript too (raea setup godot, then 3d/godot.md). - Sound:
raea guide soundandraea guide music; to cut to a song, runraea song FILE --plot FILE.song.pngand time cuts from its map, never a constant BPM. npm packages and React apps:raea guide apps. - Generated media:
raea guide genbefore the firstraea gen.
raea check --quick piece.tsx checks three stills' text (clipped, cramped, safe areas) in about a second: run it
after each save when no hook does. Then render, and look before you call it done:
raea render piece.tsx --at 0,45,89 -o frames/ # stills to look at: text fits, nothing overlaps
raea render piece.tsx --alpha -o frames/ # transparent PNGs, for an overlay in another editor
raea render piece.tsx -o out/piece.mp4 --manifest out/render.json
raea check out/piece.mp4 --manifest out/render.json --taste ~/.raea/taste/taste.ts -o out/piece.check.json # P0-P3; exits 1 on a P0 or P1
raea findings --open # what still stands, from every render and check so far
In a project, every render and check is kept in its record (.raea/record/), so raea findings tells you where the
piece stands without rereading old check files: for each thing rendered or checked, what its last run fixed, what is
new and what it carries (and since which render). --open keeps only what stands, --about NAME one part,
--check ID one check, --since RENDER sets it against an earlier run, and --json is for a script. Read it before
you fix and after each render; say what it lists rather than "looks good". A render with an error exits 1; when the
person accepts one, raea render ... --despite CHECK "why" lets it through, and findings lists what was let through.
Before you post a cut, score it with the person's fingerprint, what raea has learned of their eye on this machine
from their notes, marks and approvals: raea fingerprint score out/piece.mp4 lists the moments it expects a note on,
each named in the person's own words, beside raea check's findings. On a picture axis that has learned where, a moment
also says where in the frame and, on a render with a layer pass, the layers there ("top right on Floor"): start the fix
with that layer. Fix each gating moment, or say why you didn't, and
score the fix against the cut before: raea fingerprint score out/v2.mp4 --was out/v1.mp4 says whether each flag is
fixed, still there, or looks disguised (nearer the axis's disguised defects than clean work, so the fix hid the defect
rather than removing its cause); only a fixed flag is fixed. raea fingerprint which out/piece.mp4 names the
fingerprint that judges this piece (the project's, the workspace's, then the person's own) and why. Tell the person
the axis and the moment, never a score. In the app, rule_check scores it and holds it to every rule in one call.
fingerprint.md has the rest: the person's rules, reading a note's box on the sound, teaching the
fingerprint, and keeping one with a project.
raea fingerprint report says what each axis has learned and what it can't judge yet. A fingerprint's axes are
~/.raea/fingerprints/NAME/fingerprint.ts, typed by raea/fingerprint: add, remove or reword an axis there, never its
evidence. A script or brief scores on text axes only, and raea's own axes read pictures and sound, so a script scores
only once the person has added an axis that reads text.
For a 3D shot, check how its things sit and move. Render it with --layers, and render --aov -o out/shot.aov beside
it. Then run raea fingerprint things out/shot.mp4 --json > things.json and
raea check out/shot.mp4 --things things.json. It finds a thing floating or passing through another, the camera
lurching mid-move, and an empty frame. When the person says a project is finished,
raea fingerprint postmortem PROJECT asks them at most ten yes/no questions in the app about what the fingerprint is
least sure of. Once they've answered, --tally makes the answers evidence.
raea guide rendering covers stills, the check, bitrate and quality; raea guide rubric covers judging the rest.
5. Show it and read the notes — PAGE, PERSON
-
In the raea app, post the render to the project's feed with
feed_post(a watch, look, listen or play item); the person watches, plays and leaves notes on it there (PERSON).feed_itemsreads the items and their notes. -
Outside the app (a session in a terminal: Claude Code, Codex, Gemini CLI, Kimi Code, any harness),
raea showdoes whatfeed_postdoes:raea show FILE...puts stills (several make a storyboard), a video, a sound, aNAME.script.tsor.md, or a.tsxartifact in the project's feed as an item the person can use. Name the project as--project WORKSPACE/ID(an id fromraea workspace --json, or the person's Copy reference line pasted whole), never its title: raea refuses a title when your folder is in another project or two projects share it. Check that the place it prints (item ID, project ID in WORKSPACE) is the one you meant. It lands quietly, with a notice, and the window stays where the person is (they may be working);--openbrings the window up on it only when they're waiting on it. Ask everything you need at once, as one item: every question in it, and each choice with what it is to play or read while answering (--preview FILEafter a--choiceis that choice's; after the--question, before its choices, the question's own, such as the script it asks about):raea show --title "Orientation: three picks" --question "Which narrator?" --choice Henry --preview henry.mp3 --choice Measured --preview measured.mp3 --question "Graybox the script?" --preview film.script.ts --choice Yes --choice "Not yet". Put the choice you suggest first. Never post each option, sample or question as its own item. While the raea app is installed, never open a render, a still, a contact sheet or a question in Preview or a browser: show it. raea's hook (raea skills install --agent Aadds it to any of them) stops such an open once and names theraea showcommand; run the same command again only when the person asked for the viewer. What the person sends on it (notes, edits, picks, answers, an artifact'sapp.result) comes back as JSON lines in the inbox fileraea showprints. raea's hook hands each new line to you after your next tool call and keeps your turn from ending until you have it (where there is no hook, follow the file withtail -n0 -F FILEor your harness's monitor). Answer each: it may change what you're doing. Without the app,raea showopens the file in the Mac's own viewer and says so; take the person's notes as text then. -
When one picture holds several things (a contact sheet, a side by side, a before and after, a grid of props or characters), label each instead of naming them by position in the title or your message. A label is a tag of a few words that stands beside the picture, never on it, and points at its place when the person's pointer is on it; give it a paragraph only where a tag isn't enough. In the app,
feed_posttakeslabels: each{ text, detail?, box: [x0, y0, x1, y1] }orpoint: [x, y]in the picture's own 0-1, withframefor a storyboard's still,t(andto) for a film's seconds, orpartfor a scene's part. Outside it:raea show sheet.png --label "0,0,.5,1 v1, hook first" --label ".5,0,1,1 v2, product first" --detail "Opens on the product for two seconds, then the hook."(each--labelis the place, then its tag; a--detailis the paragraph of the--labelbefore it). A sheetraea media sheetmade comes labelled with each cell's time or file; to say more, edit the tags and paragraphs in itsOUT.labels.jsonbefore you show it. -
When you need the person to choose or fill something in (pick an opening, rank cuts, set a price), post an artifact: a React
.tsxof your own,feed_postwithtype: "artifact", the file, and anaskline. The app builds it and runs it sandboxed in the feed. Its default export is the component. It importsreact,@raea/appand its own files, nothing else (no fetch, no other packages). Tailwind classes use the feed's tokens (bg-ground,text-ink,text-ink-3,border-line,bg-accent). Saving the file updates the open artifact in place, and a file that doesn't compile shows its file and line there.import { useState } from "react" import { app, useItem } from "@raea/app" const CUTS = ["15 s, hook first", "30 s, product last", "6 s bumper"] export default function PickCut() { const item = useItem() // { title, ask, status, answered, preview, media } const [sent, setSent] = useState(false) if (!item) return null return ( <main className="p-8 text-ink"> <h1 className="text-lg font-semibold">{item.ask}</h1> <div className="mt-4 grid gap-2"> {CUTS.map((c) => ( <button key={c} disabled={sent || item.answered} className="rounded-lg border border-line p-3 text-left hover:bg-accent/10" onClick={() => app.result(`Picked: ${c}`).then(() => setSent(true))}>{c}</button> ))} </div> </main> ) }app.result(text)comes back to you as the person's next message;app.comment(text, { x, y })leaves a note on the item, pinned to a point (0 to 1 across and down). Any other call is refused, naming it. On a card the artifact is a preview that reads only; it acts once the person opens it. -
Every note, from the feed or as text, gets a move before any edit: pick the one it asks for (quieter, bolder, distill, clarify, retime, recut, regrade, remix, harden, layout, typeset, animate, delight, adapt, optimize, extract, generate, polish, critique) on the part or moment it names, and read it (
craft/verbs/MOVE.md, orraea guide MOVE) before you touch the composition. Answer in their words, and never name the move to them.
6. The next version — HEADLESS, then PAGE
- Change the composition under the person's hand edits (the
editsegments and<Nudge>props the app writes; seeraea guide rendering), render again and check again. - Render each version to a new file beside the old (
piece-v2.mp4), never over it: the earlier version stays watchable. In the app, post it withfeed_postnaming the item itreplaces(outside it,raea show --replaces ITEM FILE), so the feed keeps both as versions. - The person's edits are tasks they watch, each with an id (in your turn's prompt in the app; in the inbox line's
commentsoutside it). Mark each working as you start it and done when it's settled: in the app,comment_task, orfeed_postwithanswersnaming the comments the version settles; outside it,raea show --on ITEM --working IDand--done ID [--note LINE], orraea show FILE --replaces ITEM --done ID.... When subagents split them, name the one on each (sub,--sub NAME). Done stays in view until the person resolves it; Not done sends it back as a new edit.
7. Deliver — HEADLESS
- The delivered file:
--quality masterfor motion graphics and type,--quality highfor a film. A version made for notes takes no--qualityflag (a fifth of the bytes for the same picture:raea guide rendering). Name files with lowercase letters, digits and hyphens only (spring-launch-9x16.mp4). - A render is a standard MP4 but large: H.264 High and AAC on a Mac (VideoToolbox), H.264 Constrained Baseline and
Opus on Windows and Linux (openh264), yuv420p on all. Hand over a share copy too, which any player takes:
ffmpeg -i film.mp4 -c:v libx264 -preset slow -crf 23 -maxrate 2600k -bufsize 5200k -pix_fmt yuv420p -c:a aac -b:a 128k -movflags +faststart film-share.mp4. - Deliver to the controllers' specs (sizes, platforms, loudness) when the workspace sets them; each network's shapes, lengths and UI zones are in reference/platforms.md, and delivery.md routes the rest (one composition per shape, cutdowns, tags, handing over).
Apps: web or native — HEADLESS
An app is a React file with a default export: DOM elements, inline style or Tailwind className, on @raea/ui. One
setting picks the host that draws it. Both are desktop windows that draw every pixel themselves (neither uses the
OS's widgets or a browser), with the same kind of text and layout engines. web (the default) is Blitz on Bevy: a
browser engine, so all of CSS (grid included), web npm UI packages and the 3D world. native is Rune, an app UI
framework: springs on every change, GPU effects and kit components, a screen-reader tree (AccessKit), a ~27 MB host
against web's ~175 MB, a subset of CSS (no grid) and no 3D yet. The SDK is the same; only the setting differs. Pick
native for a small, motion-heavy app with no 3D that passes its check; anything else stays on web. A composition or a
game stays a composition; an app is an application's interface.
- Say the target in the app's own file, as a literal (anything else is refused at its line):
export const app = { target: "native", title: "Notes", size: [480, 640], minSize: [360, 480] };. With noappexport, or notargetin it, the target is"web".--target web|nativeon the command line overrides it. - The verbs, the same on both targets:
raea app run app.tsxopens it in a window;raea app check app.tsxruns it headless;raea app bundle app.tsx -o Notes.appmakes a Mac app.raea app bundlesigns ad hoc unless you give--identity "Developer ID Application: ..."(or RAEA_SIGN_IDENTITY) and--notarize PROFILE(a notarytool keychain profile): it always signs with your own identity, never raea's. - Check before you show it. Give the app its input as
export const steps = [{ press: "add" }, { type: "Ada", into: "name" }, { key: "Tab" }, { wheel: "list", dy: 120 }, { frames: 30 }];(elements bydata-testid), or as--script steps.json.raea app check app.tsx --png out/writes a PNG after the mount and after each step (00-mount.png, 01-press-add.png, ...) and tree.json (each element's role, label, text and box). Read the PNGs. Check on both targets when the app should run on both:--target weband--target native. - What the check holds each target to. native fails on any prop Rune doesn't map or call its host doesn't answer, naming each with its element's path (unmapped.json, unanswered.json). Change the prop, or keep the app on web. web passes when it draws, and says what native wouldn't draw and which Rune props it ignores.
- Native draws flex layout (no grid), sizes, padding, margin, gap, absolute insets, scroll, colours and gradients, borders, radius, shadows and rings, outlines, opacity, transforms and transitions, text, images and video, fonts from the app's folder, and Tailwind's classes with hover:, focus:, focus-visible:, active:, disabled:, dark: and sm: to 2xl:. Anything else is reported, never dropped. An empty unmapped.json means the page maps whole.
- What only Rune does is typed props from
@raea/rune:<div {...rune({ motion: "pop", transition: { effect: { push: "top" }, enter: "pop" } })}>, pluslead,instant,blur,backdropBlurandglass, and itsBadge,Spinner,Progress,RollingTextandSwitch. On web, a preset motion becomes a CSS transition and an entrance a keyframe, blur and glass become filters, and the rest is ignored and listed by the check. Without these props an element lands at once, as in a browser. - Part of a web page can be Rune's:
<RuneLayer className="w-80 h-48">...</RuneLayer>from@raea/runedraws its children with Rune, on the GPU, in its box, and the rest of the page stays Blitz's. Give it a size: the layer is its content box. Clicks and wheel reach its elements, and their handlers run as anywhere else. AgetBoundingClientRectinside one is zero, and keys don't reach a field in one yet. In a browser it's a plain div.RAEA_RUNE_LAYERS=0draws it with Blitz. - Host calls (
callandcallSyncfrom@raea/ui/wire), answered on both targets:net.fetch,net.ws.*,net.storage.*,net.clipboard.*,os.open(http, https, mailto),fs.pick,fs.save,fs.read,fs.writeanddialog.message. Headless, a step answers a dialog:{ pick: ["a.txt"] },{ save: "out.txt" },{ dialog: 0 }.world.*(BRP on the 3D world) is web's only: native refuses it with "no world on the native target". - Examples ship with raea and pass the check on both targets:
sdk/rune/examples/signin.tsx(Tailwind only) andsdk/rune/examples/motion.tsx(Rune's props). On a native app,raea app check --video out/app.mp4 [--audio music.wav]films it on the virtual clock at 60 fps, with a cursor gliding to each element it presses. The same app and steps give the same frames.
Go further
- The guides: the routers above, or
raea guide(it lists them;raea guide NAMEprints one, the same text as the copy here). - The SDK's behaviour:
sdk/raea/spec/motion.feature; what 3D reaches:raea guide coverage. - A bug in raea itself (a command that fails or hangs, a wrong result, help that says one thing while raea does
another), not in your composition: tell raea with
raea bug "WHAT'S WRONG" --text "what you did, expected, got" [--command CMD] [--error TEXT], or the feed'sbug_reporttool inside the app. Words only: paths, emails and keys are taken out before it's sent, and--dry-runshows what would go. Then carry on with a workaround.
Video Decompiler
Every film here is made one way: take a good film of its kind apart, write your own board on its shape, and build the board. The good film is one you were handed, or one the person admires, or one of the worked films in library/films/. A board is the whole film on one page before any code (BOARD.md). raea is the medium: a page of type, cards, interface and pictures under a camera, drawn from code one frame at a time.
This is the method four films a person accepted were made by, written down and tightened after them. The steps, the rules and the readers' briefs come from their record, and each worked film's README says what its own history was: which cut its readers saw, and what was written afterwards.
All commands are python SKILL_FOLDER/tools/vd.py ..., run in the film folder (or from anywhere with --film DIR). python here, and wherever a page says python sound.py, is the Python of the environment this skill was set up with (step 0), never the system's. Run each in the foreground, and check that the file it names exists before you go on. Each says what it wrote and how long it took. What they render goes to ~/.vd/out/NAME, outside the film folder, and what readers are given goes to ~/.vd/reads; what vd pin, vd measure and vd pack measured of a film is kept under ~/.vd/measures, so a second call on the same file is quick; vd new writes the film folder itself, and vd pin writes its targets into score.json. Where a command takes a finished film (vd scan, vd pack, vd measure), give the file's full path, which vd export prints: ~/.vd/out/NAME/NAME.mp4, and an earlier cut is ~/.vd/out/NAME/cuts/NAME-cutN.mp4.
Not this skill: a film cut from recorded footage (an interview, a podcast, a tutorial, a talking head), its captions, or sound for a picture that is already finished. Hand the person to legible-film, a separate skill made for that. This one can still make the parts of such a film that are drawn in code (a title, a bumper, an animated insert); its export is an ordinary video file that legible-film or an editor can cut in.
The steps
-
Set up once, and
vd doctorpasses. The skill runs in a Python environment of its own,~/.venvs/video-decompiler, outside the skill's folder. If it is not there, make it and installSKILL_FOLDER/requirements.txtinto it (python3 -m venv ~/.venvs/video-decompiler, then~/.venvs/video-decompiler/bin/python -m pip install -r SKILL_FOLDER/requirements.txt; on Windows,py -m venvandScripts\python.exewhere those saypython3 -m venvandbin/python. The repository's README has both in full under "Start"). Then runvd doctorwith that Python: it says what is missing and the line that fixes it. -
Start from a worked film.
vd new NAME --like plusonefor a product a person uses (one task done in order, with real pictures and people).vd new NAME --like stetfor a technical product (a problem shown, the mechanism, a proof, how to start).vd new NAME --like onomafor moving type, when the product works on words or sound (each typed word comes apart into the thing it names, then the product is shown making them all from one line).vd new NAME --like lindenfor a brand film built on real still pictures (one continuous camera move outward through nested worlds, no cut). Read the copy'sREADME.mdandBOARD.mdwhole, thenvd lookit, before changing a line: it is a film a person accepted, and its kit, camera and clock are what you keep. Done when the copy draws and you can say what each of its files is for. -
Hold it against one good film of its kind. Use the film you were handed, or ask the person for one they admire of this kind. Take it apart by TAKE-APART.md, which ends with its dossier in
REFERENCE.md. With no film to be had, hold yours against the worked film you started from: make an untouched copy beside your film folder withvd new NAME-anchor --like FILM(NAME is your film's name, FILM the one you started from; outputs go by a folder's name, so give every film folder on a machine its own), then runvd exportin it, which takes a few minutes. Use that file wherever a step says REF or asks for a worked film. Done whenREFERENCE.mdis written, or you have said in the board that the worked film stands in. -
Find the film's world and write your board. Read WORLD.md first: a clean film with no world reads as a competent freelancer's, and the world is what the accepted films had. Then write
BOARD.mdin the film folder, by the form in the skill's BOARD.md. Replace the worked film's board; keep nothing of its subject. Done when every heading of the form is filled and every check at its end passes but the first, which needs the sheet that step 4 makes. No film code before this. -
Gather the real material the board names, before building: the product's own screens, marks and pictures first; then public-domain or licensed pictures that have a job in the story (a museum's open-access collection for art; for photographs of ordinary things, such as food, Wikimedia Commons and Openverse can be searched by licence, and two test films each found ten CC0 photographs of food that way). Cut each to the size it is shown at, put it in
media/, and write its source and licence down. Then lay the pictures, the colours, the faces of type and the mark out as one picture, the film's world on one sheet, and look at it before you build (WORLD.md, "Lay it out before building"). In the film that was liked best, real pictures gathered at this point changed what the film was. Done when every picture the board names is inmedia/with its source line (or the board says the film uses none), the sheet is made and looked at, and the board's first check passes on it. -
Sound first, on one clock. In
sound.py, write the table of events (every beat the picture needs, by name) and the music: a chord a bar, one pattern, a tune, the events played inside it. Run it (python sound.py;vd newran it once already). It writesmedia/sound.wavandkit/times.gen.ts; the picture imports its beats from that file and from nowhere else. Done when every row of the board's beat table has a named time, andvd soundprintssound passesand says sync was checked against the named events. If it says sync was not checked, the film has no named events yet: write them. (Started fromlinden, the level line fails until your own film's sound sets its level: that film is kept at the level it was accepted at, and its README says so.) -
The hardest shot first. Build the shot your board names as hardest, alone, with its real pictures in place.
vd look --at T(one moment draws at the film's own size, up to 1920 px wide). Done when you would publish those frames. -
The whole film. Replace the worked film's acts with yours, beat by beat from the board.
vd look --at T1,T2,...after every change (several moments, one call). Thenvd export(it carries the film's ownmedia/sound.wav; each export is kept as~/.vd/out/NAME/cuts/NAME-cutN.mp4, andNAME.mp4is the latest; beside it are a share copy,NAME-share.mp4, and sheets of the whole film at four frames a second,NAME-sheet_000.jpgon, the quickest way to read the cut you just made). The first export is the first cut, not the film. The accepted films took several cuts to reach their readers: after each export, read the SCAN (pops, holds, level and flashes), make the story sheets (vd pack FILM) and read your own film on them as a stranger would, fix what you find, and export again. On the first cut,vd measure FILM --against REFlists up to forty gaps between your film and the one it is held against, the kinds that matter most first; each is a question for the frames, not an order. Keep a table inNOTES.md, a row a cut: what changed, and the scan's numbers. Every cut stays undercuts/; hold one against an earlier one withvd pack ~/.vd/out/NAME/NAME.mp4 --against ~/.vd/out/NAME/cuts/NAME-cut1.mp4. Done when a cut's SCAN has everyfix before anyone watchesline either fixed or written down as a hit you meant, everycheckline answered, and a reading of your own story sheets finds nothing you would fix first. -
Readers, one round (EYES.md has the briefs, word for word).
vd packyour film beside the film it is held against and the worked film you started from, exported (the anchor of step 2 if you made it; otherwisevd new NAME-anchor --like FILMbeside your film folder, thenvd exportin it: a few minutes, once). Two readers, from different models, each read the blind line-up; one fault-finder reads your film alone, every frame of its ten busiest seconds. Write every reading inREADINGS.md. If you cannot start other agents, there is no blind round: read your own sheets as a stranger would, and tell the person plainly that no reader has read the film. Done when all three readings are written down. With no reader to start: when that is written inREADINGS.mdwith your own reading of the sheets; then go to step 10. -
Fix what they found, story first. An action that does not read, a step that is missing, a claim that is said and never shown: these come before words cut by the frame or too small, and those before pops, swaps and dead holds. Export again, and give the new cut to a new fault-finder alone, once, with the same brief: hold its list against the first one's to see whether each fault is gone. A small fault it still finds you may fix without another reading; a device that has now failed twice goes (EYES.md). The film does not go round again. Done when every story or words fault that reading finds is fixed, or the device causing it is cut. Say in the report which cut readers last read. Report what the line-up readers said about who made each film, and where they ranked yours against the worked film: it is a judgement to weigh, not a score to chase. If both called yours a beginner's or a hobbyist's, say so plainly, and question the film's world (WORLD.md) before you rebuild its finish: when the faults they named survive a repair, look to the premise before the polish.
-
Then the person. They are the judge: readers find faults, they do not decide. Their time is for what you and the readers cannot judge (the sound, how it feels at speed, whether it is good), so hand over the share copy only now, one film, to watch alone with the sound on. Fix what they name and leave alone what they liked. Done when the person accepts it. With no person to ask, say in the report that nobody has watched it.
-
Report. How long it took (
vd profilein Claude Code; your own clock in another agent). What the readers found and what you changed. Who watched it with sound, and their words. The weakest two seconds. Every picture's source and licence.
One film at a time: finish one, with its sound, before starting another.
What every film owes
The rules the accepted films were built to. Each is in their boards.
- Board first. Every shot has a reason in the one before and sets up the one after.
- Be the obvious choice for its kind, then add a point of view. Keep everything a viewer of this kind of film expects: for a launch, the trouble in their own words first, the name, the product doing its job in pieces of its real interface, proofs, how to start.
- One thing is carried through the film, and every change of scene is decided: the thing becomes the next thing, or is carried, or is matched, or goes through a door, or the whole ground changes on the music (WORLD.md, "Every change of scene means something"). Nothing is swapped for want of a decision.
- The proof of each claim gets the frame.
- Moves a viewer can watch: a sixth to a third of a second (10 to 20 frames at 60 a second), decelerating into place. The camera eases in and out. A thing at rest eases in before it leaves. Only a hit is instant.
- Several things move at once, and no hold where nothing moves for a reason. A rest you chose is not a fault: it has a reason in the story, and one small thing in it stays alive. Do not keep things drifting only to look busy.
- No framing for more than a third of the film. A framing is where the camera sits: going close on the part that changes is a new one, in the same room.
- The product is shown large, a piece at a time. No worked film shows a whole app small in a wide frame. Plus One keeps the made thing in the middle of the frame, large, lets the interface shrink to a pointer and a few buttons, and goes close on a phone when the phone is the point. Stet shows panels of its interface, each filling the frame, and puts the camera on the row that changes. Onoma types its one request into a prompt bar nearly as wide as the frame, then goes in on the tracks while they play. When two panels must be seen together, hold them wide only for as long as it takes to see that there are two. A panel nobody is reading may be cut by the frame; a word being read and a control being pressed may not.
- The ground has a character and a job. Soft moving colour that answers what is happening, never a default flat field.
- Music first, events inside it. A chord a bar, a pattern, a tune. Finish at -15 LUFS, true peak under -1 dB.
- Type, cards, interface and real pictures, as designed layers. No rooms, terrain or rigs modelled in code. A real picture has a job in the story, and its source and licence are written down in the film's
media/(as inlibrary/films/plusone/media/art/SOURCES.md). - Words can be read. Text that carries the story is 30 px or more at 1080p at the size it is shown on screen, after any camera scale (
vd looknames text set under 30 px by its own size, before the camera, so read the tiles for text a camera shrinks), a control is never cut by the frame, and a word has finished arriving 12 frames before anything happens to it. A word is typed where the camera already is. - Every fact on screen is true in every frame, and every number is the count of what is drawn.
- About 30 to 40 seconds for a launch, a demo or a brand film. The accepted ones run 29 to 38.
What this is proven for, and what is experimental
Proven (a person accepted films made this way): a product demo, a launch film for a technical product, moving type, a brand film built on real still pictures. All are type, cards, interface and pictures cut to music.
Experimental (it renders; no film of the kind has been accepted): lit 3D scenes (no starter ships for one; library/recipes holds 3D compositions that rendered, to copy from, and TECHNIQUES.md says what each costs), scenery drawn in code, real moving footage, generated pictures, a film under ten seconds. Build one only with a test first, and say in the report that it is unproven.
Newer commands, not proven on a film. These came after the four films and no accepted film was made through them, so none is a step above. Use one when the person asks for what it makes, say in the report that it is unproven, and check its output as you would a stranger's:
vd audio TRACK --clean-voicecleans a recorded voice and refuses any step that costs the speech more than 3 dB (TECHNIQUES.md, "A recorded voice").--sheetdraws the track's sound as one picture.--tempo-mapmakes a music track the film's beat: it records the track inscore.json'smusicwith the nearest whole frames a beat, and writes the track stretched to that beat (at most 3%) and placed so its first beat, or its drop with--drop-at-beat N, falls on a beat. Then run the film'ssound.py, which takes its beat from it, so every event the picture shows moves onto the track's tempo;vd soundandvd exportlay the track under the film's own mix, or in its place with--replace-own-mix, and stop ifsound.pyhas not run since (a--kindstarter has nosound.pyand keeps its scenes in seconds: the track is mixed in, and the command says the beat's length so you can put the scenes' edges on it). A worked film's length in beats stays, so its length in seconds follows the track. A track whose beat is weak is refused unless you give its tempo with--bpm(a weak grid fits white noise too); where the tempo could be read at half or double, it takes the octave nearest the film's own beat and says so. A film's grid is one steady tempo, so it measures how far the track's beat slides from that grid, stretch by stretch (16 beats each), and refuses a track whose beat slides more than 40 ms, giving the number and each stretch's tempo and offset; it does not follow a changing tempo. The measure is a floor: a 1906 band record a listener heard speed up read 34 ms over its first 28 s, under the line, so still listen.--bpmtakes 60 to 200 BPM; a tempo outside that is refused with its half or double to give instead.vd bridgewrites the export's cuts for an editor or for legible-film, bound to that exact file (TECHNIQUES.md, "Handing a film to an editor"). It needsvd exportfirst. Its Final Cut Pro 7 file and its OpenTimelineIO file place the picture and its sound alike, the host's in-point as a gap before them, and name the sound the file has (none for a silent one). legible-film's own readers read the cue list as fresh and its sound spotting takes it; no editing program has opened either timeline, so check them in the program before trusting them.vd borrow REFfits the reference's moves and colours intodna.jsonandkit/dna.gen.ts, beside whatvd pingives (EYES.md, "Measure"). Runvd pintoo:vd measurereads pin's numbers, not borrow's.vd captureputs a repository's counts, or a real command's output lines with their times, intokit/puppet.gen.tsand a plane,kit/PuppetPlane.tsx, that your film must import itself.vd launch REPOcopiesstet, captures into it, writes the facts toREPO-FACTS.mdfor your board, and puts the plane in the film for four seconds from Stet's NUMBERS cue, on Stet's own paper: a start, to move where the board puts it.vd foleymakes a track from moves it reads in the film's code, by rule, not by measuring the drawn picture; nothing plays it unless you mix it.--mixwrites it intomedia/sound.wav, whichsound.pyowns: the next run ofsound.pydrops it, and a second--mixadds it twice. It adds the track 9.5 dB under that mix and moves the whole toward -15 LUFS by at most 6 dB with its true peak at -2.2 dBTP, and says the level it wrote (a quiet mix ends short of -15). Under a track mapped withvd audio --tempo-map, the level of the film's own mix, foley and all, isscore.json'ssound_file_gain, in dB (0 when absent). The trace it reads the moves into is~/.vd/out/NAME/telemetry.gen.json, outside the film.vd evolve NAMEpacks four world sketches as a blind line-up. Without--rendereach sketch is a fixed drawing per worked film with your subject's name on it, not a design of yours; with it, the worked films are drawn untouched. Letters are dealt at random and the key file records them (--seedfixes them for a test); Each tournament's sketches are its own, under~/.vd/out/NAME/tournaments/tN, so running it again leaves earlier ones as they were.--selectneeds the letter chosen, promotes a sketch only as its readers saw it (one changed since is refused), keeps whatvd pinandvd borrowsaved inscore.json, and makes the film folder the chosen sketch's film: what was in it is moved to~/.vd/out/NAME/before-select-N, not deleted.--readingspicks by summed reader rank: readers rank sparse sketches higher (EYES.md, "Readers"), so the person picks the world, not the count.vd playablebuilds a browser page that imitates the film for scrubbing, the whole frame scaled to the window, with the sound the export lays under the picture. It is not the film: raea does not draw it, and parts of the kit (Freezeinkit/lib/finish.tsx, 3D) do not build.
Where to read more
| When | Read |
|---|---|
| Finding the film's world: its subject, its picture board, what each change means, its moments of wonder | WORLD.md |
| Writing the board | BOARD.md |
| Taking a film apart | TAKE-APART.md |
| Choosing how a beat is drawn; what the kit holds | TECHNIQUES.md |
| A frame looks wrong, or raea refuses | TRAPS.md |
| Looking, the scan, measuring, the readers' briefs, the person | EYES.md |
The commands
| Command | Does |
|---|---|
vd doctor | is this machine ready, and the one line to fix it if not |
vd new NAME --like FILM | a film folder that is a copy of a worked film (vd new --help lists them; --kind gives the older starters) |
vd pin REF.mp4 | a film's numbers, its story and move sheets, and moments at its own size (up to 1920 px wide) |
vd look --at T1,T2 | moments as one picture, with what did not draw |
vd sound | the sound's own check, with no picture |
vd render --from A --to B | a stretch of the picture again, spliced into the picture vd export last drew (the film itself is as it was until the next vd export) |
vd export | the finished film and its share copy, then the scan (--again draws it afresh). Exit code 3 means the film was made and could not be scanned |
vd scan FILM.mp4 | pops, holds and level of any finished film |
vd pack FILM --against REF | what readers read: a blind line-up, and your film alone |
vd measure FILM --against REF | up to forty gaps between two films, the kinds that matter most first |
vd profile | where the time went (it reads a Claude Code session log) |
vd clean | what can go from ~/.vd/out (the drawn pictures and part records an export makes again), and with --yes removes it; cuts stay unless vd clean NAME --keep-cuts N (one film's folder; --keep CUT protects one); --orphans names folders whose film folder is not there and never removes them |
vd audio TRACK | not proven: clean a voice (--clean-voice), draw a track's sound (--sheet), make a music track the film's beat (--tempo-map) |
vd bridge | not proven: the export's cuts for an editor (cues.json, Final Cut Pro 7 XML, OpenTimelineIO), bound to the exported file |
vd borrow REF | not proven: a reference's fitted moves and colours (dna.json, kit/dna.gen.ts) |
vd capture, vd launch REPO | not proven: a repository's counts or a command's output, as a plane your film imports |
vd foley | not proven: a sound track made by rule from the moves in the film's code |
vd evolve NAME | not proven: four world sketches as a blind line-up |
vd playable | not proven: a browser page that imitates the film, for scrubbing |
python SKILL_FOLDER/tools/metrics.py SANS-VF.ttf MONO-VF.ttf | a worked film's table of letter widths (kit/metrics.gen.ts), made again when you change its faces of type; both must be variable fonts with a weight axis |
One raea job runs at a time on a machine; vd waits its turn and says so. Look often and export rarely.
Hooks 3
Sponsors
Details
- Marketplace
- shinyobjectz/raea-skills
- Source
- skills
- Category
- Community
