Album Release Pipeline

Album Release Pipeline

One config file in, a released album out: audio, art, film, video publish, radio deploy, on-air premiere, social announce.

The pipeline is phase-based and every phase is idempotent — re-run after any failure and it resumes where it stopped. Proven end-to-end: a seven-song album went from blank page to on-air premiere in about two and a half hours.

The release runner itself is operator-specific: it is wired to a particular radio host, credential layout, and set of provider accounts. This skill documents the shape of the pipeline and the failure modes worth knowing. Supply your own runner and provider credentials.

Phases

1. Music — render each track through your music provider in custom mode, two variants per track, resumable via a per-track ledger so a mid-album failure never re-renders what already succeeded.
2. Art — generate one cover per track from a per-track art prompt, then collect the images.
3. Film — fetch timestamped lyrics, emit per-track ASS karaoke subtitles, and assemble a 1920×1080 slideshow (one cover per song, lyrics burned in) with ffmpeg.
4. Publish — upload the film, deploy the audio to the radio host, restart the service, and fan out the announce post.

Config shape

A single JSON file drives the run:

• name, out_dir, ledger, theme, default_style
• tracks[] — each with title, style, art_prompt
• release{} — lead track, video metadata, and the deploy target

Register the album with the radio's programming layer before deploying, since the deploy phase pulls the album definition on the host. A preflight check should abort when the album is not registered — that one mistake otherwise surfaces as a silent no-op an hour later.

Lyrics: pre-write them. Drop a lyrics file per track in out_dir before running, and the pipeline uses it verbatim; otherwise it generates them. Hand-written lyrics are almost always the better album.

Per-track video release (alternate publish mode)

Instead of one album film, release one video per track plus a playlist. This mode shipped a seven-track album end-to-end (28 art pieces, 7 videos, playlist, link fanout) in one sitting:

1. Manifest — extend each track with one cover prompt plus 2-3 support image prompts. Every prompt in the batch opens differently and varies medium/palette/subject (see the art gotcha below); give each track its own visual idiom family so the album reads as a set.
2. Art batch — generate all images through the provider with generous gaps for rate limits; resumable by skipping files already on disk. Save each piece's artifact id alongside the image.
3. Render — per track, build a slideshow that cycles twice through [cover, s1, s2, s3] with equal slot lengths over the track duration (ffmpeg concat demuxer with per-image duration entries, last file repeated), scale/pad to 1280×720, mux the track audio, -tune stillimage.
4. Upload — one video per track (music category, public), cover as thumbnail re-encoded to JPEG under 2 MB. Keep a slug→video-id ledger so re-runs skip completed uploads. Space uploads by ~45s.
5. Verify — after the batch, list all uploaded ids in one API call and confirm each still exists; clear vanished ids from the ledger so a re-run repairs them. Then create a public playlist and add the videos in track order.
6. Link fanout — post the playlist link everywhere; platforms without hard character caps also get the full per-track link list. Compose per-platform: a 300-char platform gets a two-line announce + playlist URL, long-form platforms get the whole tracklist with URLs.

Phase gating

Skip phases you want to control by hand — this is how you time a premiere:

1. Run with the deploy and announce phases skipped.
2. Deploy the audio early by hand. Deploy normally runs after the art phase (~9 minutes), so if you are racing a clock, move the files yourself, renamed to the exact track titles.
3. Fire the showcase ceremony against the radio's album-showcase endpoint with the album name, a duration, and the real making-of story — the narration is built from that story, so a vague one produces vague narration.

To sync with a scheduled segment, watch the radio journal for the segment marker and fire after it. If strict ordering matters, wait for the segment's completion marker rather than its start — a slow segment can otherwise be stepped on by the showcase intro.

Gotchas (each one caused a real fire)

• Windows paths: pass the config as a C:/... style path. Embedded Python rejects MSYS /c/... form and the builder silently no-ops.
• Apostrophes: album-level theme and default_style get interpolated into single-quoted inline Python — keep them apostrophe-free. Per-track fields and lyrics are safe.
• Art prompts: diversify medium, palette, and subject across the batch or the image provider's repetition detector will start rejecting requests. One distinct medium per song works well — linocut, screenprint, gouache, oil, travel poster, ink, digital.
• Video uploads: verify the upload actually exists afterwards rather than trusting the response. Uploads can vanish after a 200.
• One-shot narration: if a scheduled segment's TTS fails, it may post its text and mark itself complete with no retry. The album premiere is unaffected, but that segment goes silent for the slot.
• Remote work: batch it into few sessions. Connection churn trips fail2ban-style protections on most hosts, and SSH connection multiplexing does not work from Windows OpenSSH.
• Lyric generation can die silently: if the lyric generator's model API credential is dead, the builder skips every track in seconds and "completes" with an empty ledger. Check the ledger is non-empty before believing a run; the pre-written-lyrics path (drop files in out_dir) is the reliable fallback and usually the better album anyway. Verify the first track's prompt round-trip against the provider's record-info endpoint before letting a batch run — multi-line lyrics are easy to truncate to their first line in shell plumbing.
• Image providers may require a session before generating: one provider added a requirement to "enter" its studio context first — every generate call 403s until you do. Open the session at batch start and re-open it whenever that specific error reappears mid-batch.
• Video-host tokens go stale per machine: the machine that last re-granted OAuth has the live refresh token; other machines keep a dead copy that fails with a bare 400. Run a token liveness probe before any batch upload and sync the credential from the machine where the grant actually happened.
• Fanout adapters read their environment: broadcast code that works under cron can silently lose adapters when run from a plain shell, because the credentials live in env files the cron sources. Silently — the adapter list shrinks, nothing errors. Source the same env the crons use, and compare the adapter list against what you expect before calling a fanout complete. Posting twice while debugging this means deleting duplicates platform by platform.
• Killing a remote batch by pattern: pkill -f over ssh can match the ssh command line that carries it and kill your own connection. Bracket a character in the pattern (pkill -f "[a]rt.py").

Related

• Sibling skill: podcast-video-publisher — episode videos and playlist management.