--- title: "Music Video · MTV-grade — any track → beat-locked cinematic music video with lyric typewriter" reliability: 4.2 # 5 − keyframe img gen .3 − i2v .6 − music gen .2 (skipped when you bring your own track: +.2) − 7-stage path .2 + .5 rendered E2E in production (the lyrics-vs-style bug was found by shipping); stitch/overlay stages are deterministic ffmpeg; cast face-swap pass OPTIONAL (−.2 when used) --- # Music Video · MTV-grade · agent playbook ⭐ flagship > Paste this whole file (with the BRIEF filled in) into Claude cowork, chat, or Code. **Bring any music** — a Suno track, a minimax-music generation, your own mp3 — Storyboard turns it into an MTV-grade music video with beat-locked visuals, smooth morph transitions, optional animated lyric typewriter sync'd to the audio, and one polished final reel ready to share. ## What you'll get Whether the source is a Suno song you generated last night, a minimax-music track Storyboard generates on the spot, or an existing audio file you upload, the pipeline ends in one 1920×1080 cinema reel with: - **6–9 cinematic scenes** matched to the song's structure (intro / verse / chorus / bridge / outro). Each scene is a krea-2-large keyframe in your chosen visual style. - **6–9 i2v animations** (seedance-i2v default; ltx-q-i2v for higher fidelity; grok-imagine-video for premium camera moves — all at `resolution:"auto"`) — one per scene, beat-locked to the song's BPM so cuts land on downbeats. - **Morph/crossfade transitions** between every scene via ffmpeg-overlay + xfade — no hard cuts, the visual story flows. - **(Lyric variant)** Animated typewriter text overlay per lyric line via `hyperframes-caption`, beautiful serif font, sync'd to the song's structure. Each line reveals during its section, fades out at the section break. - **(Instrumental variant)** Visual storytelling only — no text overlay, the visuals carry the entire narrative. - **Clean audio mux** — the song plays at full volume, never ducked, and runs **every second of the reel**: the visual cut is timed to the song length so audio and picture end together (no silent tail, no music overrun). No competing voice-over (the song IS the voice). - **Cinema 1920×1080** master + optional 1080×1920 vertical cut for socials. - **Repeatable** — every step is reproducible. Re-render any scene without re-rendering the others (via `director_re_render`). Re-time any scene (via `director_retime`). The chassis stays. **Time**: ~10–15 minutes wall clock. **Your attention**: ~5 minutes across 2 audit gates (after keyframes + after animation). **Cost**: ~$3.50–$5.50 e2e per video. ## Tell the agent about the music video ```yaml piece_title: # e.g. "City Light" piece_subtitle: # 1-sentence about the piece mode: # "lyrics" OR "instrumental" — decides whether to overlay the typewriter # Source music — pick ONE of these three paths music_source: # Path A: bring your own URL audio_url: # https://... direct mp3/wav/m4a, or @last_audio # Path B: generate on the spot generate: prompt: # e.g. "anthemic indie-pop, 60s, 110 BPM, key A major, one warm female vocal, soft synths + acoustic guitar" bpm: # 110 duration_sec: # 60 (or 90) # Path C: existing Suno track suno_url: # direct download URL from Suno # Lyrics — ONLY required if mode=lyrics lyrics: # multi-line YAML string OR an array of {text, start_sec, end_sec} # If a string, the playbook splits on line break and distributes evenly across the song. # If an array, it uses your exact timestamps for precise sync. # Example string: # | # I drew a city light tonight # and waited for the world to find # the way you used to walk through rain # and turn around to say my name # the city sleeps, the city wakes # I'm still here, for old time's sake # Example array: # - text: "I drew a city light tonight" # start_sec: 0 # end_sec: 8 # Visual style visual_style: # e.g. "painterly noir + warm amber neon", "Studio Ghibli watercolour", # "70mm film grain, 90s music-video aesthetic", "VHS dreamscape" palette: # 3-5 colour names matching the mood scene_count: # 6 (default for 60s songs) — 1 scene per 10s, beat-locked beats_per_scene: # auto from bpm × scene_count; tutorial assumes 4 beats per scene # Cast (optional — for lyric-driven videos that follow one protagonist) cast_name: # e.g. "the woman in the cafe" cast_anchor_url: # 1 reference photo to face-swap onto every scene (optional) # Typewriter (lyric mode only) typewriter_font: # e.g. "Cormorant Garamond" (serif elegant, default), # "Inter" (sans-serif modern), "Cinzel" (display) typewriter_position: # "bottom" (default), "top", "center" typewriter_color: # hex, default "#f4e8d0" (warm cream against any palette) # Finishing add_letterbox: # true (default — adds black bars top/bottom for cinema feel) add_brand_endcard: # OPTIONAL — append your brand's 2s end-card output_aspect: # "cinema" (1920×1080, default) OR "vertical" (1080×1920) OR "both" piece_slug: # kebab-case for filenames. e.g. city-light ``` ## Quality controls (auto-applied) - **Cost upfront.** Show estimate before any inference: typically ~$0.30 music + ~$0.44 keyframes + ~$2.52 i2v + ~$0.40 lyric overlays (if applicable) = **~$3.50–$5.50**. User approves first. - **Cast lock when supplied.** If `cast_anchor_url` is set, every i2v keyframe gets the cast spec re-pasted; after animation, optional `face-swap-video` pass on each scene. - **Audit gate after keyframes.** All N keyframes laid out in a grid against the style brief + palette. User approves → animation fires. - **Audit gate after animation.** Each anim plays inline; user marks any with drift; flagged scenes go to `director_re_render` once before stitch. - **Beat-lock invariant.** Every scene's `target_duration_sec` = `(60 / bpm) × beats_per_scene`. At 120 BPM × 4 beats/scene → 2s per scene. At 110 BPM × 4 → 2.18s per scene. The script enforces this in the i2v duration param. - **Audio covers the full reel.** No ducking, no VO competition — the music IS the soundtrack. The total of all scene durations is set equal to the song length (`Σ scene_duration_sec = duration_sec`), so the mux step lands audio and picture together with no silent tail and no music overrun. - **Letterbox by default.** Scales the 1920×1080 frame to 1920×816 and pads back to 1920×1080 with 132px black bars top + bottom → 2.35:1 cinematic feel. Off via `add_letterbox: false`. ## How the agent should run this (interaction contract) 1. **CONFIRM (one message, ≤1 question):** restate in 1 line ("60s MTV reel from your track, 6 beat-locked scenes + lyric typewriter, ~$3.50–5.50, ~10–15 min") + real choices: lyrics vs instrumental mode · seedance (default) vs ltx-q-i2v (fidelity) vs grok-imagine-video (premium camera) · cinema vs vertical vs both. The one question worth asking: which music source path (bring-URL / generate / Suno) if it isn't given. 2. **PREVIEW CHECKPOINT:** AUDIT GATE 1 — scene plan + the keyframe grid (~$0.44) before the ~$2.52 of i2v fires. On the generate path, play the TRACK first: a wrong song wastes every downstream dollar. 3. **NARRATE:** animate in waves of ≤4–5; per wave: "scenes 1–4 animating (seedance, ~2–4 min each), job …"; poll `get_create_media` every 10–15s, never silent >2 min. Say when you reach Stage 6 — the stitch is local ffmpeg and fast. 4. **FAIL GRACEFULLY:** the singer sings the style description → the lyrics-vs-style bug; re-run with real lyrics (or `"[Instrumental]"`) in `lyrics_prompt`; `music` cap fails → retry once → `sonilo-t2m` (licensed sibling); `seedance-i2v` hang → `ltx-q-i2v` (`num_frames:241`, `resolution:"auto"`) → Ken-Burns still; `hyperframes-caption` fail → retry once → ship without the typewriter + a note. ≤2 retries per scene; the beat-lock math survives any single swapped scene. 5. **DELIVER:** the 1920×1080 master (+ vertical if asked) + one honest line ("lyric sync is structural at the line level, not word-perfect; scene 4 was re-rendered once for drift") + ONE next step ("cut the vertical, or train a cast LoRA if this protagonist recurs"). ## The 7-stage pipeline (canonical) ``` Stage 1 — UNDERSTAND THE MUSIC If music_source.audio_url → use directly If music_source.generate → 1 × create_media( action="music", prompt=