Documentation
Reelwright docs
How Reelwright works, from the architecture and the decisions behind it to the design of each milestone, with reference pages generated from the code. Installing Studio? Start with the install steps.
Overview
Where to start: running Reelwright from source, how it is built, and where it is going.
- Run from sourceTo install Reelwright Studio, see the downloads page. This page runs Reelwright from a checkout of its source code, as its developers do.
- Use your Claude subscription with Reelwright on the webThe web edition of Reelwright, at reelwright.diy/app, works with your own Claude Pro or Max plan. Your own Claude, Claude Code or the Claude app, connects to Reelwright's MCP server and works on your
- Reelwright architectureStatus: accepted 2026-09-29. Milestones M0–M3 and M5 are done, and M4, M6, M7, M8 and M10 are under way (roadmap). Toolchain: Godot 4.7.2-stable, ffmpeg 6.1 or later, Node 24, Rhubarb Lip Sync 1.14.0
- RoadmapThe milestones follow the brief's order. Each ends with something you can watch or try. Where this plan changes the brief, the change is marked Change with the reason.
Design
How each milestone works, from the first render to the installable release.
- M1 compiler and render orchestrationHow the core turns an EpisodeIR into a Timeline, a RenderJob, and finally an MP4. Scope: the Lighthouse cold open. Read with ARCHITECTURE §7–§9 and ADRs 0006, 0008 and 0009. Code lives in core/src/com
- M1 engine designHow the engine turns a RenderJob into frames. Scope: everything the Lighthouse cold open needs. Read with ARCHITECTURE §5, §6 and §9, and ADRs 0002, 0004, 0008 and 0010.
- M2 parametric generationM2 turns patterns into instances: "generate a crew of six", "build the bridge set". It does this deterministically and offline (Tier 1), with results good enough to swap into the M1 scene. Read with A
- M3 showrunner for world-buildingM3 makes Reelwright something you talk to:
- M4 Director AIM4 turns a screenplay into a directed, voiced episode:
- M5 Writers' room and missing-asset passM5 takes a show from a premise to a script it can shoot:
- M6 FloatCharacters and props can float. The Marigold's running gag, gag.kettlegravity, says: "Whenever the bridge kettle boils, the ship's artificial gravity hiccups: everyone floats for a beat, then drops."
- M6 PerformanceM6 makes characters act: hands that hold a pose, gestures and faces chosen from what is said and done, listeners who react, and motion with the snap of the style. It ships in two parts.
- M6 PropsProps appear on screen. A prop a character picks up is in their hand, at its grip, the right size and the right way up. A prop put down stays where it was put. A prop handed over changes hands as the
- M6 Recording: voice actors in the boothA showrunner can cast real actors. They read their lines in Studio's booth, and their takes play in place of the synthetic (Kokoro) voices: the line is as long as the recording, the mouth moves to it
- M7 Re-directionRe-direct an episode on a timeline, by hand or by chat. Every edit is a change set on the EpisodeIR, proposed, previewed and approved like any other, with undo and redo from the ChangeStore.
- M7 Titles and creditsAn episode can open on a title card and close on its credits, drawn in the show's style. Until now an episode started cold on its first shot and stopped dead on its last. Nothing on screen said what i
- M8 Restyling"Restyle the whole show" switches the active StyleSpec. The engine already redraws everything in the new style. M8 makes the switch a decision the person can see and trust: what will change, side by s
- M9 Tier 2 assetsTier 2 assets are images, textures, music and the like that no deterministic builder makes. ARCHITECTURE §12 gives their pipeline: generate, post-process, QA, freeze. The generators need provider keys
- M10 3D characters: a card swapADR-0004 put the stage in 3D and kept characters as 2D cutout rigs on camera-facing cards, so that 3D characters could come later as a swap: "replace a card with a 3D character; nothing else in stagin
- M10 Continuity logA show remembers what its episodes established, and the writers' room reads it. After an episode is approved, its continuity is recorded: the facts it put on screen, the lasting changes it made, the g
- M10 Show memoryA show keeps a notebook of everything it has written, so that the fortieth episode still sounds like the first: the story so far, how each character talks, the running gags and when each last played,
- M11 Release: an installable Studio for macOS, Windows and LinuxReelwright ships first as an installable, versioned, supported desktop edition, and only then as a web service (the owner's order, 2026-10-02; ADR-0011). This note says what an installed Reelwright is
- Studio's chat on your plan, on the web, through your own computerStatus: built, 2026-10-05, opt-in and off by default. Builds on Claude on the web over MCP (m12-remote-mcp.md) and the desktop's opt-in chat on a plan (claude-plan.md, "Studio's chat on the plan").
- Claude on the web, over MCPStatus: built, 2026-10-05. Builds on the web service (m12-web-service.md), sharing (m12-sharing.md) and the desktop's Claude plan path (claude-plan.md).
- M12 Sharing a show on the serviceStatus: design, 2026-10-05. Comes after the web edition (docs/design/m12-web-service.md) and each person's own Claude key (its "Claude on the web"; core/src/host/keys.ts, grant.ts).
- M12 Web service: Reelwright with accounts, on the webThe same Reelwright, hosted. People sign in with a code sent to their email, an admin adds and invites them, and each one gets their own shows and their own session daemon on the server. Studio's web
- M13: working on a show togetherStatus: design, 2026-10-05. Builds on the service's sharing (docs/design/m12-sharing.md): show keys, one daemon per show, the host's hello rewrite, the daemon's method classes, per-person Claude keys,
- M14: Immersive editors for World, Cast and SetsStatus: design, 2026-10-05 (task #222); phase 1, the set explorer, and phase 2, the character studio, built 2026-10-05 (see "Phase 1: what was built" and "Phase 2: what was built"); phase 3, editing a
- M15: Reelwright Runner, the heavy work on your own machineStatus: all six phases built, 2026-10-06 (see "What was built" and "Proof"). Builds on the service (m12-web-service.md), the plan bridge (m12-plan-bridge.md), device sign-in and show uploads (m13-shar
- M16: Any character, not only peopleStatus: design, 2026-10-06. Phase 1 built on the branch any-character, most of phase 2 on any-character-2 (2026-10-07); see "Phase 1: what was built" and "Phase 2: what was built" at the end.
- Evaluating Claude against the heuristicStatus: built, 2026-10-10, waiting for the owner's first recording; since 2026-10-16 it records on the owner's Claude plan, with no key. The third product audit's finding 4 (0.11 plan items 6 ai-eval
- Previews drawn in the person's own browserThe web service draws every render in software on two CPUs: the cold open's 28-second preview took 17.5 minutes on four of the dev box's CPUs, and render workers only divide that by how many there are
- Using a Claude planThe showrunner talks to Claude one of two ways. Studio's chat offers both until Claude is connected (its way in, RwClaudeSetup; docs/audits/claude-setup-2026-10.md), and Settings › Claude keeps every
- Claude working on a show from outside: known and in sync (protocol 1.15)The owner's ask (2026-10-14): "When reelwright is connected the ai assistant needs to auto detect it and be synced obviously." Claude can reach a show without Studio's own chat:
- Writing a script together, liveStatus: built, 2026-10-11 (see "So far" at the end). The third product audit's finding 14 (docs/audits/product-audit-2026-10d.md): on a shared show two writers on one script are merged line by line wh
- AI direction through the person's own Claude, with no API keyStatus: built, 2026-10-14 (session protocol 1.17).
- The idle layer: bodies that actProduct audit 3 (docs/audits/product-audit-2026-10d.md, finding 6) found that faces act and bodies don't. Over Otto's four-second excited line in the cold open, the mouth flaps and the head turns a fe
- Updating Studio from StudioStatus: Linux built, 2026-10-16; macOS and Windows written down, waiting on the owner's signing. This is the fifth product audit's item 2 (docs/audits/product-audit-2026-10f.md). Until now the update
- Languages: a show in another language, and an episode dubbedThe October 2026 product audit (docs/audits/product-audit-2026-10.md, finding 27) found Reelwright English only from end to end:
- Lighting that carries a mood: fades, haze, shafts, gobos, gels and the skyStatus: design and build, 2026-10-07. It answers finding 13 of docs/audits/product-audit-2026-10.md, "Lighting can't carry a mood". Read with docs/design/world-kits.md (lighting presets, looks and the
- Lower thirdsA lower third names someone on screen: a name, and under it an optional line (a role, a place, a time): "MAYA OKAFOR / Night shift, St. Jude's". It sits in the picture's lower third, inside the title-
- Acting a line on camera: performance capture from a webcamStatus: the first half of the first branch is built, 2026-10-13 (capture-face-1: the module, the data, the engine and reelwright capture, below under "Built"); the booth's camera follows (capture-face
- A phone's messages, before and afterProduct audit 5 (#12) found that an insert showed one message and that the phone prop's screen was blank. The branch phone-inserts (batch 16, 6f03cd0ad) fixed how the director reads a phone's words (d
- Re-directing an episode from a momentStatus: designed 2026-10-15; slices 1 to 9 built (see "As built" and "Next steps"). EpisodeIR 1.66, session protocol 1.20.
- Render capacity on the web: an honest estimate, one line, quotas, render workersThe third product audit (docs/audits/product-audit-2026-10d.md, finding 9; the 0.11 plan's item 4) found every web render drawn in software on one small machine. The service is one Fly performance-2x
- The render queue: one at a time, time left, resume, failures in wordsThe second product audit (docs/audits/product-audit-2026-10b.md, finding 13) found rendering one at a time with no queue. A second render was refused ("is rendering: wait for it, or cancel it first").
- The review loop: versions, a player, notes on framesThe October 2026 product audit (docs/audits/product-audit-2026-10.md, finding 16) found no review loop. Each render overwrote the last. Watch opened the raw MP4 in a browser tab. There was no compare,
- Writing on the pageThe script editor's page view was read-only: US Letter in Courier 12 at the industry's indents, but a click only took the Fountain text there, and the writing happened in that text, flush left, with m
- Writes that do not slow down as a show growsOn 2026-10-12, words-places measured every buildset and every approve validating the whole show. With 38 places on one show, buildset went from 0.2 s to 0.9 s per set as the show filled, and approve f
- The showrunner chat, around the person's own ClaudeStatus: designed 2026-10-15; built slice by slice (session protocol 1.19). Slice 7, the card in Claude's chat and Ask in Claude Code, designed 2026-10-18.
- Sound and delivery: music, singing, directed voices, and renders to specThe October 2026 product audit (docs/audits/product-audit-2026-10.md) found that a musical could not be made (finding 5), that the voice could not be directed (finding 6), that previews were master en
- Translating what the core composesStudio speaks the language a person chooses (Settings › Appearance › Language). Its own words go through RwLang.t, and the core's messages, written whole in the core's source, are found in the catalog
- A take in the character's own voiceStatus: built, 2026-10-12. This is the third product audit's finding 8 (0.12 plan item 5, voice-from-booth). A person could record a line in the booth (m6-recording.md), or have Kokoro or their own El
- A directed cloud voiceStatus: built, 2026-10-10: the core, the command line, Studio's Settings › Voices and the character studio's Voice, and each person's key on the web service. The third product audit's finding 8 (0.12
- Voices by ageStatus: built, 2026-10-14. This is the fourth product audit's finding 3, the voices part (docs/audits/product-audit-2026-10e.md; 0.13 plan item 3, voices-by-age). Free voices for a child and an older
- World kits: a library of set pieces, a piece maker, import and lighting looksStatus: design and build, 2026-10-06. It answers finding 4 of docs/audits/product-audit-2026-10.md, "The starter kits are the limit of every world", and the lighting half of finding 13. Read with docs
Decisions
The architecture decision records: what was chosen, and why.
- ADR-0001: Record architecture decisionsReelwright has several decisions that are expensive to reverse (process split, staging model, schema conventions, determinism guarantees). Parallel contributors, human and AI, need to know what was de
- ADR-0002: Spec-first pipeline and what "deterministic" meansThe brief makes this non-negotiable: AI authors structured, versioned, schema-validated specs; deterministic systems build assets and perform episodes; same specs and seeds give the same assets and fr
- ADR-0003: Two programs: a TypeScript core and a Godot engineThe brief says "Reelwright = editor plugin + runtime + CLI" and "statically typed GDScript unless an ADR justifies C#/GDExtension for a hot path". It also asks for an AI showrunner using the Claude AP
- ADR-0004: 3D stage, 2D characters on camera-facing cardsThe brief starts with 2D cutout characters (Skeleton2D, named parts) and adds 3D later. It also asks for camera type, lens and move per shot; marks, entrances and sightlines; the 180-degree rule, shot
- ADR-0005: Schema conventionsSpecs are written by an LLM (via strict tool inputs or structured outputs), by samplers, by people in a text editor, and by UI panels. They are read by two languages. Claude's structured outputs accep
- ADR-0006: Episode IR = performance + coverage, with relative timingThe director turns a screenplay into scenes, shots, blocking, camera, transitions, timing and emotion per line. Two facts shape the format:
- ADR-0007: Versioned builders and canon locksLocked instances are canon and must never be silently regenerated. But the code that turns an instance into a rig, a set or a frame will keep improving: better line taper, a new eye style, a fix to sk
- ADR-0008: Rendering: frame server first, Movie Maker as a checked alternativeThe brief specifies Godot's Movie Maker mode (--write-movie), headless-capable, with ffmpeg for muxing. Research against Godot 4.7.2 source and test renders on macOS (Metal) and Ubuntu 24.04 (Mesa) fo
- ADR-0009: Voices and lip sync as provider chains
- ADR-0010: Engine code standards and test toolingThe brief asks for statically typed GDScript, gdUnit4 or GUT, golden-frame tests, lint in CI, and a CLI. What we verified on Godot 4.7.2:
- ADR-0011: One UI, two hosts: Reelwright Studio and the Godot editor pluginThe brief puts the showrunner chat and the timeline editor inside the Godot editor. That serves people who already live in Godot. For someone who just wants to run a show, the editor is a lot of unrel
Reference
Generated from the code: every command, showrunner tool and document kind.