From c96b6abf037bf104db00bbed0a8df4fb078f683b Mon Sep 17 00:00:00 2001
From: VEED Open Source <hello@veed.io>
Date: Thu, 3 Sep 2026 11:19:14 +0300
Subject: [PATCH] Project import generated by Copybara.

GitOrigin-RevId: 5f12ffdb29274c9c77492f59940a7a99c6c06583
---
 .claude/skills/open-edit/SKILL.md | 96 +++++++++++++++++++++++++++----
 AGENTS.md                         |  8 ++-
 docs/FLOW.md                      |  7 ++-
 pipeline/director-brief.md        |  5 +-
 4 files changed, 98 insertions(+), 18 deletions(-)

diff --git a/.claude/skills/open-edit/SKILL.md b/.claude/skills/open-edit/SKILL.md
index 882787b..a7c0a42 100644
--- a/.claude/skills/open-edit/SKILL.md
+++ b/.claude/skills/open-edit/SKILL.md
@@ -90,9 +90,13 @@ Init names which of the two it resolved (`reusing the local checkout at …` or
 at …`); read that line before trusting a run to be testing your changes. Resolve the supplied video to an
 absolute path from WORKSPACE before changing working directories.
 
-At the start of EVERY session, before doing Open Edit work, report what setup would do (init also keeps
-the workspace's SessionStart hooks current when it applies — idempotent, and a hook problem never blocks
-a run):
+**If the session opened with a note saying preflight is ready AND naming `OPEN_EDIT_ROOT`, that note IS
+the preflight** — the hook ran it. Take the root from the note, read `AGENTS.md`, and start work. Running
+init again only repeats what has already been answered.
+
+Otherwise, at the start of the session, before doing Open Edit work, report what setup would do (init also
+keeps the workspace's SessionStart hooks current when it applies — idempotent, and a hook problem never
+blocks a run):
 ```
 npx --yes @veedstudio/openedit-cli init --dry --workspace "$WORKSPACE"
 ```
@@ -133,7 +137,8 @@ client discovering instructions inside the newly cloned runtime automatically.
 Written for the footage case. PREFLIGHT, FOOTAGE, DESIGN + RENDER and PREVIEW hold for every run; **PREP**
 (transcript, frames, meta), **SAMPLE ONE STYLE** (the style draw) and **MUX AUDIO** derive from a source
 file, so a run with no video simply has no subject for them — see INPUTS: authoring, lint, `--verify` and
-`--record` are unchanged.
+`--record` are unchanged. **CUT** runs only when there is an edit to make, and it splits PREP: the sources
+are transcribed, the cut is assembled, and everything downstream then sees the edited timeline.
 
 ### PREFLIGHT — completed above  · SCRIPT
 Do not run a second dependency implementation. `pipeline/scripts/preflight.mjs` (and its `.sh` twin) is only a compatibility wrapper
@@ -141,6 +146,68 @@ around the init command. If `node` itself is missing, treat installing it as an
 (macOS: `brew install node` — the shim reports this itself; Windows: `winget install --id OpenJS.NodeJS.LTS`). The provider choice — and any sign-in or install it implies —
 remains the interactive PREP step.
 
+### CUT — assemble the footage you actually want  · SCRIPT (only when there is an edit to make; splits PREP)
+Applies whenever the deliverable is not simply one source file played end to end: something to REMOVE
+(dead air, filler, a weak take), something to REORDER, or several clips to JOIN into one piece. When the
+ask is a single clip captioned as-is, this step has no subject — skip it and run the PREP step normally.
+
+**Where it sits.** `retime-transcript` needs the SOURCES already transcribed, so this step splits PREP
+rather than preceding it: transcribe the sources (the PREP step's own batch — one command, all files),
+then CUT, then run `prep` on the assembled file. Never transcribe the assembled file.
+
+**Measure the cut points; do not take them from the transcript.**
+```
+npx @veedstudio/openedit-cli speech-probe <video> [--range a:b] [--gap 250] [--window 10] [--json]
+```
+Reports the measured noise floor, the speech onset and decay, and every sub-threshold gap at least
+`--gap` long. `--gap` and `--window` are MILLISECONDS; `--range` and every number in the EDL are seconds.
+A transcript's word boundaries are not cut points: ASR can report a gap between two words where the
+waveform shows unbroken voicing, and cutting there slices a phoneme. When the probe finds no gap at a
+boundary, there is no cut there: keep the filler word rather than make an audible seam. Optional when
+the in- and out-points come from somewhere else entirely — a storyboard, or the user naming the takes.
+
+**Write the edit down, then apply it.**
+```json
+{ "sources":     { "<id>": "<path to video>" },
+  "transcripts": { "<id>": "<path to that source's transcript.json>" },
+  "ranges":      [ { "source": "<id>", "start": 1.6, "end": 7.05, "note": "free text, ignored" } ] }
+```
+`transcripts` is optional — without it each source's transcript is read from where the transcribe command
+wrote it (`runs/<key>/transcript.json` under the runtime root, `<key>` from the source video's filename).
+`note` is optional. Every source path must exist for both tools: the ranges are snapped to each source's
+frame grid, and the grid comes from the file. Ranges play in the order written: reorder them freely, a
+beat does not have to keep its chronological place.
+```
+npx @veedstudio/openedit-cli apply-edl --edl edl.json --out cut.mp4 [--crossfade 40] [--crf 20]
+```
+One encode, one canvas (the first range's source's), joins crossfaded so the room tone carries across them, and
+the sources' colour tags kept — sources that disagree on colour or frame rate are refused rather than
+relabelled. `--crossfade` is milliseconds. Each range is snapped to the frame grid, so the assembled
+timeline is exactly the sum of the snapped ranges, and the retimed transcript below lands on the same
+instants: picture, sound and captions agree to the frame.
+
+This is the joiner for an EDIT — parts of clips, in an order you chose. The FOOTAGE step's joiner is for
+whole generated clips whose shapes disagree, and it hands back an ordinary source file you then
+transcribe; this one hands back a cut whose transcript you RETIME instead.
+
+**Move the timings; do not buy them again.**
+```
+npx @veedstudio/openedit-cli retime-transcript --edl edl.json --out "$OPEN_EDIT_ROOT/runs/cut/transcript.json"
+```
+A cut changes WHEN words were said, never WHICH, so the per-word timings you already have are the timings
+of the new file. Write it where `prep` will look for it: `$OPEN_EDIT_ROOT/runs/<key>/transcript.json`,
+where `$OPEN_EDIT_ROOT` is the runtime root preflight printed (NOT the project directory under a managed
+clone) and `<key>` is the assembled file's name without its extension, whitespace turned into
+underscores — `runs/cut/` for `cut.mp4`. Skipped when there is no transcript at all: a run with no
+speech has nothing to retime.
+
+**Never transcribe the assembled cut.** It is the most expensive mistake available in this flow, and it
+buys nothing the arithmetic above does not already give you. Every transcription route — hosted, local
+and the mapper for your own service — refuses to overwrite an existing `transcript.json` without
+`--force`, and checks before it uploads or runs anything, so a stray one costs nothing.
+
+Then continue with the PREP step, giving it `cut.mp4`.
+
 ### FOOTAGE — a video to work from, generate one, or none  · SCRIPT (only when the user brought none; runs before PREP)
 This step is about VIDEO only — stills, screenshots, slides, images and audio are inputs too, and a run can
 have them with no video at all. If the user supplied a video, continue to the PREP step unchanged. Otherwise do
@@ -404,8 +471,9 @@ The transcript comes from the provider the user chose, and either way lands at
 video's filename without its extension, whitespace replaced by `_`** — every step below takes the same
 `runs/<key>`, and each entry point prints the path it wrote.
 
-For a batch (see INPUTS above), pass every video to ONE call: a failure stops the batch with the finished
-transcripts left in place.
+For a batch (see INPUTS above), pass every video to ONE call. The hosted batch runs four at a time,
+finishes every file it can, and exits non-zero naming the ones that failed; the local batch stops at the
+first failure. Either way the finished transcripts stay in place and a re-run skips them.
 
 PROVIDER CHOICE — this whole question exists to caption speech, so **when nothing has to be transcribed
 (no footage, silent source, a graphics-only ask) do not ask it at all** and do not record anything.
@@ -932,6 +1000,8 @@ RENDER + VERIFY (OUTSIDE any sandbox — needs a real desktop session; binary =
      offers only shadow and background; when nothing reaches AA it says that too. Say `background` to the user as "a solid box" — the rung NAMES are the choice file's
      own values, so copy them across verbatim and never translate one into another word.
      - `status: pass` → all caption text clears AA. Note it and move on.
+     - `status: attention` with the note `0 runs audited` → the audit examined nothing: the statistics
+       file names no text elements. Say so plainly and offer no fixes — there is no class to choose at.
      - `status: attention` → some caption text is below AA. Speak it in PLAIN PRODUCT TERMS, briefly,
        for someone who does not know what a CSS class is. Head it `Text contrast audit — target rating:
        WCAG AA`, give the count, then ONE line per class: the class label (the `propose:` selector with
@@ -1019,7 +1089,10 @@ apply, re-run the chain so the record is made from the promoted template.
 
 ### MUX AUDIO — restore the soundtrack  · SCRIPT
 the engine renders video only. When the run's audio IS the source clip's, `npx @veedstudio/openedit-cli mux-audio runs/<key>` muxes it onto
-`final/out.silent.mp4` → **`runs/<key>/final/out.mp4`** (the deliverable). `-map 1:a:0?` tolerates a source with
+`final/out.silent.mp4` → **`runs/<key>/final/out.mp4`** (the deliverable), levelled to the delivery target
+(-14 LUFS / -1 dBTP); the command prints which correction actually ran, and `--no-loudnorm` keeps the
+source level (`gates` forwards it; pass it when gating one chapter of a longer piece, whose level belongs
+to the whole film). `-map 1:a:0?` tolerates a source with
 no audio track, and the deliverable takes the PICTURE's length, so a built mix shorter than the render cannot truncate it. Deliver `out.mp4` to the user — this is the FIRST
 moment the run is presented as done (never announce the silent render or muxing separately).
 When the audio is BUILT rather than restored — narration, music, effects, anything with more than one
@@ -1034,7 +1107,8 @@ piece — write `runs/<key>/audio/mix.json`, build the track, and mux THAT:
 npx @veedstudio/openedit-cli mix-audio runs/<key>          # → runs/<key>/audio/mix.m4a
 npx @veedstudio/openedit-cli mux-audio runs/<key> --audio runs/<key>/audio/mix.m4a
 ```
-`durationSec` is required and is the FILM's length — anything past it is trimmed, so one long cue
+The mix is levelled as a whole at mux, like a source track; set the pieces' relative gains in
+`mix.json` and leave the overall level to it. `durationSec` is required and is the FILM's length — anything past it is trimmed, so one long cue
 cannot lengthen the deliverable. A bed marked `duck` is opened by the voice itself rather than by a
 gain you guessed at; a fade-out is measured from the end of the film, because a cue's own length is not
 in the spec. `--print-graph` shows the filtergraph without running ffmpeg.
@@ -1092,8 +1166,10 @@ Kill the server(s) when the session wraps up.
   `Library not loaded: @rpath/libavutil.<N>.dylib` for several FFmpeg majors, plus a Lightning
   checkpoint-upgrade notice (Windows builds print an equivalent DLL-probing wall). Those are pyannote probing FFmpeg builds it cannot find and are HARMLESS —
   they look fatal and are not. The signal that transcription actually worked is the line
-  `[transcribe] whisperx: <N> words -> <path>`: if it appears, the transcript is written and you continue.
-  If it does NOT appear, the run failed for a real reason — read the last error, not the dlopen wall.
+  `[transcribe] whisperx: <N> words -> <path>` (it ran) or `[transcribe] cached: <path> already exists
+  (--force to transcribe it again)` (a transcript was already there and was left alone — that is a
+  success, not a skip). If NEITHER appears, the run failed for a real reason — read the last error,
+  not the dlopen wall.
 - Rendering fetches Google Fonts over the network (the .wv documents use a `<link>` to `fonts.googleapis.com`);
   an offline box = font fallback.
   FONT WARNINGS — read them precisely, don't chase noise: `no data/font-cache seed found`, generic-keyword
diff --git a/AGENTS.md b/AGENTS.md
index 109b472..0fcad36 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -86,7 +86,8 @@ fast-path/refinement switch.
 - `npx @veedstudio/openedit-cli mix-audio` — one soundtrack out of many pieces, for a run whose audio is not
   simply the source clip's. Each track states where it starts and how loud it sits; a bed marked
   `duck` is ducked by the `voice` tracks themselves rather than by a guessed gain. The mux-audio command
-  still restores a single source track; this is what a film needs instead.
+  restores a single source track and levels whichever track it is given to the delivery loudness; this
+  is what a film needs instead.
 - `veed/` — VEED-native transcription + login (one writer of `transcript.json`; real per-word timings), plus Fabric generation and video background removal on the same login. `npx @veedstudio/openedit-cli background-removal` reaches the live free VEED route by default, or fal's own `--fast` model when that variant is wanted; `npx @veedstudio/openedit-cli lipsync` (video + new audio -> re-lipsynced video) has no VEED-hosted route at all and always goes through fal. Both fal-charged paths still use the VEED login to host the local file for a URL, but the generation call itself bills the user's own fal key (the CLI's fal BYOK rail), never a VEED workspace. `npx @veedstudio/openedit-cli prep` — `meta.json` + `word-timings.json` + base frames (needs a transcript from any provider). `refs/` — `html/` refs + `tags.json` (v3, the RUNTIME INDEX — recipes only, facet taxonomy, `fit` = aspect SOT) + per-ref `recipe.md` (the prose recipe sheet a compiled recipe is derived from — the fast path runs the compiled module, never the sheet; the creative pass reads sheets as craft substrate and REMIX donors).
 - `config.ts` — all machine paths (ffmpeg / ffprobe / veed-engine). `docs/` — FLOW (orchestration) · recipe-format (the recipe law). Engine support matrix = the `feature-support.md` asset downloaded with the engine release into `.veed-engine/` (not vendored here).
 
@@ -159,8 +160,9 @@ than by hand. An absent, corrupt or unrecognised file reads as a cold start with
 a recorded `model` becomes the default tier for later runs.
 
 Every provider entry point takes `<video.mp4> [...]`, like the prep command, and writes one `runs/<key>` per
-video — so a batch asks the provider question, signs in, and installs once. A failure stops the batch and
-leaves the transcripts already written in place.
+video — so a batch asks the provider question, signs in, and installs once. The hosted batch finishes
+every file it can and exits non-zero naming the failures; the local batch stops at the first. Either way
+the transcripts already written stay in place, and a re-run skips them.
 
 ```sh
 # whisperx, installed on request only — isolated uv/pipx environment, ~2 GB with weights,
diff --git a/docs/FLOW.md b/docs/FLOW.md
index 7aa57da..3ea3792 100644
--- a/docs/FLOW.md
+++ b/docs/FLOW.md
@@ -11,7 +11,7 @@ the only gates are the FOOTAGE step's three, and they exist only when the user b
 **Inputs: any number of videos, INCLUDING NONE.** The captioned single-clip run is the shortest path
 through here, not the definition of a run: footage is a layer inside the document, and a run can be built
 from stills, slides, generated imagery, audio alone or pure motion graphics. A long piece has one
-document per chapter, gates them one at a time (`npx @veedstudio/openedit-cli gates <run-dir> --doc chapters/act-3`) and joins the
+document per chapter, gates them one at a time (`npx @veedstudio/openedit-cli gates <run-dir> --doc chapters/act-3 --no-loudnorm`) and joins the
 gated chapters with `npx @veedstudio/openedit-cli concat-chapters`.
 
 An AUTHORED run — creative face-1, a remix, or a run with no footage — writes `runs/<key>/design/system.json`
@@ -23,12 +23,13 @@ A compiled recipe needs none of that: the recipe IS the system.
 | preflight | SCRIPT | check `veed-engine-cli` vs the latest release; offer install if stale/missing |
 | footage | SCRIPT (the only step that STOPS to ask) | **only when the user supplied no footage** — generate one with VEED Fabric (`npx @veedstudio/openedit-cli generate`, same VEED login as prep) → `runs/<key>/<key>.mp4`, which the PREP step then treats as ordinary footage. Three gates, in order: FOOTAGE (generate a video, take a clip they have/will record, use another model, or build from other sources instead — a non-Fabric model gets the speech caveat, since silent clips transcribe to nothing) → WORKSPACE (whose AI Playground credits; never picked for the user) → the CREDIT APPROVAL (script + presenter + voice + framing + quoted cost in ONE yes — the only gate that spends; cost tracks the finished DURATION at ~4 credits a second, and how long a script runs depends on the voice). Confirm and spend are two passes; a charged job is collected with `--resume`, never re-paid. Procedure: the FOOTAGE step of SKILL.md |
 | prep | SCRIPT | transcript from the chosen provider (VEED `npx @veedstudio/openedit-cli transcribe --provider veed`, local WhisperX `npx @veedstudio/openedit-cli transcribe`, or the user's own via `npx @veedstudio/openedit-cli whisper`; chunks = beats, real per-word timings) → `word-timings.json` (per-word absolute-ms reveal delays, synthesized by `npx @veedstudio/openedit-cli prep`) + base frames; auto-detect aspect → write `meta.json` (canvas + duration + paths) |
+| cut | SCRIPT | **only when there is an edit to make** — measure the cut points (`npx @veedstudio/openedit-cli speech-probe`), assemble the kept ranges, snapped to the frame grid, in one encode with crossfaded joins (`apply-edl`), and move the existing per-word timings onto the same snapped timeline rather than transcribing again (`retime-transcript`). Splits PREP: sources are transcribed first, the assembled file is prepped after. Procedure: the CUT step of SKILL.md |
 | analyse | AGENT (vision) | **OPT-IN, skipped by default** — run only when the user asks to refine the style; then ONE nameless bg subagent reads the frames + transcript → `analysis.json` (per-beat shot/bboxes/neg-space/brightness in CANVAS px), and the DESIGN + RENDER step re-runs with it. The **only** vision pass. `analysis.json` existing IS the fast-path/refinement switch. |
 | sample ONE style | SCRIPT | `npx @veedstudio/openedit-cli sample-style` — facet-scored seeded draw of one aspect-matched ref from `refs/tags.json` (v3 RUNTIME INDEX, recipes only; `fit` = aspect SOT; transcript energy weights the draw) → `style.json` (facets, energy, coverage, alternates). Zero tokens. The CREATIVE PASS routes here too: face-1 (user brought materials) → the DESIGN + RENDER step, from-scratch; face-2 REMIX (any creative iteration) / RE-ROLL (variants asks) / patch (defects). |
 | design system | INLINE (authored runs only) | `runs/<key>/design/system.json` — fonts, the type ladder with each rung's own optical tracking (`pipeline/recipes/type.ts`), palette, spacing, named easings and durations, the reveal unit, the devices in play, and `donors` (recipe ids, checked against the runtime index). Written FROM the run's content: `groundedIn` must name files that exist, so a system cannot be authored before the thing it is for. Compose the documents from `pipeline/recipes/devices.ts`, `pipeline/design/captions.ts` and `pipeline/recipes/geometry.ts` rather than typing each graphic at its point of use. |
 | design + render | SCRIPT (recipe) · INLINE (creative face-1 · remix) | default → **compiled recipe** (`npx @veedstudio/openedit-cli generate-recipe`: the generator module emits `final/template.wv` + `manifest.json` deterministically — word delays from `word-timings.json` by construction, zero tokens — then drives the gate chain: lint → `--verify` with the mechanical ladder fix loop (≤2 cycles) → `--record` → probe-qa); **face-1** (INLINE, orchestrator-authored: one design system from the USER'S materials, 1-2 recipe sheets as craft substrate, per `director-brief.md`; lint + `--verify` to exit 0, then `--record` → probe-qa); **REMIX** (inline donor blend per the brief's REMIX MODE in `runs/<key>-remix`, same gates) |
-| gates | SCRIPT | `npx @veedstudio/openedit-cli gates <run-dir> [--doc <subdir>] [--audio <file>]` — design → lint → `--verify` → WCAG → `--record` → probe-qa → mux, stopping at the first failure and naming the gate. The generate-recipe command drives the same chain for a compiled recipe; every other path calls this instead of retyping it. Runs OUTSIDE any sandbox. |
-| mux audio | SCRIPT | ffmpeg muxes the source audio onto the silent render → `final/out.mp4` (the deliverable) |
+| gates | SCRIPT | `npx @veedstudio/openedit-cli gates <run-dir> [--doc <subdir>] [--audio <file>] [--no-loudnorm]` — design → lint → `--verify` → WCAG → `--record` → probe-qa → mux, stopping at the first failure and naming the gate. The generate-recipe command drives the same chain for a compiled recipe; every other path calls this instead of retyping it. Runs OUTSIDE any sandbox. Pass `--no-loudnorm` for one chapter of a longer piece: the level belongs to the whole film, and levelling each part on its own is how chapters end up stepping. |
+| mux audio | SCRIPT | ffmpeg muxes the source audio onto the silent render and normalises it to the social delivery target (-14 LUFS / -1 dBTP / LRA 11; `--no-loudnorm` keeps the source level) → `final/out.mp4` (the deliverable) |
 | preview | SCRIPT (parallel) | `npx @veedstudio/openedit-cli preview runs/<key>` — localhost preview opened for the user (read-only): watch and scrub the footage, follow the transcript, preview the subtitles; auto-swaps to the new `final/out.mp4` when an amend re-render lands. Launched in the background; the pipeline never waits on it |
 
 ## Where quality lives (do not let these drift)
diff --git a/pipeline/director-brief.md b/pipeline/director-brief.md
index 8bb0388..0befe8f 100644
--- a/pipeline/director-brief.md
+++ b/pipeline/director-brief.md
@@ -282,10 +282,11 @@ the same strips.
 
 ## RENDER + VERIFY (needs the window-server → run OUTSIDE any sandbox)
 **One command drives the whole chain**, and it is the one to use unless you have a reason not to:
-`npx @veedstudio/openedit-cli gates <run-dir> [--doc <subdir>] [--audio <file>] [--no-design] [--no-wcag] [--no-expect] [--no-probe] [--no-mux]`
+`npx @veedstudio/openedit-cli gates <run-dir> [--doc <subdir>] [--audio <file>] [--no-design] [--no-wcag] [--no-expect] [--no-probe] [--no-mux] [--no-loudnorm]`
 It runs design → lint → `--verify` → WCAG → `--record` → probe-qa → mux, stops at the first failure and names
 the gate that failed. `--doc` picks the document under the run — it defaults to `final`, and a film
-gates one chapter at a time (`--doc chapters/act-3`). When every chapter is gated, join them with
+gates one chapter at a time (`--doc chapters/act-3 --no-loudnorm`: the level belongs to the whole film,
+and levelling each chapter on its own is how they end up stepping). When every chapter is gated, join them with
 `npx @veedstudio/openedit-cli concat-chapters`, which stream-copies and refuses parts whose format differs —
 NOT `concat-videos.ts`, which re-encodes and normalises the frame rate because its inputs are
 generated clips that disagree by nature. `--no-design` only when a compiled recipe IS the