[Feature] Dual-Deck Audio Architecture & Seamless DJ Crossfading

[arkalon76]

📌 Executive Summary & User Story

As a continuous listener,
I want station changes to execute instantly with a smooth, beat-aware DJ crossfade,
So that I never hear 3–5 seconds of dead silence, audio pops, or buffering lag when surfing stations.

---

🎯 Problem Statement & Community Context

In every existing command-line radio player, switching stations stops the current stream, creates an awkward 3–5 second silence while establishing a new TCP connection and buffering audio, and then abruptly starts the new stream.

---

🏗️ Detailed Functional Requirements

1. Dual-Deck Audio Engine Architecture

• Refactor pkg/player/ to maintain two independent playback decks: Deck A and Deck B.
• While Deck A is playing live to audio output, selecting a new station assigns it to Deck B.

2. Zero-Gap Pre-Buffering & Crossfading

• When user presses n, p, or selects a station with Enter:
  1. Deck B connects to the new stream URL and pre-buffers 1.5 seconds of audio in the background.
  2. Deck A continues playing without interruption.
  3. The moment Deck B is ready, halpradio initiates a smooth equal-power crossfade (configurable duration: 1.0s–5.0s, default 2.5s).
  4. Deck A volume scales 1.0 -> 0.0 while Deck B volume scales 0.0 -> 1.0.
  5. Once crossfade completes, Deck A terminates its network connection and releases resources.

3. Visual DJ Deck Transition Indicator

• Display visual deck status ([A ► B] crossfade meter) in the playerbar during transitions.

---

🖥️ TUI & Visual Design

▶ Transitioning: [SomaFM] ──► [Nightwave Plaza]
[ Crossfade: ██████████░░░░░░░░░░ Deck A (40%) ── Deck B (60%) ]

---

🛠️ Technical Architecture & Implementation Details

• Package Location: pkg/player/manager.go, pkg/player/deck.go, pkg/player/crossfade.go.
• Mutex Discipline: Enforce strict lock synchronization across both deck goroutines.
• Backend Support: Native Go Oto engine and MPV IPC socket dual-player instance management.

---

✅ Acceptance Criteria (Definition of Done)

• Station transitions occur with 0ms dead silence.
• Configurable crossfade curves (Linear, Exponential, Equal Power) in config.yaml.
• No audio popping, clicking, or CPU spikes during deck handoff.
• Rapid station jumping handles cancellations cleanly without dangling goroutines.
• Unit tests for dual-deck lifecycle and crossfade volume curves.