--- name: video-edit description: "Runs the passes of a video edit: ledger, cuts, layouts, clips, checks, DJI lav sync, Shorts or long-form, local or Descript. Use when a raw take needs cutting, a worker gets edit passes, or a reel used a lav." tags: [drives, descript, video] lane: general --- # Video Edit A take becomes a finished cut in 9 passes, 0 to 8, each timed against the one before. Out of order, you build motion for a frame that's about to move or lay a bed before the cut ends where it will stay. Read `RUN.json` first. Its `format` picks the format file: [shorts.md](references/shorts.md) for `vertical`, [long-form.md](references/long-form.md) for `wide`. Its `route` is `local` (the take on disk, every Short today) or `descript`. On the local route, close each pass on the proof `next` names (the take folder, `cut short`, `cut check`, `check.txt`, `music offer`, `pick` plus the alpha check, `plan`, `cut final`), never a Descript command or `--anyway`. Its verbs: `retime`, `keep` and `tighten` in [cutting.md](references/cutting.md#the-local-route-cuts), `verify`, `cutcheck` and `final` in [checks.md](references/checks.md#the-local-cut-checks), `pick`, `overlay` and `layout` in [sequencing.md](references/sequencing.md#clips-and-layouts-on-the-local-route). ## Rules for every pass - **Descript goes through `pnpm descript`.** The browser, the published API and Underlord write outside the CLI's commit gate and get reverted or corrupted. The API once broke an edit that had to be re-uploaded by hand, and Underlord littered a project with test sequences. No verb for it? Write the verb in `CLIs/descript/`. Credentials and the write model: [descript-cli.md](references/descript-cli.md); renders: [rendering.md](references/rendering.md). - **Every change goes through a CLI verb.** That's `editor-os ` or `cut ` on a local project, `pnpm descript` on a Descript one. Only the edit owner writes `edit.json` and `edit.notes.json`: the studio, or a verb run on the folder with no studio up, each holding the folder's `.edit.lock`. A hand edit skips the lock and loses. A missing verb gets added to the CLI with a test, never worked round with a script. A render, matte or transcript that prints "Waiting for a render slot" is queued behind the Mac's 2 slots: let it wait, never kill it or start a second one. - **A production gets a ledger before pass 0.** `scripts/run.py` writes `RUN.md` and `RUN.json` beside the video's `plan.md` and, in the house, mirrors the rows to its task board. `next` names the pass to do and what proves it; `start` refuses a pass whose predecessor isn't done or blocked; `done` needs the proof command in `--evidence` plus `--file` (saved output) or `--run` (run.py runs it and keeps the output in `proof/`). ```bash R=.claude/skills/video-edit/scripts/run.py; D=tools/motion/src/ python3 $R init $D --code

 --project  --comp           # once
python3 $R init $D --code  --route local --take  --cut /cut.json
python3 $R next $D                                                # the ONE pass to do now
python3 $R start $D 
python3 $R done $D  --evidence "" --file    # or --run ""
python3 $R block $D  --why ""
```

- **A name carries its number and timecode**, `N [MM-SS] Description.ext`, and every `[mm-ss]` quoted downstream comes from `layout cards`, never the raw take (a cut moved every second). Rules: [projects-and-media.md](references/projects-and-media.md).
- **Export only after his human pass**, never automatically.
  Read the state back from outside the tool that wrote it after every pass: a tool reporting success isn't evidence. The project stays his to watch.

Siblings: `social` (`references/shorts-production.md` for encoding, Drive, ClickUp and calendar; captions), `video-script` (the script), `broll` (a shot that exists), `motion-design` (a clip that's built).

## The passes

`schemas/passes.json`, which `run.py` reads, is the one home of the order. A pass is done when its last column is true.

| # | Pass | Detail | Done when |
|---|---|---|---|
| pre | DJI lav sync, when a reel used one | [dji-sync.md](references/dji-sync.md) | card burned, verified, archived |
| 0 | organise | [projects-and-media.md](references/projects-and-media.md) | `descript tracks` prints `tracks clean`, `descript lint` has no naming warning |
| 1 | coach, then cut | [cutting.md](references/cutting.md) (coach runs first, so the raw take still exists) | script reads with no retake or false start left |
| 2 | reorder, chapters | `cutting.md` (`arrange.py`, then a marker per section) | markers land, chapters read right |
| 3 | rhythm, layouts | [sequencing.md](references/sequencing.md), [pins.md](references/pins.md), the layouts page in the studio (`sequence.py`, then `layout pace` and `layout apply`) | `layout cards` shows a card per beat |
| 4 | music | `music` (the `music-scout` agent: 3 options from Descript Stock, he keeps one) | `music offer` answered, no bed laid |
| 5 | motion | `motion-design` | every clip rendered, watched, in Editor OS review |
| 6 | broll | `broll` | sourced, imported, in Editor OS review |
| 7 | review | `sequencing.md` (`editor-os transcript`, `plan`, `wait`) | he decided the open beats and the music; `edit.json` holds his choices |
| 8 | handoff | `projects-and-media.md` (`descript background`, then `descript settings`) | one grid under the whole video, settings clean, project left for his pass |

A Short never coaches, reorders or chapters.

## Transcript cleanup

The first thing in the first pass, before captions, a title or the plan read the words. Whisper's transcript is a draft, so read it the way an editor would and fix it. "CLOUD.MD" went out on a title card and "agencu brain" on another because nobody read the words.

1. `editor-os transcript  --read` prints one screen: the brief's title, the names to spell right (the caption library, plus what `BRIEF.md` and `plan.md` spell), the kept sentences with source times, doubted words in {braces}, and any word one letter off a name. `--all` adds the cut-out sentences.
2. Read every sentence against the brief, the brand and the names. Fix a word everywhere with `editor-os retime  --respell =`, one saying with `editor-os respell  --at "" "="`. That's wrong names, typos, a word that makes no sense in its sentence, a number said as words. Stumbles and retakes belong to the cut, not here.
3. Write `transcript.review.md` in the video folder: one line per fix (heard, fixed, time, why), or one line saying nothing needed fixing.
4. `editor-os transcript  --reviewed --learn =` records the read. `--learn` saves a pair you're sure of, a name whisper keeps getting wrong and never a one-off, to the caption library so the next video starts right. `--learn` refuses a lowercase word whose fix is only its case or ending ("assigned=Assignee"); `editor-os transcript --learned` lists the pairs and `--unlearn ` takes a wrong one back, never the JSON by hand.

A `retime` or a new take changes the words, so the review is due again: a later `retime` needs the same `--respell` pairs, and `--reviewed` comes last. Until you record the read, `title` and `final` refuse and `plan` and `cut check` warn. It's part of pass 1's proof on the local route.

Checks on a finished cut (doctrine, strategy, the export checklist): [checks.md](references/checks.md). Coach workflow and cut-list method: `cutting.md`. Clipboard mechanics: [clipboard.md](references/clipboard.md). The drive media library: [drive-library.md](references/drive-library.md).