video-edit-edl
Skill7 starsChanged 21 days agoMITView on GitHub
Builds the EDIT of a generated-video piece as a derived EDL: the script rewritten as a beat list FIRST, the picked keepers placed by derivation, the sound placed from picture markers, the script-fidelity gate before any finish, and every note applied as a parameter change to a NEW version file. Genre switch: ads, film, music video. Use when approved keepers need a cut, a cut note or a client round changes a cut, or an EDL must be checked against the script. Triggers — "build the EDL", "cut it", "move the line to", "the word should be at", "shave a bit off the end", "carry the sound into the next shot", "beat sheet", "does the cut follow the script", "new version", "make the alternate". Not for reading a seed or setting its window — use video-take-review. Not for the render, the upscale or the delivery encode — use video-finish-qc. Not for voicing or sourcing the sound — use spot-audio-assembly.
In this repository16 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- ad-spot-preprodSkill
- client-roundsSkill
- designed-elementsSkill
- explainer-videoSkill
- film-preprodSkill
- mastering-audioSkill
- spot-audio-assemblySkill
- video-finish-qcSkill
- video-finishSkill
- video-gen-cost-gateSkill
- video-productionSkill
- video-prompt-dialectsSkill
- video-refs-continuitySkill
- video-take-reviewSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 45
Done when: every script line is a beat, every beat names its events, every marker carries the measurement it came from, and the file exists …
- Distinctive: line 130
Carried sound: when the picture cuts before the sound ends, cut the sound from the take at the cut frame and place it as an sfx at the next …
- Very specific: line 145
Done when: every VO, sfx, music and layer entry's note names the event or marker it derives from, and the beats file carries an …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Video Edit — the EDL
The edit is a derived document: the client script is the single source of truth, the keepers are
the operator's picks, and every timeline number is computed from them by a builder. A typed time is a
defect waiting for the next re-version; a hand edit to a shipped EDL is a lost audit trail. The finisher
(video-finish-qc) reads nothing but this file, and the beat gate refuses a finish the script does not
sanction. Editorial notes are cut notes first — four re-cuts in an afternoon cost zero credits;
a regen is the last rung of the repair ladder, never the first.
What varies. The ad grammar's numbers — a hook inside 2 s, the closer 0.7 s into the turntable, the last line
0.5 s before the hit, the card at its own render length (2.5 s by default) — and its captions and card belong to one genre: film and music video carry their
own (references/GENRE-GRAMMAR.md), and a brand's own spec overrides either. The
derivation, the gate and the new-file rule do not move — video-production/references/WHAT-VARIES.md.
1. Write the beat list from the script — before the EDL
Rewrite the client script (or the film beat sheet, or the track map) as prompts/<SPOT>-beats.json:
one beat per script line or on-screen stage direction, in script order, each naming the EDL events that
will realise it, the VO and sfx that belong inside it, the order rules (sfx → O.S. line → the reaction word), the
marker a line must clear (vo_ends_before), the cue edges that sit on a marker, a layer's lead before
the next beat, a minimum duration, and the ids that must NOT appear (forbidden_events, with the
reason the operator gave). Markers are {event, take} — measured on the keeper: the hit's RMS peak
in 25 ms windows, a word onset from the take's transcript, the frame a wall clears. Nothing is guessed.
- A sound-only beat still needs its visual cause on screen; a reveal is its own beat and its asset appears in no earlier beat; a client-cited beat is located in the DELIVERED file and the EDL history before anything changes.
- Schema and every gate rule:
references/BEATS-CONTRACT.md.
Done when: every script line is a beat, every beat names its events, every marker carries the measurement it came from, and the file exists before any EDL does.
2. Build the EDL by derivation
A keeper is take + in + out + the state at out (from video-take-review); the window's out-point
sits at least one frame before the take's own next internal cut. The builder — scripts/edl_build.py
on a plan, or a spot-specific build-edl.py whose every slot is an argparse flag — accumulates tl
from the ordered events, resolves every audio and layer time from a reference (a marker, an event
edge, another line's edge), writes the .bak-<ts> first, and rewrites the beats file's markers so the
gate follows the picks.
generated event → src = the pre-graded hero, look none, handle_head = in (the seek convention)
designed event → source designed, its own look, no src; the card = role endcard, its FULL render length (2.5 s by default)
native bed → only when the keeper EARNED its sound; native_audio_from/to mute what it did not
punch-in → zoom + anchor keeps the wrong thing out of frame without a regen
montage → COPY delivered spots' events, window them on the disclaimer's word times
cutaways under a voiced line (supplied footage, b-roll, stills)
→ the slots are the line's PHRASES, measured on the programme audio: scripts/phrase_slots.py (words on the
WHOLE voice file with two models → the mix shares the dry timeline, lag 0 → the cut 2 frames before each
phrase's first word); one continuous shot beats two cuts of one subject; a recommended cut goes to the
operator as a labelled proxy over the mix (scripts/preview_cut.py + its cut-check sheet) BEFORE any window
is conformed — the procedure: ad-spot-preprod/references/FOOTAGE-CURATION.md
prefix → events inserted at t=0 (a generated open) shift EVERY absolute time the plan holds — type cards,
the logo, cue edges — so those times are derived from events, never typed; a bed that is now too short
is re-looped by whole bars so its ending still lands on the card (`video-refs-continuity` § zoom-out chain)The genre decides the shape the beats take — ad spot (hook ≤ 2 s → reveal on a marker → product →
turntable + closer → card), film (the hero shot first, the self-revelation at 90 %, no captions, no
card), music video (the track map allocates the whole timeline first; later beats pay by trimming):
references/GENRE-GRAMMAR.md. The field contract the finisher reads,
and the plan's time-reference grammar: references/EDL-CONTRACT.md.
❌ A builder with no argparse — --help ran a default build and overwrote the live EDL.
✅ argparse on every CLI; .bak before every write; the same flags reproduce the same file.
A take's own cut inside a keeper's window is a rogue frame — unless the take COMPOSED it: a long generation's
internal shot change the operator kept is part of the keeper. Declare those on the event (accepted_cuts +
accepted_cuts_note); edl_check --cuts and the delivery QC then fail only an undeclared crossing. A number the
plan MEASURED from files (a bed vol, a duck, a lip-synced at, a loudness target) carries a derived block with
its inputs' hashes, and the build fails when an input changed (EDL-CONTRACT.md § Derived constants).
No cut bites a word. Where a take's own sound plays, every edge is placed from that SOUND, never from word times:
ASR word ends run early (one measured case: 0.19 s, the word's "-st" still sounding through the cut) and a speech-band
filter misses the sibilant tail. scripts/edge_audit.py reads each audible edge two ways and keeps the worse: the
broadband envelope against the event's own speech level, and two bands (300–3400 Hz and 3–7.8 kHz) each against its own
silence line. The closure of a stop consonant INSIDE a word is as quiet as a pause on the broadband read: one
compilation's bitten "ex|tent" sat in a 40 ms 't' closure 1.4 dB under the quiet line and passed every version, where the
two-band read puts it 19 dB over its line (2026-10-23). Each line also prints the quiet run that holds the edge; under
60 ms it is a fast join or a closure — a cue to listen, not a verdict. It names the fix, and with --transcripts it
marks a suggested gap that lies inside a transcript word. Either the edge moves into a measured gap (in/out, or
native_audio_from/_to where the picture must stay), or, when the picture has to change before the word ends, the
tail is carried over the next shot (§ 3). A fade never sits over a word. A supplied source that itself starts or ends
mid-word cannot be cut clean: declare it (accepted_edges) and tell the operator once; so is an edge the operator heard
and kept (the only gap there, a crosstalk the clip carries), with the ruling as the reason. A flag the delivered-file
cross-check raises is settled by this take read and a listen, never put down to the source's noise. A builder whose takes ARE the
programme (a compilation of supplied clips, each playing its own sound) declares qc.native_programme: true;
without it the audit finds no audible edge and says so.
Picture follows audio in a voiced section. Where a line is carried by cutaways, the voice sets the slots
(phrase_slots.py slots, whole frames from the phrase onsets) and each slot's clip is fitted to its slot — never the voice
to the clip (fit_slots.py): a longer window is cut, one short by ≤ 20 % is slowed (frames held, none invented), a shorter
one loops from its window start, and a slot with no clip — or a clip with no recorded pick — is reported and left empty,
which the finish refuses. A voice sped up, slowed or padded to fit a picture is the defect a listener hears. Slow and loop
fits are written as new files recorded as derived from their take (pick_gate.py), so the upscale and the finish treat
them as ordinary takes; the fitted EDL is a new file.
Done when: the builder prints the timeline, scripts/edl_check.py passes — with --require-endcard when the
beat list has a card (contiguous tl, spans = out − in, files present, windows inside their takes, the end card spanning
its whole file, no short cue) —
no derived constant is stale, and re-running the builder reproduces the EDL.
3. Place the sound from the picture
The operator gives placement as word × time × event (a word at a timeline second; a line during an event; a line ending just before the sign-off sfx; a quip's halves on the setup and the payoff). Each becomes a reference, never a number:
- The narrator chain derives backwards from the hit: the last line ends ≥ 0.5 s before
HIT(floored to the frame), earlier lines 0.1 s apart; the closer 0.7 s into the turntable; the disclaimer ends before the party or a montage window is lengthened. A product quip lands only after the product is visible; a quip's halves sit on setup and payoff. - An O.S. line sits at its take time. A dub (a line the venue refused) sits on the take's mouth shape, native muted from the onset.
- Carried sound: when the picture cuts before the sound ends, cut the sound from the take at the cut frame and place it as an sfx at the next event (a word's tail carried over the next shot; a tear carried into the next cut; a knock a beat earlier with its raps muted).
- Music is cut to the marker it ends on; a cue slams in ON the reveal marker, not on the cut before it; a bed runs under the turntable and the card; ducks under lines; no bed under the hit; a cue shorter than its span just ENDS — cut a longer excerpt. Designed-sound extras (chimes) are opt-in.
- Captions: the narrator only, word ranges, no punctuation, never over the card, never two cards on one frame; a swapped VO take re-runs the word times for that line only.
- A lip-synced line (the picture was generated to that voice) sits where the take's own audio says —
{event, take}by envelope NCC — and is RE-MEASURED whenever its file changes; a carriedatdubs the shot. - Mix constants (the bed under the voice, the duck) are measured from the client's reference stems when they exist and stamped with their inputs; a constant carried across rounds goes stale in silence.
The full grammar: references/AUDIO-PLACEMENT.md.
Done when: every VO, sfx, music and layer entry's note names the event or marker it derives from,
and the beats file carries an order/vo_ends_before/music_*_at rule for each placement the
operator specified.
4. Gate before any finish
python3 ~/.claude/skills/video-edit-edl/scripts/beat_sheet.py --root <project> --edl edit/<SPOT>-EDL.json
python3 ~/.claude/skills/video-edit-edl/scripts/edl_check.py --root <project> --edl edit/<SPOT>-EDL.json [--require-endcard] --cuts <cutlists.json>
python3 ~/.claude/skills/video-edit-edl/scripts/edge_audit.py --root <project> --edl edit/<SPOT>-EDL.json [--cuts <cutlists.json>]edge_audit.py exits 1 on any edge where a take's sound plays and a word is cut (BITE) or its onset or tail is
clipped (TIGHT), and 2 — NOT READ — when it read nothing because the EDL never says whose sound plays while a take carries
sound: a pass after reading nothing is no pass (one compilation's first cut read 0 edges and printed PASS over six bitten
words, 2026-10-22). Every EDL says it: qc.native_programme true or false, or native_audio_vol on the events. Each flag comes with the gap it measured and the take's cuts near it. This read of the take at the
exact edge is the gate. Its --deliv mode reads the delivered file at every join as a cross-check inside the QC
(video-finish-qc § 4). It skips the 10 ms either side of a join, where a hard cut rings through the band filter, so it
cannot stand in for the gate. Look at every flagged edge on a spectrogram before declaring or moving it: a sibilant or a
breath reads clearly there and nowhere else.
beat_sheet.py exits 1 on any FAIL — no finish runs on a FAIL, and its printed sheet rides in the
deliverable ask. edl_check.py --cuts takes the takes' own cut lists (from video-take-review's
qc_seed.py) and fails any window that crosses one (the rogue frames a 1 fps tile could not see) —
except a cut the event declares in accepted_cuts, which prints as INFO; --require-endcard whenever the
beat list carries a card.
A finish script calls the gate itself before its first stage; a pipeline script per version runs
build → gate → finish → QC and ends on a sentinel line, so a silent partial run cannot be mistaken for a
render.
A change to the cut path is gated by the A/V-sync suite. An edit to finish_spot.py, build_vo_stem.py or anything
else between the EDL and the delivered file re-runs scripts/av_sync_regress.py — synthetic takes whose flashes and pulses
share one clock, cut by the real finisher, read back from the decoded output — and every fixture must PASS before the change
lands. Its first run (2026-09-29) failed the finisher of the day on all five: the cut ran 36 frames long over 40 off-grid
events (each -ss/-t window rounded its own frame count), missing packets pulled a take's own sound 0.51 s early, a VO
file's timestamp gap moved the rest of the line 0.41 s early, and the two delivery limiters left the sound 10 ms late.
Done when: BEAT-SHEET PASS, EDL-CHECK PASS and, where a take's sound plays, EDGE-AUDIT PASS on the exact file
the finisher will read.
5. Revise by parameter, into a new file
A note from the operator or the client is applied as a change to the plan or a builder flag, and the
result is a new EDL file (-v9i, -final); the previous version stands untouched, and an alternate
deliverable is its own EDL with its own audio map and captions.
operator-marked frames → they ARE the cut: match them to the take (video-take-review frame_match.py),
cut that clip at those frames; no re-derivation, no verification round, no substitute
a trim ("first 0.9 s", "without the first 1/3", "shave 1/4 s off the end") → the window, on the frame
"cut before the heads swivel" → the last STILL frame by motion energy; "just before she trips" → the onset
an insert / a re-order → scripts/edl_insert.py (shifts everything downstream; a spanning cue keeps playing;
--replace re-times an existing insert)
a bad short shot → drop it; a better shot in an older version → swap it; "cuts too soon" → lengthen
a new take among the keepers → a hybrid EDL, its cuts mixed in
"the word is cut off" → edge_audit.py on EVERY edge, never only the one cited; each fix is an edge in a measured gap
or a carried tail
a missing sound → a placed sfx; a lost word → a dub; the wrong thing in frame → a punch-in
only then → a regen (video-refs-continuity → video-gen-cost-gate), with the approved cut frozenLocate first, then cut: the operator's frames identify the take's own piece in a minute, where re-cuts and a regen chase a phantom.
Done when: the new version is a new file, the previous one is byte-identical, the pipeline ran through the gate with its sentinel, and "lock these in" placements are unchanged.
Failure behavior
- A
FAILfrom either gate stops the finish; fix the plan, rebuild, re-gate — never edit the EDL's numbers by hand and never run the finisher around the gate. - A missing keeper (
take: null) stops the build with the event named; the pick comes from the operator, not from the builder. - A cue shorter than its span, a window past its take, a caption over the card: each is a FAIL with the fix named; none is a warning to ship through.
FAIL STALEfrom the builder → an input of a derived constant changed since it was measured: re-measure the constant from the current inputs, then re-stamp (--stamp-derived).--allow-stale-derivedbuilds anyway and prints every stale input — a layout to look at, never a version to finish.- A window crossing its take's own cut → a rogue frame, unless the take composed that cut and the operator kept it:
declare it on the event (
accepted_cuts+accepted_cuts_note); never drop--cutsto reach a PASS. EDGE-AUDIT NOT READ→ the EDL never says whose sound plays and a take carries sound. Declare it —qc.native_programme: truewhen the takes ARE the programme,falsewhen every take is muted, ornative_audio_volper event — and re-run; never pass--no-gateto get past it.EDGE-AUDIT FAIL→ a word is cut at an edge. Move the edge into the gap the audit measured, or carry the tail (§ 3). Declareaccepted_edgeswith the reason only for a source that itself starts or ends mid-word, or for an edge the operator heard and kept (the ruling is the reason). Never pass it by fading over the word, or by loosening--speech-db/--quiet-dbuntil it reads ok: those are leads from one job, re-measured against the ear on this project's own takes.- An end card spanning less than its file → the finisher plays the card from its first frame and cuts the master at
runtime_s, so the card's tail never plays and nothing else says so: span the whole file, or declare a meant trim on the event (card_trim_note, printed as INFO). A card starting past 0 always fails — the finisher never seeks a card. - The project tree has no VCS: every writer drops a
.bak-<ts>-<why>first, and a shipped EDL is never the file being edited.
Scripts
| script | does |
edl_build.py --root --plan --out [--beats] [--stamp-derived] [--allow-stale-derived] [--no-lufs] | the plan → EDL derivation; rewrites the beats markers; stamps and checks the input hashes of every derived constant (a stale one stops the build) |
beat_sheet.py --root --edl [--beats] | the script-fidelity gate; exit 1 on FAIL; prints the sheet; the verdict line names the EDL; the list is --beats, else the EDL's beats (edl_build.py --beats writes it), else prompts/<spot>-beats.json, and a marker on an event the cut lacks is a named FAIL |
edl_check.py --root --edl [--require-endcard] [--cuts] [--fps] · --selftest | the structural read: continuity, files, windows, cues, the seek convention, rogue frames — a crossing the event declares in accepted_cuts prints INFO; a VO line with no source WARNs; an end card starting past 0 or spanning less than its file FAILs (a trim declared in card_trim_note prints INFO); two adjacent whole-event accepted_still holds WARN (two stills in a row; the end card aside); the verdict line names the EDL |
edge_audit.py --root --edl [--cuts] [--transcripts <dir>] [--all-native] · --deliv <file> · --selftest | no word bitten at a cut: every edge where a take's sound plays (native_audio_vol > 0, or qc.native_programme) read two ways, the worse kept — a broadband 10 ms envelope against the event's speech level, and two bands against their own silence lines (--two-band-bite-db 12) — with the quiet run holding the edge printed (under --min-gap-ms 60: listen): BITE / TIGHT with the measured gap (marked when it lies inside a transcript word), CARRIED for a tail placed as an sfx, ACCEPT for accepted_edges, an L-cut (audio_lead) read at its SOUND join with the picture join printed L-CUT; --deliv reads the delivered file at every join (a join under a VO line, an sfx or a cue is reported, never judged); word times print for orientation only; exit 1 on BITE/TIGHT, 2 on NOT READ (an EDL that never says whose sound plays, a take that carries sound) or an unreadable file |
edl_insert.py --root --edl --after --id --take --in --out [--replace] | insert or re-time an event, shifting everything downstream |
fit_slots.py --root --slots --assign --edl --out [--slow-limit 0.2] [--fit-dir edit/fit] [--plan] · --selftest | picture follows audio: each voiced slot's clip CUT, SLOWED (≤ 20 % short) or LOOPED to exactly the slot's frames, a slot with no clip or no recorded pick reported MISSING and left empty; fits recorded as derived from their take; writes a new EDL; exit 3 on a missing slot |
av_sync_regress.py [--only offgrid,native,late,gap,vo] [--events 40] [--fps 24] [--grid] [--debug] [--keep <dir>] | the A/V-sync regression suite for the cut path: off-grid cuts, the take's own audio, a late audio track, missing audio packets and VO placement, through the real finisher; exit 1 on any FAIL |
trim_for_upscale.py --root --edl --ids [--out-dir] | cut keepers with handles for a hosted upscale; writes handle_head ; refuses a take with no recorded pick and records each trim as derived from it |
phrase_slots.py words --audio --out · timeline --mix --dry · slots --words --phrases "a|b|…" --fps --out [--lead 2] [--next-onset|--end] [--lag] [--onset S1=<s>] · --selftest | picture slots for a voiced section: two-model word times on the whole file with their disagreements, the proof that the mix shares the dry voice's timeline (envelope lag and score), and phrases → onsets → the cut --lead frames before each → slots in whole frames; flags a short slot and an onset the models dispute (pass the envelope read with --onset) |
preview_cut.py --root --plan --mix --out [--size 540x960] [--aspect 9:16] [--alt S1=<clip>:<f0>:<x> …] [--check-sheet <jpg>] · --selftest | a labelled REVIEW PROXY of a recommended cut over the programme mix: each slot's window through its delivery crop, grey slates for what is not made yet, --alt for a side-by-side version without touching the plan, and the check sheet — the frame either side of every cut, with timeline frame numbers — to be read before the preview is sent; never a deliverable, never overwrites |
Cross-references
references/EDL-CONTRACT.md·references/BEATS-CONTRACT.md·references/AUDIO-PLACEMENT.md·references/GENRE-GRAMMAR.md.video-take-review— the keepers and their windows, the cut lists,frame_match.pyfor an operator's frame.video-finish-qc— consumes the EDL: upscale, look, master, deliver, and the QC that reads the delivered file back against it;video-finish— the per-clip order it applies.video-refs-continuity→video-gen-cost-gate— the regen rung, only after the ladder above.- Handoffs follow
~/.claude/skills/video-production/references/CHAIN.md. - Deeper context — the upstream projects behind the rules here:
video-production/references/CONTEXT-MAP.md§ Where the deeper context lives.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

