discstation 0.1.30 → 0.1.31

package/arduino/DiscStation/DiscStation.ino

@@ -32,13 +32,21 @@
 #define DEBOUNCE_MS      50
 #define LONG_PRESS_MS    1000
 #define ENC_CLICK_GUARD_MS 200  // ignore new SW presses this soon after a rotation tick (rotation vibration can bounce SW low)
-#define ENC_DEBOUNCE_US 2000     // ignore encoder interrupts closer together than this (contact bounce)
 #define DONE_RESET_MS    30000
 #define STANDBY_BLANK_MS 60000
-#define IDLE_BLANK_MS    45000   // no input this long on HOME/STANDBY -> spinning-disc screensaver
+#define IDLE_BLANK_MS    15000   // no input this long on HOME/STANDBY -> spinning-disc screensaver
+                                 // (this power bank's no-load auto-shutoff trips at ~30s idle; keep this
+                                 // well under that so the screensaver's current draw beats it there)
 #define SAVER_FRAME_MS   90      // screensaver frame interval (~11fps)
 #define PING_TIMEOUT_MS  30000
 
+#define VU_BARS       16   // must match the host's VU: band count
+#define VU_TIMEOUT_MS 1200 // no VU: update this long -> host isn't sending (paused/stopped), fall back to text
+                           // (generous on purpose: the host's capture thread can jitter under load on a Pi -
+                           // too tight and normal jitter flickers between bars and the text screen)
+#define VU_ENTRY_DELAY_MS  10000  // stay on the text status screen this long after entering PLAY
+#define VU_RESUME_DELAY_MS  7000  // ...and this long after any input while already in PLAY
+
 #define WIFI_RESET_HOLD_MS      10000  // hold SELECT this long on HOME to wipe Wi-Fi creds
 #define WIFI_CONNECT_TIMEOUT_MS 18000  // give a stored-creds join this long before falling to the portal
 #define WIFI_RETRY_MS           15000  // if a live link drops, force a re-join after this
@@ -84,6 +92,7 @@ private:
 
 void drawSetup();       // fwd decls (defined with the other draw* below)
 void drawWifiReset();
+void drawPlayVisualizer();
 
 String deviceSuffix() {
   uint8_t mac[6];
@@ -226,7 +235,6 @@ bool playStatusTemp = false;
 unsigned long encClickDownAt = 0;
 bool encClickDown = false;
 unsigned long encClickLastDebounce = 0;
-unsigned long lastEncRotateMs = 0;   // set whenever a rotation tick is drained; guards SW against rotation noise
 
 // EJECT button - single press, no long-press timer needed
 bool ejectDown = false;
@@ -255,6 +263,15 @@ bool displayBlank = false;          // true = real UI hidden, disc screensaver r
 unsigned long lastSaverFrame = 0;
 int saverStep = 0;
 bool audioPlayMode = false;
+
+// Spectrum visualizer: host streams real playback levels as "VU:v0,v1,...".
+// While they keep arriving, PLAY shows full-screen bars instead of the usual
+// status text; VU_TIMEOUT_MS after they stop (paused/stopped host-side) it
+// falls back to the normal drawPlay() screen.
+uint8_t vuLevel[VU_BARS];
+bool visualizerActive = false;
+unsigned long lastVuAt = 0;
+unsigned long vuSuppressUntil = 0;   // bars withheld (text screen shown instead) until millis() reaches this
 int displayRotation = 0;
 
 // Indeterminate progress animation
@@ -262,21 +279,54 @@ int indeterminateCount = 0;
 unsigned long lastIndeterminateAnim = 0;
 
 // --- Rotary encoder decode ---
-// Interrupt only on CLK's falling edge (one detent = one interrupt, not four
-// - a mechanical encoder's contact bounce can otherwise fire far more often
-// than that and starve other tasks, including the USB-serial link); DT's
-// level at that instant gives direction. A short time debounce rejects
-// contact chatter. Interrupt-driven because the main loop's ~20ms cadence is
-// too slow to reliably catch a fast spin without missing ticks.
+// Ben Buxton's full-step quadrature state machine (the standard robust
+// rotary-encoder algorithm, e.g. the basis of the Arduino "Rotary" library).
+// Reads BOTH pins on every change and only commits a tick after a complete,
+// valid 4-transition sequence - contact bounce just walks between
+// non-committing states instead of producing a spurious tick, so no time
+// debounce is needed. (An earlier CLK-only + micros()-debounce version read
+// just one pin's level at one instant, which is fragile - CLK and DT edges
+// aren't perfectly synchronized on a mechanical encoder, so bounce right at
+// the sample instant could misread direction or double-fire: skipped,
+// doubled, and wrong-direction ticks. That simpler decode was chosen to
+// lighten interrupt load for the dead XIAO ESP32-C6's fragile native-USB
+// link; the current board's CP2102 bridge isn't affected by that at all.)
+#define ENC_R_START     0x0
+#define ENC_R_CW_FINAL  0x1
+#define ENC_R_CW_BEGIN  0x2
+#define ENC_R_CW_NEXT   0x3
+#define ENC_R_CCW_BEGIN 0x4
+#define ENC_R_CCW_FINAL 0x5
+#define ENC_R_CCW_NEXT  0x6
+#define ENC_DIR_CW  0x10
+#define ENC_DIR_CCW 0x20
+
+const uint8_t ENC_TTABLE[7][4] = {
+  {ENC_R_START,    ENC_R_CW_BEGIN,  ENC_R_CCW_BEGIN, ENC_R_START},
+  {ENC_R_CW_NEXT,  ENC_R_START,     ENC_R_CW_FINAL,  ENC_R_START | ENC_DIR_CW},
+  {ENC_R_CW_NEXT,  ENC_R_CW_BEGIN,  ENC_R_START,     ENC_R_START},
+  {ENC_R_CW_NEXT,  ENC_R_CW_BEGIN,  ENC_R_CW_FINAL,  ENC_R_START},
+  {ENC_R_CCW_NEXT, ENC_R_START,     ENC_R_CCW_BEGIN, ENC_R_START},
+  {ENC_R_CCW_NEXT, ENC_R_CCW_FINAL, ENC_R_START,     ENC_R_START | ENC_DIR_CCW},
+  {ENC_R_CCW_NEXT, ENC_R_CCW_FINAL, ENC_R_CCW_BEGIN, ENC_R_START},
+};
+
+volatile uint8_t encState = ENC_R_START;
 volatile int16_t encTicks = 0;   // whole detents ready for loop() to drain
-volatile uint32_t encLastIsrUs = 0;
+volatile uint32_t encLastActivityMs = 0;   // refreshed on every raw pin transition, not just
+                                            // committed ticks - guards handleSelectPress's SW
+                                            // read against bounce/crosstalk from a spin in progress
 
 void IRAM_ATTR encoderISR() {
-  uint32_t now = micros();
-  if (now - encLastIsrUs < ENC_DEBOUNCE_US) return;
-  encLastIsrUs = now;
-  if (digitalRead(ENC_CLK_PIN) != digitalRead(ENC_DT_PIN)) encTicks++;
-  else encTicks--;
+  encLastActivityMs = millis();
+  uint8_t pinState = (digitalRead(ENC_DT_PIN) << 1) | digitalRead(ENC_CLK_PIN);
+  encState = ENC_TTABLE[encState & 0xF][pinState];
+  uint8_t dir = encState & 0x30;
+  // Flipped from the table's literal CW/CCW so the tick sign matches this
+  // encoder's physical wiring: turning the knob clockwise should increase
+  // (next track, volume up), not decrease.
+  if (dir == ENC_DIR_CW) encTicks--;
+  else if (dir == ENC_DIR_CCW) encTicks++;
 }
 
 void sendHomeMode() {
@@ -591,7 +641,11 @@ bool wakeDisplay() {
     case UI_STATUS: drawStatus(); break;
     case UI_IP: drawIP(); break;
     case UI_BURN_READY: drawBurnReady(); break;
-    case UI_PLAY: drawPlay(); break;
+    case UI_PLAY:
+      if (visualizerActive && (long)(millis() - lastVuAt) < VU_TIMEOUT_MS &&
+          (long)(millis() - vuSuppressUntil) >= 0) drawPlayVisualizer();
+      else drawPlay();
+      break;
     case UI_WAITING: drawWaiting(); break;
     case UI_STANDBY: drawStandby(); break;
     case UI_DISCONNECTED: drawDisconnected(); break;
@@ -600,9 +654,35 @@ bool wakeDisplay() {
   return true;
 }
 
+#define VU_TOP_MARGIN 16   // px of empty headroom above the tallest possible bar
+
+// Full-screen-width spectrum bars, no header/chrome, capped short of the top
+// edge (VU_TOP_MARGIN) so a loud peak doesn't run the panel edge-to-edge.
+// Falls back to the normal drawPlay() text screen once VU: updates stop
+// arriving (see VU_TIMEOUT_MS in loop()).
+void drawPlayVisualizer() {
+  uiState = UI_PLAY;
+  returnToHomeAt = 0;
+  if (!displayOk) return;
+
+  display.clearDisplay();
+  const int gap = 2;
+  const int maxH = SCREEN_HEIGHT - VU_TOP_MARGIN;
+  const int barW = (SCREEN_WIDTH - gap * (VU_BARS - 1)) / VU_BARS;
+  int x = (SCREEN_WIDTH - (barW * VU_BARS + gap * (VU_BARS - 1))) / 2;
+  for (int i = 0; i < VU_BARS; i++) {
+    int h = map(vuLevel[i], 0, 63, 0, maxH);
+    if (h > 0) display.fillRect(x, SCREEN_HEIGHT - h, barW, h, SSD1306_WHITE);
+    x += barW + gap;
+  }
+  display.display();
+}
+
 void drawPlay() {
   uiState = UI_PLAY;
   returnToHomeAt = 0;
+  lastInputTime = millis();   // real status content (track change, pause/resume) gets a full
+                               // IDLE_BLANK_MS on screen before the screensaver reclaims it
   if (!displayOk) return;
 
   display.clearDisplay();
@@ -637,6 +717,28 @@ void parseMessage(String msg) {
     return;
   }
 
+  if (msg.startsWith("VU:")) {
+    // No wakeDisplay()/RCV echo here - this arrives ~15x/sec while playing,
+    // wakeDisplay() would draw stale bars a frame early, and echoing it
+    // would spam the serial log for no reason.
+    lastMsgTime = millis();
+    String rest = msg.substring(3);
+    for (int i = 0; i < VU_BARS; i++) vuLevel[i] = 0;
+    for (int i = 0; i < VU_BARS && rest.length() > 0; i++) {
+      int comma = rest.indexOf(',');
+      String tok = (comma < 0) ? rest : rest.substring(0, comma);
+      vuLevel[i] = (uint8_t)constrain(tok.toInt(), 0, 63);
+      if (comma < 0) break;
+      rest = rest.substring(comma + 1);
+    }
+    visualizerActive = true;
+    lastVuAt = millis();
+    lastInputTime = millis();   // the visualizer's own continuous redraw already beats the
+                                 // power-bank shutoff - no need for the screensaver too
+    if (uiState == UI_PLAY && (long)(millis() - vuSuppressUntil) >= 0) drawPlayVisualizer();
+    return;
+  }
+
   wakeDisplay();
   lastMsgTime = millis();
 
@@ -693,6 +795,7 @@ void parseMessage(String msg) {
     line1 = msg.substring(5);
     line2 = "Playing disc";
     playSeekMode = false;          // always start in volume mode
+    vuSuppressUntil = millis() + VU_ENTRY_DELAY_MS;   // text screen first, bars after a beat
     Out.print("POT:");             // push the last-used volume so playback starts at it
     Out.println(playVolume);
     drawPlay();
@@ -803,13 +906,16 @@ void setup() {
   Serial.begin(115200);
   esp_task_wdt_add(NULL);
   Wire.begin(21, 22);
+  Wire.setClock(400000);   // SSD1306 supports I2C fast-mode; the default 100kHz was too slow to
+                           // push a full 128x64 frame at the visualizer's ~15fps without stutter
   pinMode(BTN_EJECT_PIN, INPUT_PULLUP);
   pinMode(BTN_HOME_PIN, INPUT_PULLUP);
   pinMode(BTN_PLAYPAUSE_PIN, INPUT_PULLUP);
   pinMode(ENC_SW_PIN, INPUT_PULLUP);
   pinMode(ENC_CLK_PIN, INPUT_PULLUP);
   pinMode(ENC_DT_PIN, INPUT_PULLUP);
-  attachInterrupt(digitalPinToInterrupt(ENC_CLK_PIN), encoderISR, FALLING);
+  attachInterrupt(digitalPinToInterrupt(ENC_CLK_PIN), encoderISR, CHANGE);
+  attachInterrupt(digitalPinToInterrupt(ENC_DT_PIN), encoderISR, CHANGE);
 
   displayOk = display.begin(SSD1306_SWITCHCAPVCC, I2C_ADDRESS);
 
@@ -903,6 +1009,7 @@ void handleSelectPress(bool longPress) {
     drawStandby();
 
   } else if (uiState == UI_PLAY) {
+    vuSuppressUntil = millis() + VU_RESUME_DELAY_MS;   // any PLAY input -> back to text for a beat
     if (longPress) {
       Out.println("PLAY_STOP");
     } else {
@@ -942,6 +1049,7 @@ void handleEncoderCW() {
     displayRotation = 2;
     drawStandby();
   } else if (uiState == UI_PLAY) {
+    vuSuppressUntil = millis() + VU_RESUME_DELAY_MS;   // any PLAY input -> back to text for a beat
     if (!playSeekMode) {
       playVolume = min(100, playVolume + 5);
       Out.print("POT:");
@@ -979,6 +1087,7 @@ void handleEncoderCCW() {
     displayRotation = 0;
     drawStandby();
   } else if (uiState == UI_PLAY) {
+    vuSuppressUntil = millis() + VU_RESUME_DELAY_MS;   // any PLAY input -> back to text for a beat
     if (!playSeekMode) {
       playVolume = max(0, playVolume - 5);
       Out.print("POT:");
@@ -1023,6 +1132,7 @@ void handlePlayPauseButton(bool longPress) {
   if (wakeDisplay()) { lastInputTime = millis(); return; }
   lastInputTime = millis();
   if (uiState == UI_PLAY) {
+    vuSuppressUntil = millis() + VU_RESUME_DELAY_MS;   // any PLAY input -> back to text for a beat
     Out.println(longPress ? "PLAY_STOP" : "PLAY_BUTTON");
   } else if (uiState == UI_HOME && !longPress) {
     bool hasPlay = false;
@@ -1037,6 +1147,24 @@ void handlePlayPauseButton(bool longPress) {
   }
 }
 
+// Drains every line currently buffered on a link in one go instead of one
+// per loop() call. VU: frames arrive fast enough (~15/sec) that drawing each
+// one in turn made the display fall further and further behind real-time
+// once a single draw took longer than the send interval - only the last VU:
+// seen in a batch is kept/rendered, so the visualizer always shows "now"
+// instead of working through a backlog. Every other message type still gets
+// parsed in order; only VU: is collapsible like this.
+void drainAndDispatch(Stream &s) {
+  String pendingVu = "";
+  while (s.available()) {
+    String msg = s.readStringUntil('\n');
+    if (msg.length() == 0) continue;
+    if (msg.startsWith("VU:")) pendingVu = msg;
+    else parseMessage(msg);
+  }
+  if (pendingVu.length() > 0) parseMessage(pendingVu);
+}
+
 void loop() {
   if (!wifiInitDone && millis() > 3000) {
     wifiInitDone = true;
@@ -1079,15 +1207,13 @@ void loop() {
       Out.setClient(nullptr);
     }
     if (tcpClient && tcpClient.available()) {
-      String msg = tcpClient.readStringUntil('\n');
-      if (msg.length() > 0) parseMessage(msg);
+      drainAndDispatch(tcpClient);
     }
   }
 
   esp_task_wdt_reset();
   if (Serial.available()) {
-    String msg = Serial.readStringUntil('\n');
-    parseMessage(msg);
+    drainAndDispatch(Serial);
   }
 
   if (returnToHomeAt != 0 && (long)(millis() - returnToHomeAt) >= 0) {
@@ -1106,7 +1232,6 @@ void loop() {
     int16_t ticks = encTicks;
     encTicks = 0;
     interrupts();
-    if (ticks != 0) lastEncRotateMs = millis();
     while (ticks > 0) { handleEncoderCW(); ticks--; }
     while (ticks < 0) { handleEncoderCCW(); ticks++; }
   }
@@ -1117,7 +1242,7 @@ void loop() {
   {
     bool sw = digitalRead(ENC_SW_PIN) == LOW;
     if (sw && !encClickDown && millis() - encClickLastDebounce > DEBOUNCE_MS &&
-        millis() - lastEncRotateMs > ENC_CLICK_GUARD_MS) {
+        millis() - encLastActivityMs > ENC_CLICK_GUARD_MS) {
       encClickDown = true;
       encClickDownAt = millis();
     }
@@ -1191,9 +1316,18 @@ void loop() {
     if (!displayBlank) drawStatus();
   }
 
-  // --- Idle disc screensaver (HOME + STANDBY) ---
+  // --- Visualizer timeout: host stopped sending VU: (paused/stopped) ---
+  if (visualizerActive && (long)(millis() - lastVuAt) >= VU_TIMEOUT_MS) {
+    visualizerActive = false;
+    if (uiState == UI_PLAY && !displayBlank) drawPlay();
+  }
+
+  // --- Idle disc screensaver (HOME + STANDBY + PLAY) ---
+  // PLAY is included because a static "PLAYING" screen is just as low-current
+  // as HOME/STANDBY were - the power bank doesn't care what's on screen, only
+  // that the draw stays static this long.
   if (displayOk && !displayBlank &&
-      (uiState == UI_HOME || uiState == UI_STANDBY) &&
+      (uiState == UI_HOME || uiState == UI_STANDBY || uiState == UI_PLAY) &&
       (long)(millis() - lastInputTime) >= IDLE_BLANK_MS) {
     displayBlank = true;
     saverStep = 0;

package/docs/PLATFORM_SUPPORT.md

@@ -27,6 +27,22 @@ Set `DISC_DEVICE` if automatic drive detection fails. The one known limitation
 is **audio-CD *burning*** — `cdrdao` is the only option and often cannot claim
 the drive on recent macOS; DiscStation reports this clearly instead of hanging.
 
+### ESP32 remote: OLED spectrum visualizer
+
+The visualizer needs a one-time manual setup, since macOS has no built-in
+way to tap "whatever's currently playing" the way Linux's PulseAudio does:
+
+1. `brew install blackhole-2ch` (done automatically by `install-macos.sh`).
+2. Open **Audio MIDI Setup** (in Applications/Utilities), click **+** →
+   **Create Multi-Output Device**, and check both **BlackHole 2ch** and your
+   real output (speakers/headphones).
+3. In **System Settings → Sound**, set that Multi-Output Device as the
+   default output. Audio stays audible (routed to your real device) and is
+   simultaneously tapped (via BlackHole) for the visualizer's FFT.
+
+Without this setup the visualizer silently does nothing and PLAY just shows
+its normal text screen — nothing else is affected.
+
 ## Windows
 
 Runs the same Python host and web UI as Linux/macOS, triggered the same way

package/install-macos.sh

@@ -28,7 +28,7 @@ if ! command -v brew >/dev/null 2>&1; then
 fi
 
 brew install python ffmpeg cdrdao dvdauthor node yt-dlp xorriso mpv libdiscid handbrake \
-  libdvdcss dvdbackup libcdio-paranoia
+  libdvdcss dvdbackup libcdio-paranoia blackhole-2ch
 mkdir -p "$APP_DIR" "$VENV_DIR" "$CONFIG_DIR"
 cp -R "$ROOT_DIR/src/." "$APP_DIR/"
 python3 -m venv "$VENV_DIR"
@@ -40,9 +40,12 @@ else
 fi
 # Optional metadata deps — best effort. python-libdiscid (a C extension) is
 # Linux-only in requirements-optional.txt; on macOS install the pure-Python
-# bits and let brew's libdiscid cover disc IDs via the CLI tools.
+# bits and let brew's libdiscid cover disc IDs via the CLI tools. numpy is
+# for the OLED spectrum visualizer (needs the blackhole-2ch brew package
+# above too, plus a one-time Multi-Output Device setup - see
+# docs/PLATFORM_SUPPORT.md).
 if [[ -f "$ROOT_DIR/requirements-optional.txt" ]]; then
-  "$VENV_DIR/bin/python" -m pip install musicbrainzngs tmdbsimple \
+  "$VENV_DIR/bin/python" -m pip install musicbrainzngs tmdbsimple numpy \
     || printf 'Optional metadata deps skipped (host still works).\n'
 fi
 

package/install.sh

@@ -17,7 +17,7 @@ if command -v apt-get >/dev/null 2>&1; then
     cdrdao dvdauthor ffmpeg genisoimage growisofs handbrake-cli lsdvd mpv \
     nodejs openssl python3 python3-pip python3-serial python3-mutagen \
     python3-requests python3-pyudev python3-libdiscid python3-musicbrainzngs \
-    libdiscid0 python3-venv wodim
+    python3-numpy pulseaudio-utils libdiscid0 python3-venv wodim
 else
   printf 'Unsupported Linux package manager. Install the DiscStation dependencies manually.\n' >&2
   exit 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "discstation",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "description": "DiscStation optical-media appliance host — one cross-OS installer",
   "bin": {
     "discstation-setup": "scripts/setup.mjs",

package/requirements-optional.txt

@@ -12,3 +12,11 @@ pyudev>=0.24 ; sys_platform == "linux"
 python-libdiscid>=2.0 ; sys_platform == "linux"
 musicbrainzngs>=0.7.1
 tmdbsimple>=2.9
+
+# OLED spectrum visualizer during playback. Linux needs `parec`/`pactl`
+# (pulseaudio-utils apt package) - prefer python3-numpy via apt there, pip
+# installs are blocked on a system Python. macOS needs the BlackHole
+# loopback driver (brew install blackhole-2ch, see docs/PLATFORM_SUPPORT.md
+# for the one-time Multi-Output Device setup); numpy installs fine via pip
+# there since install-macos.sh's venv isn't externally-managed.
+numpy>=1.24 ; sys_platform == "linux" or sys_platform == "darwin"

package/src/discstation.py

@@ -621,6 +621,11 @@ try:
 except Exception:
     discstation_meta = None
 
+try:
+    import numpy as _np  # OLED spectrum visualizer during playback (optional)
+except Exception:
+    _np = None
+
 
 def _env_num(name, default, cast):
     try:
@@ -3299,6 +3304,150 @@ def _iter_proc_lines(proc, ser):
     reader.join(timeout=1)
 
 
+# --- OLED spectrum visualizer -----------------------------------------------
+# Taps the real audio the host is playing - PulseAudio's monitor source on
+# Linux, a BlackHole loopback device on macOS (see docs/PLATFORM_SUPPORT.md
+# for the one-time setup) - not a simulation, and streams it to the remote as
+# "VU:<16 comma-separated 0-63 levels>" at ~15fps. Needs numpy; anywhere else
+# (or without the capture source set up) this quietly no-ops and the remote
+# just shows its normal PLAY text screen.
+VU_BARS = 16   # must match the firmware's VU_BARS
+VU_RATE_HZ = 15
+VU_SAMPLE_RATE = 22050
+VU_DB_FLOOR = -40      # dB below the adaptive reference that maps to a flat bar
+VU_REF_DECAY = 0.995   # per-frame relaxation of the reference level (~a few sec to settle down)
+VU_PEAK_DECAY = 4      # bar units/frame a peak falls by when nothing louder follows
+
+
+def _pulse_default_monitor():
+    try:
+        sink = subprocess.run(["pactl", "get-default-sink"], capture_output=True,
+                              text=True, timeout=2).stdout.strip()
+    except Exception:
+        return None
+    return f"{sink}.monitor" if sink else None
+
+
+def _darwin_blackhole_input():
+    """Index of the 'BlackHole' avfoundation audio device, or None if it's not
+    installed. macOS has no built-in loopback source - this requires the user
+    to `brew install blackhole-2ch` and set a Multi-Output Device (BlackHole +
+    real speakers) as the system's default output, so audio is both audible
+    and tapped (see docs/PLATFORM_SUPPORT.md)."""
+    try:
+        # Device list is on stderr; ffmpeg exits non-zero here, that's normal.
+        out = subprocess.run(["ffmpeg", "-f", "avfoundation", "-list_devices", "true", "-i", ""],
+                              capture_output=True, text=True, timeout=5).stderr
+    except Exception:
+        return None
+    in_audio = False
+    for line in out.splitlines():
+        if "AVFoundation audio devices" in line:
+            in_audio = True
+            continue
+        if in_audio:
+            m = re.search(r"\[(\d+)\]\s+(.*)", line)
+            if m and "blackhole" in m.group(2).lower():
+                return m.group(1)
+    return None
+
+
+def _vu_capture_cmd():
+    """subprocess argv that streams raw s16le mono PCM at VU_SAMPLE_RATE on
+    stdout for whatever's currently playing, or None if this OS/setup can't
+    do it. One capture source per platform; the FFT/scaling pipeline below is
+    the same regardless of where the bytes came from."""
+    system = discstation_host.system_name()
+    if system == "linux":
+        monitor = _pulse_default_monitor()
+        if not monitor:
+            return None
+        # --latency-msec=50: PulseAudio's default capture buffer is several
+        # hundred ms to seconds (tuned for robust recording, not streaming) -
+        # without this, parec hands us data in ~1.5-2s bursts instead of a
+        # steady trickle, which starves the visualizer for longer than the
+        # firmware's fallback timeout and flickers back to the text screen.
+        return ["parec", "--format=s16le", f"--rate={VU_SAMPLE_RATE}", "--channels=1",
+                "--latency-msec=50", "-d", monitor]
+    if system == "darwin":
+        idx = _darwin_blackhole_input()
+        if idx is None:
+            return None
+        return ["ffmpeg", "-f", "avfoundation", "-i", f":{idx}",
+                "-ac", "1", "-ar", str(VU_SAMPLE_RATE), "-f", "s16le",
+                "-loglevel", "error", "-"]
+    return None
+
+
+def _vu_loop(ser, stop_event, pause_event):
+    cmd = _vu_capture_cmd()
+    if not cmd:
+        return
+    chunk_samples = max(256, VU_SAMPLE_RATE // VU_RATE_HZ)
+    chunk_bytes = chunk_samples * 2  # s16le, mono
+    try:
+        proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL)
+    except OSError:
+        return
+    try:
+        window = _np.hanning(chunk_samples)
+        freqs = _np.fft.rfftfreq(chunk_samples, d=1.0 / VU_SAMPLE_RATE)
+        # Log-spaced band edges so bass doesn't dominate a single FFT bin and
+        # treble isn't crammed into the last one - each bar gets a roughly
+        # equal-feeling slice of the spectrum instead of a linear split.
+        edges = _np.searchsorted(freqs, _np.geomspace(40, VU_SAMPLE_RATE / 2, VU_BARS + 1))
+        ref_level = 1e-6   # adaptive "how loud is this track" reference (see VU_REF_DECAY)
+        shown = [0.0] * VU_BARS   # last drawn height per bar, for the peak-decay fall-off
+        while not stop_event.is_set():
+            raw = proc.stdout.read(chunk_bytes)
+            if len(raw) < chunk_bytes:
+                if proc.poll() is not None:
+                    break
+                continue
+            if pause_event.is_set():
+                continue
+            samples = _np.frombuffer(raw, dtype=_np.int16).astype(_np.float32) / 32768.0
+            spectrum = _np.abs(_np.fft.rfft(samples * window))
+            mags = []
+            for i in range(VU_BARS):
+                lo, hi = edges[i], max(edges[i + 1], edges[i] + 1)
+                band = spectrum[lo:hi]
+                mags.append(float(band.max()) if band.size else 0.0)
+            # A fixed linear gain can't win: whatever multiplier shows motion at
+            # quiet volume clips solid at 63 the moment the mix gets loud/dense.
+            # Track a slowly-adapting reference level instead and scale in dB
+            # relative to it, so "loud" always means "near this track's own
+            # ceiling" rather than one guessed constant for every track/volume.
+            ref_level = max(max(mags, default=0.0), ref_level * VU_REF_DECAY, 1e-6)
+            levels = []
+            for i, mag in enumerate(mags):
+                db = 20 * float(_np.log10(mag / ref_level + 1e-9))
+                target = max(0.0, min(63.0, (db - VU_DB_FLOOR) * 63.0 / -VU_DB_FLOOR))
+                # Peak-with-decay: jump straight up to a new peak, fall a few
+                # units/frame otherwise - the classic VU-meter look, and it's
+                # what keeps a held loud note visibly settling instead of
+                # looking stuck once it's louder than the decaying reference.
+                shown[i] = target if target > shown[i] else max(0.0, shown[i] - VU_PEAK_DECAY)
+                levels.append(int(shown[i]))
+            send(ser, "VU:" + ",".join(str(v) for v in levels))
+    finally:
+        discstation_burn.stop_process(proc)
+
+
+def start_vu_visualizer(ser):
+    """Best-effort: returns (stop_event, pause_event), or (None, None) if the
+    visualizer can't run here (no numpy, no capture source, or a web-only
+    link). Linux (PulseAudio) and macOS (BlackHole, see
+    docs/PLATFORM_SUPPORT.md) only - _vu_capture_cmd() returns None anywhere
+    else, or if the OS-specific capture device isn't set up."""
+    if _np is None or isinstance(ser, VirtualSerial) or discstation_host.system_name() not in ("linux", "darwin"):
+        return None, None
+    stop_event = threading.Event()
+    pause_event = threading.Event()
+    threading.Thread(target=_vu_loop, args=(ser, stop_event, pause_event), daemon=True).start()
+    return stop_event, pause_event
+
+
 def _run_mpv(ser, cmd, label, kind=None, track_titles=None, track_starts=None):
     try:
         os.unlink(MPV_SOCKET)
@@ -3324,6 +3473,7 @@ def _run_mpv(ser, cmd, label, kind=None, track_titles=None, track_starts=None):
     # socket, so none of that output is wanted.
     proc = subprocess.Popen(run_as_desktop_user(cmd), env=env,
                             stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    vu_stop = None
 
     try:
         if not wait_for_socket(MPV_SOCKET, proc):
@@ -3343,6 +3493,7 @@ def _run_mpv(ser, cmd, label, kind=None, track_titles=None, track_starts=None):
         send(ser, "PLAY_MODE:AUDIO_CD" if kind == "audio_cd" else "PLAY_MODE:DEFAULT")
         send(ser, "PLAY:PLAYING")
         print(f"{label}. Short press toggles pause; long press stops.")
+        vu_stop, vu_pause = start_vu_visualizer(ser)
 
         last_ping = time.time()
         while proc.poll() is None:
@@ -3375,6 +3526,8 @@ def _run_mpv(ser, cmd, label, kind=None, track_titles=None, track_starts=None):
                     paused = not paused
                     mpv_command(["set_property", "pause", paused])
                     mpv_command(["set_property", "speed", 1.0])
+                    if vu_pause:
+                        vu_pause.set() if paused else vu_pause.clear()
                     send(ser, "PLAY_STATUS:PAUSED" if paused else "PLAY_STATUS:PLAYING")
 
                 elif line in ("PLAY_STOP", "EJECT"):
@@ -3447,6 +3600,8 @@ def _run_mpv(ser, cmd, label, kind=None, track_titles=None, track_starts=None):
 
             time.sleep(0.05)
     finally:
+        if vu_stop:
+            vu_stop.set()
         if proc.poll() is None:
             discstation_burn.stop_process(proc)
         try: