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

hapbeat/__init__.py

@@ -5,7 +5,7 @@ Quick start::
     import hapbeat
 
     hb = hapbeat.connect(app_name="MyExperiment")
-    hb.play("impact.hit", gain=0.3)
+    hb.play("sample-kit.sine_100hz", gain=0.3)
     hb.stop_all()
     hb.close()
 
@@ -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.1.0+local"
+        __version__ = "0.3.0+local"
 except ImportError:  # pragma: no cover
-    __version__ = "0.1.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

@@ -3,8 +3,8 @@
 Examples::
 
     hapbeat scan
-    hapbeat play impact.hit --gain 0.3
-    hapbeat stop impact.hit
+    hapbeat play sample-kit.sine_100hz --gain 0.3
+    hapbeat stop sample-kit.sine_100hz
     hapbeat stop-all
     hapbeat osc-bridge --listen 7702
     hapbeat launchpad
@@ -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")
@@ -72,6 +74,12 @@ def build_parser() -> argparse.ArgumentParser:
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
 
+    # 新しい版が出ていれば stderr に 1 行だけ (同じ版では 2 回目を出さない)。
+    # キャッシュが無ければ裏で取りに行くだけでコマンドは待たせない。
+    # ライブラリ import 側では絶対に呼ばない — CLI 実行時のみ (DEC-053 §5.4)。
+    from . import update_check
+    update_check.notify_cli(__version__)
+
     if args.command == "osc-bridge":
         from .osc import OscBridge
 
@@ -100,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

@@ -1,8 +1,10 @@
 """UDP transport for the Hapbeat SDK.
 
-Owns one datagram socket configured for broadcast. Sends command packets to
-the LAN broadcast address and runs a background thread that collects PONG
-replies so device discovery works.
+Owns one datagram socket configured for broadcast. Sends packets either to a
+known device (unicast) or to the LAN broadcast address, and runs a background
+thread that collects PONG replies so device discovery works. Which of the two
+a given packet takes is decided one layer up, in :class:`hapbeat.Hapbeat`,
+which is the layer that tracks devices.
 
 Design note — port binding:
     The standard transport is Wi-Fi UDP broadcast (see workspace CLAUDE.md).
@@ -11,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
@@ -19,9 +28,10 @@ import logging
 import socket
 import threading
 import time
-from typing import Callable, Optional
+from typing import Callable, Iterable, List, Optional
 
 from . import protocol
+from .netif import local_ipv4_subnets
 
 logger = logging.getLogger("hapbeat")
 
@@ -30,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."""
@@ -49,18 +140,51 @@ 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
+        # port-unreachable, which Winsock surfaces as ConnectionResetError
+        # (WinError 10054) on the *next* recvfrom() — even on this unconnected
+        # socket. Once we unicast (a device that is off, rebooting, or being
+        # reflashed is unreachable) that becomes routine, and the recv loop
+        # below would die on it: the SDK would then go deaf to ALL PONGs until
+        # the process restarts. SIO_UDP_CONNRESET=False tells Windows to ignore
+        # those resets. No-op elsewhere (the constant is Windows-only).
+        # Same fix as hapbeat-helper f06fa04, which shipped before this SDK.
+        if hasattr(socket, "SIO_UDP_CONNRESET"):
+            try:
+                sock.ioctl(socket.SIO_UDP_CONNRESET, False)
+            except OSError as exc:
+                logger.debug("SIO_UDP_CONNRESET ioctl failed (non-fatal): %s", exc)
         if self.bind_port == self.port:
             # Only when contending for the shared well-known port do we ask to
             # reuse it; an ephemeral bind needs no reuse and must not steal a
@@ -115,20 +239,142 @@ 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.
+
+        Returns True if at least one send succeeded. One unreachable device
+        (powered off between its last PONG and now) must not stop the packet
+        from reaching the others, so failures are logged and skipped.
+        """
+        sent = False
+        for addr in addrs:
+            if self.send(packet, addr):
+                sent = True
+        return sent
+
     # ── Recv loop ───────────────────────────────────────────────────
     def _recv_loop(self) -> None:
         while self._running:
@@ -139,12 +385,25 @@ class UdpClient:
                 data, addr = sock.recvfrom(4096)
             except socket.timeout:
                 continue
-            except OSError:
-                break
+            except OSError as exc:
+                if not self._running or self._sock is None:
+                    break  # closed by close() — expected exit
+                # Still running: residual ICMP-unreachable (should be
+                # suppressed by SIO_UDP_CONNRESET above, but stay defensive in
+                # case the ioctl was unavailable) or a brief NIC flap. Breaking
+                # here is exactly what makes an SDK go permanently deaf to
+                # PONGs, so back off briefly and keep listening.
+                logger.debug("UDP recv transient error (continuing): %s", exc)
+                time.sleep(0.2)
+                continue
             pong = protocol.parse_pong(data)
             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)

hapbeat/eventmap.py

@@ -139,7 +139,7 @@ class EventMap:
             {
               "kit": "kits/my-kit",          # kit folder, relative to this file
               "events": {
-                "impact.hit": { "target": "player_1/chest", "gain": 0.8 },
+                "sample-kit.sine_100hz": { "target": "player_1/chest", "gain": 0.8 },
                 "rain.loop":  { "target": "*/back" }
               }
             }