extract-beat-grid

Purpose

Analyse an audio or video file and produce a beat-grid.json that encodes the full rhythmic skeleton of the track: BPM, individual beat times, downbeats, bars, and onset transients. Downstream atoms consume this file to snap cut points, caption transitions, or SFX to the musical grid — replacing the previously-missing beat-sync-reel dependency that several skills referenced but no in-tree atom implemented.

If the source is a video file, the audio stream is extracted to a temporary WAV first (via ffmpeg); the atom is otherwise identical for audio-only inputs.

Inputs

Field	Required	Notes
`source`	yes	Path to an audio file (mp3, wav, m4a, aac, flac) or video file (mp4, mov, webm).
`output_dir`	yes	Directory where `beat-grid.json` and `manifest.json` are written. Created if absent.
`beats_per_bar`	no, default 4	Time signature numerator — how many beats constitute one bar.

CLI: