Beat Sync Editing

Beat-Sync Editing → cuts, rhythm and retiming

Where a cut lands matters as much as what is on screen. This turns a track and a brief into millisecond cut points on the timeline.

motion-direction sets the energy; this turns it into a grid and an arc. motion-graphics carries the op contract for the calls named here. video-audio-continuity decides where the bed comes from before there is a grid to read: a track you add yourself, or one generated clip carrying every scene.

Get the grid from the audio, not from arithmetic

When the bed does not exist yet, generate it with the grid in mind: a Stable Audio prompt states its BPM (stable-audio-prompting), and an ElevenLabs composition_plan pins each section's length in milliseconds (elevenlabs-audio-prompting), so the drop lands where the plan says instead of where the model felt like putting it. Then measure it anyway — the generated file, not the prompt, is the grid.

detect_audio_events on the music clip reports onsets and a tempo.

• onsets.times are in seconds. Every timeline op takes milliseconds, so multiply by 1000. This is the single most common mistake here.
• Read tempo.reliable before you build anything off bpm. Speech and room tone produce a confident-looking number from nothing. Unreliable means use the onsets directly.
• The first onset is the grid's offset. A grid anchored at 0 instead of beat one puts every cut a few frames early — the edit that feels "almost right".

With a reliable tempo:

ms_per_beat = 60000 / bpm
frames_per_beat = (60 / bpm) × fps          # fps comes from get_timeline

At 120 BPM: 500ms a beat, 15 frames at 30fps, a 2000ms bar. Round each cumulative beat, never the step, or the grid drifts over a long edit.

Lay the grid down so you can see it, then pull edges onto it:

{"op": "set_markers_from_beats", "onsets_ms": [0, 500, 1000], "count": 32}
{"op": "snap_to_beats", "targets": "all", "tolerance_ms": 60,
 "mode": "start", "action": "move"}

Either takes onsets_ms, or a bpm with an offset_ms. The 60ms default tolerance is about two frames at 30fps — close enough to read as on the beat, tight enough not to drag an edge onto a beat it was never near. snap_to_beats reports every target including the ones nothing was in reach of, with the reason. action: "move" keeps the clip's length and shifts what follows; action: "trim" changes the length and leaves the neighbours alone. Move a title that has to land on a hit; trim a picture clip whose out point has to meet the next shot.

For an animation that should follow tempo changes, store a beat anchor on the animation: {index: 3, scope: "clip", offsetMs: -20} counts from the clip's start; scope: "sequence" counts from the document tempo's offsetMs. index is one-based, and delayMs adds another offset. This is distinct from snapping a clip edge or baking a measured audio curve. animate_clip does not accept beat in its tool input; write the animation's beat through the full document with set_timeline_document. A stored animation needs its id, role, preset, and durationMs; keep those and the rest of the animation when adding beat. Keep the document's tempo, setup, media tracks, template identity, clips, tracks, and markers in the write.

Cut on phrases, not on beats

A cut on every beat is relentless and the viewer fatigues by beat eight. Cut on 2, 4 or 8 beats, and accent on the eighth grid sparingly.

Put the single biggest visual on the drop. One piece, one peak.

Shape an arc

Uniform pacing reads as flat regardless of content.

Hide the seam

A cut is invisible when motion carries the eye across it. Cut during a movement, and match its direction and speed across the cut. For graphics, cut at a transform peak — mid-travel, not at rest.

Default to the hard cut: two clips on the same track, meeting exactly. Reach for anything else only when it is motivated.

Two things the engine does whether you asked or not:

• Two clips on one track whose times overlap dissolve across the overlap with no call at all. An accidental overlap is an accidental dissolve. When a cut looks soft where you wanted it hard, check startMs and durationMs first.
• A transition plays over the incoming clip's head against whatever is beneath it. With no overlap there is nothing under it and it reads as a fade from black.

J and L cuts are built by splitting picture and sound onto separate clips, not by a transition: the shot's audio twin already sits on its own audio track after an assemble, so move that clip rather than the picture.