lyric_video_production v1.0.0

name: "lyric_video_production" description: "Build lyric videos end to end: timed-lyrics alignment, beat mapping for pacing, karaoke subtitle generation, phone-first typography, and distributor-ready exports. Use when making a lyric video, syncing lyrics to audio, or choosing export specs for a music video."

Lyric Video Production

Purpose

Turn a song plus its lyrics into a finished lyric video: word-level timing, beat-synced pacing, readable kinetic typography, and export files that meet distributor specs. The output is a render-ready subtitle package (or burned-in video) plus placement-specific masters.

Workflow

1. Get timed lyrics. Two paths:

• Lyrics are known: transcribe the song with faster-whisper (word_timestamps=True), then align the known lyrics against the transcript. Simple reliable approach: group Whisper word times into lines at natural pauses, then match each lyric line to the overlapping segment and shift times onto it. Tip from practice: transcribe speech/vocal segments separately starting ~0.15 s before the first sound, because Whisper stretches first words across leading silence.
• No lyrics file: use Whisper's own transcription, then proofread it against the song. Music confuses ASR; always hand-check proper nouns. Emit timed_lyrics.json: {"lines":[{"text": "...", "words": [{"w": "...", "start": 1.0, "end": 1.45}, ...]}, ...]}. Spot-check verse 1, the chorus, and the bridge against the audio before continuing. A sync error caught here costs seconds; caught at render it costs an hour.

1. Map the beats. Run the bundled tracker: python3 bin/lyric_beats.py song.mp3 --json It reports BPM and beat timestamps (numpy + ffmpeg only, no librosa needed). Use beats as sync points: lyric line entries, emphasis pulses, and visual cuts land on beats, never between them. On rubato or multi-tempo songs, verify the grid by ear against the chorus; the tracker is an aid, not the truth.

1. Design the type system. Decide before rendering:

• Readability first, expression second. One animation vocabulary for the whole song (vary timing and emphasis, not the effect). Animate the smallest unit that serves meaning: line, then word, then syllable.
• Minimum lyric size at 1080p: 72 px for headlines; 42 px for any secondary text; never below 30 px on vertical. Font choice follows the song's mood (bold grotesques for high-energy tracks, lighter faces for ballads).
• Keep all text inside the platform safe zone: 9:16 universal zone is x 60-960, y 210-1480 at 1080x1920; 16:9 keeps a 10% title-safe margin.

1. Render.

• Karaoke overlay (fastest): python3 bin/lyric_ass.py timed_lyrics.json lyrics.ass then burn in with ffmpeg: ffmpeg -i bg.mp4 -vf "ass=lyrics.ass" -c:a copy out.mp4. The \k karaoke tags sweep the highlight word by word. Override style with --style "FontSize=72,Alignment=2" when the default does not fit.
• Motion graphics: hand the timed JSON plus the beat map to your motion pipeline (After Effects, Remotion, or the explainer-animation skill's ffmpeg/Numpy pipe). Keep one motion vocabulary across the song.
• Backgrounds must never compete with text. If a frame is busy, darken or blur behind the type, never the type itself.

1. Export. See references/export-specs.md. One 1080p or 4K 16:9 master, one native 9:16 vertical master, named by placement. +faststart on every MP4. Re-check platform UI overlays on the vertical master.

Output Contract

• timed_lyrics.json in the documented schema, timings verified by spot-check.
• Beat map (BPM + beat timestamps) used for pacing decisions.
• Render-ready subtitles (lyrics.ass) or a motion build driven by the same data.
• Final exports per placement with verified specs and safe-zone clearance.

Operating Rules

• Every factual claim in on-screen text (song title, artist, credits) comes from the artist or label, never from memory.
• Words appear exactly when sung. If a timing is uncertain, hold the previous word rather than guessing early.
• Never run motion on every word at full intensity; it becomes visual noise within seconds. One animated idea per line, maximum.
• Do not invent distributor specs. When a distributor publishes its own spec (Vevo, a label aggregator), follow that document over the reference defaults.
• Lyrics belong to their writers. Work only with lyrics the artist/label provided or licensed; never scrape and re-publish copyrighted lyrics to a public surface.