beat-grid
Installation
SKILL.md
Beat grid
Sound is a timeline input, not a file dropped under the video at the end. One clock, audio/beats.json, drives the picture (states change on beats) and the sound (hits land on the same timestamps). When both read the same file they cannot drift.
Copy scripts/analyze_audio.py from this skill's folder into the film's scripts/. It needs only ffmpeg and numpy; run it with uv run, which installs numpy for that run.
Apply only the routes and checks for the selected job. Read a linked skill's named file from its installed folder when available, or from the linked source. Report an unavailable required reference instead of inventing it. [skill-authoring, DISTRIBUTION.md#composing-skills]
Pick the source
| Situation | Do |
|---|---|
| The user supplied a track | Use it unchanged. Measure it. |
| They want music but have none | Search free-for-commercial-use libraries (Mixkit's music is free for commercial use; check the licence page of anything else). Download 5-10 candidates into audio/candidates/, scan them, and pick by tempo, energy and a clear downbeat. Record the source and licence in brief.md. |
| Synthesized sound only | Choose a tempo: 120 BPM gives exactly 30 frames per beat at 60 fps (100 → 36, 150 → 24). Set FILM.bpm and skip measurement; the sound-pass bed follows it. |
| Narration drives the film | Call the Skill tool with "voiceover": word timestamps are the clock, and music sits under them. |
Never fetch or use music the brief can't license.