Director — the Editorial Brain

Director turns a written brief into an assembled edit. It isn't "LLM + search" — it's an orchestrated editorial team running against a structured template, with deterministic rules that ground the model when it slips.

Running a Director job

1. BRIEF — write what the edit should be, who it's for, the vibe. ("A 60-second hype trailer for the championship final, fast cuts, build to the winning goal.")
2. SOURCES — open the project's Director so the run is scoped to that project's library.
3. STYLE — pick an editorial template (Trailer, Explainer, Recap, …) and a pacing profile (Fast / Standard / Slow). See Templates for the full catalog. Optionally turn on human-in-the-loop review (see below). Two separate controls: the Review plan before cutting checkbox pauses once, after the plan; the Director's Cut run mode pauses twice — after the plan and after the Showrunner finalizes the cut.
4. ENGINE — pick Local or Jockey for this run. The choice is per-run, not per-project — the same project can run either engine on any brief, in any order. Studio remembers your last pick per project within a session. See Reasoning engines for the trade-offs.
5. DIRECT — run it. Watch the pipeline progress; the result is a storyboard of clips that opens directly in the multi-track editor.

The engine you pick is frozen onto the storyboard row at enqueue (storyboards.run_mode) so re-opening the run later shows the right trace and the right affordances.

Local engine pipeline

The Local engine takes your brief, template, pacing profile, and the project's library understanding, and runs five LLM stages plus a deterministic enforcer pass:

1. Story Editor — LLM call. Produces the plan.
2. Assistant Editor — no LLM. Retrieves candidate clips per scene.
3. Sequence Editors — one LLM call per template phase. Each picks clips for its phase.
4. Lead Editor — LLM call. Arranges the final ordering.
5. Showrunner — LLM call. Critiques and can swap up to three weak picks.
6. Deterministic enforcers — pure code. Cohesion snap, duration budget, chronology re-sort.

The output is a storyboard that opens in the multi-track timeline editor.

Each stage is observable in the Job Monitor — open the RUN_DIRECTOR job and use the 🐞 toggle to see each step's prompt and response inline.

1. Story Editor (Plan)

A single LLM call. Reads:

• Your brief verbatim
• Per-asset recap + structure + insights (the enriched library context for everything in the project)
• The template's phase definitions

Produces:

• A content category read (detected_domain — "sports", "wedding", "conference", …) so downstream steps know what kind of footage they're working with.
• A plan: ordered scenes, one per phase of the template, each with an intent (what this scene should accomplish editorially), a target duration, and which assets to draw from.

The Story Editor is the only hard-fail step. Every other agent soft-fails — the rest of the pipeline catches transient errors and falls back. But without a plan, there's nothing downstream can do.

2. Assistant Editor (Search)

No LLM. For each scene in the plan, runs:

• A KNN search over the project's segment embeddings, weighted per modality.
• A keyword text-match pass against transcripts and Pegasus segment descriptions.

Returns a ranked candidate pool per scene (tens of clips, scaling with the run's target length), ranked by combined score. This pool is what the Sequence Editors pick from.

3. Sequence Editors (Select)

One LLM call per phase, in sequence. Each Sequence Editor reads:

• Its phase's intent + clip-duration envelope + cut rules
• The brief
• The candidate pool from the Assistant Editor for this phase
• The previous phases' chosen clips (so it doesn't pick duplicates)

Picks the clips that satisfy the phase's selection spec (preferred traits, avoided traits, hook/closer requirements where applicable).

Soft-fail: if a Sequence Editor times out or returns garbage, Studio logs the failure, skips that phase entirely (no picks for it), and continues to the next phase. The Showrunner and the duration enforcer compensate downstream.

4. Lead Editor (Arrange)

One LLM call. Reads the unioned set of picks from all Sequence Editors and the template's ordering.enforcesChronology flag. Outputs a final ordering for the storyboard.

Soft-fail: if the LLM returns garbage, Studio defaults to the Sequence Editors' natural order.

5. Showrunner (Critique)

One LLM call. Re-reads the final ordered cut, flags weak picks, and can swap out up to 3 clips for alternatives from the original candidate pool. This is the "step back, look at the whole thing" pass.

Soft-fail: if it errors, the run completes with the Lead Editor's output unchanged.

6. Deterministic enforcers

Pure code. Run after the agents and make rules true even if the model ignored them:

• `snapCohesion` — clip ends snap to transcript-utterance boundaries (priority: transcript > spoken > shot > hard cap). Eliminates mid-sentence cuts.
• `enforceDurationBudget` — total duration must be within ±10% of the template's target. Trim overlong clips first; if still over, drop the weakest picks until the budget fits.
• Chronology re-sort — if ordering.enforcesChronology is set, re-sort the cut by source timestamps regardless of what the Lead Editor returned.

These run for both engines — see the Jockey engine section below.

Jockey engine pipeline

The Jockey engine replaces the multi-call local pipeline with a single streaming call to Jockey's /responses endpoint. (Local runs 1 Story Editor + one Sequence Editor per template phase (N) + 1 Lead Editor + 1 Showrunner = 3 + N LLM calls — a 60s Trailer has 5 phases, so ≈ 8 calls.) The flow is:

1. Send the brief, template, pacing, and the project's Knowledge Store context to /responses as a streaming request.
2. The master agent plans, selects, and arranges in one reply — you watch it reason in real time on the player's thinking surface.
3. The same deterministic enforcers (cohesion snap, duration budget, chronology re-sort) run post-Jockey.

The output is a storyboard that opens in the multi-track timeline editor — the same surface as the Local engine.

The master agent's prompt is built from your brief, the template definition (phases, pacing, rules), Pegasus structure blocks for every asset in the Knowledge Store, entity blocks for extracted people / brands / locations, and per-asset insight blocks (the web-grounded research dossier). The Director's player frame doubles as a thinking surface — a live trace of the master agent's /responses reasoning + drafted output, rendered as streaming text in the player overlay. You can watch the agent reason in real time.

The same deterministic enforcers then run post-Jockey (enforcePostJockey), so cohesion, duration budget, and chronology constraints are honored regardless of which engine you picked.

See Reasoning engines for the full Local vs Jockey side-by-side, including the unified ingest pipeline that makes per-run engine switching cheap.

Human-in-the-loop review

Two controls turn on review, and they differ in how many times the pipeline pauses:

• Review plan before cutting (checkbox) — pauses once, after the plan. You approve the scenes, then the agents run straight through to the finished cut.
• Director's Cut (run mode) — pauses twice: after the plan and after the Showrunner finalizes the cut.

Director's Cut pauses twice — first after the Story Editor's plan (scene review), then again after the final cut is assembled (cut review). Each pause uses its own continuation map; resuming after either review continues from where the pipeline parked.

Pause 1 — plan review (both controls)

After planning, Studio shows you the planned scenes in a review sheet:

• Edit a scene's intent
• Re-order scenes
• Delete or duplicate a scene
• Adjust the target duration

Pause 2 — cut review (Director's Cut only)

After the Showrunner finalizes the cut, Director's Cut pauses again for a cut review: you can drop or swap individual clips, pulling replacements from the unused candidate pool, before the deterministic enforcers run.

When you're ready at either pause, click Resume and the pipeline continues. Cancel terminates the run cleanly (it propagates a CancellationError that the pipeline catches and rolls back).

The pipeline parks on a CheckedThrowingContinuation keyed by storyboard id, so the resume is exact — no re-running prior stages.

After a run

• The storyboard opens in the multi-track timeline editor — reorder, trim, split, and version the cut. The Director seeds an editable timeline from its output; your manual edits are versioned on top. See Timeline & publishing.
• Leave notes on a run — free-text feedback that feeds forward into the next run's Story Editor prompt. ("This had too many wide shots — go tighter next time.")
• Per-clip rating (👍 / neutral / 👎) — aggregates per template in the Workshop's Health tab; tells you which picks the editor kept and which got swapped.
• Regenerate re-runs from the brief. This resets the edit history for that storyboard — useful when the brief was wrong, not when the cut just needs nudges.
• When you're happy, Publish it or export it — see Timeline & publishing.

Telemetry — closing the loop

Every completed run writes a template_runs row carrying:

• mode (local | jockey) — the engine you picked on the Direct sheet, sourced from the storyboard's run_mode
• template_id
• detected_domain (the Story Editor's content-category read)
• picks_initial, picks_dropped, picks_trimmed
• duration_deviation_pct (how far off from the template target)
• tokens_input, tokens_output, cost_usd

The Editorial Workshop & Guide (Help menu) aggregates these into per-template stats with per-engine + per-domain breakdowns. Because the engine is per-run on a shared library, the same brief can be run on both engines and compared side-by-side. Patterns like "Trailer's Climax phase drops 18% of picks on sports footage — cuts/sec is too aggressive" surface there, and templates can be tuned in response.

When to use Director vs. Timeline directly

• Director first if you have a brief in your head and a library you haven't touched — let the agents draft, then refine.
• Timeline first if you already know which clips you want and just need a place to assemble them. The same multi-track editor works driven by you or by the Director; you can always run the Director later against a project that has a manual timeline.

The Workshop

The Editorial Workshop & Guide (Help menu) is where Director's behavior is inspectable: per-template health stats (trim/drop %, duration deviation, cost, success rate), a phase strip showing each template's structure, and a prompt sandbox where you can iterate on the Story Editor / Sequence Editor prompts without changing live behavior.

It's also where you tune or add templates — see Templates. Worth a look once you've run a few edits and want to understand why the cuts come out the way they do.