[Feature] Smart Zap: Speech vs. Music Classifier & Commercial/Banter Auto-Diverter

[arkalon76]

📌 Executive Summary & User Story

As a focused listener and programmer,
I want halpradio to automatically detect when a station cuts to speech banter or loud commercials and either mute or temporarily divert playback to a backup music station,
So that my deep focus is never broken by intrusive ads or unwanted talk radio.

---

🎯 Problem Statement & Community Context

Intrusive advertising and morning show "yapping" are universally cited as the #1 frustration of broadcast internet radio. When coding, a sudden loud car commercial or loud banter immediately breaks flow state.

---

🏗️ Detailed Functional Requirements

1. Voice Activity Detection (VAD) & Audio Energy Classifier

• Integrate an ultra-lightweight on-device audio classification filter in pkg/player/dsp/vad.go.
• Analyze spectral flux, harmonic ratio, and zero-crossing rate of the decoded PCM buffer to distinguish between continuous music and spoken voice / commercial jingles.

2. Auto-Divert Mode (Station Surfer)

• When sustained speech or commercial format is detected on the primary station:
  1. Smoothly crossfades volume down over 500ms.
  2. Diverts playback to the user's configured Fallback Focus Station (e.g. Lofi Girl or SomaFM Drone Zone).
  3. Continues analyzing the primary station in a low-bitrate background listener.
  4. Once music resumes on the primary station, smoothly crossfades back!

3. Auto-Ducking / Mute Mode

• Alternative lightweight behavior: Smoothly attenuates volume to 10% (ducking) or mutes entirely until the music resumes.

4. Configuration & User Control

• Settings in config.yaml:

  smart_zap:
    enabled: true
    mode: divert # divert | duck | mute
    fallback_station: "somafm_groovesalad"
    speech_threshold_seconds: 15

• Hotkey Z (in player) to quickly toggle Smart Zap on/off.

---

🖥️ TUI & Visual Design

▶ BBC Radio 6 Music  [⚡ SMART ZAP ACTIVE: Diverted to SomaFM Groove Salad]
[ ☕ Music Resuming on BBC 6 in ~15s... Press 'Z' to cancel divert ]

---

🛠️ Technical Architecture & Implementation Details

• Package Location: pkg/player/dsp/, pkg/player/diverter.go.
• Pure Go / Zero Heavy CGo: Use lightweight energy-based zero-crossing and spectral roll-off algorithms or WebAssembly neural VAD (e.g. Silero-VAD in Wasm via Wazero).
• Background Stream Monitor: Low-overhead metadata + packet probe to monitor primary station recovery.

---

✅ Acceptance Criteria (Definition of Done)

• Accurately detects sustained speech intervals (> 15s) vs musical tracks.
• Divert mode crossfades seamlessly to fallback station without audio glitches.
• Returns to primary station cleanly when music resumes.
• Duck mode lowers volume smoothly and restores initial volume level.
• TUI displays distinct status badges when Smart Zap is actively mitigating an ad/talk segment.