---
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.

2. **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.

3. **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.

4. **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.

5. **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.