discstation 0.1.29 → 0.1.31

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.29",
+  "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:
@@ -4558,7 +4713,7 @@ def main():
                 port = discstation_host.serial_port()
                 if port:
                     print(f"Using ESP32 serial port: {port}")
-                    ser = serial.Serial(port, discstation_burn.BAUD, timeout=1, write_timeout=1)
+                    ser = serial.Serial(port, discstation_burn.BAUD, timeout=1, write_timeout=2)
                     if discstation_host.system_name() == "linux":
                         ser.setDTR(False)
                         time.sleep(0.1)

package/src/discstation_burn.py

@@ -538,9 +538,23 @@ def send(ser, msg):
             pass
     if not ser:
         return False
+    payload = (msg + '\n').encode()
     try:
         with SERIAL_WRITE_LOCK:
-            ser.write((msg + '\n').encode())
+            # pyserial's Serial.write() on Linux waits on select() for the fd
+            # to report writable before it calls the real write() - some
+            # USB-CDC-ACM devices (e.g. the ESP32-C6's native USB peripheral,
+            # unlike a CP2102/CH340 bridge chip) never signal that through
+            # select() even though a plain write succeeds instantly, so
+            # ser.write() times out forever on those. Write through the raw
+            # fd directly for a real serial port; other transports
+            # (TcpSerial/VirtualSerial) keep their own write().
+            fileno = getattr(ser, "fileno", None)
+            if isinstance(ser, serial.Serial) and fileno:
+                os.write(fileno(), payload)
+            else:
+                ser.write(payload)
+        return True
     except (serial.SerialException, OSError) as e:
         if not _serial_write_failed:
             print(f"serial send error ('{msg[:30]}'): {e}")
@@ -549,7 +563,6 @@ def send(ser, msg):
     except Exception as e:
         print(f"serial send error ('{msg[:30]}'): {e}")
         return False
-    return True
 
 def safe_send(ser, msg):
     if not ser: