D10 The Review Room: A Human-in-the-Loop Backend for Previewing, Editing Lines, and Regenerating a Single Shot

Today's Goals

Build a review page that displays assets shot by shot, supporting preview, line editing, and single-shot regeneration
Feed human edits back into the workflow, so regeneration only affects the downstream nodes it touches
Explain what version comparison and rollback need to store, and the trade-offs of a canvas-style workbench

Yesterday pushed output to several episodes in parallel; today we face its first consequence: once volume rises, human checking becomes the new bottleneck. When you finish, scroll back up and tick the three goals off.

Plain-Language Walkthrough

The screening room: where the human steps in

A proper production has a room called the screening room. It is not on set and not in the edit suite; it exists purely for looking. Director, producer and platform sit together, go through material take by take, and say keep this one, reshoot that one, change that line.

The room's existence is itself an engineering judgment: a film is not checked after shooting, it is checked while shooting. Wait until everything is shot and discover the actor wore the wrong jacket in shot three, and every shot that cuts against it was shot for nothing.

A generative pipeline is the same, only harsher — every step costs money, and rework is written straight onto the bill. So the question is not whether a human should intervene but where.

Three natural checkpoints, judged by how expensive that step's downstream is:

First, after the script is locked and before any asset is generated. Nothing has been spent yet, changing a line costs approximately zero, and it sets the direction of every asset that follows. This is the highest-value checkpoint and the easiest to skip, because there is no picture yet and it looks like there is "nothing to review."

Second, after first frames exist and before video generation. First frames are the cheapest tier on this line and video is the most expensive, one to two orders of magnitude apart for the same shot. Generating video from a bad first frame means spending the big money on a discarded image. This is the single highest-value human gate on the whole line.

Third, after the cut is assembled and before publishing. This one catches risk rather than quality: content safety, copyright, labeling compliance. Tomorrow covers it in full.

Of the three, today's console mainly serves the second: look at assets shot by shot and stop the line at any point.

Minimal information architecture: run, episode, shot

What the console looks like depends on how many layers you split the information into. This line's natural structure has three: a run, an episode, a shot.

A run is the outer layer, one runId and one directory. It answers "when was this batch produced and from what input."

An episode is the middle layer and the unit people actually care about. Operations does not ask whether shot seventeen is done; they ask whether episode three can ship.

A shot is the innermost layer and the only unit that can be redone on its own. This is the judgment that keeps recurring in this course: if the smallest redo unit is an episode, changing one line re-burns forty shots of video; if it is a shot, changing one line affects one shot's dubbing.

Lay the page out by shot, five things per card: the first frame, the shot video, the line, the voice audio, and that shot's version list. The page itself need not be complex; hand-written HTML and a few JSON endpoints suffice:

HTMLHTML

<section class="card">
  <h3>s02 - close - 4s</h3>
  <img src="/media/.../first-frame.png" alt="s02 first frame" />
  <video src="/media/.../clip.mp4" controls></video>
  <audio src="/media/.../voice-1.mp3" controls></audio>
  <textarea rows="2">Five minutes from now? That is impossible</textarea>
  <button>Compute blast radius</button>
  <button class="primary">Regenerate affected nodes</button>
</section>

The lab deliberately introduces no frontend framework: node:http serves it, the page is a single HTML file, and it still runs with pnpm install --ignore-workspace && pnpm start. The reason is that today teaches interfaces and data shapes, not build tooling. Ninety percent of a review console's value is in the backend data design; the frontend merely displays it.

The blast radius: who is affected by one changed line

When a human clicks regenerate, the system must answer one question: what did this edit invalidate?

The answer is computed from the dependency graph, not guessed. The relationships here are clear: the visual description determines the first frame, the first frame determines the shot video; the line determines the voice; every video and voice together determine the timeline.

So changing one line invalidates that shot's voice and the episode's timeline — because the voice duration changed and later shots' start and end times must be re-laid. The first frame and the video are entirely unaffected, not one frame re-burned. Changing the visual description is the opposite: first frame, video and timeline are invalidated, and the voice is untouched.

Mind the direction of the algorithm: propagate forward along "who depends on me" from the edited node, not upward to find dependencies. Searching upward re-runs unaffected upstream work, and it is the most common way to get this backwards.

affected.js

// Dependency edges: frame -> clip; dialogue -> voice; all clips and voices -> timeline
const graph = [
  { id: 's02:frame', deps: [] },
  { id: 's02:clip', deps: ['s02:frame'] },
  { id: 's02:voice', deps: [] },
  { id: 'episode:timeline', deps: ['s02:clip', 's02:voice'] },
]
 
// Editing dialogue seeds at the voice; editing visual seeds at the frame
const SEED = { dialogue: 'voice', visual: 'frame' }
 
function affectedNodes(graph, shotId, field) {
  const affected = new Set([`${shotId}:${SEED[field]}`])
  // Propagate forward along "who depends on me" until a fixed point
  for (let changed = true; changed; ) {
    changed = false
    for (const n of graph) {
      if (affected.has(n.id)) continue
      if (n.deps.some((d) => affected.has(d))) {
        affected.add(n.id)
        changed = true
      }
    }
  }
  return graph.map((n) => n.id).filter((id) => affected.has(id))
}
// Editing a line -> ['s02:voice', 'episode:timeline']; not one frame of video is re-burned

affected.py

# Dependency edges: frame -> clip; dialogue -> voice; all clips and voices -> timeline
GRAPH = [
    {"id": "s02:frame", "deps": []},
    {"id": "s02:clip", "deps": ["s02:frame"]},
    {"id": "s02:voice", "deps": []},
    {"id": "episode:timeline", "deps": ["s02:clip", "s02:voice"]},
]
 
# Editing dialogue seeds at the voice; editing visual seeds at the frame
SEED = {"dialogue": "voice", "visual": "frame"}
 
 
def affected_nodes(graph, shot_id: str, field: str) -> list[str]:
    affected = {f"{shot_id}:{SEED[field]}"}
    changed = True
    while changed:  # propagate forward along "who depends on me" until a fixed point
        changed = False
        for node in graph:
            if node["id"] in affected:
                continue
            if any(dep in affected for dep in node["deps"]):
                affected.add(node["id"])
                changed = True
    return [n["id"] for n in graph if n["id"] in affected]
 
 
# Editing a line -> ['s02:voice', 'episode:timeline']; no video is re-burned

One step after computing the radius is often missed: unaffected nodes must have their artifacts copied from the previous version, not regenerated. Without that, however accurate your computation, you saved nothing.

And once computed, show the radius to the human before running anything. The console's orange banner reads "pending: dialogue changed; affects s02's voice and the episode timeline." That looks like a mere notice; in practice it is the console's most valuable piece of information, because it tells the human what this edit will cost before they commit. If one changed line means one re-synthesized voice clip, they click without hesitation; if the notice says three shots of video will be re-burned, they will stop and think about whether the change is worth it. Moving the cost in front of the decision beats handing over a bill afterwards.

How do you prove you actually saved? Do not compare file hashes — offline, the same prompt generates a byte-identical placeholder image, so matching hashes prove nothing about whether work was skipped. Count the API calls: the lab's self-check prints "this regeneration made 0 image calls, 0 video calls, 1 speech call," and that evidence holds equally against a real vendor.

A version is not a backup

Someone edits a version, decides it was worse, and wants to go back. That sounds like a backup, and it is not.

A backup means "something broke, bring it back": one recent good state is kept, and after restoring, the old one is gone. A version means "both exist": old and new coexist, can be compared side by side, can be switched between, and which to ship is a human judgment.

Review needs the latter. When the director says "wasn't the earlier one better," you must be able to put both side by side immediately, not offer to restore one so they can look again.

In data terms the difference shows up in three places:

First, artifacts are stored in per-version directories, v1/ and v2/, with nothing deleted. Disk is vastly cheaper than regeneration.

Second, the current version is a pointer, not a copy. Rolling back moves the pointer, touches no files, and is therefore instant and reversible.

Third, each version records what it re-ran and why. Storing artifacts alone is not enough — three days later, when someone asks why version two is better than version one, you need an answer.

version.js

// A shot's state: a list of versions plus a current pointer. Rollback moves the pointer only.
const shotState = {
  current: 2,
  versions: [
    {
      version: 1,
      at: '2026-09-07T10:00:00Z',
      dialogue: 'Five minutes from now? That is impossible',
      artifacts: { 's02:frame': 'shots/s02/v1/first-frame.png', 's02:voice': 'shots/s02/v1/voice-1.mp3' },
      regenerated: ['s02:frame', 's02:clip', 's02:voice'],
      reason: 'initial generation',
    },
    {
      version: 2,
      at: '2026-09-07T10:12:31Z',
      dialogue: 'Five minutes from now? Someone is playing a joke on me',
      artifacts: { 's02:frame': 'shots/s02/v2/first-frame.png', 's02:voice': 'shots/s02/v2/voice-1.mp3' },
      regenerated: ['s02:voice', 'episode:timeline'], // the frame was copied from v1
      reason: 'human edit to dialogue',
    },
  ],
}
 
const rollback = (state, version) => ({ ...state, current: version })

version.py

# A shot's state: a list of versions plus a current pointer. Rollback moves the pointer only.
shot_state = {
    "current": 2,
    "versions": [
        {
            "version": 1,
            "at": "2026-09-07T10:00:00Z",
            "dialogue": "Five minutes from now? That is impossible",
            "artifacts": {
                "s02:frame": "shots/s02/v1/first-frame.png",
                "s02:voice": "shots/s02/v1/voice-1.mp3",
            },
            "regenerated": ["s02:frame", "s02:clip", "s02:voice"],
            "reason": "initial generation",
        },
        {
            "version": 2,
            "at": "2026-09-07T10:12:31Z",
            "dialogue": "Five minutes from now? Someone is playing a joke on me",
            "artifacts": {
                "s02:frame": "shots/s02/v2/first-frame.png",
                "s02:voice": "shots/s02/v2/voice-1.mp3",
            },
            "regenerated": ["s02:voice", "episode:timeline"],  # the frame was copied from v1
            "reason": "human edit to dialogue",
        },
    ],
}
 
 
def rollback(state: dict, version: int) -> dict:
    return {**state, "current": version}

One knock-on effect is easily forgotten: rolling back one shot changes the episode's timeline. If version two's voice is a second longer than version one's, switching back re-lays every later shot's start and end times. So rollback is not only a pointer move; it also recomputes the timeline — which is cheap, being pure local computation.

Canvas or list

Anyone who has seen AI video tools will ask: why not a canvas? The node-graph workbench with dragging and zooming looks far more professional.

A canvas does have something irreplaceable: when the dependency relationships themselves are what the user edits. If users decide which image a shot's first frame comes from, or how two branches merge, then the dependencies are the object of editing and a canvas is their only intuitive expression.

But the price is real:

Interaction cost is high. Doing one "edit line and regenerate" on a canvas means locating the node, opening it, editing, then finding the run button. On a list it is one text field and one button. Review happens hundreds of times a day, and three extra seconds each is half an hour.

Mobile is basically unusable. And review is exactly the kind of task suited to a phone — a producer can go through an episode on the move.

Implementation is an order of magnitude larger. Dragging, zooming, edges, auto-layout, undo and redo all have to be written, and written badly they are painful.

There is a more fundamental difference: review is rhythmic work. People want the next one, the next one, the next one — a conveyor-belt momentum, stopping when something is wrong and continuing after. A list supports that rhythm natively; scrolling is progress. A canvas asks the person to keep relocating themselves in space, and with two hundred nodes spread out, just finding the next shot to look at takes seconds. A tool's shape should follow the rhythm of the work, not the shape of the data.

The criterion is simple: fixed dependencies mean a list; user-editable dependencies mean a canvas. This line's dependencies are fixed — the first frame determines the video, the line determines the voice — and users neither need nor should change that. So this course chooses a list.

Review notes must be structured

One last thing, and the one most often built as decoration: what the human says during review, whether it is stored, and how.

Stored as free text — "the lead's face is a bit off in this shot" — it is useless to the next round of automation, which cannot read it. Stored as structured fields, it is a different matter:

JSONJSON

{
  "shotId": "s03",
  "verdict": "redo",
  "tags": ["face-inconsistent", "subtitle-overflow"],
  "comment": "the lead's face shape does not match the look test",
  "at": "2026-09-07T10:20:00Z"
}

With verdict and tags you can write rules like: a shot tagged face-inconsistent twice in a row stops being auto-retried and is flagged for a human; a character with a significantly higher face-inconsistent rate needs its look test redone.

There is a bonus: structured, these records double as an evaluation set. Accumulate one or two hundred records with a verdict and you have labeled data for "what humans consider acceptable" — and tomorrow, when a vision model scores automatically, the threshold that matches human judgment is found by back-testing against that data rather than guessing. That is another reason to build the console early: from the day it goes live, it accumulates data for you.

That is what "make human judgment reusable by the next round of automation" means — not having a model read human prose, but having the human's notes born in a shape a machine can use. The price is a few more buttons and preset tags on the console instead of one all-purpose text box. Tomorrow's automated QC picks these records up directly: machine-scored conclusions and human review conclusions use the same verdict and tags vocabulary.

Source Reading

Hands-On Lab

🧪 D10 lab: a minimal review backend with preview, line editing, and single-shot regeneration

Code location: labs/ai-drama-pipeline/day-10-review-console

Acceptance criteria:

The self-check prints 7 results, all passing in the solution, with exit code zero.
Editing one line computes affected nodes as exactly "that shot's voice plus the episode timeline," with the first frame and video excluded.
After regeneration, the new version's recorded re-run nodes match the previous step, and the image and video APIs were not called once.
Unaffected shots keep their version numbers, and only the edited shot gains a version two.
Rolling back to version one restores both the line and the voice, while version two's artifacts remain on disk and can be switched back to.

This is the only day whose lab starts an HTTP service, on port 3080. A long-running service cannot be fed input through a pipe, so the acceptance entry point is MOCK=1 SELFTEST=1 pnpm start: the process starts, runs the whole flow itself, prints a pass or fail per item, and exits accordingly. To click around by hand, use MOCK=1 pnpm start and open port 3080 in a browser.

Run the solution's self-check first, understand what each of the seven items verifies, then look at the starter's four exercises.
Implement the blast-radius computation and confirm via the self-check that editing a line touches only the voice and the timeline.
Implement "copy unaffected artifacts from the previous version" and confirm this regeneration made zero image and video calls.
Implement rollback; in the browser, edit a line, regenerate, then roll back, and see the image and audio really switch back.
Implement structured review notes on disk, and open review.json in the artifact directory to confirm the fields are complete.

Interview Questions

Today's three questions are in the question bank below, focused on choosing human intervention points, computing the impact scope of a partial regeneration, and the data design of versions and rollback. Read the analysis before the key points — practicing the derivation beats memorizing them. The cn / global labels let you pick by target market.

Checklist and Tomorrow

I can build a review page that displays assets shot by shot, supporting preview, line editing, and single-shot regeneration
I can feed human edits back into the workflow, so regeneration only affects the downstream nodes it touches
I can explain what version comparison and rollback need to store, and the trade-offs of a canvas-style workbench
I can name the three human checkpoints and why the first-frame one has the highest value
I can explain the semantic difference between a version and a backup, and why rollback recomputes the timeline
All 5 lab acceptance criteria pass
I can answer at least 2 of the 3 interview questions without looking at the key points

Tomorrow (D11) we hand today's human judgment to a machine: a vision model scores the cut item by item, low-scoring shots are automatically sent back, and content safety plus generated-content labeling land in the export step. The order is deliberate — with a human review flow and structured conclusions in place, machine review has a target to align to; do automated QC first and you cannot even settle on what score counts as a pass.

The Review Room: A Human-in-the-Loop Backend for Previewing, Editing Lines, and Regenerating a Single Shot