---
name: beatcut
description: Auto-cut video footage to audio transients/beats. Detects onsets in any audio file (kick, snare, vocal hits, drops) using librosa, then chops a video at those exact timestamps and concatenates the cuts. Use when the user wants to sync edits to a beat, cut a music video, drop chops on the kick, or auto-edit footage to a song.
---


# beatcut

Sync any video to any audio. Detects transients in the audio file, then cuts the video at those timestamps and reassembles.

## Workflow

1. Detect onsets in the music file (librosa onset_detect, hop=512).
2. Filter onsets by minimum gap (avoid sub-50ms double hits).
3. For each onset, grab a fixed-length micro-segment of the video starting at a different offset (or random pool of source clips).
4. Concatenate segments to match the audio duration.
5. Mux the original audio.

## Run

```bash
python3 ~/.claude/skills/beatcut/scripts/beatcut.py \
  --audio track.mp3 \
  --video footage.mp4 \
  --out out.mp4 \
  --segment 0.4 \
  --min-gap 0.18
```

Multi-source mash:

```bash
python3 ~/.claude/skills/beatcut/scripts/beatcut.py \
  --audio track.mp3 \
  --video clipA.mp4 --video clipB.mp4 --video clipC.mp4 \
  --out mash.mp4 --segment 0.5
```

## Tuning

- `--sensitivity` (0.3-3.0, default 1.5) — onset peak threshold
- `--min-gap` — minimum seconds between cuts (avoids strobing)
- `--segment` — duration of each cut. Defaults to gap-aware (each cut ends at next onset)
- `--start-pool` — random or sequential video offsets per cut