beat_synced_video_editing v1.0.0

name: "beat_synced_video_editing" description: "Cut video to the beat: beat-map a music track, place cuts on rhythm with correct lead-in, shape pacing curves across sections, and land transitions on hits. Use when a video needs to feel driven by its music — montages, trailers, music videos, ads, short-form, highlight reels."

Beat-Synced Video Editing

Purpose

Turn a music track plus footage into an edit where the cuts feel owned by the rhythm. The job has four moves: map the track's beats and structure, decide the pacing curve (how cut density rises and falls across sections), place each cut with correct lead-in so the visual lands on the beat, and land transitions and effects on rhythmic hits. This skill covers the craft method, not just "put markers on beats." For automatic beat analysis, use bin/beatmap.py.

Workflow

1. Analyze the track. Get the BPM, a beat map (timestamp + intensity for every beat), and the song structure: intro, verses, pre-chorus, chorus, bridge, drops, outro. A four-beat map is wrong for a song with a 64-bar build and one 8-bar drop. Structure first, beats second.
2. Build the pacing curve. Assign each section a cut-density target (shots per 8 bars), written down before touching the timeline. Rule of thumb: verse = sparse, pre-chorus = rising, chorus/drop = dense, bridge = hold back. The quietest section should be at most half the density of the loudest. See references/beat-craft.md for worked curves.
3. Mark the grid. Drop markers on beats. Downbeats (start of a bar) are the strong positions for big changes; off-beats and subdivisions are for energy within a section. Mark structural boundaries (chorus in, drop, outro) separately from regular beats so they stay visible.
4. Place cuts with lead-in. A cut placed exactly on the beat feels late because the eye needs a frame or two to register the new image. Place the cut 1 to 2 frames BEFORE the beat so the new shot is fully readable at the hit. Verify by looping the cut at speed: if the hit feels swallowed, move the cut earlier; if the shot feels hurried, move it later.
5. Layer, don't stack. Never put a cut, a transition effect, and a camera move all on the same frame. The rhythm gets one hero per hit: either the cut lands on the beat, or an effect lands on it, or a motion peak does. Stacking two of them reads as a glitch.
6. Hold through the chaos. The biggest trap in beat-sync editing is cutting on every beat. Deliberately hold some shots THROUGH frantic passages (the zvoque taxonomy's term for the fix: overlap and stagger rather than lining everything up). A held shot in a dense section makes the next dense section hit harder. Contrast is the whole game.
7. Land the structural hits. Section changes get the biggest moves: a match cut, a whip, a white flash, or a full stop on a hard stop. Downbeat one of the chorus is the most-watched frame in the video; the shot there should be the strongest image in the section, not a throwaway.
8. Render check. Watch the finished edit twice: once at full speed for feel, once watching only the cut points with the sound muted. Muted check catches cuts that only work because the music is carrying them.

Output Contract

• Beat map: JSON from bin/beatmap.py with tempo, beat times, per-beat intensity, onsets, and structural note placeholders. CSV marker list for import into the NLE.
• Cut plan: a table of clip -> in/out timecodes aligned to beat times, with per-section density targets, before the timeline is touched.
• Edit notes: for each structural hit, which move lands there (cut, transition, effect) and which shot it uses. One hero per hit.
• QA pass: full-speed watch note plus muted-cut-check note, with any moved cuts listed.

Operating Rules

1. Never cut on every beat. Density targets are per section, and the densest section still skips some beats.
2. Cut 1 to 2 frames early, never late. A cut that lands on the beat reads as late.
3. One hero per hit: cut OR transition OR motion peak on a given beat, never two.
4. Structure before beats: the pacing curve follows the song's sections, not the metronome.
5. Hold through at least one frantic passage per edit for contrast.
6. Downbeat one of the loudest section gets the section's strongest image.
7. Verify with the muted cut check. If a cut only works with the music on, it does not work.
8. Every factual claim about the track (BPM, structure, downbeat positions) must come from the beat map or the waveform, never from memory or assumption. Downbeat positions from beatmap.py are heuristic (assumes 4/4 from the first strong beat); confirm against the waveform before trusting them.