Resolve Multicam Autocut

---
name: resolve-multicam-autocut
description: Turn folders of multi-camera footage (one folder per song/take, e.g. two GoPros at band practice) into DaVinci Resolve projects — one .drp per folder with an audio-synced multicam clip and a timeline trimmed to the song with beat-snapped camera cuts. Works with FREE Resolve (no scripting API) by generating the project file itself. Use when someone wants multicam projects built, synced or rough-cut automatically in DaVinci Resolve.
---

# Resolve multicam autocut

Free DaVinci Resolve (21.1+) has no external scripting or MCP server — both are Studio-only. So this skill does not
drive Resolve at all. It writes Resolve's own project-export format (`.drp`), cloned from a project the user
exported once, and the user imports the result (File → Import Project, or Project Manager → right-click → Import).

What each generated project contains:
- one multicam clip, one angle per camera file in the folder, **synced by audio** (not timecode);
- one timeline, trimmed to where the music starts and stops, with the video cutting between angles every
  ~10 s on a bar line, and one uncut audio track from a single camera.

## Read this before you start (lessons that cost time)

1. **"Create New Multicam Clip Using Selected Clips" exists only on the Media page's Media Pool** (left-most
   icon in the bottom page ribbon). It is not on the Edit page's Media Pool right-click menu. Bin variant: right-click
   empty space in a bin with nothing selected → "Create New Multicam Clip Using Selected Bin".
2. **Don't trust camera timecode for sync.** GoPro HERO13s timecode-synced through Quik were measured 12–22 frames
   (0.4–0.75 s) off — visible lip-sync error. Cameras not synced were 62 s off. Audio cross-correlation was stable
   to about a frame. The script ignores timecode for alignment and reports how wrong it was.
3. **Loudness can't find the song.** Rehearsal chatter is as loud as an acoustic song. "Pulse clarity" — how
   periodic the onset envelope is at 50–200 bpm — separates playing (≈0.35–0.8) from talk (≈0.05–0.25).
4. A **generated project with no `TimelineHandleVec` entries imports with no timelines**; the script fills it.
5. Resolve shows 29.97 **drop-frame** timecode; the file stores frame numbers. Never derive frames from the
   displayed string by dividing by 30.
6. The format is undocumented and version-specific. That is why the template must come from the user's own Resolve.

## Workflow

Make a task list; tell the user which steps are theirs (1 and 7).

1. **User builds the template (about 1 minute, once per Resolve version / camera setup).** In Resolve: new project →
   Media page → add one song folder's camera files → select them → right-click → Create New Multicam Clip Using
   Selected Clips (Angle Sync: Sound or Timecode, rest default) → on the Edit page, make a timeline from the multicam
   (dragging the multicam onto an empty timeline is enough) → File → Export Project → save as
   e.g. `template.drp`. The template's angle count is the number of cameras every folder must have.
2. **Check prerequisites:** `python3`, `ffmpeg` on PATH, and
   `pip install numpy scipy soundfile librosa zstandard` (add `--break-system-packages` on managed Pythons).
3. **Lay out footage:** one sub-folder per song/take under a root folder, each holding one file per camera
   (`.mp4`/`.mov`). Folder name becomes the project, multicam and timeline name. File order (sorted by name) sets
   Camera 1, Camera 2, …
4. **Dry run:** `python3 scripts/autocut.py --root "<root>" --template template.drp --dry-run`
   Read the per-song line back to the user: song in/out seconds, tempo, beats per cut, number of shots, and the
   sync correction vs timecode. A `WARN` about sync windows disagreeing means check that song by eye.
5. **Generate:** same command with `--in-place` (writes `<folder>/<folder>.drp`) or `--outdir DIR`.
   Options: `--cut-seconds 10`, `--audio-angle 1` (which camera's audio to keep), `--only "Song A,Song B"`.
6. **Verify:** `python3 scripts/verify.py <dir with the .drp files>` — expects 0 dups, 0 unresolved, timeline
   items contiguous, cameras alternating.
7. **User imports** each `.drp` and plays the timeline. Multicam angles can be re-picked per shot in the Edit page
   viewer; the full clips stay in the multicam, so in/out points can be extended.

## When things don't fit

- Folder with one camera file: skipped (no multicam). Folder with a different camera count than the template:
  skipped — make a template with that many angles.
- Cameras started more than ±75 s apart: raise `search` in `audio_lag` (`scripts/autocut.py`).
- Song start/end wrong: tune `THR` (pulse threshold), `preroll`, `ringout` in `plan`/`song_region`.
- Beat tracker can lock to double or half tempo; cuts still land ~`--cut-seconds` apart, but may sit mid-bar.
- Non-29.97 footage, chaptered GoPro files (GX01…, GX02… of one take), or a different Resolve version: untested.
  `scripts/lib/canon.py file.drp` prints a decoded, id-normalised dump — diff the user's template against a
  generated file to see what changed. `reference/drp-format.md` documents what is known.

## Files

- `scripts/autocut.py` — the pipeline (probe → ffmpeg audio → sync → song region → beats → cuts → .drp).
- `scripts/gen.py` — `.drp` writer: clones clip, multicam and timeline records from the template; remaps every UUID.
- `scripts/probe.py` — pure-Python MP4 reader for the per-file values Resolve stores (tmcd frame, frames, audio samples, mvhd time).
- `scripts/lib/blobs.py`, `walk.py` — codecs for the hex blobs (Qt QVariantMap, raw/zstd protobuf), byte-exact round trip.
- `scripts/verify.py` — structural check of generated projects.
- `reference/drp-format.md` — format notes.

Tested on DaVinci Resolve (free) 21.1.1 for macOS (`DbPrjVer="17"`), GoPro HERO13 Black, 4K 29.97 DF, HEVC + AAC 48 kHz.