beat-sync-editing

README.md

references/editing-techniques.md

# Editing Techniques — Detailed Cookbook

Concrete recipes for rhythm, transitions, and retiming, with the math to make cuts frame-accurate.

## BPM → frame math

```
frames_per_beat = (60 / BPM) * fps
seconds_per_beat = 60 / BPM
```

Reference (frames per beat):

| BPM | 24 fps | 25 fps | 30 fps | 60 fps |
|----|----|----|----|----|
| 90  | 16.0 | 16.7 | 20.0 | 40.0 |
| 100 | 14.4 | 15.0 | 18.0 | 36.0 |
| 120 | 12.0 | 12.5 | 15.0 | 30.0 |
| 128 | 11.25| 11.7 | 14.06| 28.13|
| 140 | 10.3 | 10.7 | 12.86| 25.7 |

When `frames_per_beat` is fractional (e.g. 128 BPM at 30 fps = 14.06), round each *cumulative* beat to avoid accumulating drift:

```js
const cut = (i) => Math.round(i * (60 / bpm) * fps); // round at the end, not per-step
```

Cut on phrases, not beats:

| Energy | Cut every |
|---|---|
| Frantic / climax | 1–2 beats |
| Energetic | 4 beats (1 bar in 4/4) |
| Moderate | 8 beats (2 bars) |
| Calm / establishing | 16 beats (4 bars) |

Detect BPM offline (aubio, `web-audio-beat-detector`, or tap-tempo) and also capture the *offset* of beat 1 — the grid rarely starts at 0:00.

## Cut on action / cut on motion

The eye tracks moving subjects; a cut placed mid-motion is masked by that movement.

- Identify a continuous action spanning two shots (door opening, head turn, object thrown).
- Place the cut roughly one-third into the action, and continue the *same* action and direction in the next shot.
- Match screen direction (subject moving left exits left, enters from right) and velocity.
- In motion graphics: cut while a shape is mid-travel (transform velocity high), not when it has settled — the motion blur and momentum hide the splice.

## Match cut, step by step

A match cut equates two shots via a shared visual so the cut reads as a transformation.

1. Find or design a shape/position/motion shared by the end of shot A and the start of shot B (a round clock → a round wheel; an arm wiping frame → next scene revealed).
2. Align them in screen space: same size, same position, same orientation at the cut frame.
3. Match motion vector and speed across the cut so momentum carries through.
4. Cut on the exact frame where the two forms register; a 1–2 frame mismatch breaks the illusion.
5. Optionally add a 1–3 frame motion-blur bridge to fuse them.

Common forms: graphic match (shape), motion match (direction/velocity), audio match (a sound bridges the cut), and the "invisible wipe" where a foreground object wipes the frame and the next shot is revealed behind it.

## J-cut and L-cut

Audio and picture do not have to cut at the same frame.

```
J-CUT  (audio of B leads its picture — pulls forward)
  Picture:  AAAAAAAA | BBBBBBBB
  Audio:    AAAAA BBBBBBBBBBBBB
                  ^ B's audio starts ~6–12 frames early

L-CUT  (audio of A trails under B's picture — smooths)
  Picture:  AAAAAAAA | BBBBBBBB
  Audio:    AAAAAAAAAAAA BBBBBB
                       ^ A's audio continues ~6–18 frames past the picture cut
```

Typical offsets: dialogue J-cuts 4–12 frames; ambient L-cuts 12–24 frames. In an NLE, unlink audio/video and trim only the audio edge. In a code timeline, place the `<Audio>` for shot B with a `from` earlier than B's picture sequence.

## Speed ramp recipe (with motion blur)

```
Impact ramp, 30 fps, drop on frame 28:
  Frame   Speed     Note
  0–20    100%      run-up, normal motion blur
  20–28   100%→25%  ease-OUT deceleration into the hit
  28      25%       IMPACT, lands on the downbeat
  28–34   25%→100%  ease-IN re-acceleration
  34+     100%      release
```

Settings:
- Use smooth (Bezier) interpolation on time-remap keyframes; linear ramps look mechanical.
- Enable **optical flow** (or frame-blending) for sub-100% speeds so slow-mo isn't strobed; optical flow generates intermediate frames.
- Keep motion-blur shutter consistent across the ramp — if the source has motion blur, the slow section keeps it; if synthetic, hold a constant shutter angle (e.g. 180°).
- Land the slowest frame *on the beat*; the ramp is felt, the impact is heard.

In AE: enable time remapping, keyframe the source time, ease the keyframes, set frame blending to Pixel Motion. In Remotion: drive a remapped source time via eased `interpolate` and keep effects deterministic.

## Sequence arc templates

```
30s social spot (≈ 900 frames @30fps):
  Establish  0–120    2 shots, ~2s each (longer holds)
  Develop    120–540  shots shortening 1.5s → 0.8s, rising energy
  Climax     540–720  fastest cuts 0.3–0.5s, the drop at ~600
  Resolve    720–900  one long hold, logo/CTA breathes
```

Plot average shot length as a curve: high at the start, descending to the climax, then a single long shot to release. Energy is the *derivative* of cut frequency — accelerate cuts to build, decelerate to land.

## NLE timeline vs code timeline

| Concept | NLE | Remotion | After Effects |
|---|---|---|---|
| Clip placement | drag to track at TC | `<Sequence from durationInFrames>` | layer in/out points |
| Back-to-back shots | adjacent clips | `<Series>` | trimmed layers |
| Crossfade | overlap + dissolve | overlap `Series` + opacity interp | opacity keyframes / overlap |
| Speed ramp | time-remap keyframes | eased source-time `interpolate` | time remap + frame blending |
| J/L cut | unlink + trim audio | `<Audio from>` ≠ picture seq | offset audio layer |
| Beat marker | timeline markers | beat array `frame/fps` | comp markers / expression |

To port an edit plan: express each cut as a frame number (from the BPM math), each clip as `from`/`duration`, each transition as an overlap, and each retime as an eased time-remap. The plan is renderer-agnostic; only the placement syntax differs.

## Example edit plan (portable)

```
Track: 128 BPM, 30fps → 14.06 f/beat, drop at beat 32 (frame 450)
Cut on 4-beat phrases (≈56 frames):
  f0    ShotA  establish, hold
  f56   ShotB  cut on action (subject turns)
  f112  ShotC  match cut from B (shared circle)
  f168  ...    cuts shorten toward climax
  f450  DROP   biggest visual; speed ramp 100→25→100 around f450
  f700  CTA    long hold, L-cut audio trails in
```

---
Cut on the beat and ramp with purpose and the edit moves with the music. Built by **[iart.ai](https://iart.ai/?utm_source=github&utm_medium=readme&utm_campaign=motion-design-skills&utm_content=skill_footer&utm_term=beat-sync-editing)** — the AI motion agent for editable, on-brand motion graphics.

SKILL.md

---
name: beat-sync-editing
description: This skill should be used when the user asks to "cut to the beat", "fix the pacing", "edit this sequence", "sync cuts to music/BPM", "add a match cut / J-cut / L-cut", "build a speed ramp", or "plan a shot sequence / edit timeline". Covers editing rhythm, transitions, retiming, and translating an edit plan to an NLE or a code timeline (Remotion/AE frames).
version: 0.1.0
---

# Beat-Sync Editing (Cuts & Rhythm)

The timeline craft: how clips and beats assemble into a piece that *feels* right. Editing is temporal design — when a cut lands matters as much as what is on screen. This skill turns musical and narrative structure into concrete cut points, transitions, and retimes, expressible in an NLE or as frame numbers in code.

## When to use

- Assembling a sequence or cutting footage to a music track.
- Pacing drags or feels choppy; transitions feel arbitrary.
- Building speed ramps, match cuts, or tension/release structure.
- Converting an edit plan into a frame-accurate timeline (Remotion, AE, NLE).

## Decision tree

```
What's the editing problem?
├─ Cuts feel off the music
│   └─ get BPM + offset → frames_per_beat = (60/BPM)*fps
│      → cut on PHRASES (2/4/8 beats), biggest visual on the drop
├─ A cut feels jarring / visible
│   └─ cut on action (mid-motion), match direction + velocity
│      → still rough? motivate a transition (match / J / L), else hard cut
├─ Pacing drags or feels flat
│   └─ shape an arc: Establish → Develop → Climax → Resolve
│      → shorten avg shot length toward climax, hold after it
├─ A hit needs impact
│   └─ speed ramp INTO it (slow-mo), snap back; land slowest frame on the beat
└─ Need to hand it to code
    └─ express every cut as a frame number, clip as from/duration,
       transition as overlap, retime as eased time-remap (Remotion/AE)
```

**Cross-reference — apply the shared frameworks.**

- **Motion Personality** (`motion-art-direction`) sets cut rhythm: the chosen energy maps straight to phrase length and transition family. Pick one and commit (see the table below).
- **Three Pillars** + beat-sync (`animation-principles`): settle *emotional intent* first (hype vs. calm) — it decides whether you cut every bar or hold for four. `animation-principles` defines the BPM→beat relationship; this skill turns it into frame-accurate cut points and the transition/retime craft on top.

### Motion Personality → cut rhythm

| Personality | Phrase (cut every) | Transition family | Retime | Reads as |
|---|---|---|---|---|
| **Playful** | 4 beats, syncopated accents | match cuts, quick whips | light ramps, bouncy | fun, kinetic |
| **Premium** | 8–16 beats, long holds | hard cut + occasional dissolve | slow, smooth ramps | elegant, unhurried |
| **Corporate** | 8 beats, steady | hard cut, clean | minimal | clean, trustworthy |
| **Energetic** | 1–2 beats at climax | hard cut, whips, hard snaps | aggressive ramps on beats | bold, hype |

## Core workflow

### 1. Find the grid: BPM → frames

Cut on the music's rhythmic grid, not on arbitrary timecodes. Convert BPM to frames so cut points are frame-accurate.

```
frames_per_beat = (60 / BPM) * fps
```

At 120 BPM, 30 fps: `(60/120)*30 = 15` frames per beat (500ms/beat) — a cut every 15 frames is on-beat. Cut on *phrases* (every 2/4/8 beats), not every beat, or the edit feels frantic. Land the single biggest visual moment on the musical drop.

The **eighth-grid**: subdivisions of the beat give finer accent points without going off-grid. At 120 BPM / 30 fps:

| Subdivision | ms | frames @30fps | Use |
|---|---|---|---|
| 1 beat (quarter) | 500 | 15 | main cut grid |
| ½ beat (eighth) | 250 | 7.5 | accent / quick flash cut |
| ¼ beat (sixteenth) | 125 | 3.75 | hits, stutter, transient FX |
| 1 bar (4 beats) | 2000 | 60 | phrase / section boundary |

Snap accents to the eighth-grid; keep structural cuts on the beat or bar.

```js
// Generate on-beat frame numbers (JS / Remotion / AE-friendly)
const bpm = 120, fps = 30;
const framesPerBeat = (60 / bpm) * fps;       // 15
const phrase = 4;                              // cut every 4 beats
const cuts = Array.from({length: 16}, (_, i) =>
  Math.round(i * framesPerBeat * phrase));     // [0,60,120,180,...]
```

### 2. Hide the seam: cut on action / motion

A cut is invisible when motion carries the eye across it. Cut *during* a movement (a turn, a hand reaching, a whip) so the brain tracks the action through the cut. Match the motion's direction and speed across the cut. For motion-graphics, cut on a transform peak — at the moment a shape is mid-travel, not at rest.

### 3. Choose transitions with intent

Default to the **hard cut**. Reach for anything else only when motivated:

- **Match cut** — outgoing and incoming frames share a shape, position, or motion vector, so the cut reads as a transformation (a circle becomes the moon; a wipe of an arm reveals the next scene). The strongest transition in motion design.
- **J-cut** — audio of the *next* shot starts *before* its picture (sound leads). Pulls the viewer forward; great for dialogue and reveals.
- **L-cut** — audio of the *current* shot continues *under* the next picture (sound trails). Smooths scene changes.
- **Whip / motion blur transition** — fast pan blends two shots; needs matched blur direction.
- **Luma/wipe/dissolve** — signals time passing or a softer mood; overuse reads as amateur.

Cut-type quick table:

| Cut type | What aligns | Signals | Typical offset | Reach for it when |
|---|---|---|---|---|
| Hard cut | nothing — instant | neutral, default | 0 | 90% of cuts |
| Match cut | shared shape / position / motion vector | transformation | 0 (1–2f tolerance) | two shots rhyme visually |
| J-cut | audio of B leads its picture | pulls viewer forward | audio 4–12f early | dialogue, reveals |
| L-cut | audio of A trails under B | smooths the change | audio 12–24f late | scene changes, ambient |
| Whip / motion blur | matched blur direction across pan | energy, "swoosh" | ~6–10f blend | hype, scene jumps |
| Speed ramp | retime, not a cut | impact / emphasis | lands on beat | a hit needs to land |

### 4. Retime: speed ramps

Speed ramps (gradual time-warp) add impact: ramp *into* a hit with slow-motion, then snap back to speed. Keep motion blur consistent through the ramp or the slow section looks strobed.

```
Speed ramp on an impact (frames, 30fps):
  0–20    100% speed   (run-up)
  20–28   ease down to 25%  (anticipation, slow-mo on the hit)
  28      IMPACT lands on the beat
  28–40   ease back to 100% (release)
```

In an NLE use time-remap keyframes with smooth interpolation and enable frame-blending/optical-flow for clean slow-mo. In Remotion/AE, drive a `timeRemap`/`valueAtTime` curve with eased interpolation and keep a consistent shutter/motion-blur setting.

### 5. Shape the arc: sequence pacing

A piece needs a shape, not one constant intensity:

```
Establish → Develop → Climax → Resolve
  longer holds   shortening cuts   fastest + the drop   release/breathe
```

Vary shot length deliberately: fast cuts build energy, longer holds let key moments land. Build toward the climax by shortening average shot length, then give a beat of rest after it. The classic mistake is uniform pacing — it reads as flat regardless of content.

Pacing arc — tension → release (energy is the *derivative* of cut frequency):

| Phase | Cut every | Avg shot length | Tension | Note |
|---|---|---|---|---|
| Establish | 8–16 beats | longest | low | set place/mood, let it breathe |
| Develop | 8 → 4 beats | shortening | rising | accelerate cuts to build |
| Climax | 1–2 beats | shortest | peak | the drop; biggest visual + speed ramp |
| Resolve | one long hold | longest | release | logo/CTA breathes after the peak |

## Quick reference

| Goal | Move |
|---|---|
| On-beat cut | `(60/BPM)*fps` frames per beat; cut on phrases |
| Land the drop | biggest visual on the musical drop |
| Invisible cut | cut on action / matched motion |
| Transform feel | match cut (shared shape/motion) |
| Pull forward | J-cut (audio leads) |
| Smooth scene change | L-cut (audio trails) |
| Impact | speed ramp into the hit, snap out |
| Build energy | shorten average shot length |
| Let it breathe | hold after the climax |

## Worked examples

### GOOD — 30s energetic product spot, 128 BPM, 30 fps

> **Brief**: hype sneaker drop, Energetic personality, drop at beat 32.
>
> - **Grid**: 14.06 f/beat. Drop = beat 32 ≈ frame 450 (rounded cumulatively to avoid drift).
> - **Arc**: Establish 0–120 (two 2s holds). Develop 120–450 (cuts shortening 8→4→2 beats, rising energy — matches Energetic). Climax at 450 (the drop). Resolve 700–900 (one long CTA hold).
> - **Cuts**: structural cuts on the bar; two accent flash-cuts snapped to the eighth-grid in Develop.
> - **Craft**: f112 is a match cut (shared circular logo → wheel). The drop at 450 carries the biggest visual *and* a speed ramp 100%→25%→100% landing the slowest frame on the downbeat. CTA enters under an L-cut (audio trails ~18f).
> - **To code**: each cut a frame number, each clip `<Sequence from/durationInFrames>`, ramp = eased time-remap, beats verified `frame/fps` against detected beat seconds.
>
> Why it works: phrase-based grid, an arc, one big moment on the drop, motivated transitions, frame-accurate and portable.

### ANTI-PATTERN — "cut on every beat with a dissolve each time"

> - A hard cut on all 32 beats → relentless, no focal moment, viewer fatigues by beat 8.
> - A 12-frame crossfade on *every* cut to "smooth it" → mushy, amateur, and now nothing is on the beat because the dissolve midpoint drifts off-grid.
> - Uniform 15-frame shots start to finish → flat; no establish, no climax, the drop lands on nothing.
> - BPM math done from frame 0 ignoring the track's offset → every cut sits a few frames early, feels "almost right" but wrong.
>
> Fix: cut on 4/8-beat phrases, hard cut by default, build an arc, anchor the grid to beat-1 offset, and put the one biggest visual on the drop.

## Common mistakes

| Symptom | Why | Fix |
|---|---|---|
| Edit feels frantic / busy | cutting on every beat | cut on 2/4/8-beat phrases; accent on the eighth-grid sparingly |
| Cuts feel "almost on beat" | grid started at 0:00, ignored track offset | capture beat-1 offset; anchor cumulative frame math to it |
| Drift over a long edit | rounding frames_per_beat per step | round each *cumulative* beat, not per-step |
| Cut feels jarring | placed at rest, between motions | cut on action / mid-motion; match direction + velocity |
| Slow-mo strobes | sub-100% speed without interpolated frames | enable optical-flow / frame-blending; consistent shutter |
| Whole piece feels flat | uniform pacing | shape Establish→Develop→Climax→Resolve; shorten toward the drop |
| Transitions look amateur | dissolves/wipes used as a crutch | default to hard cut; motivate match/J/L; fix timing first |
| Nothing lands | no single climax | put the biggest visual on the drop; hold after it |

## Deliverable — an edit-timing plan

A good plan is renderer-agnostic and hands off to an NLE or a code timeline (`remotion-video`, `after-effects`):

- **Track spec**: BPM, fps, beat-1 offset, drop frame(s), frames_per_beat.
- **Arc**: the four phases with frame ranges and target average shot length per phase.
- **Cut list**: every cut as an absolute **frame number** (from the BPM math), the clip at that cut, and the cut type.
- **Transitions**: type (hard/match/J/L/whip), and for J/L the audio offset in frames.
- **Retimes**: each speed ramp as eased time-remap keyframes (from→to %, frames, optical-flow on).
- **Beat markers**: the on-beat/eighth-grid frame array for verification.
- **Cross-refs**: the Motion Personality that set the rhythm.

> For Remotion/AE this plan IS the frame timing: cuts → `from`/`durationInFrames` (or layer in/out), ramps → eased `interpolate`/time-remap, J/L → offset `<Audio from>` / audio layer. See `references/editing-techniques.md` for the NLE↔code mapping table.

### Before you finish — checklist

- [ ] BPM + fps + beat-1 offset captured; frames_per_beat computed and cumulatively rounded.
- [ ] Cuts on phrases (2/4/8 beats), not every beat; accents on the eighth-grid only.
- [ ] The single biggest visual lands on the drop.
- [ ] An arc exists (Establish→Develop→Climax→Resolve); avg shot length shortens toward the climax, then a hold.
- [ ] Hard cut is the default; every other transition is motivated; J/L audio offsets specified in frames.
- [ ] Speed ramps land the slowest frame on the beat; optical-flow/frame-blending enabled.
- [ ] Cut rhythm matches the chosen Motion Personality.
- [ ] Every cut, transition, and retime expressed as a frame number / from-duration so it ports to Remotion/AE/NLE.
- [ ] Audio sync verified: `frame/fps` against detected beat seconds.

## Gotchas

- Cutting on *every* beat is busy; cut on 2/4/8-beat phrases and accent sparingly.
- Speed ramps without consistent motion blur look strobed; enable optical-flow/frame-blending for slow-mo.
- Crossfades/dissolves are not a fix for a bad cut — fix the timing first.
- Audio sync drift: in code timelines verify `frame/fps` against detected beat seconds; in NLEs lock audio to a frame-accurate guide track.
- One pacing throughout = flat. Always shape an arc.

## Reference files

- `references/editing-techniques.md` — BPM→frame math with phrase tables, cut-on-action breakdowns, building a match cut step by step, J-cut/L-cut audio-lead/trail diagrams with frame offsets, full speed-ramp recipe with motion-blur/optical-flow settings, sequence-arc templates with shot-length curves, and mapping an edit plan between an NLE timeline and a code timeline (Remotion `<Sequence>` / AE time-remap).