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

hapbeat/__init__.py

@@ -17,9 +17,15 @@ from __future__ import annotations
 
 from . import protocol
 from .client import DEFAULT_BROADCAST, DEFAULT_PORT, UdpClient
-from .clip import ClipStreamer
 from .eventmap import EventDef, EventMap
 from .hapbeat import Device, Hapbeat, connect
+from .stream import (
+    DeferredReason,
+    PlaybackStatus,
+    StreamEndpoint,
+    StreamHub,
+    StreamPlayback,
+)
 from .wav import WavPcm, read_wav_pcm16
 
 try:  # populated from installed package metadata
@@ -28,9 +34,9 @@ try:  # populated from installed package metadata
     try:
         __version__ = version("hapbeat-python-sdk")
     except PackageNotFoundError:  # running from a source checkout
-        __version__ = "0.2.0+local"
+        __version__ = "0.3.0+local"
 except ImportError:  # pragma: no cover
-    __version__ = "0.2.0+local"
+    __version__ = "0.3.0+local"
 
 __all__ = [
     "connect",
@@ -38,7 +44,11 @@ __all__ = [
     "Device",
     "EventMap",
     "EventDef",
-    "ClipStreamer",
+    "StreamHub",
+    "StreamPlayback",
+    "StreamEndpoint",
+    "PlaybackStatus",
+    "DeferredReason",
     "WavPcm",
     "read_wav_pcm16",
     "UdpClient",

hapbeat/cli.py

@@ -33,6 +33,8 @@ def build_parser() -> argparse.ArgumentParser:
     p_play = sub.add_parser("play", help="play an event by id")
     p_play.add_argument("event_id")
     p_play.add_argument("--gain", type=float, default=None, help="0..1 (default: kit baseline)")
+    p_play.add_argument("--pan", type=float, default=0.0,
+                        help="-1 left .. 0 centre .. +1 right (default 0)")
     _add_common(p_play)
 
     p_stop = sub.add_parser("stop", help="stop one event id")
@@ -106,9 +108,19 @@ def main(argv: list[str] | None = None) -> int:
 
     hb = connect(port=args.port, default_target=getattr(args, "target", ""), keepalive=False)
     try:
+        if args.command in ("play", "stop", "stop-all"):
+            # Discover before sending. Without a PONG the SDK knows no devices,
+            # so the command would go out as a broadcast — which the AP holds
+            # back until the next DTIM beacon, and which on a multi-homed host
+            # may leave through an interface with no Hapbeat behind it. One
+            # reply is enough to pick the subnet and unicast, and it normally
+            # arrives in a few milliseconds; the wait only costs the full
+            # window when nothing is there to answer.
+            hb.discover(timeout=0.4, stop_early=True)
+
         if args.command == "play":
-            ok = hb.play(args.event_id, args.gain)
-            print(f"play {args.event_id} gain={args.gain if args.gain is not None else 'baseline'} -> {'sent' if ok else 'FAILED'}")
+            ok = hb.play(args.event_id, args.gain, pan=args.pan)
+            print(f"play {args.event_id} gain={args.gain if args.gain is not None else 'baseline'} pan={args.pan} -> {'sent' if ok else 'FAILED'}")
         elif args.command == "stop":
             print("sent" if hb.stop(args.event_id) else "FAILED")
         elif args.command == "stop-all":

hapbeat/client.py

@@ -13,6 +13,13 @@ Design note — port binding:
     back to an ephemeral bind: sends still work and PING replies still arrive
     at the ephemeral source port; only async broadcast pushes on 7700 are
     missed, which level-1 does not rely on.
+
+Design note — broadcast destinations:
+    Discovery fans out across every local subnet (see :class:`BroadcastRoute`),
+    while playback goes to exactly one destination. Keeping those two apart is
+    not a detail: firmware older than v0.3.0 does not de-duplicate PLAY/STOP by
+    sequence number, so a device reachable on two destinations would fire the
+    haptic twice. PING and CONNECT_STATUS are idempotent and safe to duplicate.
 """
 
 from __future__ import annotations
@@ -21,9 +28,10 @@ import logging
 import socket
 import threading
 import time
-from typing import Callable, Iterable, Optional
+from typing import Callable, Iterable, List, Optional
 
 from . import protocol
+from .netif import local_ipv4_subnets
 
 logger = logging.getLogger("hapbeat")
 
@@ -32,6 +40,87 @@ DEFAULT_BROADCAST = "255.255.255.255"
 
 PongCallback = Callable[[dict, str], None]
 
+# Stand-in "destination" for the case where a whole fan-out failed, so that
+# outage gets the same once-per-outage treatment as a single address.
+_ALL_DESTINATIONS = "all broadcast destinations"
+
+
+def _to_uint32(dotted: str) -> int:
+    a, b, c, d = (int(p) for p in dotted.split("."))
+    return (a << 24) | (b << 16) | (c << 8) | d
+
+
+def _to_dotted(value: int) -> str:
+    return "{}.{}.{}.{}".format(
+        (value >> 24) & 0xFF, (value >> 16) & 0xFF, (value >> 8) & 0xFF, value & 0xFF
+    )
+
+
+class BroadcastRoute:
+    """One address the SDK can broadcast to.
+
+    ``255.255.255.255`` leaves a multi-homed host through the single interface
+    with the lowest metric. On a machine running Hyper-V / WSL2 / Docker that is
+    often an always-up virtual switch with no Hapbeat behind it — and no
+    Ethernet cable is needed for that to happen, which is why the symptom looks
+    nothing like "multi-homed". A subnet-directed address (``192.168.0.255``)
+    resolves through the directly-connected route for its subnet instead, so the
+    metric never applies. That is also why hapbeat-helper kept working on such a
+    host: it finds devices over mDNS and unicasts, which resolves the same way.
+    """
+
+    __slots__ = ("addr", "network", "mask", "limited")
+
+    def __init__(self, addr: str, network: int = 0, mask: int = 0,
+                 limited: bool = False) -> None:
+        self.addr = addr
+        self.network = network
+        self.mask = mask
+        self.limited = limited
+
+    def contains(self, ip: str) -> bool:
+        """Whether ``ip`` sits on this route's subnet."""
+        if self.limited or not self.mask:
+            return False
+        try:
+            return (_to_uint32(ip) & self.mask) == self.network
+        except (ValueError, AttributeError):
+            return False
+
+    def __repr__(self) -> str:  # pragma: no cover — debugging aid
+        return f"BroadcastRoute({self.addr})"
+
+
+def enumerate_broadcast_routes() -> List[BroadcastRoute]:
+    """One destination per local IPv4 subnet, plus the limited broadcast.
+
+    The address comes from each interface's real mask rather than being assumed
+    to end in ``.255``: a /16 broadcasts to ``x.y.255.255`` and a /25 to
+    ``x.y.z.127``, and the subnet itself is whatever the router hands out.
+    Deduplicated by address — two interfaces on one subnet (a laptop docked over
+    Ethernet while Wi-Fi is still up) would otherwise deliver every packet twice.
+
+    The limited broadcast is always kept as a catch-all, so SoftAP setups and
+    platforms whose interfaces cannot be enumerated behave exactly as before.
+    """
+    routes: List[BroadcastRoute] = []
+    seen = set()
+
+    for ip, prefix in local_ipv4_subnets():
+        try:
+            ip_value = _to_uint32(ip)
+        except ValueError:
+            continue
+        mask = (0xFFFFFFFF << (32 - prefix)) & 0xFFFFFFFF
+        addr = _to_dotted((ip_value & mask) | (~mask & 0xFFFFFFFF))
+        if addr in seen:
+            continue
+        seen.add(addr)
+        routes.append(BroadcastRoute(addr, network=ip_value & mask, mask=mask))
+
+    routes.append(BroadcastRoute(DEFAULT_BROADCAST, limited=True))
+    return routes
+
 
 class UdpClient:
     """Broadcast-capable UDP socket plus a PONG receive loop."""
@@ -51,16 +140,35 @@ class UdpClient:
         # also receive the device's unsolicited broadcasts (daemon use).
         self.bind_port = bind_port
         self.broadcast_addr = broadcast_addr
+        # An explicit broadcast_addr is the caller naming the destination, so
+        # honour it verbatim: no enumeration, no fan-out, no route locking.
+        # This doubles as the escape hatch for anyone who does need to pin the
+        # destination by hand, which is why there is no separate setting.
+        self._auto_routes = broadcast_addr == DEFAULT_BROADCAST
+        self._routes: List[BroadcastRoute] = []
+        # The route a device actually answered on; None until the first PONG.
+        # Written from the receive thread, read from every sending thread —
+        # rebinding one attribute, which is atomic under the GIL.
+        self._locked_route: Optional[BroadcastRoute] = None
         self._sock: Optional[socket.socket] = None
         self._thread: Optional[threading.Thread] = None
         self._running = False
         self._bound_well_known = False
+        # Destinations currently in a failed state, so each outage is reported
+        # once rather than once per packet. See _note_send_failed.
+        self._failed_destinations: set[str] = set()
         self._pong_callbacks: list[PongCallback] = []
 
     # ── Lifecycle ───────────────────────────────────────────────────
     def open(self) -> None:
         if self._sock is not None:
             return
+        # Enumerated per open() rather than once per process: the host's
+        # interfaces change when a laptop is docked, a VPN comes up or Wi-Fi
+        # moves to another network.
+        self._routes = enumerate_broadcast_routes() if self._auto_routes else []
+        self._locked_route = None
+        self._failed_destinations = set()
         sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
         sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
         # Windows only: a prior sendto() to an unreachable peer queues an ICMP
@@ -131,20 +239,129 @@ class UdpClient:
             pass
 
     # ── Send ────────────────────────────────────────────────────────
+    def broadcast_destination(self) -> str:
+        """The single address a broadcast currently goes to.
+
+        Once a device has answered this is its subnet's broadcast address;
+        before that (and whenever the caller named ``broadcast_addr``) it is the
+        limited broadcast, exactly as it has always been.
+        """
+        locked = self._locked_route
+        return locked.addr if locked is not None else self.broadcast_addr
+
+    def _note_send_failed(self, dst: str, exc: OSError) -> None:
+        """Report a failed send at most once per destination, per outage.
+
+        A link that fails keeps failing, and stream chunks go out roughly 100
+        times a second — logging every one would bury the very lines an operator
+        needs. Tracked per destination rather than globally: a host normally has
+        an adapter that can never carry a broadcast (Bluetooth PAN, Wi-Fi
+        Direct, a virtual switch), and one shared flag would flip to "failed" and
+        back to "recovered" on every single fan-out. Cleared when that same
+        destination works again, so a later, unrelated outage is still reported.
+        """
+        if dst in self._failed_destinations:
+            return
+        self._failed_destinations.add(dst)
+        logger.warning(
+            "UDP send to %s:%d failed: %s. The socket stays open; further send "
+            "errors to this destination are silenced until it recovers.",
+            dst, self.port, exc)
+
+    def _note_send_ok(self, dst: str) -> None:
+        """Say once that a destination works again.
+
+        Without this an unattended installation's log shows when haptics broke
+        but never whether they came back.
+        """
+        if dst not in self._failed_destinations:
+            return
+        self._failed_destinations.discard(dst)
+        logger.info("UDP sending to %s recovered.", dst)
+
     def send(self, packet: bytes, addr: Optional[str] = None) -> bool:
-        """Send a prebuilt packet. ``addr=None`` -> broadcast."""
+        """Send a prebuilt packet. ``addr=None`` -> broadcast.
+
+        One destination only. A failure is reported but never tears anything
+        down: a lost datagram says nothing about whether the socket is still
+        usable, and closing it here is what turns one Wi-Fi hiccup into a
+        session that never recovers.
+        """
         sock = self._sock
         if sock is None:
             logger.error("send before open()")
             return False
-        dst = self.broadcast_addr if not addr else addr
+        dst = self.broadcast_destination() if not addr else addr
         try:
             sock.sendto(packet, (dst, self.port))
+            self._note_send_ok(dst)
             return True
         except OSError as exc:
-            logger.warning("UDP send to %s:%d failed: %s", dst, self.port, exc)
+            self._note_send_failed(dst, exc)
             return False
 
+    def send_discovery(self, packet: bytes) -> bool:
+        """Send on every candidate broadcast destination.
+
+        Reserved for PING and CONNECT_STATUS. Both are idempotent, so a device
+        reachable on two destinations simply receives the message twice with no
+        visible effect — whereas duplicating PLAY would fire the haptic twice on
+        firmware that predates sequence de-duplication. This fan-out is what
+        reaches a device the limited broadcast never gets to, and the PONG it
+        provokes is what pins playback to the right subnet.
+        """
+        sock = self._sock
+        if sock is None:
+            logger.error("send before open()")
+            return False
+        # Already pinned to a subnet, or no enumeration to fan out over: one
+        # destination, same as any other packet.
+        if self._locked_route is not None or not self._routes:
+            return self.send(packet)
+
+        sent = False
+        last_error: Optional[OSError] = None
+        for route in self._routes:
+            try:
+                sock.sendto(packet, (route.addr, self.port))
+                sent = True
+                self._note_send_ok(route.addr)
+            except OSError as exc:
+                # Routine, and not worth a warning on its own: most hosts carry
+                # an adapter that can never take a broadcast (Bluetooth PAN,
+                # Wi-Fi Direct, an idle virtual switch). Trying anyway and
+                # letting the others through is exactly what this fan-out is
+                # for. Only total failure below is worth an operator's
+                # attention — the difference is "one path is dead" versus
+                # "discovery is dead".
+                last_error = exc
+                logger.debug("discovery send to %s:%d failed: %s",
+                             route.addr, self.port, exc)
+        if sent:
+            # Clear the "nothing got out" state too, so a second, later outage
+            # is reported instead of being swallowed by the first one's flag.
+            self._note_send_ok(_ALL_DESTINATIONS)
+        elif last_error is not None:
+            self._note_send_failed(_ALL_DESTINATIONS, last_error)
+        return sent
+
+    def _lock_route_for(self, ip: str) -> None:
+        """Pin broadcasts to the subnet a device actually replied from.
+
+        First reply wins, and the choice lasts until the socket is reopened.
+        With devices on two subnets at once this settles on whichever answered
+        first; broadcasts do not cross subnets anyway, so the alternative is not
+        reaching both, it is reaching neither reliably.
+        """
+        if self._locked_route is not None or not self._routes:
+            return
+        for route in self._routes:
+            if route.contains(ip):
+                self._locked_route = route
+                logger.info("broadcasting to %s (a device answered from %s)",
+                            route.addr, ip)
+                return
+
     def send_many(self, packet: bytes, addrs: Iterable[str]) -> bool:
         """Unicast the same packet to several devices.
 
@@ -183,6 +400,10 @@ class UdpClient:
             if pong is None:
                 continue
             ip = addr[0]
+            # A reply proves which subnet the device is really on. Until this
+            # happens a broadcast still goes out limited, which on a multi-homed
+            # host may be leaving through an interface with no Hapbeat behind it.
+            self._lock_route_for(ip)
             for cb in list(self._pong_callbacks):
                 try:
                     cb(pong, ip)