spl-dashboard 0.5.0__py3-none-any.whl

spl_dashboard/__init__.py

@@ -0,0 +1,3 @@
+"""SPL Dashboard telemetry service."""
+
+__version__ = "0.4.4"

spl_dashboard/addresses.py

@@ -0,0 +1,56 @@
+"""Discover the machine's LAN addresses so operators can reach the dashboard.
+
+Browsers on other devices (an iPad, a phone, a laptop) connect to one of these
+addresses over the local network. Nothing is installed on those devices; they
+only view the dashboard.
+"""
+
+import socket
+
+IPAD_NOTE = (
+    "Other devices (iPad, phone, laptop) only view the dashboard over your "
+    "network; nothing is installed on them."
+)
+
+
+def local_ipv4_addresses() -> list[str]:
+    """Return non-loopback, non-link-local IPv4 addresses for this machine."""
+    found: set[str] = set()
+    # Primary outbound interface. connect() on a UDP socket sends no packets;
+    # it only selects the route the OS would use, revealing the local address.
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as probe:
+            probe.connect(("192.0.2.1", 80))  # TEST-NET-1: reserved, never routed.
+            found.add(str(probe.getsockname()[0]))
+    except OSError:
+        pass
+    # Every address the hostname resolves to (covers additional interfaces).
+    try:
+        for info in socket.getaddrinfo(socket.gethostname(), None, socket.AF_INET):
+            found.add(str(info[4][0]))
+    except OSError:
+        pass
+    return sorted(
+        address
+        for address in found
+        if not address.startswith("127.") and not address.startswith("169.254.")
+    )
+
+
+def address_report(port: int) -> dict:
+    """Build the local and LAN URLs for the admin console and the /display strip."""
+    lan = [
+        {
+            "host": address,
+            "admin": f"http://{address}:{port}/",
+            "display": f"http://{address}:{port}/display",
+        }
+        for address in local_ipv4_addresses()
+    ]
+    return {
+        "port": port,
+        "localAdmin": f"http://localhost:{port}/",
+        "localDisplay": f"http://localhost:{port}/display",
+        "lan": lan,
+        "note": IPAD_NOTE,
+    }

spl_dashboard/calibration.py

@@ -0,0 +1,131 @@
+"""Calibration file parsing; vendor sensitivity is retained, never guessed."""
+
+import hashlib
+import re
+from dataclasses import dataclass
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy import signal
+
+
+@dataclass(frozen=True)
+class Calibration:
+    digest: str
+    serial: str | None
+    sensitivity: float | None
+    frequencies: NDArray[np.float64]
+    response: NDArray[np.float64]
+    analog_gain: float | None = None
+
+    def fir(self, sample_rate: int) -> NDArray[np.float64]:
+        # Vendor data is measured response, so correction has the opposite sign.
+        grid = np.linspace(0, sample_rate / 2, 8193)
+        response = np.interp(
+            np.log10(np.maximum(grid, 1)), np.log10(self.frequencies), self.response
+        )
+        return signal.firwin2(2049, grid, 10 ** (-response / 20), fs=sample_rate)
+
+
+def parse_calibration(text: str) -> Calibration | None:
+    if not text.strip():
+        return None
+    if len(text) > 200000:
+        raise ValueError("Calibration file exceeds 200 kB")
+    sensitivity = re.search(r"Sens\s+Factor\s*=\s*([-+\d.eE]+)\s*dB", text, re.I)
+    if re.search(r"Sens\s+Factor", text, re.I) and not sensitivity:
+        raise ValueError("Invalid sensitivity factor header")
+    analog_gain = re.search(r"AGain\s*=\s*([-+\d.eE]+)\s*dB", text, re.I)
+    if re.search(r"AGain", text, re.I) and not analog_gain:
+        raise ValueError("Invalid analog gain header")
+    file_gain = float(analog_gain[1]) if analog_gain else None
+    if file_gain is not None and (not np.isfinite(file_gain) or not 0 <= file_gain <= 60):
+        raise ValueError("Invalid analog gain")
+    serial = re.search(r"SERNO\s*:\s*([\w-]+)", text, re.I)
+    points: list[tuple[float, float]] = []
+    for number, line in enumerate(text.splitlines(), 1):
+        line = line.strip()
+        if not line or line[0] not in "+-.0123456789":
+            continue
+        columns = line.replace(",", " ").split()
+        try:
+            frequency, gain = float(columns[0]), float(columns[1])
+        except (ValueError, IndexError) as exc:
+            raise ValueError(f"Invalid calibration data on line {number}") from exc
+        if not np.isfinite([frequency, gain]).all() or not 0 < frequency <= 96000:
+            raise ValueError(f"Invalid frequency or gain on line {number}")
+        if abs(gain) > 30:
+            raise ValueError("Calibration response exceeds ±30 dB; inspect the file")
+        if points and frequency <= points[-1][0]:
+            raise ValueError("Calibration frequencies must be strictly increasing")
+        points.append((frequency, gain))
+    if len(points) < 2:
+        raise ValueError("Calibration requires at least two frequency/response pairs")
+    sens = float(sensitivity[1]) if sensitivity else None
+    if sens is not None and (not np.isfinite(sens) or not -100 <= sens <= 40):
+        raise ValueError("Invalid sensitivity factor")
+    values = np.asarray(points, dtype=np.float64)
+    return Calibration(
+        hashlib.sha256(text.encode()).hexdigest(),
+        serial[1] if serial else None,
+        sens,
+        values[:, 0],
+        values[:, 1],
+        file_gain,
+    )
+
+
+@dataclass(frozen=True)
+class InputCalibration:
+    """Evidence from the selected device, not from a browser-supplied offset."""
+
+    supported_umik: bool = False
+    direct_pcm: bool = False
+    analog_gain_db: float | None = None
+    digital_gain_db: float | None = None
+    usb_serial: str | None = None
+    binding: str = "name"
+    reason: str = "Waiting for the selected microphone"
+
+
+def serial_digits(serial: str | None) -> str:
+    return re.sub(r"[^0-9]", "", serial or "")
+
+
+def usable_serial(serial: str | None) -> bool:
+    digits = serial_digits(serial)
+    return bool(digits and set(digits) != {"0"})
+
+
+def umik_file_offset(
+    calibration: Calibration | None, device: InputCalibration, confirmed_serial: str = ""
+) -> tuple[float | None, str]:
+    """UMIK-1 direct PCM convention; see docs/umik-sensitivity.md.
+
+    Full-scale sample magnitude is 1; full-scale sine RMS is -3.0103 dBFS.
+    The internal analog gain is already included in the supplied sensitivity.
+    Only a difference from the file's gain is compensated, never the gain twice.
+    """
+    if calibration is None or calibration.sensitivity is None:
+        return None, "Load the microphone's calibration file with its Sens Factor"
+    if not device.supported_umik or not device.direct_pcm:
+        return None, device.reason
+    if device.analog_gain_db is None or device.digital_gain_db is None:
+        return None, "Input gain could not be verified; use an explicit acoustic reference"
+    serial = serial_digits(calibration.serial)
+    if not serial:
+        return None, "The calibration file has no microphone serial"
+    if usable_serial(device.usb_serial):
+        if serial_digits(device.usb_serial) != serial:
+            return None, "Calibration file serial does not match the connected microphone"
+    elif serial_digits(confirmed_serial) != serial:
+        return None, "Confirm that the file serial matches the label on this microphone"
+    reference_gain = calibration.analog_gain if calibration.analog_gain is not None else 18.0
+    offset = (
+        124.0
+        - calibration.sensitivity
+        + reference_gain
+        - device.analog_gain_db
+        - device.digital_gain_db
+    )
+    return offset, "Calibrated to the supplied UMIK-1 sensitivity file"

spl_dashboard/capture.py

@@ -0,0 +1,269 @@
+"""Bounded local capture. Audio never leaves this module's process."""
+
+import re
+import subprocess
+import threading
+import time
+import wave
+from dataclasses import dataclass
+from pathlib import Path
+from queue import Empty, Full, Queue
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+from .calibration import InputCalibration, usable_serial
+from .dsp import SAMPLE_RATE
+
+CAPTURE_BLOCK = 4800
+
+_portaudio_lock = threading.RLock()
+_active_streams = 0
+
+
+@dataclass
+class AudioBlock:
+    samples: NDArray[np.float64]
+    captured: float
+    sequence: int
+    overflow: bool = False
+
+
+def devices() -> list[dict[str, Any]]:
+    """Refresh PortAudio only when no input stream is open; never interrupt capture."""
+    import sounddevice as sd
+
+    with _portaudio_lock:
+        if not _active_streams:
+            sd._terminate()
+            sd._initialize()
+        hosts = sd.query_hostapis()
+        result = []
+        for index, device in enumerate(sd.query_devices()):
+            if device["max_input_channels"] < 1:
+                continue
+            name = device["name"]
+            host = hosts[device["hostapi"]]["name"]
+            stable_name = re.sub(r"\s*\(hw:\d+,\d+\)", "", name)
+            identity = f"portaudio:{host}:{stable_name}"
+            binding, serial, vendor, product, card_index = "name", None, None, None, None
+            match = re.search(r"hw:(\d+),(\d+)", name)
+            if host == "ALSA" and match:
+                card_index = int(match[1])
+                card = Path(f"/sys/class/sound/card{card_index}/device").resolve()
+                for parent in [card, *list(card.parents)[:4]]:
+                    if (parent / "idVendor").is_file() and (parent / "idProduct").is_file():
+                        vendor = (parent / "idVendor").read_text().strip()
+                        product = (parent / "idProduct").read_text().strip()
+                        serial_path = parent / "serial"
+                        serial = serial_path.read_text().strip() if serial_path.is_file() else None
+                        if usable_serial(serial):
+                            identity = f"usb:{vendor}:{product}:{serial}:pcm{match[2]}"
+                            binding = "serial"
+                        else:
+                            # A placeholder serial identifies a model, not a physical microphone.
+                            controller = next(
+                                (
+                                    p.name
+                                    for p in parent.parents
+                                    if re.fullmatch(
+                                        r"[0-9a-f]{4}:[0-9a-f]{2}:[0-9a-f]{2}\.[0-7]", p.name
+                                    )
+                                ),
+                                "unknown",
+                            )
+                            port = parent.name.partition("-")[2]
+                            identity = (
+                                f"usb-port:{vendor}:{product}:{controller}/{port}:pcm{match[2]}"
+                            )
+                            binding = "usb-port"
+                        break
+            result.append(
+                {
+                    "id": identity,
+                    "index": index,
+                    "name": name,
+                    "channels": device["max_input_channels"],
+                    "defaultSampleRate": device["default_samplerate"],
+                    "serialBound": binding == "serial",
+                    "binding": binding,
+                    "usbSerial": serial,
+                    "usbVendor": vendor,
+                    "usbProduct": product,
+                    "alsaCard": card_index,
+                }
+            )
+        return result
+
+
+def inspect_calibration_input(selected: dict[str, Any]) -> InputCalibration:
+    """Recognize the legacy UMIK-1 direct ALSA path and verify its mixer controls."""
+    common = {"usb_serial": selected.get("usbSerial"), "binding": selected.get("binding", "name")}
+    gain_match = re.search(r"Umik-1\s+Gain:\s*(\d+)dB", selected["name"], re.I)
+    if (selected.get("usbVendor"), selected.get("usbProduct")) != (
+        "2752",
+        "0007",
+    ) or not gain_match:
+        return InputCalibration(
+            **common, reason="Automatic calibration needs a supported direct UMIK-1 input"
+        )
+    gain = float(gain_match[1])
+    if gain not in (0, 6, 12, 18, 24, 30, 36) or selected.get("alsaCard") is None:
+        return InputCalibration(**common, reason="UMIK analog gain could not be identified")
+    try:
+        mixer = subprocess.run(
+            ["amixer", "-c", str(selected["alsaCard"]), "contents"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=True,
+        ).stdout
+    except (OSError, subprocess.SubprocessError):
+        return InputCalibration(**common, reason="Cannot inspect ALSA gain; install alsa-utils")
+    # This device generation exposes only a mute switch. Reject volume/unknown
+    # controls rather than guessing their gain mapping or silently applying it.
+    sections = [
+        part
+        for part in mixer.split("numid=")[1:]
+        if not ("iface=PCM" in part and "name='Capture Channel Map'" in part)
+    ]
+    if not sections or any(
+        "name='Mic Capture Switch'" not in part or "type=BOOLEAN" not in part for part in sections
+    ):
+        return InputCalibration(
+            **common, reason="Unexpected input gain controls; use an acoustic reference"
+        )
+    if any(re.search(r": values=(?:off|0)(?:\s|,|$)", part) for part in sections):
+        return InputCalibration(**common, reason="MIC MUTED — enable the ALSA capture switch")
+    return InputCalibration(
+        **common,
+        supported_umik=True,
+        direct_pcm=True,
+        analog_gain_db=gain,
+        digital_gain_db=0.0,
+        reason="Direct ALSA PCM; no digital gain control",
+    )
+
+
+class DeviceInput:
+    def __init__(self, identity: str, channel: int):
+        import sounddevice as sd
+
+        global _active_streams
+        self.closed = False
+        with _portaudio_lock:
+            matches = [d for d in devices() if d["id"] == identity]
+            if len(matches) != 1:
+                raise ValueError("Selected device is missing or ambiguous; select a unique input")
+            selected = matches[0]
+            if channel >= selected["channels"]:
+                raise ValueError("Selected channel does not exist")
+            self.calibration_info = inspect_calibration_input(selected)
+            self.queue: Queue[AudioBlock] = Queue(maxsize=8)
+            self.dropped = 0
+            self.sequence = 0
+            self.stream = sd.InputStream(
+                device=selected["index"],
+                samplerate=SAMPLE_RATE,
+                blocksize=CAPTURE_BLOCK,
+                channels=channel + 1,
+                dtype="float32",
+                callback=self.callback(channel),
+            )
+            try:
+                self.stream.start()
+            except Exception:
+                self.stream.close()
+                raise
+            _active_streams += 1
+
+    def callback(self, channel: int) -> Any:
+        def receive(data: Any, frames: int, timing: Any, status: Any) -> None:
+            self.sequence += 1
+            block = AudioBlock(
+                np.asarray(data[:, channel], dtype=np.float64).copy(),
+                time.monotonic(),
+                self.sequence,
+                bool(status),
+            )
+            try:
+                self.queue.put_nowait(block)
+            except Full:
+                self.dropped += 1
+
+        return receive
+
+    def read(self) -> AudioBlock | None:
+        try:
+            return self.queue.get(timeout=0.25)
+        except Empty:
+            return None
+
+    def close(self) -> None:
+        global _active_streams
+        with _portaudio_lock:
+            if self.closed:
+                return
+            try:
+                self.stream.stop()
+            finally:
+                try:
+                    self.stream.close()
+                finally:
+                    _active_streams -= 1
+                    self.closed = True
+
+
+class WavInput:
+    def __init__(self, path: Path, channel: int):
+        self.file = wave.open(str(path), "rb")
+        self.channel = channel
+        self.sequence = 0
+        if (
+            self.file.getframerate() != SAMPLE_RATE
+            or self.file.getsampwidth() not in (2, 3, 4)
+            or self.file.getcomptype() != "NONE"
+            or channel >= self.file.getnchannels()
+        ):
+            self.file.close()
+            raise ValueError("WAV must be 48 kHz PCM 16/24/32-bit with the selected channel")
+
+    def read(self) -> AudioBlock | None:
+        raw = self.file.readframes(CAPTURE_BLOCK)
+        width = self.file.getsampwidth()
+        channels = self.file.getnchannels()
+        if len(raw) != CAPTURE_BLOCK * width * channels:
+            return None  # No zero padding and no silent loop across a discontinuity.
+        if width == 3:
+            triples = np.frombuffer(raw, dtype=np.uint8).reshape(-1, 3).astype(np.int32)
+            integer = triples[:, 0] | (triples[:, 1] << 8) | (triples[:, 2] << 16)
+            integer = (integer ^ 0x800000) - 0x800000
+            samples = integer.astype(np.float64) / 8388608
+        else:
+            samples = np.frombuffer(raw, dtype=f"<i{width}").astype(np.float64)
+            samples /= 2 ** (width * 8 - 1)
+        self.sequence += 1
+        return AudioBlock(
+            samples.reshape(-1, channels)[:, self.channel], time.monotonic(), self.sequence
+        )
+
+    def close(self) -> None:
+        self.file.close()
+
+
+class DemoInput:
+    def __init__(self) -> None:
+        self.sequence = 0
+        self.rng = np.random.default_rng(42)
+
+    def read(self) -> AudioBlock:
+        t = (np.arange(CAPTURE_BLOCK) + self.sequence * CAPTURE_BLOCK) / SAMPLE_RATE
+        amplitude = 0.025 * 10 ** (3 * np.sin(t / 8) / 20)
+        samples = amplitude * (np.sin(2 * np.pi * 1000 * t) + 0.6 * np.sin(2 * np.pi * 80 * t))
+        samples += self.rng.normal(0, 0.002, CAPTURE_BLOCK)
+        self.sequence += 1
+        return AudioBlock(samples, time.monotonic(), self.sequence)
+
+    def close(self) -> None:
+        pass

spl_dashboard/cli.py

@@ -0,0 +1,108 @@
+"""Console entry point: ``spl-dashboard``.
+
+Starts the LAN service with a single Uvicorn worker and prints the addresses to
+open on this machine and on other devices on the same network.
+"""
+
+import argparse
+import os
+from pathlib import Path
+
+from platformdirs import user_data_dir
+
+from .addresses import IPAD_NOTE, local_ipv4_addresses
+
+DEFAULT_PORT = 8000
+# A LAN monitor is meant to be reachable across the local network by default.
+DEFAULT_HOST = "0.0.0.0"
+
+
+def default_data_dir() -> Path:
+    """Per-user data directory (platform-appropriate), matching the service default."""
+    return Path(user_data_dir("spl-dashboard", appauthor=False))
+
+
+def _parse_args(argv: list[str] | None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="spl-dashboard",
+        description=(
+            "Run the SPL Dashboard sound monitor on this computer and serve it to "
+            "browsers on your local network."
+        ),
+    )
+    parser.add_argument(
+        "--host",
+        default=DEFAULT_HOST,
+        help=f"Address to bind (default {DEFAULT_HOST}, i.e. all network interfaces).",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=DEFAULT_PORT,
+        help=f"Port to serve on (default {DEFAULT_PORT}).",
+    )
+    parser.add_argument(
+        "--data-dir",
+        default=None,
+        help=(
+            "Where events, configuration and calibration are stored "
+            f"(default: {default_data_dir()})."
+        ),
+    )
+    parser.add_argument("--version", action="store_true", help="Print the version and exit.")
+    return parser.parse_args(argv)
+
+
+def _print_banner(host: str, port: int, data_dir: Path) -> None:
+    lines = ["", "  SPL Dashboard is starting.", ""]
+    lines.append("  On this computer:")
+    lines.append(f"    Admin console:  http://localhost:{port}/")
+    lines.append(f"    Strip display:  http://localhost:{port}/display")
+    addresses = local_ipv4_addresses()
+    if host not in ("0.0.0.0", "::") and host not in ("localhost", "127.0.0.1"):
+        # An explicit non-wildcard bind is the only reachable LAN address.
+        addresses = [host]
+    if addresses:
+        lines.append("")
+        lines.append("  From an iPad, phone or laptop on the same Wi-Fi (open /display):")
+        for address in addresses:
+            lines.append(f"    http://{address}:{port}/display")
+    else:
+        lines.append("")
+        lines.append("  No LAN address detected yet; connect this computer to your network.")
+    lines.append("")
+    lines.append(f"  {IPAD_NOTE}")
+    lines.append(f"  Data directory: {data_dir}")
+    lines.append("  Press Ctrl+C to stop.")
+    lines.append("")
+    print("\n".join(lines), flush=True)
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = _parse_args(argv)
+    if args.version:
+        from importlib.metadata import version
+
+        print(version("spl-dashboard"))
+        return
+
+    data_dir = Path(args.data_dir).expanduser() if args.data_dir else default_data_dir()
+    data_dir.mkdir(parents=True, exist_ok=True)
+    # create_app reads SPL_DATA_DIR when Uvicorn imports the app in this process.
+    os.environ["SPL_DATA_DIR"] = str(data_dir)
+
+    _print_banner(args.host, args.port, data_dir)
+
+    import uvicorn
+
+    uvicorn.run(
+        "spl_dashboard.main:app",
+        host=args.host,
+        port=args.port,
+        workers=1,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()