[ajisth69]

Summary

Implements a unified, production-grade Auto DJ (Intelligent Queue & Prefetch Controller) and Automix (Beat-Synchronized C++ Dual-Deck DJ Transition Engine) for LastWave-Native.

---

Core Rules & Interlocks

• Independent Toggles & Defaults: autoDjEnabled defaults to false on clean installs. Both autoDjEnabled and automixEnabled operate independently or simultaneously.
• Bit-Perfect Interlock: Suspends Automix DSP automatically when usbExclusiveBitPerfect == true (preserving integer bit-perfect output) and resumes on standard/Oboe output.
• Sequential Album Bypass (sequentialAlbumBypass, default ON): Transitions consecutive tracks (trackNumber == prevTrackNumber + 1) from the same album with Shuffle OFF gaplessly without beat-mixing.

---

Part 1: Auto DJ — Asynchronous Prefetch Pipeline & Queue Controller

• 10-Stage Lifecycle State Machine: QUEUED -> RESOLVING_STREAM -> STREAM_RESOLVED -> DECODING_HEAD_WINDOW -> ARMED_READY -> TRANSITIONING -> PLAYING -> COMPLETED (plus EXPIRED, FAILED_RETRYING, SKIPPED_UNPLAYABLE, CANCELLED).
• Immediate Next-Track Resolution & Advance Arming: Begins resolving index + 1 as soon as playback starts or the queue mutates; decodes head 35 seconds into Deck B ring buffer $\ge 40$ seconds before exit cue.
• Bounded Concurrency & Fault Tolerance: Concurrency capped at maxConcurrentResolvers = 2. Up to 2 bounded retries with exponential backoff before SKIPPED_UNPLAYABLE; silent background refresh of expired URLs.
• Smart Track Ordering & Radio Continuation: Scores candidate tracks by BPM proximity ($\pm 10%$, $0.5\times$, $2.0\times$ ratios) and energy continuity. Automatically fetches recommendations when $\le 2$ tracks remain, deduplicated against the last 50 played track IDs.
• Always-Armed Skip-Mix: Even with Auto DJ OFF, keeping Automix ON maintains index + 1 pre-resolved and armed for instant skip-mixing.

---

Part 2: Automix Transition Planner

• Hard 30-Second Window Clamp: Strictly bounds automatic transition exit cues within [durationMs - 30_000, durationMs - 4_000].
• Lyrics-Aware + Spectral Vocal Guard: Snaps outCueMs to downbeats following the end of sung phrases using synced lyrics timestamps and mid-band ($300\text{ Hz} - 3.5\text{ kHz}$) vs. sub-bass ($60\text{ Hz} - 140\text{ Hz}$) spectral ratio analysis.
• Spoken Intro Skit Skipper: Scans Deck B's head 35 seconds for speech/ambient intro energy ($< -20\text{ dBFS}$ without periodic kicks), locks onto the first 4-kick drop ($> -15\text{ dBFS}$), and sets inCueMs 1 or 2 bars before the drop—never landing mid-sentence.
• Phrase Length Modes: Supports Auto, 8 Bars ($6.0\text{s} - 18.0\text{s}$), 16 Bars ($10.0\text{s} - 26.0\text{s}$), and Fast Skip 4 Bars ($5.0\text{s} - 7.0\text{s}$).

---

Part 3: Native C++ Oboe Dual-Deck Transition DSP & FX Send Suite

• BPM Beat-Grid & WSOLA Time-Stretching: Normalizes half/double-time tempo deltas ($\pm 8%$) and glides back to $1.000\text{f}$ over 6.0 seconds post-mix.
• Windowed Loudness Matching: Gated RMS loudness matching ($[-4.0\text{ dB}, +5.5\text{ dB}]$) decays to $0\text{ dB}$ over 10.0 seconds. Equal-power gain curves with $-1.5\text{ dB}$ center trim and $-0.5\text{ dBFS}$ soft-knee tanh limiter prevent sum clipping.
• Complementary 3-Band Crossover & Downbeat Bass-Swap:
  • $t = 0.00 \to 0.55$: Deck A holds $100%$ sub-bass ($<180\text{ Hz}$ at $0\text{ dB}$); Deck B runs a $200\text{ Hz}$ HPF ($-18\text{ dB}$ sub-bass).
  • $t = 0.55$ Midpoint Swap (over 1 beat): Deck B HPF drops to $20\text{ Hz}$ ($0\text{ dB}$ sub-bass slam) while Deck A's resonant HPF ($Q=1.25$) sweeps $60\text{ Hz} \to 550\text{ Hz}$. Zero bass holes, zero double-bass mud.
• Vocal-Pocket Ducking: Applies a dynamic $-9.0\text{ dB}$ peaking cut ($1200\text{ Hz}, Q=0.7$) to Deck A when Deck B has vocals.
• Instrumental Loop-Lock & Reverb Tail: Beat-repeat slicer / 1-bar loop-lock on Deck A only when vocal-free; $1.4\text{s}$ stereo damping reverb tail rings out after Deck A dry signal ends. Single texture FX auto-chooser (sweep, stereo expander, phaser, none).
• Automix on Skip: Pressing Next during playback triggers an instant 4-bar blend into Deck B's entry cue.

---

Part 4: UI, Seekbar, Lyrics & Artwork Synchronization

• Lockstep Pause/Resume: Pausing/resuming pauses and resumes Deck A, Deck B, and DSP FX tails in lockstep.
• Midpoint Handover ($t = 0.55$): Seekbar, elapsed time, and synced lyrics smoothly hand over to Deck B at the bass-swap downbeat without backward jumps or freezes.
• Scrubbing Mid-Transition: Scrubbing before $t = 0.55$ cleanly cancels and restores Deck A; scrubbing past $t = 0.55$ commits to Deck B.
• Now Playing Status Pill & Cross-Dissolve: Minimalist status pill ("Auto DJ · Next Armed" / "Auto DJ · Standby" when idle; animated "Automix · 8-Bar Bass Swap [BPM Synced]" with pulsing glow aura when blending). Album artwork cross-dissolves smoothly between decks across the transition window.

---

Verification

• test_transition_planner.cpp: PASSED (lifecycle state machine, 40s advance arming, refill on $\le 2$ tracks, hard 30s clamp, vocal snapping, skit skipper, vocal-pocket ducking, skip blend).
• test_automix_dsp_upgrades.cpp: PASSED (equal-power gain, -18dB bass swap, resonant filter sweep, drop beat onset, in-place processing).