hapbeat-python-sdk 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

hapbeat/hapbeat.py

@@ -24,6 +24,7 @@ or as a context manager::
 from __future__ import annotations
 
 import logging
+import secrets
 import threading
 import time
 from dataclasses import dataclass, field
@@ -32,8 +33,24 @@ from typing import Optional, Union
 
 from . import protocol
 from .client import DEFAULT_BROADCAST, DEFAULT_PORT, UdpClient
-from .clip import ClipStreamer
 from .eventmap import EventDef, EventMap
+from .stream import (
+    LEGACY_STREAM_MODE,
+    EndpointStreamMode,
+    StreamEndpoint,
+    StreamHub,
+    StreamPlayback,
+)
+from .stream_lease import (
+    PENDING_PING_MAX_AGE,
+    V2_LEASE_REFRESH_INTERVAL,
+    EndpointClass,
+    EndpointLeaseState,
+    PendingPing,
+    PongLeaseDecision,
+    StreamSessionIdentity,
+    evaluate_pong_lease,
+)
 from .wav import WavPcm, read_wav_pcm16
 
 logger = logging.getLogger("hapbeat")
@@ -47,6 +64,7 @@ class Device:
     name: str = ""
     address: str = ""
     firmware_version: str = ""
+    port: int = DEFAULT_PORT
     last_seen: float = field(default_factory=time.monotonic)
 
 
@@ -54,6 +72,14 @@ def _now_us() -> int:
     return int(time.time() * 1_000_000)
 
 
+def _new_client_incarnation() -> int:
+    """A fresh nonzero uint64 (stream-session-v2.md client_incarnation)."""
+    while True:
+        value = secrets.randbits(64)
+        if value:
+            return value
+
+
 class Hapbeat:
     """A connection to Hapbeat devices over Wi-Fi UDP.
 
@@ -93,6 +119,13 @@ class Hapbeat:
         self._seq_lock = threading.Lock()
         self._devices: dict[str, Device] = {}
         self._devices_lock = threading.Lock()
+        # Stream session v2 (contracts stream-session-v2.md), all guarded by
+        # _devices_lock. A fresh incarnation per open(); each device IP's
+        # class / lease comes only from matched replies to our extended PING.
+        self._client_incarnation = 0
+        self._pending_pings: dict[int, PendingPing] = {}
+        self._last_ping_timestamp_us = 0
+        self._stream_states: dict[str, EndpointLeaseState] = {}
         self._keepalive = keepalive
         self._keepalive_interval = keepalive_interval
         self._keepalive_stop: Optional[threading.Event] = None
@@ -110,14 +143,15 @@ class Hapbeat:
             device_ttl if device_ttl is not None
             else max(5.0, keepalive_interval * 3.0)
         )
-        # Unicast destinations for the active stream session, snapshotted once
-        # in stream_begin (STREAM_DATA/END carry no target of their own).
-        # None = broadcast the session; [] = the snapshot matched nobody, so
-        # send nothing; non-empty = unicast to exactly these IPs.
-        self._stream_dests: Optional[list[str]] = None
-        # Clip streaming (level-2). The streamer calls this object's
-        # stream_begin/stream_data/stream_end (StreamSink protocol).
-        self._clip = ClipStreamer(self, send_ahead_sec=stream_send_ahead)
+        # One deep module owns all logical sources and endpoint wire sessions.
+        # STREAM_DATA/END have no target, so every session is exact-unicast to
+        # one PONG-reported endpoint; unresolved sources remain Deferred.
+        self._stream_hub = StreamHub(
+            self,
+            self._stream_endpoints,
+            send_ahead_sec=stream_send_ahead,
+            mode_provider=self._stream_mode,
+        )
         self._clip_cache: dict[str, WavPcm] = {}
 
     # ── Lifecycle ───────────────────────────────────────────────────
@@ -126,6 +160,13 @@ class Hapbeat:
         may both call it, so a second call while open is a no-op."""
         if self._opened:
             return self
+        # A (re)connect is an explicit stream-ownership (re)acquisition: a new
+        # incarnation, no outstanding requests of the old one. v2 states of the
+        # old incarnation stop being usable; legacy devices keep their class.
+        with self._devices_lock:
+            self._client_incarnation = _new_client_incarnation()
+            self._pending_pings.clear()
+        self._stream_hub.open()
         self._opened = True
         self._client.add_pong_listener(self._on_pong)
         self._client.open()
@@ -137,7 +178,7 @@ class Hapbeat:
         if not self._opened:
             return
         self._opened = False
-        self._clip.stop()  # end any in-flight clip stream
+        self._stream_hub.close()
         # Tell the device this app is leaving so the OLED clears.
         if self.app_name:
             try:
@@ -224,7 +265,8 @@ class Hapbeat:
         *,
         target: Optional[str] = None,
         target_time_us: int = 0,
-    ) -> bool:
+        pan: float = 0.0,
+    ) -> Union[StreamPlayback, bool]:
         """Play a haptic event by id. The EventMap decides the mode.
 
         - **command** event (manifest ``events``) → a PLAY instruction; the
@@ -235,7 +277,9 @@ class Hapbeat:
         Either way the caller writes the same one-liner. ``gain`` is the wire
         gain (0..1); when omitted, the bound :class:`EventMap` supplies the
         per-event default (its manifest ``intensity``), else ``1.0``.
-        ``target_time_us`` applies to command mode only.
+        ``pan`` is the left/right balance (-1 left, 0 centre, +1 right).
+        ``target_time_us`` applies to command mode only. ``pan`` applies to
+        both modes; clip-mode balance is mixed into the endpoint PCM.
         """
         ev = self.event_map.get(event_id) if self.event_map else None
         if gain is None:
@@ -244,7 +288,7 @@ class Hapbeat:
         target_eff = self._effective_target(ev, target)
 
         if ev is not None and ev.streaming:
-            return self.play_clip(event_id, gain, target=target_eff)
+            return self.play_clip(event_id, gain, target=target_eff, pan=pan)
 
         pkt = protocol.build_play(
             self._next_seq(),
@@ -252,15 +296,16 @@ class Hapbeat:
             target=target_eff,
             target_time_us=target_time_us,
             gain=gain,
+            pan=pan,
         )
         return self._send_routed(pkt, target_eff)
 
     def stop(self, event_id: str, *, target: Optional[str] = None) -> bool:
-        """Stop one event id. Clip events end the active stream; command
-        events send a STOP."""
+        """Stop one event id. Clip events stop matching logical sources;
+        command events send a STOP."""
         ev = self.event_map.get(event_id) if self.event_map else None
         if ev is not None and ev.streaming:
-            self._clip.stop()
+            self._stream_hub.stop_key(event_id, target=target)
             return True
         target_eff = self._effective_target(ev, target)
         pkt = protocol.build_stop(self._next_seq(), event_id, target=target_eff)
@@ -268,14 +313,63 @@ class Hapbeat:
 
     def stop_all(self, *, target: Optional[str] = None) -> bool:
         """Stop every event on matching devices (and any active clip stream)."""
-        self._clip.stop()
+        if target is None:
+            self._stream_hub.stop_all()
+        else:
+            self._stream_hub.stop_target(target)
         target_eff = self._resolve_target(target)
         pkt = protocol.build_stop_all(self._next_seq(), target=target_eff)
         return self._send_routed(pkt, target_eff)
 
     def ping(self) -> bool:
-        """Broadcast a PING (keep-alive / discovery probe)."""
-        return self._client.send(protocol.build_ping(self._next_seq(), _now_us()))
+        """Broadcast a PING (keep-alive / discovery probe).
+
+        Goes out on every local subnet until a device answers — this is what
+        finds a Hapbeat that the limited broadcast cannot reach on a multi-homed
+        host. Safe to duplicate: a device answers each PING independently.
+
+        It is the extended (16-byte) PING of stream-session-v2.md: its matched
+        replies classify each device (v2 lease or legacy firmware) for clip
+        streaming.
+        """
+        seq = self._next_seq()
+        with self._devices_lock:
+            if self._client_incarnation == 0:
+                self._client_incarnation = _new_client_incarnation()
+            # strictly increasing: class / lease adoption is ordered by the
+            # echoed timestamp, and two immediate PINGs may read the same clock
+            timestamp_us = max(_now_us(), self._last_ping_timestamp_us + 1)
+            self._last_ping_timestamp_us = timestamp_us
+            now = time.monotonic()
+            self._pending_pings = {
+                pending_seq: pending
+                for pending_seq, pending in self._pending_pings.items()
+                if now - pending.sent_at <= PENDING_PING_MAX_AGE
+            }
+            self._pending_pings[seq] = PendingPing(
+                timestamp_us, self._client_incarnation, now
+            )
+            incarnation = self._client_incarnation
+        return self._client.send_discovery(
+            protocol.build_ping(seq, timestamp_us, incarnation))
+
+    def reacquire_stream_ownership(self) -> bool:
+        """Retake stream ownership after a device reported this client's lease
+        as superseded by another writer (stream-session-v2.md).
+
+        Starts a new client incarnation and re-PINGs: sessions under the old
+        incarnation's leases end, and every v2 device issues a fresh lease on
+        its matched reply, after which deferred sources resume. Call it once
+        the other writer has stopped. Returns the PING send result, or False
+        when the connection is not open.
+        """
+        if not self._opened:
+            return False
+        with self._devices_lock:
+            self._client_incarnation = _new_client_incarnation()
+            self._pending_pings.clear()
+        self._stream_hub.reconcile()
+        return self.ping()
 
     def connect_status(self, *, connected: bool = True) -> bool:
         """Announce connection state so the device OLED shows the app name."""
@@ -286,7 +380,9 @@ class Hapbeat:
             app_name=self.app_name,
             device_name=self.device_name,
         )
-        return self._client.send(pkt)
+        # Idempotent display state, so it can share the discovery fan-out and
+        # clear "app not connected" without waiting for a PONG first.
+        return self._client.send_discovery(pkt)
 
     # ── Clip streaming (level-2) ─────────────────────────────────────
     def play_clip(
@@ -295,7 +391,9 @@ class Hapbeat:
         gain: Optional[float] = None,
         *,
         target: Optional[str] = None,
-    ) -> bool:
+        pan: float = 0.0,
+        loop: Optional[bool] = None,
+    ) -> Union[StreamPlayback, bool]:
         """Stream a clip-mode event's WAV to the device.
 
         Usually you call :meth:`play`, which routes clip events here. The WAV
@@ -310,14 +408,16 @@ class Hapbeat:
         wav = self._load_clip(event_id, ev)
         if wav is None:
             return False
-        self._clip.play(
+        return self._stream_hub.play_pcm(
             wav.data,
             sample_rate=wav.sample_rate,
             channels=wav.channels,
             gain=max(0.0, min(1.0, float(gain))),
+            pan=max(-1.0, min(1.0, float(pan))),
+            loop=ev.loop if loop is None else loop,
             target=self._effective_target(ev, target),
+            key=event_id,
         )
-        return True
 
     def play_clip_file(
         self,
@@ -325,21 +425,24 @@ class Hapbeat:
         gain: float = 1.0,
         *,
         target: Optional[str] = None,
-    ) -> bool:
+        pan: float = 0.0,
+        loop: bool = False,
+    ) -> Union[StreamPlayback, bool]:
         """Stream an arbitrary PCM16 WAV file (not from a manifest)."""
         try:
             wav = read_wav_pcm16(path)
         except (OSError, ValueError) as exc:
             logger.warning("cannot read clip %s: %s", path, exc)
             return False
-        self._clip.play(
+        return self._stream_hub.play_pcm(
             wav.data,
             sample_rate=wav.sample_rate,
             channels=wav.channels,
             gain=max(0.0, min(1.0, float(gain))),
+            pan=max(-1.0, min(1.0, float(pan))),
+            loop=loop,
             target=self._resolve_target(target),
         )
-        return True
 
     def stream_pcm(
         self,
@@ -348,15 +451,22 @@ class Hapbeat:
         sample_rate: int = 16000,
         channels: int = 1,
         gain: float = 1.0,
+        pan: float = 0.0,
+        loop: bool = False,
         target: Optional[str] = None,
-    ) -> None:
-        """Stream an ad-hoc PCM16 buffer (e.g. synthesized cues). ``channels=2``
-        with per-channel amplitude conveys L/R balance (PLAY has no pan)."""
-        self._clip.play(
+    ) -> StreamPlayback:
+        """Register an ad-hoc PCM16 source in the shared endpoint mixer.
+
+        The returned handle adjusts or stops only this source. Multiple calls
+        may run concurrently, including calls aimed at different targets.
+        """
+        return self._stream_hub.play_pcm(
             pcm,
             sample_rate=sample_rate,
             channels=max(1, channels),
             gain=max(0.0, min(1.0, float(gain))),
+            pan=max(-1.0, min(1.0, float(pan))),
+            loop=loop,
             target=self._resolve_target(target),
         )
 
@@ -399,63 +509,121 @@ class Hapbeat:
         self._clip_cache[event_id] = wav
         return wav
 
-    # ── StreamSink (called by ClipStreamer) ─────────────────────────
-    def _snapshot_stream_destinations(self, target: str) -> None:
-        """Pick the destinations for one stream session.
+    # ── EndpointStreamSink (called only by StreamHub) ───────────────
+    def _stream_endpoints(self) -> list[StreamEndpoint]:
+        return [
+            StreamEndpoint(ip=device.ip, address=device.address, port=device.port)
+            for device in self._alive_devices()
+            if device.address
+        ]
 
-        Only STREAM_BEGIN carries a target, so the choice is made once here and
-        reused for every STREAM_DATA/END of the session (also keeping the
-        destination set stable while the clip thread is running).
+    def _stream_mode(self, endpoint: StreamEndpoint) -> Optional[EndpointStreamMode]:
+        """Legacy, v2 under its usable lease, or None (unknown class, invalid
+        or superseded lease, lease of an old incarnation): sources defer."""
+        with self._devices_lock:
+            state = self._stream_states.get(endpoint.ip)
+            incarnation = self._client_incarnation
+        if state is None:
+            return None
+        if state.endpoint_class is EndpointClass.LEGACY:
+            return LEGACY_STREAM_MODE
+        lease = state.usable_v2_lease(incarnation)
+        return EndpointStreamMode(lease) if lease is not None else None
+
+    # v1 stream: pre-v2 firmware only (exact unicast, END without payload)
+    def stream_begin_endpoint(self, endpoint: StreamEndpoint) -> None:
+        packet = protocol.build_stream_begin(
+            self._next_seq(),
+            sample_rate=16000,
+            channels=2,
+            fmt=protocol.AUDIO_FORMAT_PCM16,
+            total_samples=0,
+            gain=1.0,
+            target=endpoint.address,
+        )
+        self._client.send(packet, endpoint.ip)
 
-        Unlike a one-shot command, a filtered-to-empty result means *send
-        nothing* rather than broadcast: a stream is hundreds of packets, and
-        blasting all of them at devices the target excluded would waste far
-        more airtime than a lost stream costs (the device just stays silent —
-        nothing gets stuck, unlike a lost STOP).
-        """
-        if not self.unicast:
-            self._stream_dests = None
-            return
-        alive = self._alive_devices()
-        if not alive:
-            self._stream_dests = None  # nobody known yet -> broadcast
-            return
-        self._stream_dests = [
-            d.ip for d in alive
-            if not d.address or protocol.address_matches(target, d.address)
-        ]
+    def stream_data_endpoint(
+        self, endpoint: StreamEndpoint, offset: int, data: bytes
+    ) -> None:
+        packet = protocol.build_stream_data(self._next_seq(), offset, data)
+        self._client.send(packet, endpoint.ip)
 
-    def _send_stream(self, packet: bytes) -> bool:
-        dests = self._stream_dests
-        if dests is None:
-            return self._client.send(packet)
-        if not dests:
-            return False  # snapshot matched no device — see _snapshot_stream_destinations
-        return self._client.send_many(packet, dests)
+    def stream_end_endpoint(self, endpoint: StreamEndpoint) -> None:
+        self._client.send(protocol.build_stream_end(self._next_seq()), endpoint.ip)
 
-    def stream_begin(self, *, sample_rate: int, channels: int,
-                     total_samples: int, gain: float, target: str) -> None:
-        self._snapshot_stream_destinations(target)
-        self._send_stream(protocol.build_stream_begin(
-            self._next_seq(), sample_rate=sample_rate, channels=channels,
-            fmt=protocol.AUDIO_FORMAT_PCM16, total_samples=total_samples,
-            gain=gain, target=target,
-        ))
+    # stream session v2: envelope on every packet
+    def stream_begin_v2(
+        self, endpoint: StreamEndpoint, identity: StreamSessionIdentity
+    ) -> None:
+        packet = protocol.build_stream_begin_v2(
+            self._next_seq(),
+            identity.lease.boot_id,
+            identity.lease.ticket,
+            identity.generation,
+            sample_rate=16000,
+            channels=2,
+            fmt=protocol.AUDIO_FORMAT_PCM16,
+            total_samples=0,
+            gain=1.0,
+            target=endpoint.address,
+        )
+        self._client.send(packet, endpoint.ip)
 
-    def stream_data(self, offset: int, data: bytes) -> None:
-        self._send_stream(protocol.build_stream_data(self._next_seq(), offset, data))
+    def stream_data_v2(
+        self, endpoint: StreamEndpoint, identity: StreamSessionIdentity,
+        offset: int, data: bytes,
+    ) -> None:
+        packet = protocol.build_stream_data_v2(
+            self._next_seq(),
+            identity.lease.boot_id,
+            identity.lease.ticket,
+            identity.generation,
+            offset,
+            data,
+        )
+        self._client.send(packet, endpoint.ip)
 
-    def stream_end(self) -> None:
-        self._send_stream(protocol.build_stream_end(self._next_seq()))
+    def stream_end_v2(
+        self, endpoint: StreamEndpoint, identity: StreamSessionIdentity
+    ) -> None:
+        packet = protocol.build_stream_end_v2(
+            self._next_seq(),
+            identity.lease.boot_id,
+            identity.lease.ticket,
+            identity.generation,
+        )
+        self._client.send(packet, endpoint.ip)
 
     # ── Discovery ───────────────────────────────────────────────────
-    def discover(self, timeout: float = 1.0) -> list[Device]:
-        """Broadcast a PING and collect devices that reply within ``timeout``."""
+    def discover(self, timeout: float = 1.0, *, stop_early: bool = False) -> list[Device]:
+        """Broadcast a PING and collect devices that reply within ``timeout``.
+
+        ``stop_early`` returns as soon as the first device answers instead of
+        waiting the whole window. Use it when the point is to *route* the next
+        packet rather than to inventory the LAN — a one-shot command needs one
+        reply to know which subnet to send on, and on a quiet LAN that arrives
+        in a few milliseconds.
+        """
         before = time.monotonic()
         self.ping()
-        time.sleep(max(0.0, timeout))
-        with self._devices_lock:
-            return [d for d in self._devices.values() if d.last_seen >= before - 0.05]
+
+        def replied() -> list[Device]:
+            with self._devices_lock:
+                return [d for d in self._devices.values()
+                        if d.last_seen >= before - 0.05]
+
+        deadline = before + max(0.0, timeout)
+        if not stop_early:
+            time.sleep(max(0.0, timeout))
+            return replied()
+
+        while time.monotonic() < deadline:
+            found = replied()
+            if found:
+                return found
+            time.sleep(0.01)
+        return replied()
 
     @property
     def devices(self) -> list[Device]:
@@ -464,12 +632,44 @@ class Hapbeat:
 
     def _on_pong(self, pong: dict, ip: str) -> None:
         with self._devices_lock:
+            previous = self._stream_states.get(ip)
+            decision, state = evaluate_pong_lease(
+                pong, self._pending_pings, self._client_incarnation, previous
+            )
+            if decision is PongLeaseDecision.DISCARD:
+                # a reply for a retired request / old incarnation: must not roll
+                # the device's address or liveness back either
+                return
+            if decision is PongLeaseDecision.ACCEPT:
+                self._stream_states[ip] = state
             dev = self._devices.get(ip) or Device(ip=ip)
             dev.name = pong.get("device_name", dev.name)
             dev.address = pong.get("address", dev.address)
             dev.firmware_version = pong.get("firmware_version", dev.firmware_version)
             dev.last_seen = time.monotonic()
             self._devices[ip] = dev
+        if decision is PongLeaseDecision.ACCEPT:
+            self._log_stream_state_change(ip, previous, state)
+        self._stream_hub.reconcile()
+
+    @staticmethod
+    def _log_stream_state_change(
+        ip: str,
+        previous: Optional[EndpointLeaseState],
+        state: EndpointLeaseState,
+    ) -> None:
+        if previous is None or previous.endpoint_class is not state.endpoint_class:
+            logger.info(
+                "stream receiver %s classified as %s", ip,
+                "stream session v2" if state.endpoint_class is EndpointClass.V2
+                else "legacy (pre-v2 firmware)",
+            )
+        if state.lease_superseded and not (previous and previous.lease_superseded):
+            logger.warning(
+                "stream lease at %s was superseded by another writer; streams "
+                "to it are deferred. Call reacquire_stream_ownership() after "
+                "the other writer has stopped.", ip,
+            )
 
     # ── Keep-alive thread ───────────────────────────────────────────
     def _start_keepalive(self) -> None:
@@ -487,7 +687,7 @@ class Hapbeat:
             self.connect_status(connected=True)
 
         def loop(stop: threading.Event) -> None:
-            while not stop.wait(self._keepalive_interval):
+            while not stop.wait(self._keepalive_wait()):
                 self.ping()
                 if self.app_name:
                     self.connect_status(connected=True)
@@ -498,6 +698,21 @@ class Hapbeat:
         )
         self._keepalive_thread.start()
 
+    def _keepalive_wait(self) -> float:
+        """The keep-alive interval, capped unless every known device is
+        legacy: a v2 device lease expires after 15 s without PING, and a
+        device not yet classified (or none heard yet) may turn out to be v2."""
+        with self._devices_lock:
+            states = [self._stream_states.get(ip) for ip in self._devices]
+            states.extend(self._stream_states.values())
+            all_legacy = bool(states) and all(
+                state is not None and state.endpoint_class is EndpointClass.LEGACY
+                for state in states
+            )
+        if all_legacy:
+            return self._keepalive_interval
+        return min(self._keepalive_interval, V2_LEASE_REFRESH_INTERVAL)
+
     def _stop_keepalive(self) -> None:
         if self._keepalive_stop is not None:
             self._keepalive_stop.set()

hapbeat/launchpad.py

@@ -131,7 +131,8 @@ class App:
         if not event:
             return {"ok": False, "error": "event id is empty"}
         ok = self.hb.play(event, _num(p, "gain", 0.5, 0, 1),
-                          target=str(p.get("target", "")))
+                          target=str(p.get("target", "")),
+                          pan=_num(p, "pan", 0.0, -1, 1))
         return {"ok": bool(ok)}
 
     def stop_all(self) -> dict: