fframes studio

INSIDE FFRAMES STUDIO

An agent edits.
Studio checks.

A change starts as a draft. Follow the checks that stand between an agent’s edit and the revision you see.

Follow the draft
THE OPERATING PRINCIPLE

Your working preview stays available while Studio prepares the next revision.

Current revision Candidate Accepted

THE FFRAMES RENDERING ENGINE

From Rust code
to a finished video.

Your assistant writes the animation in Rust. fframes turns that description into pictures, one frame at a time, then combines the frames and audio into a video file.

ONE ANIMATION, ONE FRAME AT A TIME SCROLL TO ADVANCE THE FRAME · ILLUSTRATION
01Describe the frame
For each frame, render_frame samples the slide animation to get the square’s x position and returns an svgr! tree with a static title and a square at that position. The static title is cached; the square is rebuilt every frame. fn render_frame(&self, frame, ctx) let x = frame.animate(&self.slide); svgr!(<svg …> <text>"Hello"</text> <rect x={x} … /></svg>) frame 89 · 2.97 s → x = 220.0 <text> static · cached <rect x={x}> rebuilt each frame

A tree of drawing instructions, not pixels yet.

02Draw with Skia
Skia draws the tree into a frame: the cached title is reused and the green square is drawn at this frame’s x position, on Metal or Vulkan when a supported GPU is available, otherwise with tiny-skia on the CPU. FRAME 89 / 89 30 FPS Hello CACHED GPU · Metal / Vulkan CPU · tiny-skia

This frame’s x becomes pixels.

03Encode with FFmpeg
The finished frames join the sequence in time order. FFmpeg encodes them, mixes in the audio and writes one video file. Frames in time order + audio FFmpeg · encode + mux video.mp4 90 / 90

Pictures and sound become one file.

No usable GPU? Automatic mode takes the CPU path: tiny-skia draws the frames; Skia shader effects are unavailable.
Scrolling advances one shared clock through 90 frames. Each frame, render_frame samples the animation, the renderer draws the tree, and the frame joins the sequence that FFmpeg encodes. Scroll back to reverse. This illustrates the rendering stages, not measured speed or a live export. Real renders draw frames on several threads, and rendering and encoding may use different hardware.
  1. 01 / DESCRIBE EACH FRAME

    Rust sets the scene.

    At each point in time, the video’s render_frame function describes the text, shapes, images and their positions. The svgr! macro builds an SVG-style tree of drawing instructions. Animation changes those values as time advances.

  2. 02 / DRAW THE PICTURE

    Skia draws on the GPU.

    With a supported GPU backend, Skia—the graphics library—draws those instructions into a frame on the graphics card. fframes supports Metal on macOS and Vulkan on other supported builds. Skia also runs custom shader effects, programs that calculate the colors of pixels.

  3. 03 / SAVE THE VIDEO

    FFmpeg encodes the result.

    Rendering creates the pictures; encoding compresses them for playback. fframes uses FFmpeg to encode the frames and combine them with the audio. Studio’s export options come from the project’s worker, including the formats and sizes it supports.

What if there is no usable GPU? Studio’s automatic mode tries Skia on the GPU, then falls back to the built-in tiny-skia CPU renderer. That fallback cannot draw Skia shader effects, so Studio reports the missing capability. A separate Skia CPU mode is also available. Backend availability depends on the project’s SDK and the machine.

GPU rendering and hardware video encoding are separate. Some compatible backend and encoder combinations can pass frames directly on the GPU; other paths copy pixels back to CPU memory. Using a GPU does not mean every export stays on it.

Read the renderer implementation

A CONNECTED WORKSPACE

Separate processes.
Clear responsibilities.

The app coordinates the work. Your coding agent edits a draft in its own process. Your video runs in a separate preview worker.

WHO DOES WHATSCROLL TO FOLLOW · ILLUSTRATION
Studio, the coding agent and preview worker are separate processes Studio holds the UI, engine, task workflow, build service, journal and read-only broker. A managed coding-agent process edits its draft. The build service prepares a separate preview worker. Directed paths illustrate launch, tool calls and preview preparation. STUDIO APPLICATION UI + interaction Draws; forwards input Engine state Serialized commands Agent workflow Task + draft lifecycle Build service Shared, keyed builds Preparing preview… Journal + store History + recovery Read-only broker Project facts + output Coding agent Managed child process Edits its draft copy Agent draft Separate working files + src/lib.rs edited Preview worker Your compiled video Frames · timing · audio TOOLS SEPARATE WORKER, SEPARATE PROCESS 01 Studio coordinates the work 02 The workflow launches the coding agent 03 The agent edits its own draft 04 It asks the read-only broker for project facts 05 The build service prepares the preview worker
Studio holds the UI, engine, task workflow, build service, journal and read-only broker. A managed coding-agent process edits its draft. The build service prepares a separate preview worker. Directed paths illustrate launch, tool calls and preview preparation. STUDIO APPLICATION UI + interaction Draws; forwards input Engine state Serialized commands Journal + store History + recovery Read-only broker Project facts + output Agent workflow Task + draft lifecycle Build service Shared builds Preparing preview… Coding agent Managed child process; edits its draft copy Preview worker Your compiled video: frames, timing, audio Agent draft Separate working files + src/lib.rs edited TOOLS SEPARATE WORKER, SEPARATE PROCESS 01 Studio coordinates the work 02 The workflow launches the coding agent 03 The agent edits its own draft 04 It asks the read-only broker for project facts 05 The build service prepares the preview worker
Responsibility map, not a complete call graph. The agent owns draft edits; the preview worker remains separate from the Studio UI.

01 / THE EDIT TRANSACTION

A draft goes in.
A revision comes out.

Five stages on the successful path. Scroll to move the candidate through them, or jump to a stage.

01 / CAPTURE

Freeze what
will be checked.

After the agent finishes and its writer is quiet, Studio captures the draft twice. Both captures must match.

A changing working copy cannot become the candidate that passes validation.

02 / BUILD

Build the
captured candidate.

Studio compiles in an isolated copy bound to the project’s managed SDK. The build must identify the candidate it actually compiled.

A cached compiler success alone is not an acceptance proof.

03 / INSPECT

Check the result.
Report the coverage.

The worker supplies inspected and rendered frames, range boundaries, and audio checks. Diagnostics and capability gaps stay in the report.

A compile or validation failure can trigger at most one automatic repair turn. Checks do not guarantee that every frame is correct.

04 / REVIEW POLICY

Apply by policy.
Review by choice.

The default policy applies a validated candidate automatically. Manual review waits for Apply; you can inspect diffs and keep a subset of files.

A selected subset is validated again before it can be applied.

05 / ACCEPT

Write the revision.
Keep a way back.

A journaled file-set transaction publishes the accepted changes. If an outside writer races with it, Studio preserves the variants and stops with a conflict.

Undo and per-file revert pass validation too. Revert is refused if the file changed since.

THE CANDIDATE’S PATHILLUSTRATION · SUCCESSFUL PATH
From captured draft to accepted revision The candidate rises through capture, build, inspection, review policy and acceptance. Manual review is optional. Failure retains a draft; successful acceptance publishes a journaled file-set transaction. This is an architecture illustration. 01 / Capture twice Matching, immutable bytes 02 / Build Isolated copy · pinned SDK 03 / Inspect Frames · boundaries · audio 04 / Review policy Automatic, or manual Apply 05 / Accept Journaled file-set transaction ACCEPTED REVISION CAPTURED AGENT DRAFT Failure keeps draft STAGES, NOT ELAPSED TIME · REVIEW IS OPTIONAL
The candidate rises through capture, build, inspection, review policy and acceptance. Manual review is optional. Failure retains a draft; successful acceptance publishes a journaled file-set transaction. This is an architecture illustration. ACCEPTED REVISION 01 / Capture twice Matching, immutable bytes 02 / Build Isolated copy · pinned SDK 03 / Inspect Frames · boundaries · audio 04 / Review policy Automatic, or manual Apply 05 / Accept Journaled file-set transaction CAPTURED AGENT DRAFT Failure keeps draft
Each plane represents a stage, not a physical component or an application screen. Manual review is optional.
WHY CAPTURE TWICE?SCROLL TO FOLLOW · ILLUSTRATION
Only matching captures proceed to validation Once the writer is quiescent, Studio captures the draft twice. Matching bytes can proceed to validation. Any difference fails the capture. Writer ready Draft is ready for capture quiet Capture A Captured bytes 7f 3a c1 09 e4 52 Capture B Captured bytes 7f 3a c1 09 e4 52 = = = = = = Same bytes? Yes → validate No → refuse A CHANGING DRAFT DOES NOT PROCEED 01 Writer goes quiet 02 Capture A 03 Capture B 04 Compare byte by byte 05 Match → validate
Once the writer is quiescent, Studio captures the draft twice. Matching bytes can proceed to validation. Any difference fails the capture. Writer ready Draft is ready for capture quiet Capture A Captured bytes 7f 3a c1 09 e4 52 Capture B Captured bytes 7f 3a c1 09 e4 52 = = = = = = Same bytes? Yes → validate · No → refuse A CHANGING DRAFT DOES NOT PROCEED 01 Writer goes quiet 02 Capture A 03 Capture B 04 Compare byte by byte 05 Match → validate
Two captures are compared after writer quiescence. A compile success cannot replace this capture check.
TWO POLICIES, ONE ACCEPTANCE BOUNDARYSCROLL TO FOLLOW · ILLUSTRATION
Automatic application or manual Apply The default policy applies a validated candidate automatically. The optional manual policy waits for Apply. Both publish through the same guarded transaction. A changed file subset is validated again. Valid candidate Checks completed for this candidate Automatic Default policy Applies on its own Manual Wait for Apply Apply OR GUARDS Accepted Guarded file-set publication SUBSET CHANGED? VALIDATE THAT SUBSET AGAIN. 01 A candidate passed its checks 02 Automatic: applied by default 03 Manual: waits for Apply 04 You press Apply 05 Both pass the same guards
The default policy applies a validated candidate automatically. The optional manual policy waits for Apply. Both publish through the same guarded transaction. A changed file subset is validated again. Valid candidate Checks completed for this candidate Automatic Default policy Applies on its own Manual Wait for Apply Apply OR GUARDS Accepted Guarded file-set publication SUBSET CHANGED? VALIDATE THAT SUBSET AGAIN. 01 A candidate passed its checks 02 Automatic: applied by default 03 Manual: waits for Apply 04 You press Apply 05 Both pass the same guards
Alternative policies, not sequential steps. Manual review is optional; neither route bypasses the publication guards.

02 / GROUNDING

From a visible object
to useful context.

When the worker supports object selection, a click uses the object map attached to that exact frame. Topmost paint order wins; cycling reveals overlapping objects.

Stable editor keys identify objects. A source anchor is optional and must be registered by the project; Studio does not infer an exact source location for every pixel.

THE SELECTION BECOMES CONTEXTSCROLL TO FOLLOW · ILLUSTRATION
A selected title supplies project context A selected title supplies a stable editor key. A registered source anchor can add source context. It is optional and supplied by the project. 01 / SELECTED FRAME Hello. Selected object · headline 02 / OBJECT IDENTITY intro / starter-title headline / primary From this frame’s object map 03 / SOURCE ANCHOR src/lib.rs render_frame Only if registered SELECTION PROVIDES CONTEXT. IT DOES NOT EDIT SOURCE. 01 Click an object in the frame 02 Studio resolves its stable editor key 03 A registered anchor can add a source location
A selected title supplies a stable editor key. A registered source anchor can add source context. It is optional and supplied by the project. 01 / SELECTED FRAME Hello. Selected object · headline 02 / OBJECT IDENTITY intro / starter-title headline / primary From this frame’s object map 03 / SOURCE ANCHOR src/lib.rs render_frame Only if registered SELECTION PROVIDES CONTEXT. IT DOES NOT EDIT SOURCE. 01 Click an object in the frame 02 Studio resolves its stable editor key 03 A registered anchor can add a source location
Frame → stable object identity → optional source anchor. Without a registered anchor, Studio does not infer a source location.
PROJECT-SUPPLIED IDENTITY

The project registers a stable key and, optionally, an anchor. This excerpt illustrates the API; it is not a complete video. 

let title_key = EditorObjectKey::new(
    scene_key, "starter-title", "headline", "primary",
)?.with_source_anchor(
    "src/lib.rs", "render_frame", Some("title-marker"),
)?;
let title_id = title_key.render_id();

03 / PROJECT TOOLS

A way to look.
Nine read-only tools.

Studio’s tool broker lets your agent inspect the project and rendered output. These nine tools do not provide shell execution, file writes, or export.

The agent’s own tools can still edit files or run commands, subject to your permission policy. Read-only describes Studio’s broker, not the entire agent.

LOOK THROUGH THE BROKERSCROLL TO FOLLOW · ILLUSTRATION
The agent requests read-only project information The coding agent requests information from Studio's read-only broker. Project facts and rendered output return to the agent. The agent's own editing tools remain separate. CODING AGENT request STUDIO BROKER 01 project_context 02 selection_context 03 source_lookup 04 timeline 05 render_frame 06 render_strip 07 inspect 08 style_context 09 build_status 09 read-only tools No file writes PROJECT Frames Timing Checks PROJECT CONTEXT RETURNS TO THE AGENT 01 The agent sends a request 02 The broker offers nine read-only tools 03 One call reads project facts or output 04 The answer returns to the agent
The coding agent requests information from Studio's read-only broker. Project facts and rendered output return to the agent. The agent's own editing tools remain separate. CODING AGENT request STUDIO BROKER 01 project_context 02 selection_context 03 source_lookup 04 timeline 05 render_frame 06 render_strip 07 inspect 08 style_context 09 build_status 09 read-only tools No file writes PROJECT Frames Timing Checks PROJECT CONTEXT RETURNS TO THE AGENT 01 The agent sends a request 02 The broker offers nine read-only tools 03 One call reads project facts or output 04 The answer returns to the agent
Read-only applies to Studio’s broker. The agent’s own tools can edit under your permission policy.
  • project_contextProject facts
  • selection_contextFrozen task scope
  • source_lookupVerified source snippets
  • timelineScene timing
  • render_frameA rendered frame
  • render_stripA frame contact sheet
  • inspectFrame diagnostics
  • style_contextStyle context
  • build_statusBuild status

BROKER BOUNDARY   /   No shell · no writes · no export

04 / PREVIEW READINESS

Prepare the whole revision.
Then switch.

The current build keeps playing while the next one is prepared. Worker, frame, and audio switch together at the playhead, once the revision is ready.

Failed or cancelled builds keep the previous preview. The diagram shows a successful preparation; its spacing does not represent elapsed build time.

ONE COORDINATED HANDOFFSCROLL TO FOLLOW · ILLUSTRATION
Prepare a revision before switching the preview The current revision remains available while the candidate compiles and prepares its worker, frame and audio. Only once ready can the revision replace it at the playhead. Diagram spacing is illustrative, not elapsed build time. CURRENT CANDIDATE Working preview remains available Hello. Make your move. Compile Prepare worker, frame, audio Ready to replace SWITCH AT THE PLAYHEAD Worker · frame · audio together Compile alone is not readiness.
The current revision remains available while the candidate compiles and prepares its worker, frame and audio. Only once ready can the revision replace it at the playhead. Diagram spacing is illustrative, not elapsed build time. CURRENT Working preview remains available Hello. Make your move. CANDIDATE Compile alone is not readiness. Compile Prepare worker, frame, audio Ready to replace SWITCH AT THE PLAYHEAD Worker · frame · audio together
The old revision remains available through compile and preparation. Readiness is more than a compiler success.

05 / WRITER CONTAINMENT

A process boundary.
A condition for capture.

Windows uses a job object; Linux and macOS use a process group with escape checks. If Studio observes a writer escape, its candidate is refused.

Containment is not a general sandbox. Work performed by pre-existing services on an agent’s behalf is outside the observed process group or job.

OBSERVED ESCAPE → CAPTURE REFUSEDSCROLL TO FOLLOW · ILLUSTRATION
An observed writer escape blocks candidate capture The agent and child processes are tracked in a Windows job object or a process group with escape checks. If Studio observes a writer escape, its candidate is refused. This is not a general-purpose sandbox. OBSERVED WRITER PROCESS TREE Agent Managed writer Child process For example: node Child process For example: cargo Observed escape Outside tracked tree Candidate refused CAPTURE DOES NOT PROCEED WINDOWS: JOB OBJECT · LINUX/macOS: PROCESS GROUP + CHECKS 01 The agent starts child processes 02 Studio tracks the agent and its children 03 A writer leaves the tree 04 Its candidate is refused
The agent and child processes are tracked in a Windows job object or a process group with escape checks. If Studio observes a writer escape, its candidate is refused. This is not a general-purpose sandbox. OBSERVED WRITER PROCESS TREE Agent Managed writer Child process For example: cargo Child process For example: node Observed escape Outside tracked tree Candidate refused CAPTURE DOES NOT PROCEED WINDOWS: JOB OBJECT LINUX/macOS: PROCESS GROUP + CHECKS 01 The agent starts child processes 02 Studio tracks the agent and its children 03 A writer leaves the tree 04 Its candidate is refused
The dashed line is an observed process boundary, not a universal sandbox. Work delegated to pre-existing services can be outside this boundary.

06 / RECOVERY

Keep the accepted revision.
Retain the unfinished work.

After a crash, Studio recovers to the last accepted revision, marks unfinished work interrupted, and offers the retained draft. Process exit is not proof of a successful build or apply.

An older Studio file format is refused and left unchanged. Studio does not silently migrate it.

Read the architecture and source references
AN INTERRUPTED TASK IS NOT AN ACCEPTED EDITSCROLL TO FOLLOW · ILLUSTRATION
Recovery keeps the accepted revision and retains the draft After an interruption, the last accepted revision remains the recovery point. Unfinished work is marked interrupted and its draft retained. The draft does not become the accepted revision. ACCEPTED TASK STARTS INTERRUPTION RECOVERY ACCEPTED REVISION Kept. Recovery baseline UNFINISHED TASK Editing its draft… Marked interrupted RETAINED DRAFT Draft remains. Available after recovery ACCEPTED FILES ARE THE BASELINE RETAINED DRAFT ≠ ACCEPTED REVISION 01 You accept a revision 02 A new task edits its own draft 03 The task is interrupted before it finishes 04 Recovery restores the accepted revision and keeps the draft
After an interruption, the last accepted revision remains the recovery point. Unfinished work is marked interrupted and its draft retained. The draft does not become the accepted revision. ACCEPTED TASK STARTS INTERRUPTION RECOVERY ACCEPTED REVISION Kept. Recovery baseline UNFINISHED TASK Editing its draft… Marked interrupted RETAINED DRAFT Draft remains. Available after recovery ACCEPTED FILES ARE THE BASELINE RETAINED DRAFT ≠ ACCEPTED REVISION 01 You accept a revision 02 A new task edits its own draft 03 The task is interrupted before it finishes 04 Recovery restores the accepted revision and keeps the draft
Two separate outcomes: recover the accepted revision and retain the interrupted draft. Retaining a draft does not accept it.
TIMING HAS ITS OWN DOCUMENTSCROLL TO FOLLOW · ILLUSTRATION
Timeline edits reuse the current Rust build Compiled scenes supply stable keys. Timeline gestures update order, splits and trims in timeline.json. The worker applies timing with the same source build. TIMELINE · SPLIT · MOVE · TRIM · UNDO / REDO A / Intro TRIM B / Main B₂ C / Outro Compiled scenes Stable scene keys Current built source timeline.json Order · splits Trims · separate timing revision REV 1 REV 2 REV 3 REV 4 Preview worker Applies timing Same Rust build TIMING CHANGE ≠ SOURCE REBUILD 01 Scenes in code order 02 Split Main in two 03 Move Outro to the front 04 Trim the end of Intro 05 Worker applies it · same build
Compiled scenes supply stable keys. Timeline gestures update order, splits and trims in timeline.json. The worker applies timing with the same source build. TIMELINE · SPLIT · MOVE · TRIM · UNDO / REDO A / Intro TRIM B / Main B₂ C / Outro Compiled scenes Stable scene keys · current built source timeline.json Order · splits Trims · separate timing revision REV 1 REV 2 REV 3 REV 4 Preview worker Applies timing Same Rust build TIMING CHANGE ≠ SOURCE REBUILD 01 Scenes in code order 02 Split Main in two 03 Move Outro to the front 04 Trim the end of Intro 05 Worker applies it · same build
Timing-only changes reuse the current build. Source changes still need compilation; timing edits are unavailable during an agent task.
A FROZEN PROJECT, THE SESSION’S TIMINGSCROLL TO FOLLOW · ILLUSTRATION
Export combines a frozen project with session timing The worker reports supported formats. Export uses a frozen project revision plus the current session timing document. Its worker encoder renders the chosen output with progress and cancellation. Worker formats Supported formats Export settings Format · size · fps Frozen project Code revision Immutable input Session timing Current timeline Render job Worker encoder Progress + Cancel Video file 01 The worker reports its formats 02 Settings pick format · size · fps 03 A frozen project and the session’s timing 04 The worker encoder renders 05 A video file is written
The worker reports supported formats. Export uses a frozen project revision plus the current session timing document. Its worker encoder renders the chosen output with progress and cancellation. Worker formats Supported formats Export settings Format · size · fps Frozen project Code revision Immutable input Session timing Current timeline Render job Worker encoder Progress + Cancel Video file 01 The worker reports its formats 02 Settings pick format · size · fps 03 A frozen project and the session’s timing 04 The worker encoder renders 05 A video file is written
Formats are worker-dependent. The frozen project's source and the session’s timing are separate inputs; rendering does not hold the live project open.