album-transitions

Build cinematic, stem-aware transitions between tracks for continuous album playback. Inspired by MBDTF / Donda / Vice City radio / Don Toliver albums where songs bleed into each other.

When to invoke

User says any of:

• "make transitions between these tracks" / "crossfade my album"
• "stem-based transitions" / "make it cinematic"
• "tape stop from track A to track B"
• "DJ mix these songs together"
• "continuous album mix"
• "Kanye-level transitions"
• Drops multiple tracks + a manifest asking for a continuous mix

What it does

For each boundary between two tracks, composes a transition block from:

1. Stems (Demucs-separated drums/bass/vocals/other) — keep A's melody playing under B's intro
2. Time-stretch via Rubberband — align A's tempo to B's for clean overlap
3. Key-matched pad — synthesized sine chord in track B's key, BPM-bar-synced
4. Creative SFX — generated via ElevenLabs sound-generation API (sirens, crashes, phones, risers)
5. Voice interludes (optional) — TTS via ElevenLabs with your cloned voices

Quick start

One-shot render

python3 ~/.claude/skills/album-transitions/scripts/render_album.py \
  --manifest /path/to/album.json \
  --stems-dir /path/to/demucs_output \
  --out /path/to/FULL_ALBUM.mp3

Manifest format (album.json)

{
  "title": "ALBUM v1",
  "brand_kicker": "OPERATION LOOP",
  "tracks": [
    {"num": 1, "name": "01 INTRO", "file": "src/01.mp3", "bpm": 92, "key": "D# minor"},
    {"num": 2, "name": "02 TRACK TWO", "file": "src/02.mp3", "bpm": 136, "key": "C# major"}
  ],
  "transitions": [
    {"from": 1, "to": 2, "type": "DRONE_BRIDGE",
     "voice_prompt": "[whispered] you ready for this?",
     "voice_character": "voicemail",
     "sfx_prompt": "cinematic riser building into crash"}
  ]
}

First-time setup

bash ~/.claude/skills/album-transitions/scripts/setup.sh

Installs: demucs (stem separation), pyrubberband + rubberband binary (time-stretch), playwright (for PDF tracklist). Also writes ElevenLabs API key at ~/.elevenlabs/key.

Transition types

Each boundary gets one type. Bar allocations in config/transition_types.json:

Optional: stem separation via Demucs

If you have Demucs installed (via setup.sh or manual), the builder will use stems so:

• A's drums are dropped during overlap (no rhythm clash with B's drums)
• A's other (melody/synth) keeps playing, pitch-shifted toward B's key
• B's stems stage-in: other first, bass next, drums at 50%, vocals last

Without stems, the pipeline falls back to time-stretched full mix, which still works but less surgical.

Optional: ElevenLabs SFX + voice

Set ELEVENLABS_API_KEY in env or ~/.elevenlabs/key file. Then include sfx_prompt and/or voice_prompt in each transition manifest entry.

Voice characters supported:

• voicemail — unhinged/emotional (uses voice_id from config)
• dj — aggressive hype announcer
• Custom voice IDs can be passed directly via voice_id field

Output

• ALBUM_MIX.mp3 — continuous 256kbps MP3
• ALBUM_MIX.m4a — same audio, AAC, with chapter markers per track (skip in any modern player)
• tracklist.pdf (optional) — printable tracklist via analyst-pdf skill
• transitions_log.json — every transition's generated assets for debugging

Dependencies

• Python 3.9+
• ffmpeg (ships with most systems or install via brew install ffmpeg)
• Demucs 4.x (optional, for stem-based transitions) — GPU/MPS-accelerated
• Rubberband binary + pyrubberband (optional, for high-quality time-stretch)
• ElevenLabs API key (optional, for SFX + voice)

Fallback behavior

• No Demucs → uses full mix, time-stretched. Still works.
• No Rubberband → falls back to ffmpeg atempo (lower quality above 1.5x shifts).
• No ElevenLabs → skips SFX + voice, transitions are pad-only.

The pipeline is designed to gracefully degrade based on what's available.