agentleFS
koptsev63koptsev63/premiere-claude-bridge/skills/film-editing/SKILL.md

film-editing

Skill2 starsChanged 14 days agoMITView on GitHub

Editing principles for Premiere Pro work via the Claude Bridge. Encodes Walter Murch's "In the Blink of an Eye" — the Rule of Six, the blink theory, misdirection, eye trace, dreaming in pairs — as concrete decision rules Claude must apply when cutting a sequence. Trigger this skill whenever editing video — whether building a teaser, a trailer, a documentary cut, a reel, a short, or a feature assembly — and when reviewing or critiquing an existing edit. Pair with `mcp__premiere__*` tools.

  • Reads credentials
  • Installs packages

The file

Show its rules and text

We split this skill into the rules it gives an agent

19 rules. About 0 are common, 12 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Always paired with the mcp__premiere__* tools (pr_eval_jsx, pr_get_active_sequence, pr_list_timeline, pr_set_playhead, pr_add_marker, …

    line 18
  2. Distinctive:

    Cut at the end of a thought, not in the middle of one: Every shot should end at a moment of completion (the end of a gesture, the end of a …

    line 51
  3. Distinctive:

    Use when continuity matters and you must hide the seam.

    line 74
  4. Distinctive:

    Before each cut, ask: where is the viewer's eye in the outgoing frame?

    line 80
  5. Distinctive:

    If the new focal point lands near the old position → cut works for eye trace.

    line 86
  6. Distinctive:

    If not — either re-frame (motion effect / Position kf), or reorder the cut, or accept the eye-trace cost (allowed if the upper four rules …

    line 87
  7. Distinctive:

    When selecting clips for a sequence: storyboard the pairs, not the singles.

    line 97
  8. Distinctive:

    Cut by feel, then justify: If a cut feels wrong but you can't say why — trust the feel, find the why later.

    line 126
  9. Very specific:

    When using pi.setInPoint(ss, 4) and pi.setOutPoint(ss + dur, 4) via the bridge, the out-point of each clip should ideally fall at or just …

    line 136
  10. Distinctive:

    Before placing a clip on the timeline:

    line 142
  11. Distinctive:

    After laying down a sequence:

    line 151
  12. Distinctive:

    When Vladimir uses Russian terms, map to Murch concepts:

    line 161
  13. Very specific:

    Classify: keep or drop: Write desc_ru + tags + keep per clip and feed back via --desc.

    line 251
  14. Distinctive:

    Only the transcript reveals that.

    line 288
  15. Very specific:

    After that the editing skill can call /watch on any clip in the project bin.

    line 395
  16. Very specific:

    Don't watch everything: Use analyze_clips.py first (motion + audio + horizon) to rank, then /watch only the top 10–15 candidates.

    line 400
  17. Very specific:

    Self-verification is mandatory and fail-closed: Run core.qc with the OpenCV venv before saying "done".

    line 479
  18. Distinctive:

    Report verified vs pending: Never claim a fix you did not measure.

    line 489
  19. Very specific:

    After rendering, confirm the file actually carries an audio stream (ffprobe ...

    line 499

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Film Editing — Murch's Operating System

Encodes the canonical principles of film editing as a hierarchy Claude follows when making cut decisions inside Premiere via the bridge. Source: Walter Murch, In the Blink of an Eye: A Perspective on Film Editing (1995, expanded 2001) — the most-cited text in editing pedagogy. Murch edited Apocalypse Now, The Conversation, The English Patient (Oscars for both editing and sound).

When to invoke

  • Building any sequence on a Premiere timeline (teaser, trailer, scene, reel)
  • Choosing in/out points or clip durations
  • Deciding cut order
  • Reviewing an existing cut and proposing changes
  • Anytime Vladimir says: смонтируй, перемонтируй, нарежь, склей, тизер, трейлер, монтаж, сцена, ритм, темп, edit, recut, cut, pacing

Always paired with the mcp__premiere__* tools (pr_eval_jsx, pr_get_active_sequence, pr_list_timeline, pr_set_playhead, pr_add_marker, pr_export_ame).


I. The Rule of Six — the priority stack

Murch's hierarchy for evaluating any cut. Read top-down: an upper rule outranks every rule below it. Allocations are Murch's own (lecture, Sydney 1988):

#CriterionWeightWhat it means in practice
1Emotion51%Does the cut feel right for the audience's emotional state at that beat? "If you're true to the emotion of the moment, the audience will forgive technical problems."
2Story23%Does the cut advance the story? Is information delivered when the audience needs it?
3Rhythm10%Does the cut land at the right musical/breathing moment? Editing is "visual music."
4Eye trace7%Where is the viewer's eye at the cut point — and where does the new shot place the next focus?
52D plane (planarity)5%Compositional continuity within the frame: does the new shot's composition flow from the old?
63D space (continuity)4%The 180° rule, screen direction, spatial geometry.

Operational consequence — when criteria conflict, sacrifice from the bottom:

  • Sacrifice 3D continuity to preserve eye trace.
  • Sacrifice eye trace to preserve rhythm.
  • Sacrifice rhythm to preserve story.
  • Sacrifice story to preserve emotion.
  • Never sacrifice emotion.

Murch's exact line: "An ideal cut satisfies all six criteria at once. If you can't have all six, get the top four. If you can't have the top four, get the top three. The top three is most important — preferably the top two, and most of all the top one."


II. The Blink Theory

Murch's central insight: humans blink at moments of mental punctuation — when one thought completes and another begins. Cuts work because the audience already does this internally; a good cut aligns with where the audience would naturally blink.

Rules:

  1. Cut at the end of a thought, not in the middle of one. Every shot should end at a moment of completion (the end of a gesture, the end of a sentence, the end of a beat).
  2. The cut is the visual equivalent of the audience's blink — make it land where the audience is mentally ready to receive a new image.
  3. Watch the actor's eyes — performers blink at the same moments the audience does. If your subject blinks at frame X, X is a candidate cut point.

III. The Idea Cut vs the Continuity Cut

Murch distinguishes two paradigms:

  • Continuity editing — the invisible cut, hides the join (Hollywood classical).
  • Idea editing — uses the discontinuity itself as a meaning-maker (Eisenstein, Resnais, Godard).

For documentaries, teasers, and montage sequences (like Grave Stakes): lean toward idea cuts. The juxtaposition between two shots produces a third meaning that exists in neither shot alone. Example: the НОВОСИБИРСКИЙ КРЕМАТОРИЙ T-shirt + a guy intensely digging a grave = the absurdist joke.


IV. Misdirection

Borrowed from stagecraft: distract the viewer's attention away from the cut so the cut is invisible. Tools:

  • A sudden movement on one side of the frame masks a cut on the other side.
  • A character's quick gesture or look can hide a transition.
  • An on-screen sound spike (door slam, gunshot, hand clap) at the cut point.

Use when continuity matters and you must hide the seam. Skip in idea-cut sequences where the seam IS the point.


V. Eye Trace — concrete protocol

Before each cut, ask: where is the viewer's eye in the outgoing frame? Then ensure the incoming shot's primary subject lands at or near that same screen position.

Practical protocol when working in Premiere via the bridge:

  1. pr_set_playhead to the last frame of the outgoing clip.
  2. Identify the focal point (face, action, contrast peak).
  3. pr_set_playhead to the first frame of the incoming clip.
  4. If the new focal point lands near the old position → cut works for eye trace.
  5. If not — either re-frame (motion effect / Position kf), or reorder the cut, or accept the eye-trace cost (allowed if the upper four rules win).

VI. Dreaming in Pairs

A cut is never about one shot — always about two. Always evaluate the A→B relationship, not A or B in isolation.

  • Two cuts that work individually may not work together (rhythm collision).
  • Two cuts that look weak alone may sing as a pair.

When selecting clips for a sequence: storyboard the pairs, not the singles.


VII. Pacing rules of thumb (Murch + standard practice)

These are starting points, not absolutes. Override per Rule of Six.

Beat typeTypical durationWhy
Establishing / breath shot5–8 secAudience needs time to orient
Hook / opening reveal4–6 secLong enough to register, short enough to provoke
Comedy beat4–5 secJoke needs time to read; cut on the audience's mental "punchline received"
Rhythmic action montage2–4 sec eachCumulative energy; no single shot dominates
Cinematic / emotional center6–8 secThe shot the trailer is built around — let it land
Interview / talking head5–7 sec minimumBelow 5s the speech feels truncated
Title card3–5 secLong enough to read aloud + 1 sec
End title6–10 secClosure beat
Climax / payoff reveal6–10 secThe "moneyshot" — overrides all rhythm rules

Ratio rule: the longest shot in a teaser should be 2–4× the shortest. More than that and the sequence breaks rhythm; less and it feels monotone.


VIII. Process — the editor's workflow Murch advocates

  1. First viewing — DON'T touch tools. Just watch all the rushes. Make notes by hand.
  2. Mark "selects" — the moments that are alive, the gold.
  3. First assembly is always too long. The teaser will be 2–3× its target length on first pass.
  4. Cut by feel, then justify. If a cut feels wrong but you can't say why — trust the feel, find the why later.
  5. Watch a cut, walk away, watch again. Distance reveals what's hidden when too close.
  6. Show to one person you trust before locking. Their gut reaction is data.

IX. The Decisive Moment

Borrowed from Cartier-Bresson: the single frame in any take where everything aligns — gesture, expression, light, composition. For every clip going into a sequence, identify its decisive moment and ensure the cut either lands ON or LEADS TO that frame.

When using pi.setInPoint(ss, 4) and pi.setOutPoint(ss + dur, 4) via the bridge, the out-point of each clip should ideally fall at or just past the decisive moment — never before it.


X. Concrete operational checklist for Premiere via the bridge

Before placing a clip on the timeline:

  • Have I identified the decisive moment? (If not — pr_set_playhead and scrub via pr_eval_jsx to find it.)
  • Does this clip serve emotion FIRST?
  • Does it advance story?
  • Is its duration appropriate to its beat type (table above)?
  • Does its first frame eye-trace from the previous shot's last frame?
  • Does its last frame complete a thought?
  • If breaking 3D continuity — am I doing it deliberately?

After laying down a sequence:

  • Pull pr_list_timeline and audit the duration distribution. Is the longest shot 2–4× the shortest?
  • Are the 3 most important emotional beats the 3 longest shots?
  • Is there variety — are no 4 consecutive shots the same length?
  • Mark suspect cuts with pr_add_marker for human review.

XI. Russian terminology mapping

When Vladimir uses Russian terms, map to Murch concepts:

RussianMurch
склейкаcut
монтажная фразаmontage sequence
ритм / темпrhythm
эмоциональный центрemotional center / decisive moment
внутрикадровый монтажintra-shot continuity
8-ка / правило восьмёрки180° rule (3D continuity)
перебивкаcutaway / reaction shot
монтажный аттракционidea cut / Eisensteinian montage
стык по движениюmotion-matched cut (eye-trace tool)
на эмоции"cut on the emotion"
дать вздохнуть"let it breathe" (extend a shot)
дожатьtighten, trim further

XII. Bridge tool reference (one-liners)

ToolUse during editing
mcp__premiere__pr_statusSanity check before any session
mcp__premiere__pr_get_project_infoInspect bins, find clips by name/nodeId
mcp__premiere__pr_get_active_sequenceGet sequence specs (fps, dimensions, tracks)
mcp__premiere__pr_list_timelineAudit current cuts (durations, in/out, order)
mcp__premiere__pr_get_playhead / pr_set_playheadScrub to specific timecode
mcp__premiere__pr_add_markerMark decisive moments, problem cuts, notes
mcp__premiere__pr_export_ameSend to Adobe Media Encoder for output
mcp__premiere__pr_eval_jsxEscape hatch for any custom ExtendScript (set in/out, insertClip, motion params, color)
pr_make_sequence / pr_build_sequences (0.6)Sequences from clip ranges with NO dialog (never createNewSequence with a preset id: it opens "Создать эпизод" and hangs the bridge)
pr_import_media / pr_probe_mediaCodec gate first: AV1/VP9 import as sound only; get the H.264 copy command for just the range; nothing under 2 GB free
pr_set_motion / pr_set_motion_keyframesScale/Position in pixels; hold: true between shots (interpolation 4; 5 is Bezier and slides). Keys live in media time (inPoint + t), the tool converts; verify with a frame export, getValueAtTime cannot tell
pr_add_markers / pr_get_inoutMarkers in bulk; the clip borders after the editor's manual trim, for a render from his borders
pr_dialog_checkA tool timed out? Ask this before touching the keyboard: it names the modal window and the button
pr_journal_snapshot / pr_journal_report, pk.js journal (0.7)The editor's journal: his decisions (trims in frames, razors, moves, J/L cuts, tempo) from live snapshots or his Auto-Save folder. With his consent; structure only. Feed the numbers into §III rules

XIII. Analysis pipeline — making the LLM "see" motion

Hard truth: by default the LLM sees stop-frames, not motion. Murch's Rule of Six leans on perceiving how a gesture begins and completes — impossible from one frame. The pipeline below partially closes that gap.

Tool: tools/analyze_clips.py

# needs the OpenCV venv for shake + horizon (.venv/bin/python):
.venv/bin/python skills/film-editing/tools/analyze_clips.py \
  /path/to/raw_footage \
  /path/to/output_log [--whisper] [--desc descriptions.json]

Per clip, two layers. Machine layer (measured by the program):

OutputWhat it capturesLLM use
_thumb.jpgmid-clip frame, 480widentify content (faces, objects, location)
_strip.jpg6 evenly-spaced frames hstackedapproximate motion: see how subject moves across the clip
motion_scorescene-change frequencydistinguish action clips from static b-roll
audio_peak_db + audio_peak_time_secloudness peak + whenfind applause, gasps, dialogue moments — these are emotional anchors
audio_mean_dbaverage loudnessidentify speech-bearing vs ambient-only clips
horizon_tilt_deg + horizon_correction_filterlevel check (OpenCV)flag/level tilted shots — unreliable on vertical video, do not auto-rotate portrait
shake_score + needs_stabilizationcamera-shake (OpenCV, 24 samples)rank jitter; feeds core.value
speech_text (with --whisper)transcript first 300 charsexact dialogue + timing

Meaning layer (written by a person or by Claude looking at the thumbs, fed back via --desc descriptions.json, keyed by clip name):

FieldWhat it isWhy it exists
desc_ruone line: what is actually in the shot, plain Russiana metrics dump is not a usable log; the picture's content is the thing you cut on
tagskeywords (дед, сарай, руки, природа, монолог…)search/group; the cut is built from these, not from loudness
keeptrue = part of the story, false = junk to dropthe program cannot know a clip is "not from this story" — only eyes can

Output bundle: report.json (machine-readable, UTF-8) + report.html (contact sheet with desc/tags + a green в историю / red лишнее badge). Both are rewritten after every clip, so the table is viewable while the run goes.

Mandatory editorial protocol with this data

The metrics rank by loudness and movement. They have no eyes and no meaning — left alone they produce a chaotic dump that glues a market, a cow and a stranger together because all three read "loud + moving". Meaning is the agent's job, and it comes first.

  1. Run the pipeline on the source folder (.venv/bin/python, ~15 min for 60 clips incl. shake/horizon). It writes the table after every clip.
  2. SEE every clip. Build contact sheets from the thumbs (ffmpeg tile=7x3) and Read them. One mid-frame can lie (see Grave Stakes below) — for anything ambiguous read its _strip.jpg or /watch it.
  3. Classify: keep or drop. Write desc_ru + tags + keep per clip and feed back via --desc. Mark keep:false for anything not in this story — the author's later life, another place/date, a stranger. (Дед: 8 of 63 were a husky, a European city, a café, a child — dropped.)
  4. For talking footage, get the words, then order by meaning. Loudness never tells you what he says. Transcribe the talkers (--whisper, or the /watch local backend, real --language + --word_timestamps), read the transcripts yourself, and sequence the spoken beats by content/arc — that is what "сложить по смыслу" means. Picture serves the words: market talk → show the market; hard-labour talk → his hands, the shed.
  5. Only now use the metrics — for in/out and ranking within a kept, meaningful group: audio_peak_time_sec as a candidate IN-anchor, shake/horizon to flag fixes, core.value to order energy inside a beat.
  6. Cross-reference rankings against your gut — a clip that ranks high but reads wrong usually has the wrong in-point; look at its strip again.

Lessons from Grave Stakes case study

  • Don't trust a single thumbnail. The clip 00172.MTS looked like a static "wooden frame on grass" from one mid-frame. The strip revealed: first half static, second half a tight digger close-up at ss≈15+. Almost dropped a strong clip.
  • Audio peak ≠ visual peak. For documentary footage, audio peaks (a clap, a shout, a tool strike) often mark the moment that ought to be in the cut. Use audio_peak_time_sec as a candidate IN-anchor.
  • Whisper tiny model fails on noisy field audio in non-English languages. For real dialogue extraction use --model medium --language XX. Plan for ~15 sec/min of audio per Whisper pass.

Lessons from the Дед case study

63 phone clips of an old man in a Russian village (Aug 2019), lots of talk and dead air. A value-ranked auto-cut on this was rejected outright — twice — and the reasons are the rules above:

  • A loudness/motion auto-cut on talking footage is a chaotic dump. It had no editorial logic and it glued in clips that were not the story. The metric layer is blind; do not ship its order as a cut.
  • The agent must SEE and CLASSIFY before cutting. Contact sheets of all 63 revealed 8 clips that belonged to the author's later life (a husky in a flat, a European street, a café, a child) — invisible to motion/audio, obvious to eyes. Drop them via keep:false.
  • "Сложить по смыслу" = transcribe, read, then sequence by content. The monologues were about repression, prisons, hard peasant labour, the market. Only the transcript reveals that; loudness ranked the silent action clips on top instead. Picture follows the words.
  • The table must be COMPLETE. A 12-clip subset is not a log of a 63-clip shoot. Run all of it; every clip gets desc_ru + tags + keep.
  • The horizon detector lies on vertical video. One portrait clip read −29.67°; auto-rotating it would have wrecked the frame. Trust horizon on landscape only; never auto-rotate portrait.

Roadmap for the analysis pipeline

CapabilityStatusHow
Motion-score✅ shippedffmpeg scene detect
Audio peaks✅ shippedffmpeg astats + ametadata parse
6-frame motion strip✅ shippedffmpeg hstack
HTML contact sheet✅ shippedinline jinja-style template
Horizon tilt + filter✅ shippedOpenCV (.venv), unreliable on portrait
Shake score✅ shippedOpenCV phase-correlation, 24 samples
Russian desc + tags + keep/drop✅ shipped--desc file, written by agent/person
Story-by-meaning✅ processtranscribe → read → sequence (not metrics)
Speech-to-text⚠️ use small/medium + --languageWhisper (tiny/base garble dialect+mat)
OCR (signage, T-shirts)🚧 plannedtesseract on motion-strip frames
Auto silent-trim (kill dead air)✅ shippedcore.silence — ffmpeg silencedetect → speech segments; tighten_cutlist repacks. Дед: 38-51% of a talking take was dead air
Optical flow direction🚧 plannedffmpeg mestimate filter for match-cut
Multicam sync🚧 plannedaudio waveform xcorr
Face recognition⛔ out of scopeprivacy boundary — search by what's said, not faces

XIV. Real video perception via the bundled /watch skill

The honest limitation called out in §XIII — "the LLM sees stop-frames, not motion" — is partially closed by vendoring bradautomates/claude-video into skills/watch/. See skills/watch/ATTRIBUTION.md for the full credit.

/watch does what our 6-frame motion strip can't:

  • Pulls 30–100 frames per clip (auto-scaled to duration), not 6
  • Pulls a timestamped transcript — native captions if available, Whisper API (Groq or OpenAI) as fallback
  • Lets Claude Read every frame as a multimodal image and align to the transcript

When to use /watch from inside an editing session

Editing taskWithout /watchWith /watch
Verify a candidate cutone mid-frame thumbnail--start ss --end ss+dur → ~30 frames + transcript over the cut window
Find the decisive moment in a clipguess from one frame + audio_peak_time_secscan ~60 frames, hear what's said, pick precisely
Read interview contentbroken tiny Whisper (see §XIII)--whisper groq runs whisper-large-v3 (handles Hungarian, Russian, etc.)
Study a reference trailern/a/watch <youtube-url> "what's the structure?"

Concrete recipes

Find decisive moment in a clip before placing it:

python3 skills/watch/scripts/watch.py "/path/to/clip.MTS" --start 28 --end 35

Then in the editing thread: read the frames, pick the in/out, call pi.setInPoint(...) via the bridge.

Get a real transcript of the interview clip used in Grave Stakes (Hungarian) — three backends, no key needed if you have local whisper:

# 1. Local backend (no API key, runs offline). Recommended for non-English:
python3 skills/watch/scripts/watch.py "/path/to/Videos/00195.MTS" \
    --whisper local --language Hungarian

# 2. Groq cloud (faster, ~$0.0002/min, needs key in ~/.config/watch/.env):
python3 skills/watch/scripts/watch.py "/path/to/Videos/00195.MTS" --whisper groq

# 3. OpenAI cloud (slower, ~$0.006/min, needs key):
python3 skills/watch/scripts/watch.py "/path/to/Videos/00195.MTS" --whisper openai

# Default (no --whisper flag): tries Groq → OpenAI → local in order.

The transcript appears in the markdown report. Use the timestamped lines to pick which 6-second slice of the interview lands on the timeline.

Local backend setup (one-time, zero ongoing cost):

pip install -U openai-whisper
# Default model is "medium" (~1.5GB, downloaded on first run).
# Override with: WATCH_LOCAL_WHISPER_MODEL=small  (244MB, faster, decent quality)
#                WATCH_LOCAL_WHISPER_MODEL=large-v3  (3GB, best, slower)

For Grave Stakes' noisy field-recorded Hungarian, small --language Hungarian was tested and produces usable transcripts in ~30s on M-series Mac. medium and large-v3 improve accuracy further but take 2-5× longer.

Reference-driven cutdown:

# Vladimir wants the new teaser to feel like the Sundance trailer for Anora
python3 skills/watch/scripts/watch.py "https://youtu.be/<anora-trailer>" "describe the cut structure beat by beat with timestamps"

Claude will return a beat sheet you can encode as a recipe in skills/trailer-bridge/.

Setup (one-time)

# macOS — auto-installs ffmpeg + yt-dlp via brew
python3 skills/watch/scripts/setup.py

# Pick ONE Whisper backend:

# (a) Free, offline, no key — recommended default. Handles any language well:
pip install -U openai-whisper

# (b) Cloud (faster for short clips), Groq (cheap) or OpenAI:
echo 'GROQ_API_KEY=gsk_...' > ~/.config/watch/.env
chmod 600 ~/.config/watch/.env

After that the editing skill can call /watch on any clip in the project bin.

Cost discipline

  • Each /watch call burns ~30–100 image tokens. On a 108-clip raw folder, watching all of them = ~5 000 frames = significant context pressure.
  • Don't watch everything. Use analyze_clips.py first (motion + audio + horizon) to rank, then /watch only the top 10–15 candidates.
  • For long clips, always use --start/--end once you know roughly where the action is.

XVI. The automated pipeline (core/)

The editing decision is NLE-agnostic: produce one Cutlist, a backend renders it. The full chain, in order, with the module that owns each step. See core/README.md, epics #6 (core) and #7 (roadmap: color, variant board, voice-directed turnkey).

#StepModuleWhat it gives you
1Analyzeskills/film-editing/tools/analyze_clips.pyreport.json: motion, audio_peak(+time), horizon tilt+filter, shake_score, duration
2Value ("meat")core.value.ValuePoolcomposite rank + explicit meat_tag; protected() is never dropped; anchors() reserved for PIT/PAYOFF
3Variantscore.variants.build_variantsDRIVE + BREATH — two contrasting cuts, both is_clean by construction, length-aware. Two, because the director picks the feel
4Conformcore.conformbare clip names → real media on this machine (+ proxy)
5Cleanupcore.cleanup.corrections_for_cutlisthorizon leveled whenever flagged; stabilization for relative outliers only
6Rendercore.renderanamorphic-safe geometry (un-squish) + horizon rotate; never ffmpeg deshake
7StabilizeResolveAdapter.apply_corrections() → TimelineItem.Stabilize()Resolve's own pro stabilizer (Similarity/Perspective), live in DaVinci
8Backendcore.probe.select_adapter / core.adaptersPremiere (ExtendScript via bridge) / Resolve (Python API, Studio) / FCPXML (round-trip)
9Review loopcore.review_loopanalyze_cutlist (deterministic Murch) → CutlistPatch → re-render, with history/diff()
10QC gatecore.qcmandatory: geometry no-squish + residual-shake; fail-closed
11Colour gatecore.colorgatemandatory before showing a grade: burnt (clipping / oversat / skin) and invisible (mean ΔE, floor 5.0); assert_ok() fail-closed
12Round tripcore.prprojreads the editor's saved .prproj back — his cues, his razors, his cut points — so subtitles and grade conform to his version
13Loudness gatecore.loudnessshots levelled against each other, then static gain + true-peak limiter; check_delivery() gates LUFS, true peak and shot-to-shot spread, fail-closed
14Delivery integritycore.qc.qc_deliverythe file decodes clean end to end, has the promised size and rate, and has sound

Discovery + finishing modules (not strictly sequential):

StepModuleWhat it gives you
Librarycore.library.MediaLibrarytag + search the footage by speech/tags/name, find_lines() a character's dialogue, and to_cutlist() pulls matches into a NEW sequence (Denis's "split by character / don't lose it"). NO face recognition — by what's said.
Subtitlescore.subtitlestranscript → SRT (deliverable, e.g. DUALITY SUB/SRT) + styled ASS karaoke (2-word UPPERCASE, MarginV 90 safe-zone); burn() via ffmpeg. Word-level karaoke needs Whisper --word_timestamps (now on in skills/watch). Auto-align: timeline_transcript(cutlist, transcripts) maps per-clip transcripts onto the assembled — or dead-air-tightened — cut, so subtitles follow the edit; parse_srt reuses an existing SRT as the source.
Overlayscore.overlayslower-thirds / title / brand (lime #C8FF00) via ffmpeg drawtext; from_markers(cutlist) auto-titles from the edit's own beats.
Screen insertcore.screen_compa clip inside a phone / monitor / TV in the plate: ECC camera track, quad or mask, optional glass/CRT look, colour-exact Rec.709 I/O; the gate proves the plate outside the screen came back unchanged. Affine track only - no parallax, no occlusion.
Eyes + hatchcore.adapters.resolve_run, mcp-server/pk.jscomposited timeline frames from Resolve (still, grab), clip dump with gaps(), and a script runner on each side for what the typed tools do not cover.
Dead aircore.silencedetect silence (ffmpeg silencedetect) → keep speech-dense regions; tighten_cutlist removes pauses inside takes so a rambling talking head goes tight. Loudness-gated, not semantic — pair with the meaning pass.

Progress is measured, not vibed: examples/grave-stakes-teaser/benchmark/ scores every version with analyze_cutlist (v3 not-clean → v4 clean → v5 two clean variants).

The review loop (operationalizes §VIII)

Assemble → perceive (ReviewLoop.watch_plan() + /watch, §XIV — this is where taste lives, yours) → measure (analyze_cutlist: §VII 2-4× ratio, §X monotony, beat-pacing — objective inputs, not a substitute for taste) → patch (CutlistPatch, immutable, validated) → re-render to any backend. Repeat until is_clean() and the emotion (Rule 1) is right — emotion is never decided by the analyzer.

python -m core.cutlist validate examples/grave-stakes-teaser/cutlist_v3.json
python -m core.probe                       # which NLE is reachable now
python -m core.tests                       # full core suite (must be green)

XVII. Hard rules (non-negotiable — learned from real defects)

These were paid for in shipped mistakes. Do not relearn them.

  1. Anamorphic is the default trap. Source .MTS is 1440×1080 SAR 4:3 — it must display 1920×1080. A naive scale=1920:1080 squishes faces while the container DAR still reads 16:9, so a thumbnail check misses it. core.render applies pixel aspect before fit, always. core.qc.qc_geometry exists solely to catch a regression here.
  2. ffmpeg deshake is banned. It crawls/jitters — worse than the untouched handheld. Real stabilization is Resolve's TimelineItem.Stabilize(). A standalone stabilized MP4 needs libvidstab (2-pass vidstab) — a tracked follow-up; never fake it with deshake.
  3. Stabilize relative outliers only, never blanket. Handheld documentary energy is intentional; over-smoothing kills it (Rule 1/3 > technical polish). core.cleanup uses median + k·MAD.
  4. Self-verification is mandatory and fail-closed. Run core.qc with the OpenCV venv before saying "done"; "can't verify" ≠ pass. Also read a full-resolution frame yourself — a tiled thumbnail sheet hid the squish once. The QC gate has already caught my own measurement bugs; trust it over a clean-looking metric.
  5. Two variants, not one. DRIVE/BREATH — the director chooses the feel. Taste is never the system's call.
  6. Interpreter map. Resolve fusionscript binds CPython 3.9–3.13 (not 3.14); otio file-IO needs 3.12/3.13; shake/qc need the analysis venv (OpenCV). Wrong interpreter = false "can't verify", not a real verdict.
  7. Report verified vs pending. Never claim a fix you did not measure.
  8. ASR is a draft, not a subtitle. Whisper on dialect/field audio misreads words and drops particles — a lost «не» flips the meaning. After transcription the agent must read the text and fix it for sense before it becomes subtitles (Дед: «Скотт»→«скот, скотина»; restored a dropped «не» that had reversed «тогда не болели» into «тогда болели»). Build subs from word timestamps (readable_chunks) so a sentence split by dead-air removal is never duplicated.
  9. A talking cut is never silent. core.render(audio=True) is the default; only a b-roll/teaser that gets music laid under it renders audio=False. After rendering, confirm the file actually carries an audio stream (ffprobe ... stream=codec_type) — a silent sync cut is a defect.
  10. Deliver a project, not a file. An .mp4 is a preview; the delivery is sequences inside the editor's own open project, so he can drag a cut himself. Check what is open (pr_get_project_info) before building anything, build into that project, and never touch a sequence he has edited — his version wins by default. Titles go on a real caption track he can retype, not burned into the picture. When he saves, read his version back with core.prproj.conform_captions() and conform the renders to it.
  11. Colour is gated, both ways (core.colorgate). Every grade runs check_grade(base, graded) before it is shown: clipping, oversaturation and skin against the ungraded base and mean ΔE against it. A burnt grade fails; so does an invisible one — the floor is ΔE 5.0, set by a director who did not notice a 3.23 grade at all. Inspect frames large (≥400px plus a face crop), never an 8-up thumbnail sheet: small previews are exactly how blown highlights shipped once already.
  12. Two grading traps. Never auto-white-balance on whole-frame statistics — a frame that is mostly wall pulls the wall neutral and drags skin orange; correct exposure at half strength (clamp 0.9–1.15) and leave balance to an eye. Film-emulation LUTs (Kodak 2383, Fuji 3513) expect Cineon Log input — the .cube header says so; fed Rec709 they blow the highlights. On Rec709 blend them at ≤55% and let the gate walk the strength down, or build the look by hand (S-curve, teal in the shadows, warmth in the highlights).
  13. End cards go after the fade, on black. A title over the last frame lands on the speaker's face. Fade the picture, pad ~2.5s of black, put the card there — it also gives a clean still to screenshot.
  14. Two off-by-ones that hide on short tests. Resolve's AppendToTimeline takes endFrame exclusive (one frame lost per clip: 13 clips = 0.43s and drifted subtitles). And a stock brew ffmpeg can ship without libass/drawtext/lut3d — check -filters before trusting a burn, use a full build if missing, feed labelled graphs through -filter_complex, and keep filter paths free of spaces.
  15. panel not connected is usually a port race, not a dead bridge. Each Claude session starts its own MCP server; only one holds port 9876 and the panel. Since 0.5.0 the calling session takes it over by itself; an error naming a pid means an older bridge sits on the port (restart that session). Before telling anyone Premiere is unreachable, run node mcp-server/pk.js info - it goes through the panel's debug port and works from every session. Resolve has no such race: python -m core.adapters.resolve_run exec script.py.
  16. Never clear a queue you did not fill. A frame grab that calls DeleteAllRenderJobs() deletes the editor's own queued renders. resolve_run.grab starts and deletes only its own job ids; do the same in any script you write. grab leaves the render format on PNG - reload the delivery preset before the real render.
  17. Level the shots first, then normalise (core.loudness). One normalise pass over a cut made of several takes moves the average and keeps every jump. Change the gain at the join and hold it for the shot; easing back to unity at the edges puts the jump right on the cut. Static gain plus a true-peak limiter, not a dynamic normaliser, for a single voice. check_delivery(out, cuts).assert_ok() before the file leaves: ±1 LU of the target, true peak under the ceiling, ≤ 2 dB between shots.
  18. State the colour matrix on every pipe (core.screen_comp). Decoding a Rec.709 file through a default path and encoding the composite back shifts the whole plate, and the shot no longer cuts with its neighbours. Matrix and range go in explicitly on the way in and out; tags go on the frames with setparams (the -color_primaries / -color_trc output options alone are ignored for raw RGB input on current ffmpeg - check with ffprobe, not by eye). The gate compares the plate outside the screen before and after; it passes mechanics, not taste, so look at the corners of a tracked insert yourself.
  19. Master out of Resolve as ProRes; make the H.264 with ffmpeg. On one job Resolve's built-in H.264 export damaged occasional frames. Render the master to ProRes, encode the delivery with libx264 (rule: never a hardware encoder, see core.render), then run core.qc.qc_delivery - a full decode with nothing on the error channel - on the file that is actually sent.
  20. Caption tracks are invisible to the ExtendScript API and do not ripple. razor + TrackItem.move() shift video and audio only; a caption track in the base sequence stays put, so after the first insert every one of its cues sits on the wrong shot, and exportAsMediaDirect burns every VISIBLE caption track regardless of the preset. Before cloning a sequence that carries someone else's captions, hide that track (the eye icon on its header); the clone inherits the hidden state and the burn stops. Six variants shipped with foreign subtitles before this was understood (06.10.2026). Your own captions go in as a fresh SRT track remapped by core.ripple.remap_cues.
  21. Deletions by native extract, never by moving clips left. qe.project.getActiveSequence().setInOutPoints(a,b); extract() ripples all tracks; TrackItem.move() to the left leaves black frames at the old place. And run ALL deletions before ANY insert: an inserted clip that later passes through extract can make the whole sequence un-exportable ("low-level exception").
  22. An AAC-in-mp4 music sliver shorter than 0.3 s kills Premiere's audio renderer ("could not create audio renderer" on every export). The builder drops such slivers at every cut; the cure is relinking the song's project item to a PCM .mov (projectItem.changeMediaPath).
  23. Clips imported from another project may arrive with a Rec.709 colour-space override and look grey. Copy the colour space of a native clip: item.setOverrideColorSpace(ref.getColorSpace()). Measured: mean saturation 28 against 68 on the master before the fix. But override ONLY the items whose camera actually shot log: the same blanket fix applied to a Rec.709 drone clip (DJI) turned it yellow and oversaturated, and the director caught it, not the gate. Filter by camera prefix, then read back getColorSpace().name per item.
  24. Inserted AI shots are not "hooks", they are a block with a frame and a music track. The viewer needs a card that says why the fight is there; the song under the block is cut on its beat grid (tempo from onset autocorrelation, bars of four, the drop on the strongest visual hit); the inserts go in as video-only files and their own synthetic sound is gone, with two or three accents mixed into the music file at -10..-14 dB. A black card gets room tone under it, never silence.
  25. Handing a cut to a Resolve editor: XML per timeline, media into the pool first, stills fixed. Export FCP7 XML from a proxy-linked copy of the project (new project + importSequences, relink, never the director's own project), run core/xml_handoff.py (remap_paths, fix_stills), and tell the editor: drag the media folder into the Media Pool, then import the XML with "automatically import source clips" OFF. With it on, foreign paths make the import fail outright. A 3840-px title at Scale 50 arrives half size in Resolve (it fits the still and applies the scale on top): ship 1080 twins, 50 -> 100, no filter -> 200, any other value stays.
  26. Before you say "it opens in Resolve", open it in Resolve. External scripting works: launch hidden, create a throwaway project, import media one file per call (two numbered stills in one call become an image sequence), import the timeline, compare duration to the frame and count items without media, export title frames with ExportCurrentFrameAsStill and put them next to the Premiere render. Then load nothing, delete the throwaway project, quit. Seven timelines took five minutes; the half-size titles were invisible in every count and obvious in the first exported frame.
  27. A grading pull from an editor's .drt is audited clip by clip before the render, and neither file is the truth. Import, relink to the camera originals with ReplaceClip(realpath) (a relink by name keeps the proxy's properties), reset the grades, then core/drt_audit.py: the .drt In against the NLE's LeftOffset for every clip. Any disagreement stops the render and becomes one question to the editor: source timecode and file name for that shot. One clip of 79 went out wrong three times on a teaser: Resolve put a crowd shot there (LeftOffset -1885), the .drt In (191) gave a close-up, the editor's 17:48:20:17 was frame 1884. Frame count and a contact sheet were clean every time. AppendToTimeline endFrame is exclusive.
  28. A replacement shot for the editor is cut by the editor's timecode from the original, and shown before it is sent. ffmpeg -ss on the original, ProRes with -timecode set, PSNR of the first frame against that source frame (56 dB on the hit, 32 dB one frame off). Never send your own guess about which part of a clip the editor meant.
  29. Resolve's H.264 encoder is not a master. On the same job it corrupted frames in the mp4. Render ProRes from Resolve, make the mp4 from that with ffmpeg.
  30. Caption files go in one at a time: pr_import_captions. importFiles([several .srt], suppressUI=true, ...) hung Premiere on "Импорт файлов..." for good (20.10.2026). One file per call with the UI allowed, then createCaptionTrack(item, 0, CAPTION_FORMAT_SUBTITLE).
  31. Effects by the name Premiere shows, verified: pr_add_video_effect. In a Russian UI getVideoEffectByName("Black & White") returns an object and addVideoEffect adds nothing, with no error; the name is "Черное и белое". Count components.numItems before and after.
  32. Never export a sequence with an ingest/proxy preset. IngestPresets/Proxy/02_H.264 MP4.epr squashed a 1080x1920 vertical into 1280x720. Use a Match Source preset and read the output size with ffprobe before the file leaves.
  33. Two projects open = check whose sequence is active. On 21.10.2026 app.project was a test copy while app.project.activeSequence was the director's Grave Stakes sequence. The bridge's caption and effect tools refuse that; in your own scripts compare activeSequence.sequenceID with app.project.sequences before writing.
  34. A YouTube download is AV1 until proven otherwise. yt-dlp picks AV1; Premiere 26 then imports the audio only and the timeline gets an empty V1 (24.10.2026, ten podcast shorts). Before import: python -m core.media_gate FILE --start S --end E and cut an H.264 copy of the needed range only; a full hour is ~10 GB. Or download H.264 in the first place: yt-dlp -S vcodec:h264.

XVIII. Phone-HDR jobs and the order of work (August 2026, five failures in one job)

The order is not negotiable: assemble on the raw source -> the director says "locked" -> subtitles generated from the sequence -> colour. Subtitles built before the lock drift when he moves a cut; colour built before the lock is redone. His words: "we lock the edit on the raw source, and only then work on colour".

  1. Probe before any decision. ffprobe -show_entries "stream=codec_name,profile,pix_fmt,width,height,color_primaries,color_transfer, r_frame_rate:stream_side_data=rotation". Working dimensions are those of the decoded frame, never the coded ones - a clip that reports 1920x1080 with rotation=-90 is a 1080x1920 vertical. Reading frames without honouring rotation produced a stretched picture, a false "his head is wider than a 9:16 frame" conclusion, and a crop that cut his face off.
  2. A green picture in Premiere means the codec did not decode. iPhone HEVC Main 10 HLG (color_transfer=arib-std-b67, bt2020) does this. Two quick fixes first (Preferences > Media > disable hardware HEVC decoding, clear the media cache), 5 minutes maximum, then cut a mezzanine.
  3. A mezzanine never grades. It may change container, codec, chroma subsampling, baked rotation and frame timing - nothing else. Keep the source tags: -color_trc arib-std-b67 -color_primaries bt2020 -colorspace bt2020nc -movflags +write_colr, and no colour filter at all: no tonemap, no zscale transfer conversion, no lut3d/eq/curves/colorbalance. Transcoding through tonemap=hable and handing that file to the director got the verdict "you brought me a yellow source, that is wrong". Neutrality gate, all four required: tags match the original; PSNR against the original Y >= 50 dB (-lavfi psnr -frames:v 300); |YAVG delta| <= 0.5; duration within one frame. A fast tell that a cast crept in: the skin share of the frame (colorgate.FrameStats.skin_share) jumping above ~85% means the wall itself drifted into flesh tones.
  4. Assemble in frames and ticks only. Accumulated float seconds leave one-frame holes between clips - the director had to close them by hand and called them "микропропуски". The next clip goes at the actual seq.end in ticks, read back from the sequence, never at a number you added up yourself. Safer still: lay the whole clip down and razor with ripple, where a hole is structurally impossible. Tools: tools/build_sequence.jsx, tools/verify_timeline.jsx.
  5. Gate every assembly before a human sees it. Strict equality V1[i].end.ticks == V1[i+1].start.ticks (zero tolerance), V1 clip count == A1 clip count, zero offline. ok:false means it is not ready.
  6. Verify through the NLE's own picture, not through ffmpeg. An API that returns "ok" says nothing about what is on screen. After import and after assembly, export one frame from the sequence (seq.exportAsMediaDirect(png, ".../PNG Sequence (Match Source).epr", 1)) and look at it. A green or black frame stops the job.
  7. Colour lives in his sequence - Lumetri on one adjustment layer per variant - or, when he asks for something simpler, as ready-made LUTs plus a labelled contact sheet built on his frame. Curate LUTs with the colour gate and a pairwise ΔE >= 4.5 so no two options are the same look twice.
  8. Rhythm beats polish. A rough cut in his project by minute 10, then an artefact or a status with an ETA every 15 minutes. Ninety minutes of silent perfectionism was the worst failure of that day, ahead of every technical one.

XV. Reference

  • Walter Murch, In the Blink of an Eye: A Perspective on Film Editing, 2nd ed., Silman-James Press, 2001 (Russian: «В мгновение ока», аудиокнига Кирилла Никитенко 2024)
  • Murch's Sydney lecture (1988) — origin of the Rule of Six
  • StudioBinder, "Walter Murch's The Rule of Six" — modern annotation with examples (Godfather, Eternal Sunshine, Bonnie and Clyde, Fight Club, Mad Max: Fury Road, The Shining, Inception)

Last updated: 2026-10-06 (§XVI steps 13-14 and two finishing modules; §XVII hard rules 15-19: the port race and the direct path, never clearing a render queue you did not fill, shots levelled before normalising, the colour matrix stated on every pipe, and ProRes out of Resolve with the H.264 made by ffmpeg.) Earlier: 2026-08-17 (§XVI pipeline steps 11-12: core.colorgate two-sided colour gate and core.prproj round trip; §XVII hard rules 10–14: deliver a project rather than a file, gate every grade both ways, the auto-WB and Cineon-Log LUT traps, end cards after the fade on black, and the two off-by-ones — Resolve's exclusive endFrame and ffmpeg builds without libass/lut3d. All from a vertical announcement reel cut, conformed, graded and delivered end to end in August 2026.) Earlier: 2026-05-22 (§XIII meaning layer: analyze_clips --desc adds Russian desc_ru + tags + keep/drop and shake/horizon to a complete per-clip table written incrementally; editorial protocol rewritten meaning-first — see → classify → transcribe → sequence by content, metrics last; Дед case study: why a loudness/motion auto-cut on talking footage is a dump and how the agent fixes it). Earlier: 2026-05-18 §XVI automated pipeline + §XVII hard rules (anamorphic un-squish, Resolve-native Stabilize over banned ffmpeg deshake, relative-outlier stabilization, mandatory fail-closed QC, two-variant pick). Maintained as part of the premiere-claude-bridge open-source release.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.