Editor — Role-Specific Production Guide

This document contains the detailed mandates, checklists, and procedures for the Editor (Post-Production Lead) across all 7 production steps. Read the main Video Production Playbook first for the overall workflow and cross-role coordination.

Genre Integrity — Editorial Guardrails

The Idea Person will define Editorial Guardrails in the design_brief.md — explicit restrictions on pacing and sound design tropes that would undermine the intended genre. Read these before making any pacing, transition, or music decisions. Editors naturally build tension; for non-thriller genres, that instinct can sabotage the film. If the design_brief.md says “no dead silence, no heartbeat bass drops, no slow pull-ins,” respect those boundaries — they exist because AI-generated footage already skews dramatic without editorial help.

Step 2: The Beat Sheet

Mathematical Pacing Review

Define the Musical Arc (noting that music spans multiple scenes).

You MUST write a Python script (or use a similar quantitative method) to parse the scene_list.md, sum the durations of all shots/scenes, and mathematically verify that the total runtime falls exactly within the 3:00 to 5:00 minute target.

Step 2.5: Scene Review & Object Anchoring

Co-lead with Idea Person.

Review the scene/shot list for objects, vehicles, or structures that appear in more than one shot.
Help annotate the shot list with object reference image mappings.

Step 3: Character Workshop

Monitor “Visual Texture”—verify character designs work across planned cuts and close-ups.

Step 4: The Storyboard

Sub-agent Reliability: The Scene-Shard Strategy

High-volume tasks (like reviewing 62 storyboard frames or 31 video clips) can exceed a single sub-agent’s context capacity, leading to stalls or garbled output.

Guideline: Instead of one sub-agent for the whole film, shard the workload by scene.
Limit: Use one sub-agent per scene (max 12 frames or 6 video clips per agent).
Naming: Use descriptive slugs like `iota-checker-scene1`, `iota-checker-scene2`, etc.
Outcome: This ensures context isolation, allows for parallel verification, and provides a clear recovery path if a single shard fails.

Continuity & Traversability Review

Ensure the delta between a shot’s start and end frames can realistically be connected by the video model, given the written Motion Prompt and planned shot duration.
Verify the logical cut from shot_N_end.png to shot_N+1_start.png.

Step 5: Principal Photography

The “Takes” Protocol

You are the strict quality control gate for every generated shot.

Load and review each shot, checking for glitches, continuity errors, and motion quality.
You may request up to two reshoots per shot, requiring the Tech/Idea pair to tweak prompts.
In extreme cases of failure, you may demand a re-render of the Step 4 bookend frames.

Voice Stem Duration Audit (Mandatory Gate)

Before assembly, you MUST audit the actual speech duration of every voice stem. TTS models frequently generate audio longer or shorter than the scripted “Timing Hints.”

Audit Tool: Use /workspace/tools/bin/ffprobe to check actual file durations.
Action: If a stem is longer than the planned timeline window (e.g. an 8s shot with a 13s voice stem), you MUST either extend the shot duration or request a “faster/punchier” regen from the Tech Lead.
Verification: Ensure source_out in the timeline JSON encompasses the full speech duration of every stem to prevent clipping.

Duration Verification (Mandatory Gate)

Before any shot proceeds to the timeline, you MUST run verify-dailies against the dailies directory using the Technical Lead’s shot-manifest.json. This is a hard gate — no clips move to assembly until verify-dailies passes with zero failures.

Run it in two phases:

Quick scan (no manifest): verify-dailies --dir ./dailies — catches obvious anomalies like suspiciously long or uniform clips.
Full verification: verify-dailies --dir ./dailies --manifest shot-manifest.json — checks every clip against expected durations and detects extend double-count bugs.

Step 6: The Soundstage

Temporal Mapping (A/V Sync)

Use the Timing Hints provided in the scene list to map dialogue and VO stems to the visual action in the `timeline.json`.

For `[COMPOUND]` shots, ensure at least 0.5s of silence between VO and Dialogue segments.
Align speech with visible mouth movement periods. If a clip’s action occurs at second 6, place the dialogue stem at second 6, not second 0. \n

The Working Directory Mandate

The `genmedia-assemble` tool resolves relative file paths in the `timeline.json` (e.g., `”./dailies/shot_1.mp4”`) relative to the CURRENT working directory of the shell, not the location of the JSON file.

Mandate: Before running ANY assembly or verification command, you MUST `cd` into your team’s shared directory (e.g., `cd /workspace/shared-dirs/iota-team/`).
Failure Mode: Running from the workspace root (`/workspace/`) will cause FFmpeg to fail silently or error out with “File not found” as it looks for dailies in the wrong location.

Timeline JSON Creation

You must create a Timeline JSON file (see genmedia-assemble timeline in USAGE.md) that maps the exact start/end timestamps for every video clip, VO, SFX, and Music stem on named tracks.

The timeline format supports:

Per-clip fades
Crossfade transitions (via clip overlap)
Gaps (auto black frames)
Per-track volume and ducking (duck_under/duck_db)
Source trimming (source_in/source_out)

This file is the single source of truth for assembly — adjust timings in the JSON and re-run. See examples/timeline-crossfade.json and examples/timeline-full.json for reference.

Helper agent delegation: To protect your context window from noisy JSON syntax and complex duration math, spin up a timeline-helper agent to construct the JSON. Provide it with your shot breakdown, audio stems, and transition rules.

Step 7: The Editing Suite

You lead this step.

Final Cut Mandates

Transitions: Use the “overhang” from Step 5 to create precision timing for crossfades (overlap adjacent clips in the timeline and set "transition": "crossfade"). Consider fade-to-black transitions where appropriate. All films MUST end with a fade-to-black (use fade_out in the video settings). It is acceptable to slightly extend the total runtime to accommodate transitions.
The Voiceover Sync: MUST ensure that all Narrator Voiceover stems generated in Step 3 are placed on the voice track in the timeline JSON with correct start/end times. Do not release a master without verifying the voiceover is present and audible.
The Iterative Rough Cut: Do not go straight to final output. Generate a Rough Cut by running the timeline. Adjust timings in the JSON and re-run as needed.
Simulation Ban: You MUST use genmedia-assemble timeline to execute real FFmpeg operations. Do not write placeholder stubs. The timeline JSON is your production manifest.

Audio Mixing

Music levels in the pilot were too loud, drowning out the voiceover. You are responsible for proper volume balancing:

Voiceover/narration must always be clearly audible over music and ambient sound
Use the Timeline JSON format to configure per-track ducking (duck_under/duck_db) to automatically duck music under dialogue
Review every assembled cut with audio levels as a primary pass/fail criterion

Scene Transitions

The pilot had abrupt scene cuts. Aim for smoother transitions:

Use cross-fades or dissolves between scenes where the narrative benefits
Leverage the Overhang Principle (clips are slightly longer than needed) to give yourself transition material
Match outgoing and incoming visual energy to avoid jarring jumps

Editor (Post-Production Lead)