beat-sync-editor

Files (5)

• SKILL.md
• beat_cut_plan.py · scripts/
• beat_cut_plan_test.py · scripts/
• speed_ramp_plan.py · scripts/
• speed_ramp_plan_test.py · scripts/

SKILL.md (first lines)

# Beat-sync editor

Use this when the user asks to cut to music, sync to a beat, make a
montage, hit a drop, or match visual energy to audio rhythm.

## Workflow

### 1. Create the beat plan

Use the first-party `beats` index sidecar when available:
`index/beats/raw/<asset>.json`. If it is missing, run indexing for the
`beats` MCP producer before falling back to an external beat file. Then run:

```bash
python3 <skill-root>/scripts/beat_cut_plan.py \
  --beats beats.json \
  --audio-energy index/audio-energy/raw/<asset>.json \
  --shot index/shot/raw/<asset>.json \
  --cut-every 4 \
  --duration-s 60
```

The script outputs target cut points and transition suggestions. When
audio-energy is available, it favors louder/accented beat candidates
instead of a rigid cadence. When the shot index exists, it marks beats
that land during motion-heavy shots so you can prefer cut-on-action
rather than arbitrary beat cuts.

### 2. Align cuts

Use `apply_edl` to split/trim/move clips so cuts land within 50ms of
target beats. Hard cuts are the default. Use transitions only when the
music changes energy or structure. After each batch, call
`view_timeline` and verify the graph now contains the intended clip
order, source ranges, and transition placements. Before render/report,
call `vedit_diff` and verify the diff matches the beat plan.

### 3. Motivate transitions and speed

Use `montage.cross_dissolve` or `SMPTE_Dissolve` for soft phrase
changes, `montage.fade_black` only for intentional starts/ends or
chapter resets, and speed accents only on drops or action peaks. To plan
speed accents, run:

```bash
python3 <skill-root>/scripts/speed_ramp_plan.py \
  --beats beats.json \
  --duration-s 60 \
  --accent-every 4 \
  --slow-factor 0.4 \
  --fast-factor 1.3 \
  --ramp-window-s 0.18 \
  --edl-anchor "clip:<clip-name>" \
  --rationale "speed accents on downbeats"
```

The script outputs an `montage.time_remap` effect plan with a concrete
`curve` and, when `--edl-anchor` is present, prints an applyable
`Set Effect` operation. That path works today; switch to the dedicated
`Set Time Remap` EDL op once that op is available. Do not use legacy
`montage.fade_in/out` between ordinary adjacent clips, and do not add
decorative transitions unsupported by `apply_edl`.

### 4. Verify

Render and verify cut alignment. If the plan cannot meet 50ms tolerance,
report the exact clips that need manual source replacement.

## Rules

- Cut on action when possible.
- Match cut density to musical energy.
- Do not keep the same cadence for the whole song.
- Do not use nonexistent transitions.
- Do not call the edit done until `vedit_diff` matches the beat plan.

From explicit09/montage, Apache-2.0.

More from explicit09/montage