opencode-rgbify-plugin 0.1.3 → 0.1.5

package/bridge/ble_bridge.py

@@ -1,25 +1,28 @@
 #!/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.
+ACK-GATED DELIVERY: every line is written to the projector with response=True,
+and the next line is NOT written until the previous one is ACKed. Lines that
+arrive during the ACK window are SKIPPED (latest wins on a maxsize-1 queue), so
+the last text is the only text — nothing queues on the projector and nothing
+plays out of order. The host auralizer plays EXACTLY the bytes the projector
+receives (fed pre-write, same skips), at the measured ACK pace.
 
 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.
+writes each line to the TEXT_BRIDGE characteristic and reconnects forever with
+backoff so the plugin stays a silent no-op while the projector is out of range
+or powered off.
+
+The host auralizer (miniaudio) runs always and independently of the BLE
+connection; when the projector is reachable both play the same line. Lines
+missed while the projector is down are dropped for the projector (no replay on
+reconnect) so the two stay in sync.
+
+On a clean stop (parent death, stdin EOF, SIGTERM/SIGINT) the bridge exits
+WITHOUT an explicit BLE disconnect: bluetoothd owns the shared ACL link, so the
+projector stays connected and the shared-link RGBify website keeps its
+connection. Only error recovery (wedged link) explicitly disconnects before
+re-dialing.
 
 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).
@@ -27,10 +30,11 @@ 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).
+Host (desktop) volume is controlled independently of the projector: the opencode
+TUI's RGBify volume popup writes the state file below, and the bridge watches it
+and applies changes live (works even with the projector off). It is NOT mirrored
+from the projector's VOLUME characteristic. Initial value comes from the file or
+RGBIFY_VOLUME.
 
 stdout protocol (one line per event, for debugging):
   ok <addr>          connected / a line delivered
@@ -73,7 +77,6 @@ except (ImportError, OSError):
 
 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
@@ -83,27 +86,25 @@ SCAN_TIMEOUT = 5.0
 # 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.
+# Max time a single write ACK may take. The write is response=True (gated ACK):
+# the firmware sends the ATT write response once the whole message has been
+# received, so it normally resolves in tens of milliseconds; this is only a
+# guard against a wedged BlueZ DBus call so a stalled 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).
+# freq = auralizer_freq[clamp(ord(c)-32)] for EVERY char including whitespace —
+# whitespace is NOT a rest (a rest would click the piezo chain and gate the tone
+# off mid-delta; it must play its ASCII slot continuously).
 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.
+# ack_ms/char after every write and EMA-smooths it; the auralizer plays at that
+# pace so host notes 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
@@ -160,6 +161,27 @@ AURALIZER_FREQ = [
 ]
 
 
+# Whitespace is NOT a rest (a gap would click the piezo chain and gate the tone
+# off mid-delta), and NOT the 5000Hz table slot (space/newline would scream).
+# It plays a LOW note — clearly below the melody range, full-bodied, not the
+# tinny high slots. (1970 was tried; still sounded bad. 150 = bass.)
+WHITESPACE_FREQ = 150.0
+
+
+def _char_freq(ch: str) -> float:
+    """Whitespace plays the resonant note (WHITESPACE_FREQ); every other char
+    maps to its ASCII slot in the log-scale table, clamped to [0,90]. No rest,
+    no high-pitch scream for spaces."""
+    if ch in " \t\n\r":
+        return WHITESPACE_FREQ
+    idx = ord(ch) - 32
+    if idx < 0:
+        idx = 0
+    elif idx > 90:
+        idx = 90
+    return AURALIZER_FREQ[idx]
+
+
 # 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
@@ -177,8 +199,6 @@ 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
@@ -277,60 +297,30 @@ def _calibration_scale() -> float:
     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."""
+    """Always-on host audio sink — a REAL-TIME FREQUENCY FOLLOWER.
+
+    The miniaudio device thread continuously synthesizes a square wave at the
+    current frequency (straight-through phase accumulator + persistent piezo
+    biquad chain). The bridge loop never does synthesis, never sleeps, never
+    touches the volume file per message: it only hands over a list of note
+    frequencies (whitespace INCLUDED — every char plays its ASCII table slot,
+    no rests, no fades) and the audio clock drives one note per NOTE_SEC.
+
+    The tone changes frequency per character, plays continuously through the
+    whole line, and only goes silent once the line's notes are exhausted (the
+    end of a delta). A new line replaces the pending notes immediately (latest
+    wins — matching the projector's interrupt semantics). Note duration is
+    adaptive: set_pace() feeds the measured ACK ms/char so host notes last
+    exactly as long as the ACK window (no gap while plugged in)."""
 
     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._seq = None      # list[float] Hz per char for the current line, or None
+        self._off = True      # True when no tone should sound
+        self._note_sec = NOTE_SEC  # per-char playback duration (adaptive)
+        self._amp = int(32767 * max(0, min(10, load_volume())) / 10.0)
         self._stop = False
 
     def start(self) -> None:
@@ -341,10 +331,6 @@ class HostAuralizer:
                 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
@@ -362,46 +348,100 @@ class HostAuralizer:
         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.
+        # Straight-through async synthesis on the audio thread. Per-sample:
+        # polyBLEP square @ current freq -> HPF -> ring -> HF mode, all with
+        # PERSISTENT filter state (a continuous tone, no clicks, no fades). The
+        # audio clock advances one note every NOTE_SEC; when the line's notes
+        # are exhausted it goes silent (end of delta). A new seq object swaps in
+        # at the next callback (latest wins), interrupting whatever was playing
+        # exactly like the firmware's text_bridge_pos=0 reset.
         required = yield b""
+        phase = 0.0
+        x1a = x2a = y1a = y2a = 0.0  # HPF state
+        x1b = x2b = y1b = y2b = 0.0  # ring state
+        x1c = x2c = y1c = y2c = 0.0  # HF state
+        seq = None
+        pos = 0
+        left = 0
+        scale = _calibration_scale()
         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.
+                cur = self._seq
+                off = self._off
+                amp = self._amp
+                note_sec = self._note_sec
+            if cur is not seq:
+                seq = cur
+                pos = 0
+                left = int(SAMPLE_RATE * note_sec) if cur is not None else 0
+            out = array.array("h")
+            for _ in range(required):
+                if off or seq is None or pos >= len(seq):
+                    out.append(0)
+                    continue
+                freq = seq[pos]
+                dt = freq / SAMPLE_RATE
+                naive = 1.0 if phase < 0.5 else -1.0
+                x = (naive - _poly_blep(phase, dt)) * amp
+                y = (_HPF_COEFFS[0] * x + _HPF_COEFFS[1] * x1a
+                     + _HPF_COEFFS[2] * x2a - _HPF_COEFFS[3] * y1a
+                     - _HPF_COEFFS[4] * y2a)
+                x2a, x1a, y2a, y1a = x1a, x, y1a, y
+                x = y
+                y = (_RING_COEFFS[0] * x + _RING_COEFFS[1] * x1b
+                     + _RING_COEFFS[2] * x2b - _RING_COEFFS[3] * y1b
+                     - _RING_COEFFS[4] * y2b)
+                x2b, x1b, y2b, y1b = x1b, x, y1b, y
+                x = y
+                y = (_HF_COEFFS[0] * x + _HF_COEFFS[1] * x1c
+                     + _HF_COEFFS[2] * x2c - _HF_COEFFS[3] * y1c
+                     - _HF_COEFFS[4] * y2c)
+                x2c, x1c, y2c, y1c = x1c, x, y1c, y
+                v = y * scale
+                if v > 32767:
+                    v = 32767
+                elif v < -32768:
+                    v = -32768
+                out.append(int(v))
+                phase += dt
+                if phase >= 1.0:
+                    phase -= 1.0
+                left -= 1
+                if left <= 0:
+                    pos += 1
+                    left = int(SAMPLE_RATE * note_sec)
+            required = yield out.tobytes()
+
+    def play_notes(self, freqs: list) -> None:
+        # Latest wins: a fresh note list replaces the pending one; the audio
+        # thread picks it up at the next buffer boundary. O(n) tiny, no I/O.
+        with self._lock:
+            self._seq = freqs
+            self._off = False
+
+    def note_off(self) -> None:
+        with self._lock:
+            self._off = True
+            self._seq = None
+
+    def set_volume(self, v: int) -> None:
+        with self._lock:
+            self._amp = int(32767 * max(0, min(10, v)) / 10.0)
+
+    def set_pace(self, note_sec: float) -> None:
+        # Adaptive host pacing: per-char note duration matches the measured ACK
+        # window so host notes last exactly as long as the projector's playback.
         with self._lock:
-            self._note = note
-            self._pos = 0
+            self._note_sec = note_sec
 
     # 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)
+        self.play_notes([self.CHIRP_HZ])
 
     def stop(self) -> None:
         self._stop = True
@@ -493,14 +533,11 @@ async def main() -> None:
         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.
+    # most recent line. ACK-GATED DELIVERY: while a message is in flight (awaiting
+    # its write ACK), newer lines replace the pending slot — intermediate texts
+    # are SKIPPED, only the newest survives and is written after the ACK. Nothing
+    # queues on the projector; the last text is the only text.
     host_line: asyncio.Queue = asyncio.Queue(maxsize=1)
     ble_line: asyncio.Queue = asyncio.Queue(maxsize=1)
 
@@ -510,7 +547,20 @@ async def main() -> None:
 
     auralizer = HostAuralizer()
 
+    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 read_stdin() -> None:
+        # Latest-line fan-out, no intermediary queue. While connected, a line
+        # goes to ble_line only — the BLE loop hands every written chunk back to
+        # host_line so the host plays EXACTLY the bytes the projector receives
+        # (char-perfect sync). While disconnected, lines go to host_line only,
+        # so the host keeps auralizing always-on and nothing accumulates for
+        # replay on reconnect.
         while True:
             raw = await reader.readline()
             if not raw:
@@ -520,35 +570,17 @@ async def main() -> None:
                 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.
+        # Real-time frequency follower: hand the audio thread one frequency per
+        # char (whitespace INCLUDED) and let the device clock drive playback.
+        # No synthesis, no sleep, no volume-file I/O on this loop — play_notes
+        # is O(n) and non-blocking, so the bridge loop stays free to read stdin
+        # and drive BLE (the loop never stalls, so nothing backs up to opencode).
         auralizer.start()
         try:
             while not stop_event.is_set():
@@ -561,9 +593,7 @@ async def main() -> None:
                     continue
                 if not line:
                     continue
-                auralizer.play_note(
-                    synth_message(line, load_volume(), ack_pace_sec)
-                )
+                auralizer.play_notes([_char_freq(c) for c in line])
         finally:
             auralizer.stop()
 
@@ -580,13 +610,32 @@ async def main() -> None:
                 request_stop()
                 return
 
+    async def watch_host_volume() -> None:
+        # Desktop volume is controlled externally (the opencode TUI popup writes
+        # the host-volume file). Watch it so live changes apply even with the
+        # projector off — no BLE round-trip, no mirroring of the projector VOLUME.
+        last = load_volume()
+        auralizer.set_volume(last)
+        while not stop_event.is_set():
+            await asyncio.sleep(0.5)
+            cur = load_volume()
+            if cur != last:
+                last = cur
+                auralizer.set_volume(cur)
+                auralizer.chirp()
+                dbg(f"vol file {cur}")
+
     asyncio.create_task(read_stdin())
-    asyncio.create_task(broadcast())
     asyncio.create_task(watch_parent())
+    asyncio.create_task(watch_host_volume())
     host_task = asyncio.create_task(host_auralize())
 
     async def ble_loop() -> None:
-        nonlocal connected, ack_pace_sec
+        nonlocal connected
+        # Adaptive host pacing (see NOTE_SEC_* above): the BLE loop measures the
+        # ACK time per char after every write and EMA-smooths it; the auralizer
+        # plays at this pace so host notes last exactly as long as the ACK window.
+        ack_pace_sec = NOTE_SEC
         while not stop_event.is_set():
             try:
                 addr = await discover_address(override)
@@ -601,170 +650,138 @@ async def main() -> None:
             # 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()
 
+            # 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:
-                        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)
+                        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 either — the firmware
+                # interrupts on every write.
+
+            # Explicit client, NOT `async with`: we control connect/disconnect.
+            # On a clean stop we exit WITHOUT client.disconnect() — bluetoothd
+            # owns the BLE link, so an abrupt exit leaves the projector connected
+            # and the shared-link RGBify website keeps its connection. Only error
+            # recovery explicitly disconnects (a wedged link must be torn down
+            # before re-dialing).
+            client = BleakClient(addr, disconnected_callback=on_disconnect)
+            connected = False
+            try:
+                await client.connect()
+            except Exception as e:
+                # Failed connect: make sure nothing lingers, then re-dial.
+                try:
+                    await client.disconnect()
+                except Exception:
+                    pass
+                dbg(f"loop err {e}")
+                print(f"err {e}", flush=True)
+                await asyncio.sleep(RECONNECT_DELAY)
+                continue
 
+            try:
+                # 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:
-                        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,
+                        q.get_nowait()
+                    except asyncio.QueueEmpty:
+                        pass
+                connected = True
+                dbg(f"connected {addr}")
+                print(f"ok {addr}", flush=True)
+                # Desktop volume is NOT mirrored from the projector. It is
+                # controlled externally (TUI popup -> host-volume file, watched
+                # by watch_host_volume below) and works with the projector off.
+                # No connect-time GATT read, so the first message is not gated
+                # behind a volume round-trip.
+                # 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 write resolves only once the firmware ACKs
+                # it, so the round-trip serializes delivery: the next line is NOT
+                # written until the previous is ACKed. Lines that arrive DURING
+                # the ACK window are SKIPPED (latest wins on the maxsize-1
+                # ble_line), so the last text is the only text and nothing queues
+                # on the projector.
+                while True:
+                    kind, text = await wait_line_or_stop(
+                        ble_line, stop_event, IDLE_CHECK_MS
+                    )
+                    if kind == "stop":
+                        # Clean stop: leave the BLE link to bluetoothd — do NOT
+                        # disconnect, so the shared-link website stays connected.
+                        connected = False
+                        return
+                    if kind == "idle":
+                        if not client.is_connected:
+                            raise ConnectionError(
+                                "projector disconnected while idle"
                             )
-                        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.
+                        continue
+                    if not text:
+                        continue
+                    # SYNC: hand the message to the host auralizer NOW, so
+                    # it starts the same notes at the same moment the
+                    # projector does.
+                    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_s = time.monotonic() - t_write
+                    dbg(f"ack {ack_s * 1000:.0f}ms")
+                    # Adaptive host pacing: learn the firmware's REAL per-char
+                    # playback time from this ACK so host notes last exactly as
+                    # long as the ACK window.
+                    inst = min(NOTE_SEC_MAX, max(
+                        NOTE_SEC_MIN, ack_s / max(1, len(text))
+                    ))
+                    ack_pace_sec += ACK_PACE_EMA * (inst - ack_pace_sec)
+                    auralizer.set_pace(ack_pace_sec)
+                    print("ok", flush=True)
             except Exception as e:
+                # Error recovery (wedged link, write timeout, disconnect while
+                # idle): explicitly disconnect so a clean re-dial is possible.
+                try:
+                    await client.disconnect()
+                except Exception:
+                    pass
                 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.
+    # Hard fallback: once a stop is requested, the graceful path exits within a
+    # few seconds (the idle wait is up to IDLE_CHECK_MS), but never let the
+    # bridge linger as an orphan. Note this abrupt exit also leaves the BLE link
+    # to bluetoothd (no disconnect) — exactly what we want on shutdown.
     async def watchdog() -> None:
         await stop_event.wait()
         await asyncio.sleep(10)
@@ -772,7 +789,18 @@ async def main() -> None:
 
     asyncio.create_task(watchdog())
 
-    await asyncio.gather(host_task, ble_loop())
+    try:
+        await asyncio.gather(host_task, ble_loop())
+    finally:
+        # NEVER return from main: asyncio.run would shut the event loop down,
+        # cancelling bleak's _disconnect_monitor task, whose CancelledError
+        # handler sends a BlueZ device "Disconnect" — dropping the shared ACL
+        # link and ejecting the RGBify website. os._exit bypasses all Python
+        # cleanup; the OS closes our socket and bluetoothd keeps the projector
+        # connected ("let the OS handle BT connections"). On macOS/Windows the
+        # OS tears the link down on process exit regardless — no spurious
+        # disconnect either way.
+        os._exit(0)
 
 
 if __name__ == "__main__":