opencode-rgbify-plugin 0.1.3

package/bridge/ble_bridge.py

@@ -0,0 +1,779 @@
+#!/usr/bin/env python3
+"""BLE bridge: stream newline-delimited text from stdin to the RGBify projector.
+
+Interrupt semantics end to end: every line is a new message that supersedes
+anything still in flight. The host auralizer and the BLE write path each keep
+only the LATEST line — a newer line interrupts (replaces) the previous one at
+the next note/chunk boundary, so the last message is the only message. Nothing
+is queued, delayed, or replayed.
+
+Discovers the projector at connect time (by advertised service UUID, then name),
+chunks each line into codepoint-safe pieces that fit within the projector's TEXT_BRIDGE
+and writes them to the TEXT_BRIDGE characteristic. Reconnects forever
+with backoff so the plugin stays a silent no-op while the projector is out of
+range or powered off.
+
+Every line is ALSO auralized on the host (miniaudio) at the firmware's native
+cadence (one ~33ms note per char, log-scale freq table identical to the
+firmware, whitespace = rest), so
+sound never stops while the projector is away. The host auralizer runs always
+and independently of the BLE connection; when the projector is reachable both
+play the same line (best-effort sync). Lines missed while the projector is down
+are dropped for the projector (no replay on reconnect) so the two stay in sync.
+
+miniaudio bundles its own native audio lib, so the host auralizer needs no
+system deps (no PortAudio) and works cross-platform (WASAPI/CoreAudio/Pulse/ALSA).
+
+Set RGBIFY_PROJECTOR_ADDR to skip discovery and use a fixed address.
+Set RGBIFY_HOST_AURALIZER=0 to disable the host auralizer (projector unaffected).
+
+Host volume is mirrored from the projector's VOLUME characteristic whenever the
+projector is connected and persisted to the state file below so it survives
+restarts. While the projector is down you can still adjust the host volume by
+editing that file (or set RGBIFY_VOLUME as an initial default).
+
+stdout protocol (one line per event, for debugging):
+  ok <addr>          connected / a line delivered
+  err <message>      delivery failure (will retry)
+"""
+import os
+import sys
+import math
+import array
+import signal
+import threading
+import asyncio
+import time
+
+from bleak import BleakClient, BleakScanner
+
+# Optional debug trace, shared with the plugin's log (same env var) so both
+# sides land in ONE unified timeline. Appends are line-sized and atomic.
+DEBUG_LOG = os.environ.get("RGBIFY_DEBUG_LOG", "").strip()
+
+
+def dbg(line: str) -> None:
+    if not DEBUG_LOG:
+        return
+    try:
+        with open(DEBUG_LOG, "a") as f:
+            f.write(f"{time.time() * 1000:.0f} bridge {line}\n")
+    except OSError:
+        pass
+
+# Host auralizer: miniaudio bundles its own native lib and is cross-platform
+# (WASAPI/CoreAudio/PulseAudio/ALSA), so no PortAudio/system deps are needed.
+# Optional — the projector path works without it.
+try:
+    import miniaudio
+    MINIAUDIO_OK = True
+except (ImportError, OSError):
+    miniaudio = None
+    MINIAUDIO_OK = False
+
+SERVICE_UUID = "8bc01404-0000-4bf4-95d1-ce27a0477183"
+TEXT_BRIDGE_UUID = "8bc01404-0009-4bf4-95d1-ce27a0477183"
+VOLUME_UUID = "8bc01404-0004-4bf4-95d1-ce27a0477183"
+DEVICE_NAME = "RGBify Projector"
+RECONNECT_DELAY = 2.0
+SCAN_TIMEOUT = 5.0
+# The projector advertises as soon as it powers up, but needs a moment to
+# finish booting before it can accept a BLE connection. On a first connect
+# after power-up a failed attempt just retries (RECONNECT_DELAY), so keep this
+# small instead of adding a fixed multi-second delay on every reconnect.
+CONNECT_DELAY = 1.0
+
+# Max time a single write ACK may take. The firmware holds the ACK until a
+# whole message plays (~8 chars * 33ms = ~264ms), so this must be comfortably
+# above that but still short enough that a wedged link is torn down quickly.
+WRITE_TIMEOUT = 3.0
+
+# Fallback VOLUME poll interval (seconds). Notifications from the device are
+# primary, but the poll guarantees the host mirrors webapp volume changes even
+# if a notification is lost.
+VOL_POLL_SEC = 2.0
+
+# Host auralizer: mirrors the firmware Auralizer (one note per frame @ 30fps,
+# freq = -1021 + c*37 Hz for non-space chars, whitespace = rest, volume 0-10).
+SAMPLE_RATE = 44100
+NOTE_SEC = 1.0 / 30
+# Adaptive host pacing: the firmware's REAL per-char time is slower than its
+# nominal 30fps under load (measured ACKs of ~43ms/char vs 33ms nominal), so a
+# fixed 33ms host note runs out before the next ACK-gated dispatch — a small
+# periodic silence, only present while plugged in. The BLE loop measures
+# ack_ms/char after every write and EMA-smooths it into this variable;
+# host_auralize synthesizes at that pace so host buffers last exactly as long
+# as the ACK window. Clamped to sane bounds; falls back to nominal when cold.
+NOTE_SEC_MIN = 0.020
+NOTE_SEC_MAX = 0.080
+ACK_PACE_EMA = 0.3
+# Host note amplitude as a fraction of full-scale int16. The firmware drives a
+# piezo at resonance (loud); the host speaker at 0.05 was nearly inaudible, at
+# 0.4 it masked the piezo — 0.3 rebalances the mix.
+HOST_GAIN = 0.3
+HOST_AURALIZER = os.environ.get("RGBIFY_HOST_AURALIZER", "1").strip() != "0"
+HOST_VOLUME = int(os.environ.get("RGBIFY_VOLUME", "10").strip() or "10")
+# Persisted host volume: mirrored from the projector's VOLUME characteristic
+# when connected; editable at any time even when the projector is off. Lives in
+# the global opencode config dir (the user may not be inside a project), with
+# RGBIFY_STATE_DIR as an explicit override.
+STATE_DIR = os.environ.get(
+    "RGBIFY_STATE_DIR",
+    os.path.join(os.path.expanduser("~"), ".config", "opencode", "state"),
+)
+VOLUME_FILE = os.path.join(STATE_DIR, "host-volume")
+
+
+def load_volume() -> int:
+    try:
+        with open(VOLUME_FILE) as f:
+            return max(0, min(10, int(f.read().strip())))
+    except (OSError, ValueError):
+        return HOST_VOLUME
+
+
+def save_volume(value: int) -> None:
+    try:
+        os.makedirs(STATE_DIR, exist_ok=True)
+        with open(VOLUME_FILE, "w") as f:
+            f.write(str(max(0, min(10, value))))
+    except OSError:
+        pass
+
+
+# Mirror the firmware's log-scale auralizer lookup table exactly (firmware
+# rgbify-projector-esp32.ino `auralizer_freq[91]`, committed 691c899):
+# index = ord(c) - 32 for ASCII 32..122, mapping ' '=space..'z' -> 5000..100 Hz.
+AURALIZER_FREQ = [
+    5000, 4887, 4778, 4672, 4569, 4468, 4371, 4276,
+    4183, 4093, 4004, 3918, 3834, 3752, 3671, 3593,
+    3515, 3440, 3366, 3293, 3222, 3153, 3084, 3017,
+    2951, 2886, 2823, 2760, 2698, 2638, 2578, 2520,
+    2462, 2405, 2349, 2294, 2240, 2187, 2134, 2082,
+    2031, 1980, 1931, 1881, 1833, 1785, 1738, 1691,
+    1645, 1600, 1555, 1510, 1466, 1423, 1380, 1338,
+    1296, 1255, 1214, 1173, 1133, 1094, 1055, 1016,
+    978, 940, 902, 865, 828, 792, 756, 720,
+    684, 649, 615, 580, 546, 513, 479, 446,
+    413, 381, 348, 316, 285, 253, 222, 191,
+    161, 130, 100,
+]
+
+
+# TRUE PIEZO SIMULATION: the projector's sound chain is toneAC driving the
+# bare piezo disc with a SQUARE wave, and the disc's mechanical response has
+# a dominant resonance ring at ~1897 Hz (firmware RESONANT_FREQ), an upper
+# efficiency mode around 3-5 kHz (why the real device's high notes scream),
+# and poor LF radiation below ~1 kHz. Model:
+#   square wave @ note freq ──► 12 dB/oct HPF @ PIEZO_HPF_HZ
+#                           ──► peaking ring @ PIEZO_RING_HZ (Q, +dB)
+#                           ──► peaking HF mode @ PIEZO_HF_HZ (Q, +dB)
+# Constants are physics-derived starting points — tune by ear via prompts.
+PIEZO_RING_HZ = 1897.0
+PIEZO_RING_Q = 3.0
+PIEZO_RING_GAIN_DB = 10.0
+PIEZO_HPF_HZ = 800.0
+PIEZO_HF_HZ = 3800.0
+PIEZO_HF_Q = 1.2
+PIEZO_HF_GAIN_DB = 8.0
+
+_wave_cache = {}
+
+
+def _poly_blep(t: float, dt: float) -> float:
+    """PolyBLEP correction for a naive bandlimited-violating square edge at
+    phase t in [0,1) with increment dt per sample."""
+    y = 0.0
+    if t < dt:
+        tt = t / dt
+        y -= tt + tt - tt * tt - 1.0
+    elif t > 1.0 - dt:
+        tt = (t - 1.0) / dt
+        y += tt * tt + tt + tt + 1.0
+    return y
+
+
+def _square_wave(freq: float, note_sec: float, amp: int) -> "array.array":
+    """Naive square wave with polyBLEP-corrected edges, ±amp int16."""
+    n = int(SAMPLE_RATE * note_sec)
+    dt = freq / SAMPLE_RATE
+    out = array.array("h")
+    p = 0.0
+    for _ in range(n):
+        naive = 1.0 if p < 0.5 else -1.0
+        v = (naive - _poly_blep(p, dt)) * amp
+        if v > 32767:
+            v = 32767
+        elif v < -32768:
+            v = -32768
+        out.append(int(v))
+        p += dt
+        if p >= 1.0:
+            p -= 1.0
+    return out
+
+
+def _peaking_coeffs(f: float, q: float, gain_db: float):
+    A = 10 ** (gain_db / 40.0)
+    w0 = 2.0 * math.pi * f / SAMPLE_RATE
+    cw = math.cos(w0)
+    alpha = math.sin(w0) / (2.0 * q)
+    b0 = 1 + alpha * A
+    b1 = -2 * cw
+    b2 = 1 - alpha * A
+    a0 = 1 + alpha / A
+    a1 = -2 * cw
+    a2 = 1 - alpha / A
+    return (b0 / a0, b1 / a0, b2 / a0, a1 / a0, a2 / a0)
+
+
+def _highpass_coeffs(f: float, q: float = 0.707):
+    w0 = 2.0 * math.pi * f / SAMPLE_RATE
+    cw = math.cos(w0)
+    alpha = math.sin(w0) / (2.0 * q)
+    b0 = (1 + cw) / 2
+    b1 = -(1 + cw)
+    b2 = (1 + cw) / 2
+    a0 = 1 + alpha
+    a1 = -2 * cw
+    a2 = 1 - alpha
+    return (b0 / a0, b1 / a0, b2 / a0, a1 / a0, a2 / a0)
+
+
+def _biquad(buf, coeffs) -> list:
+    """Direct-form-I biquad over a numeric buffer. Returns FLOATS — no
+    clamping here; intermediate stages must not clip (the ring boost exceeds
+    int16 by design). Final stage converts + clamps."""
+    b0, b1, b2, a1, a2 = coeffs
+    x1 = x2 = y1 = y2 = 0.0
+    out = []
+    append = out.append
+    for x in buf:
+        y = b0 * x + b1 * x1 + b2 * x2 - a1 * y1 - a2 * y2
+        x2 = x1
+        x1 = x
+        y2 = y1
+        y1 = y
+        append(y)
+    return out
+
+
+_RING_COEFFS = _peaking_coeffs(PIEZO_RING_HZ, PIEZO_RING_Q, PIEZO_RING_GAIN_DB)
+_HF_COEFFS = _peaking_coeffs(PIEZO_HF_HZ, PIEZO_HF_Q, PIEZO_HF_GAIN_DB)
+_HPF_COEFFS = _highpass_coeffs(PIEZO_HPF_HZ)
+_calib_scale = None
+
+
+def _calibration_scale() -> float:
+    """Global level calibration: a square AT the ring frequency, through the
+    full piezo chain, defines the calibrated peak (HOST_GAIN × full scale).
+    All other notes keep their authentic relative levels around that anchor."""
+    global _calib_scale
+    if _calib_scale is None:
+        ref = _biquad(_biquad(_square_wave(PIEZO_RING_HZ, NOTE_SEC, 32767), _HPF_COEFFS), _RING_COEFFS)
+        peak = max(abs(v) for v in ref)
+        target = 32767 * HOST_GAIN
+        _calib_scale = target / max(1, peak)
+    return _calib_scale
+
+
+def synth_message(text: str, volume: int, note_sec: float = NOTE_SEC) -> "array.array":
+    """Render one message as continuous PCM: cached polyBLEP squares per char,
+    chained and run through the simulated piezo chain (LF rolloff + resonance
+    ring). The device's own sample clock paces playback; adaptive `note_sec`
+    matches the firmware's measured cadence."""
+    amp = int(32767 * max(0, min(10, volume)) / 10.0)
+    buf = array.array("h")
+    n_samples = int(SAMPLE_RATE * note_sec)
+    rest = array.array("h", [0]) * n_samples
+    for ch in text:
+        c = ord(ch)
+        if ch in " \t\n\r" or not (32 <= c <= 122):
+            buf.extend(rest)
+            continue
+        key = (ch, volume, round(note_sec, 3))
+        sq = _wave_cache.get(key)
+        if sq is None:
+            sq = _square_wave(AURALIZER_FREQ[c - 32], note_sec, amp)
+            _wave_cache[key] = sq
+            if len(_wave_cache) > 512:
+                _wave_cache.clear()
+        buf.extend(sq)
+    if not buf:
+        return buf
+    # Float chain: HPF → ring → HF mode (unclamped — the boosts legitimately
+    # exceed int16; calibration scales it back). Then global scale, tail fade,
+    # clamp.
+    buf = _biquad(_biquad(_biquad(buf, _HPF_COEFFS), _RING_COEFFS), _HF_COEFFS)
+    scale = _calibration_scale()
+    fade = min(len(buf), int(SAMPLE_RATE * 0.005))
+    out = array.array("h", bytes(2 * len(buf)))
+    k = len(buf) - fade
+    for j in range(len(buf)):
+        v = buf[j] * scale
+        if j >= k:
+            v *= (j - k + 1) / fade
+        if v > 32767:
+            v = 32767
+        elif v < -32768:
+            v = -32768
+        out[j] = int(v)
+    return out
+
+
+class HostAuralizer:
+    """Always-on host audio sink. Plays one ~33ms note at a time; a newer note
+    interrupts (replaces) the previous one, so the last message is the only
+    message on the host too."""
+
+    def __init__(self) -> None:
+        self._device = None
+        self._lock = threading.Lock()
+        self._note = None  # array.array int16 mono of the current note (latest wins)
+        self._pos = 0      # frames consumed from _note
+        self._stop = False
+
+    def start(self) -> None:
+        if not (MINIAUDIO_OK and HOST_AURALIZER):
+            return
+        try:
+            self._device = miniaudio.PlaybackDevice(
+                output_format=miniaudio.SampleFormat.SIGNED16,
+                nchannels=1,
+                sample_rate=SAMPLE_RATE,
+                # Small device buffer: play_note's latest-wins swap only takes
+                # effect at the next buffer boundary, and the 200ms default
+                # made the host audibly lag the projector by up to 200ms. 20ms
+                # is under the firmware's own 33ms frame granularity.
+                buffersize_msec=20,
+            )
+            # PRIME the generator: miniaudio's data callback does
+            # `generator.send(framecount)`, and Python forbids a non-None
+            # send() on a just-started generator — every callback would raise
+            # TypeError and produce silence. One initial next() runs it to the
+            # first yield, after which send() is legal.
+            gen = self._generator()
+            next(gen)
+            self._device.start(gen)
+        except Exception as e:
+            self._device = None
+            print(f"err host auralizer unavailable: {e}", flush=True)
+            return
+        print("ok host auralizer", flush=True)
+
+    def _generator(self):
+        # miniaudio pull model: each yield returns the number of frames the
+        # device wants next. Serve the current note, then silence.
+        required = yield b""
+        while not self._stop:
+            with self._lock:
+                note = self._note
+                pos = self._pos
+            if note is None or pos >= len(note):
+                data = array.array("h", [0]) * required  # rest
+            else:
+                take = min(len(note) - pos, required)
+                data = note[pos : pos + take]
+                with self._lock:
+                    self._pos = pos + take
+                if take < required:
+                    data = data + array.array("h", [0]) * (required - take)
+                    with self._lock:
+                        self._note = None
+            required = yield data.tobytes()
+
+    def play_note(self, note: "array.array") -> None:
+        # Latest wins: a note pushed while the previous one is playing replaces
+        # it at the next device buffer boundary.
+        with self._lock:
+            self._note = note
+            self._pos = 0
+
+    # Mirror the firmware's volume-change chirp: a short ~1970 Hz beep at the
+    # current volume, so the host confirms volume changes like the projector.
+    CHIRP_HZ = 1970
+    CHIRP_SEC = 0.030
+
+    def chirp(self) -> None:
+        if self._device is None:
+            return
+        n = int(SAMPLE_RATE * self.CHIRP_SEC)
+        peak = (max(0, min(10, load_volume())) / 10.0) * 32767 * HOST_GAIN
+        step = 2.0 * math.pi * self.CHIRP_HZ / SAMPLE_RATE
+        note = array.array("h", (int(math.sin(step * i) * peak) for i in range(n)))
+        self.play_note(note)
+
+    def stop(self) -> None:
+        self._stop = True
+        if self._device is not None:
+            try:
+                self._device.stop()
+                self._device.close()
+            except Exception:
+                pass
+            self._device = None
+
+
+async def discover_address(override: str):
+    if override:
+        return override
+    devices = await BleakScanner.discover(timeout=SCAN_TIMEOUT, return_adv=True)
+    for addr, (dev, adv) in devices.items():
+        if adv and SERVICE_UUID in {u.lower() for u in adv.service_uuids}:
+            return addr
+        if dev.name == DEVICE_NAME:
+            return addr
+    return None
+
+
+IDLE_CHECK_MS = 5.0
+
+
+def arm_parent_death_signal(parent_pid: int) -> None:
+    """Linux: have the kernel SIGTERM us the instant our parent (opencode) dies,
+    no matter how (SIGKILL, destroyed terminal, crash). prctl is per-thread and
+    racy — the parent can die before we arm it — so set it on the main thread
+    and bail out immediately if the parent is already gone (the ppid changed).
+    On non-Linux or if prctl is unavailable, silently fall back to the ppid
+    watchdog in watch_parent()."""
+    if not sys.platform.startswith("linux"):
+        return
+    try:
+        import ctypes
+
+        ctypes.CDLL(None, use_errno=True).prctl(1, signal.SIGTERM)  # PR_SET_PDEATHSIG
+    except Exception:
+        return
+    if os.getppid() != parent_pid:
+        os._exit(0)
+
+
+async def wait_line_or_stop(
+    q: "asyncio.Queue", stop_event: "asyncio.Event", timeout: float
+):
+    """Race the BLE line queue against the stop event. Returns
+    ("line", text) when a line arrives, ("stop", None) the instant a stop is
+    requested (no waiting for the timeout), or ("idle", None) after `timeout`
+    with no line and no stop. Without this, a SIGTERM during the idle wait was
+    only noticed after IDLE_CHECK_MS (5s) — the disconnect lagged."""
+    line_task = asyncio.ensure_future(q.get())
+    stop_task = asyncio.ensure_future(stop_event.wait())
+    done, pending = await asyncio.wait(
+        {line_task, stop_task}, timeout=timeout, return_when=asyncio.FIRST_COMPLETED
+    )
+    for t in pending:
+        t.cancel()
+    if stop_task in done:
+        return ("stop", None)
+    if line_task in done:
+        return ("line", line_task.result())
+    return ("idle", None)
+
+
+async def main() -> None:
+    override = os.environ.get("RGBIFY_PROJECTOR_ADDR", "").strip()
+    arm_parent_death_signal(os.getppid())
+    loop = asyncio.get_running_loop()
+    reader = asyncio.StreamReader()
+    protocol = asyncio.StreamReaderProtocol(reader)
+    await loop.connect_read_pipe(lambda: protocol, sys.stdin)
+
+    # Graceful shutdown on every death path: SIGTERM (plugin dispose,
+    # pdeathsig), SIGHUP (terminal destroyed), stdin EOF (parent's pipe gone),
+    # or the ppid watchdog. Each sets stop_event; the tasks unwind so the
+    # BleakClient exits its `async with` and disconnects cleanly first.
+    stop_event = asyncio.Event()
+
+    def request_stop() -> None:
+        stop_event.set()
+
+    for sig in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP):
+        try:
+            loop.add_signal_handler(sig, request_stop)
+        except (NotImplementedError, RuntimeError):
+            pass
+
+    lines: asyncio.Queue = asyncio.Queue()
+    # Adaptive host pacing (see NOTE_SEC_* above): the BLE loop measures the
+    # ACK time per char after every write and EMA-smooths it here;
+    # host_auralize synthesizes at this pace so host buffers last exactly as
+    # long as the ACK window — no periodic silence while plugged in.
+    ack_pace_sec = NOTE_SEC
+    # Latest-line slots (maxsize 1, replace-on-full): each sink keeps only the
+    # most recent line, so a newer line interrupts (replaces) the previous one.
+    host_line: asyncio.Queue = asyncio.Queue(maxsize=1)
+    ble_line: asyncio.Queue = asyncio.Queue(maxsize=1)
+
+    # While disconnected, no lines reach either sink — nothing is queued or
+    # replayed. Delivery starts fresh with the first line after a connect.
+    connected = False
+
+    auralizer = HostAuralizer()
+
+    async def read_stdin() -> None:
+        while True:
+            raw = await reader.readline()
+            if not raw:
+                # stdin closed = the opencode plugin that spawned us is gone.
+                dbg("stdin EOF")
+                request_stop()
+                return
+            line = raw.decode("utf-8", "replace").rstrip("\n")
+            dbg(f"in len={len(line)}")
+            await lines.put(line)
+
+    def push_latest(q: asyncio.Queue, line: str) -> None:
+        try:
+            q.put_nowait(line)
+        except asyncio.QueueFull:
+            q.get_nowait()
+            q.put_nowait(line)
+
+    async def broadcast() -> None:
+        # Fan every line out as the LATEST line. While the projector is
+        # connected, feed only ble_line — the BLE loop hands every chunk it
+        # writes back to host_line, so the host auralizer plays EXACTLY the
+        # bytes the projector receives (char-perfect sync). While disconnected,
+        # raw lines go to host_line only, so the host keeps auralizing
+        # always-on and nothing accumulates for replay on reconnect.
+        while not stop_event.is_set():
+            line = await lines.get()
+            if connected:
+                push_latest(ble_line, line)
+            else:
+                push_latest(host_line, line)
+
+    async def host_auralize() -> None:
+        # Play the whole message as ONE continuous PCM buffer. The miniaudio
+        # device's own sample clock paces it — exactly one ~33ms note per char,
+        # matching the firmware's 30fps cadence with no drift. A newer message
+        # replaces the playing one at the next device buffer boundary (latest
+        # wins), so the host always plays the same notes as the projector.
+        auralizer.start()
+        try:
+            while not stop_event.is_set():
+                kind, line = await wait_line_or_stop(
+                    host_line, stop_event, IDLE_CHECK_MS
+                )
+                if kind == "stop":
+                    return
+                if kind == "idle":
+                    continue
+                if not line:
+                    continue
+                auralizer.play_note(
+                    synth_message(line, load_volume(), ack_pace_sec)
+                )
+        finally:
+            auralizer.stop()
+
+    async def watch_parent() -> None:
+        # Robust orphan guard. stdin EOF normally exits us when the opencode
+        # plugin that spawned us dies, but if another child of opencode (e.g. an
+        # MCP server) inherited the pipe's write end, EOF never arrives. Detect
+        # the parent's death directly instead: when it dies we are reparented
+        # (ppid changes), so request a graceful stop then.
+        ppid = os.getppid()
+        while not stop_event.is_set():
+            await asyncio.sleep(1)
+            if os.getppid() != ppid:
+                request_stop()
+                return
+
+    asyncio.create_task(read_stdin())
+    asyncio.create_task(broadcast())
+    asyncio.create_task(watch_parent())
+    host_task = asyncio.create_task(host_auralize())
+
+    async def ble_loop() -> None:
+        nonlocal connected, ack_pace_sec
+        while not stop_event.is_set():
+            try:
+                addr = await discover_address(override)
+            except Exception as e:
+                print(f"err scan failed: {e}", flush=True)
+                await asyncio.sleep(RECONNECT_DELAY)
+                continue
+            if addr is None:
+                print("err projector not found", flush=True)
+                await asyncio.sleep(RECONNECT_DELAY)
+                continue
+            # The projector advertises immediately on power-up but isn't ready to
+            # accept a connection until it finishes booting. Give it a moment.
+            await asyncio.sleep(CONNECT_DELAY)
+            try:
+                # When the projector resets/reboots, drop any queued text so
+                # stale lines buffered before the disconnect are not delivered
+                # on reconnect.
+                def on_disconnect(_client) -> None:
+                    nonlocal connected
+                    connected = False
+                    dbg("disconnected")
+                    for q in (host_line, ble_line):
+                        try:
+                            q.get_nowait()
+                        except asyncio.QueueEmpty:
+                            pass
+                    print("disconnect", flush=True)
+                    # NOTE: no `bluetoothctl disconnect` here. On Linux all
+                    # clients (bridge AND the RGBify website) share ONE BlueZ
+                    # ACL link, so a device-wide disconnect ejected the
+                    # website every time a bridge went away. Stale writes
+                    # can't survive anymore anyway — flow-control ACK means
+                    # every write is fully played before its response.
+
+                async with BleakClient(addr, disconnected_callback=on_disconnect) as client:
+                    # Clear anything that slipped in before the flag flipped, so
+                    # delivery starts fresh with the first line after connect.
+                    for q in (host_line, ble_line):
+                        try:
+                            q.get_nowait()
+                        except asyncio.QueueEmpty:
+                            pass
+                    connected = True
+                    dbg(f"connected {addr}")
+                    print(f"ok {addr}", flush=True)
+                    # Volume sync: read once on connect, subscribe to change
+                    # notifications, AND poll as a fallback — the notification
+                    # path has proven unobservable under flow-control load, so
+                    # a cheap periodic read guarantees the host mirrors device
+                    # volume changes (e.g. from the RGBify website).
+                    vol_state = {"last": None}
+
+                    def apply_volume(v: int, src: str, chirp: bool) -> None:
+                        if v == vol_state["last"]:
+                            return
+                        vol_state["last"] = v
+                        dbg(f"vol {src} {v}")
+                        save_volume(v)
+                        if chirp:
+                            auralizer.chirp()
+
+                    try:
+                        value = await client.read_gatt_char(VOLUME_UUID)
+                        if value:
+                            vol_state["last"] = value[0]
+                            save_volume(value[0])
+                            dbg(f"vol connect {value[0]}")
+                    except Exception as e:
+                        dbg(f"vol read err {e}")
+
+                    def on_volume_changed(_handle, data: bytes) -> None:
+                        if data:
+                            dbg(f"vol notify {data[0]}")
+                            apply_volume(data[0], "notify", True)
+
+                    try:
+                        await client.start_notify(VOLUME_UUID, on_volume_changed)
+                        dbg("vol notify subscribed")
+                    except Exception as e:
+                        dbg(f"vol notify FAILED: {e}")
+
+                    last_vol_check = 0.0
+
+                    async def poll_volume() -> None:
+                        # Fallback for lost notifications: rate-limited to one
+                        # read per VOL_POLL_SEC; applies silently (the device
+                        # already chirped at change time).
+                        nonlocal last_vol_check
+                        now = time.monotonic()
+                        if now - last_vol_check < VOL_POLL_SEC:
+                            return
+                        last_vol_check = now
+                        try:
+                            value = await client.read_gatt_char(VOLUME_UUID)
+                            if value:
+                                apply_volume(value[0], "poll", False)
+                        except Exception as e:
+                            dbg(f"vol poll err {e}")
+                    # WHOLE-MESSAGE DELIVERY, ACK-GATED: each line (the last
+                    # 8 chars of a coalesced delta burst) is written in ONE
+                    # write with response=True. The firmware holds the ACK
+                    # until every char has been played, so the write resolves
+                    # exactly when playback finishes — nothing can buffer in
+                    # either BLE stack. Lines that arrive DURING playback are
+                    # NOT discarded: they chain immediately after the ACK, so
+                    # notes play back-to-back for as long as text keeps
+                    # streaming.
+                    while True:
+                        kind, text = await wait_line_or_stop(
+                            ble_line, stop_event, IDLE_CHECK_MS
+                        )
+                        if kind == "stop":
+                            return
+                        if kind == "idle":
+                            if not client.is_connected:
+                                raise ConnectionError(
+                                    "projector disconnected while idle"
+                                )
+                            await poll_volume()
+                            continue
+                        if not text:
+                            continue
+                        # SYNC: hand the message to the host auralizer NOW, so
+                        # it starts playing the same notes at the same moment
+                        # the projector does — NOT after the ACK (which would
+                        # put the host one message behind).
+                        push_latest(host_line, text)
+                        dbg(f"host play len={len(text)}")
+                        t_write = time.monotonic()
+                        try:
+                            await asyncio.wait_for(
+                                client.write_gatt_char(
+                                    TEXT_BRIDGE_UUID, text.encode("utf-8"),
+                                    response=True,
+                                ),
+                                timeout=WRITE_TIMEOUT,
+                            )
+                        except asyncio.TimeoutError:
+                            # Firmware wedged / connection stalled: drop the
+                            # link and reconnect rather than freeze both sinks.
+                            dbg("write TIMEOUT")
+                            raise ConnectionError("write ACK timed out")
+                        except Exception as e:
+                            # Transient/failed write: move on; the next delta
+                            # starts fresh.
+                            dbg(f"write err {e}")
+                            continue
+                        ack_ms = (time.monotonic() - t_write) * 1000.0
+                        dbg(f"ack {ack_ms:.0f}ms")
+                        # Adaptive host pacing: learn the firmware's REAL
+                        # per-char playback time from this ACK so host buffers
+                        # last exactly as long as the ACK window.
+                        inst = min(NOTE_SEC_MAX, max(
+                            NOTE_SEC_MIN, (ack_ms / 1000.0) / max(1, len(text))
+                        ))
+                        ack_pace_sec += ACK_PACE_EMA * (inst - ack_pace_sec)
+                        print("ok", flush=True)
+                        # Fallback volume poll (rate-limited to VOL_POLL_SEC):
+                        # catches webapp changes even if a notification is
+                        # lost. Cheap monotonic-time check when under rate.
+                        await poll_volume()
+                        # NO flush here: anything that arrived during playback
+                        # stays queued and plays immediately on the next loop
+                        # iteration — notes chain back-to-back for as long as
+                        # deltas keep coming ("keep playing until the next
+                        # delta arrives"). The maxsize-1 queue bounds lag at
+                        # ~one extra message; when deltas stop, the last one
+                        # plays out and the auralizers go quiet.
+            except Exception as e:
+                connected = False
+                dbg(f"loop err {e}")
+                print(f"err {e}", flush=True)
+                await asyncio.sleep(RECONNECT_DELAY)
+
+    # Hard fallback: once a stop is requested, the graceful path normally
+    # disconnects within a few seconds (the idle wait is up to IDLE_CHECK_MS),
+    # but never let the bridge linger as an orphan.
+    async def watchdog() -> None:
+        await stop_event.wait()
+        await asyncio.sleep(10)
+        os._exit(0)
+
+    asyncio.create_task(watchdog())
+
+    await asyncio.gather(host_task, ble_loop())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())