sync-captions-to-music

Purpose

Music-video ads need captions that feel like the song — short bursts, hits on the vocal, mid-frame placement, mixed-weight typography. This atom is the bridge between a rendered song (with timing data) and a burned-in caption pass.

It is a thin composition wrapper. It does NOT re-implement ASS generation or ffmpeg burning — it normalizes word timestamps to the schema the existing add-captions-burn/make_klap_style_subs.py script consumes, then invokes that script with a music-video preset.

If the song was produced by create-music-elevenlabs --with-timestamps, the timestamps come straight from music_metadata.json. If timestamps are missing or unreliable (a known risk for fast rap lines), the atom can fall back to running Whisper on the rendered MP3.

When to use

• After the song is approved at the MUSIC GENERATE state of molecules/music-video-ad.
• Re-burning captions after a song revision (re-runs are cheap; the song is the expensive part).
• Standalone: any time you have a vocal track + lyrics and want fast-paced word-burst captions in the music-video style.

Do NOT use for:

• VO ads with a deadpan narrator — those want bottom-third Klap karaoke; use add-captions-burn directly.
• iMessage chat or motion-graphic ads — they have their own caption systems.