Skip to content

Films: self-contained works produced at three levels, with a cut editor - #99

Merged
phoebus-84 merged 17 commits into
mainfrom
feat/film-projects
Nov 16, 2026
Merged

phoebus-84 merged 17 commits into
mainfrom
feat/film-projects

Conversation

@phoebus-84

Copy link
Copy Markdown
Owner

What this adds

The studio made serialised content: a channel keeps producing episodes of a series. This adds the other kind of work — a film: one self-contained piece, short or feature length, made from real footage, stock, generated and programmed material, with recorded or generated dialogue, sound and music, edited on a timeline and rendered with FFmpeg. It can be produced unattended, or directed by a person at any level and granularity.

The decision record is ADR-0050.

A film is produced at three levels

library/<film>/                 film.yaml · bible/ characters/ locations/ footage/ music/ …
  artifacts/cut.json  output/   the film: its scenes' renders, music, the mix
  scenes/<scene>/               scene.yaml
    artifacts/cut.json  output/ the scene: its shots' renders, dialogue, ambience
    shots/<shot>/               shot.yaml
      assets/  artifacts/cut.json  output/   the shot: its take, trimmed and graded

The hierarchy is film / scene / shot; sequences and acts group scenes in film.yaml rather than being a directory level. Knowledge lives at every level, as it does for a channel.

Each level is a production unit like an episode — its own pipeline state, journal, approvals, budget view and renders — addressed with the three positions every tool and route already takes, with _ for the level itself (tide/010-shore/_ is a scene). Nothing that worked on an episode needed a second code path.

A shot's render is a source of its scene's cut, and a scene's of the film's. Freshness is derived from fingerprints, so a change to one shot re-renders that shot and re-joins what is above it — not the film.

By layer

  • Contracts — Film, Scene, Shot manifests; delivery formats; the CutTimeline (tracks, clips in frames, trims, speed, transitions, picture and sound effects, fades, ducking, markers, master); layout paths for films.
  • @av/video-composer — the cut renderer: 44 effects with declared parameters, dissolves/fades/wipes, a mix with ducking and loudness, the timeline rendered in windows kept by content hash, one composed frame on demand, contact sheets, cut detection, proxies. It knows nothing of films.
  • @studio/film (new) — units and manifests, cut store with revisions and locks, assembly, cascading render and freshness, footage ingest and log, the film tree.
  • Pipelines — film-project, film-scene, film-shot, with -auto and -directed variants that differ only in where they wait for a person; a unit's pipeline.yaml names its own and the one the levels under it run. A film's budget covers every unit under it.
  • Agent — 14 film tools (pva_create_film … pva_render_cut), written once and served to Pi and to Claude Code; seven skills: film-producer, film-development, film-breakdown, footage-ingest, shot-production, film-sound, film-editing.
  • Gateway — films in the library listing; film routes for the tree, manifests, who decides, footage, the cut (revision-checked), a composed frame, and renders with progress over the event stream.
  • Web — below.

The browser studio

  • Films are listed apart from channels and started from the library. A film opens on its board: scenes and shots in running order, where each stands (a mark and a word, never colour alone), and what stands between the film and its render. A scene opens on its shot list, a shot on its plan and takes. Manifests are forms; Who decides sets the pipelines per level; Footage shows the log with sheets and proxies.
  • Cut is one editor at all three levels: sources, monitor, multitrack timeline (drag, trim, snap, split, lock, keyboard for everything), and an inspector for the clip, track or master drawn from the renderer's own effect catalog. The monitor shows the draft played from its sources, the unit's render, or one frame composed with every effect — and says which. A person edits a draft with undo; a save names the revision it was made on, so neither a person nor the agent overwrites the other.
  • Room to work — focus mode (⌘) puts both side panels away; the agent bar folds to a line; the inspector panel becomes the cut's inspector while a cut is showing; layout is remembered.
  • Structured files — JSON and YAML open as fields (tables for lists of records, typed inputs, YAML comments kept) with the source one click away.

Fixed on the way

  • Closing a side panel pushed the canvas into the divider's 14px column.
  • A YAML file could be edited but had no Save.
  • The library was read with one request after another; it is read in parallel.
  • A runtime test ran a whole stage on a 40 ms lease and failed about one time in two on a loaded machine, on main too; its lease is longer.

How it was checked

  • npm run check passes (paths, boundaries, contracts, pipelines, docs, typecheck, every package's tests), as do the web app's svelte-check, tsc and eslint.
  • The cut renderer's tests render with real FFmpeg; @studio/film's cover create → assemble → cascade render → staleness → locks → ingest.
  • In a browser against a demo film: edit a clip, add an effect, undo/redo, save, compose a frame, render with cascade, play the draft and the render.

Not in this PR

  • Keyframed effect parameters, multi-camera sync, subtitles as a track, EDL/OTIO interchange.
  • Music is brought in, licensed or made as procedural beds; there is no composing model.
  • The agent reviews a render from a contact sheet and measured loudness. It cannot hear a mix, and the review record says what it could not check.
  • Series episodes keep the edit timeline and Remotion; nothing about them changes.

🤖 Generated with Claude Code

phoebus-84 and others added 17 commits November 11, 2026 14:33
A film is the other kind of project a library holds (ADR-0050): a
directory with a film.yaml, produced at three levels addressed with the
three positions a channel's are. layout.mjs reads the kind from disk;
`_` names a level's own unit. film.mjs and cut-timeline.mjs are the
manifests' and the cut's contracts, readable in the browser.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Clips of picture and sound on tracks, rendered by FFmpeg: trims, speed,
fit, opacity, dissolves, fades and wipes, a catalog of picture and sound
effects, ducking, a mix mastered to a loudness target. Rendered window
by window and kept between renders, so a changed shot re-renders the
windows it is in. Stills, contact sheets, cut detection and proxies for
reading footage before it is cut.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@studio/film: making films, scenes and shots; a cut stored with counted
revisions and edited by operations that hold together; clips a person
locked left to the person; assembling a shot from its media, a scene
from its shots, the film from its scenes; rendering with a cascade that
renders exactly what is not fresh; footage ingest with sheets, cuts,
proxies and loudness; the film as a tree with where each unit stands.

A film's budget is one purse: its ledger is the journal of the level
that declares it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…at renders a cut

film-project, film-scene and film-shot, each with an automatic variant
(and a directed one for shots). A level's pipeline.yaml names the
pipeline of the levels below it (scenes:, shots:), so one film can be
automatic in most shots and directed by a person in one scene. The
cut-render adapter performs every film render stage.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
pva_create_film/scene/shot, pva_film (the film in running order and what
stands between it and its render), pva_update_unit, pva_ingest_footage,
pva_footage, pva_inspect_media, pva_assemble_cut, pva_edit_cut,
pva_check_cut, pva_render_cut, pva_cut_frame, pva_cut_effects. The
studio's other tools reach a film's units as channel/series/episode,
with _ for the level itself.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A film is listed beside the channels with its kind; its scenes come in
running order and its shots in cutting order, each with the state of its
cut and render. /api/films/:film/tree is the film at a glance; a unit's
manifest and cut are read and written through their contracts, a cut is
assembled, shown at a frame and rendered in the background with progress
on the event bus.

Review threads are kept inside the episode: they were still written to
the layout-1 path, outside it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… under it; a still per render

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The renderer keeps its rendered windows under .cut/ and a unit's locks
under .locks/; a render in progress writes *.partial.mp4. None of them is
something a person opens, so the default ignore rules leave them out.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A JSON or YAML file opens as its fields: a number is typed as a number, a
long text gets room, a list of small records is a table, and anything that
holds more opens and closes, so a long file is first an outline. An edit
changes the one field it names and rewrites the text around it as it was;
for YAML the comments and the order of the keys survive. The source is one
click away, and is where a file that does not parse is fixed.

A pipeline manifest keeps its own view: it has a chain to draw.

Whether a file can be saved is the artifact's declaration, not the name of
the viewer it was narrowed to: a YAML file could be edited and had no Save.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…he cut

A film is listed apart from the channels and opens on its board: its
scenes in running order, each with its shots, where each stands between
its cut and its render, and what stands between the film and its own. A
scene opens on its shot list, a shot on its plan and its takes. Each level
edits its manifest as a form, says who decides at it and under it, and
renders. A film is started from the library.

The cut is one editor at the three levels: sources (the units under it,
its files, the film's footage, a colour), a monitor, the timeline, and an
inspector for the clip, the track or the whole cut, with the renderer's
own effect catalog. The monitor shows the draft played from its sources,
the unit's render, or one frame composed with every effect, and says which.
A person edits a draft with undo; a save names the revision it was made
on, so an edit the agent made meanwhile is never overwritten.

The shell gives the work its room: focus puts both side panels away
(Cmd-\), the agent bar folds to one line, and the inspector panel is the
cut's inspector while a cut is showing. A closed panel no longer pushes
the canvas into the divider's column. In a film the inspector, the
palette and the agent bar say film, scene and shot.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The film pipelines named skills that did not exist. They do now:
film-producer (the three levels, how a unit is addressed, who decides,
what to do next from where each unit stands), film-development (treatment
and screenplay, to length), film-breakdown (the bible, scenes and shots as
units, a scene's direction), footage-ingest (bringing real material in and
logging what it shows), shot-production (a shot planned, its takes made or
found, each looked at), film-sound (dialogue, ambience, effects, music and
how they sit in a mix) and film-editing (the cut's operations and rules,
effects, rendering and reviewing a render).

The executive producer says what a film is and which tools make one, and
the film package has its generated page.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
"stops rather than dispatching when the stage-started write is dropped"
gave its service a 40 ms lease, and then ran a whole stage on it: on a
loaded machine the run that follows the lapse lost its own lease before it
finished, and the test failed one time in two — on main as well. The lease
is 400 ms and the wait for its lapse 450.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… squeezed to a letter

The log entry's last column could not shrink below its content and left
the panel. The agent bar's status gave all its room to the suggestions.
The empty canvas names films among the things to choose.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The decision record for films: produced at three levels, each a unit with
its own cut and renders, joined by a cut whose clips are the renders of the
units under it. The workspace contract has a film's layout, the pipeline
model its families and how a level says who decides, the running guide the
film tools and what the studio shows, the gateway's API its film routes,
and the web operator's guide the board, the cut and the keys.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
A film has no channel.md and no series/. The doctor checked every project
of the library as a channel, so a library with one film reported two
errors for it and was never healthy. A directory with a film.yaml is a
film: it is checked for the container its scenes live in.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…he library

The doctor exits non-zero when the library has an error, and health read
that exit as the runtime being down: one old episode short of a folder
made the whole studio "unhealthy". When the doctor answered with a report
the runtime is ready, and the count of what it found is said beside it.
It is down only when the command fails without one.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@phoebus-84

Copy link
Copy Markdown
Owner Author

Integration validation: npm run check passes (22 workspace test runs), and npm run docs:build passes. Fixed a pre-existing S3 cached-unreachable path that opened an unconsumed file stream, producing an unhandled asynchronous error after fixture cleanup; regression coverage now uses a nonexistent source to ensure the file is never opened. The single-frame renderer timeout seen in the first run did not reproduce in isolation or in the full rerun.

@phoebus-84
phoebus-84 merged commit dab5baf into main Nov 16, 2026
71 of 72 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant