hapbeat-python-sdk 0.1.0__tar.gz → 0.2.0__tar.gz

{hapbeat_python_sdk-0.1.0 → hapbeat_python_sdk-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hapbeat-python-sdk
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python SDK for driving Hapbeat haptic devices over Wi-Fi UDP
 Author-email: Hapbeat <yus988@hapbeat.com>
 License: MIT
@@ -71,10 +71,10 @@ a tiny stdlib HTTP server that relays button presses to the device over UDP
 ```python
 import hapbeat
 
-hb = hapbeat.connect(app_name="MyExperiment")  # opens UDP broadcast + keep-alive
-hb.play("impact.hit", gain=0.3)   # fire event "impact.hit" at gain 0.3
-hb.play("impact.hit")             # gain omitted -> kit baseline intensity
-hb.stop("impact.hit")
+hb = hapbeat.connect(app_name="MyExperiment")  # opens the UDP socket + keep-alive
+hb.play("sample-kit.sine_100hz", gain=0.3)   # fire event "sample-kit.sine_100hz" at gain 0.3
+hb.play("sample-kit.sine_100hz")             # gain omitted -> kit baseline intensity
+hb.stop("sample-kit.sine_100hz")
 hb.stop_all()
 hb.close()
 ```
@@ -83,10 +83,10 @@ or as a context manager:
 
 ```python
 with hapbeat.connect(app_name="MyExperiment") as hb:
-    hb.play("impact.hit")
+    hb.play("sample-kit.sine_100hz")
 ```
 
-`"impact.hit"` must be an event id present in the **kit deployed to the
+`"sample-kit.sine_100hz"` must be an event id present in the **kit deployed to the
 device** (via [Hapbeat Studio](https://devtools.hapbeat.com)). The SDK sends
 the *instruction*; the waveform lives in the kit on the device.
 
@@ -97,6 +97,19 @@ for dev in hb.discover(timeout=1.5):
     print(dev.ip, dev.address, dev.firmware_version)
 ```
 
+### How packets are sent
+
+Commands and clip streams are **unicast** to every device that answered a PING,
+and broadcast only while no device is known. Wi-Fi APs hold broadcast frames
+until their next DTIM beacon (100–300 ms) whenever any client on the AP is
+power-saving, which is heard as late haptics and stuttering streams; unicast is
+not batched that way. The 5-second keep-alive PING keeps that table current, so
+leave `keepalive=True`.
+
+Pass `connect(unicast=False)` to always broadcast — worth it when many devices
+must fire in lockstep, since one broadcast reaches them all at once while N
+unicasts go out one after another.
+
 ## EventMap — the tuning side (optional)
 
 Keep per-event default gains in one place and let `play("id")` resolve them,
@@ -105,11 +118,11 @@ so firing code never hard-codes intensities:
 ```python
 em = hapbeat.EventMap.from_manifest("my-kit/my-kit-manifest.json")
 hb = hapbeat.connect(event_map=em)
-hb.play("impact.hit")        # uses the kit manifest's intensity for this event
+hb.play("sample-kit.sine_100hz")        # uses the kit manifest's intensity for this event
 ```
 
 `EventMap` reads the kit manifest (schema 2.0.0) `intensity` as the baseline
-gain. You can also build one by hand: `EventMap.from_dict({"impact.hit": 0.5})`.
+gain. You can also build one by hand: `EventMap.from_dict({"sample-kit.sine_100hz": 0.5})`.
 
 ### Haptic file — add targeting on top of the kit
 
@@ -123,15 +136,23 @@ resolves the target without the caller passing it:
 {
   "kit": "kits/my-kit",
   "events": {
-    "impact.hit": { "target": "player_1/chest", "gain": 0.8 },
-    "rain.loop":  { "target": "*/back" }
+    "sample-kit.sine_100hz": { "target": "player_1/pos_neck", "gain": 0.8 },
+    "rain.loop":  { "target": "*/pos_back" }
   }
 }
 ```
 
+Targets are matched **positionally**: segment *i* of the target is compared
+with segment *i* of the device address, `*` stands for one **whole** segment
+(`pos_*` is compared literally — use `player_1/*`), and a short target
+front-matches. Device addresses are always `player_<N>/<position>/group_<M>`,
+defaulting to `player_1` / `group_1`, so a group has to be written
+`*/*/group_2`: plain `group_2` is compared against the *player* slot and never
+matches.
+
 ```python
 hb = hapbeat.connect(app_name="MyApp", haptics="haptics.json")
-hb.play("impact.hit")     # goes to player_1/chest at gain 0.8 — from the file
+hb.play("sample-kit.sine_100hz")     # goes to player_1/pos_neck at gain 0.8 — from the file
 ```
 
 ## Two playback modes: command and clip
@@ -158,7 +179,7 @@ my-app/
 ```python
 import hapbeat
 hb = hapbeat.connect(app_name="MyApp", kit="kits/my-kit")
-hb.play("impact.hit")     # command -> device plays its installed clip
+hb.play("sample-kit.sine_100hz")     # command -> device plays its installed clip
 hb.play("rain.loop")      # clip    -> SDK streams stream-clips/<wav> over UDP
 hb.stop("rain.loop")      # ends the active stream
 ```
@@ -189,7 +210,7 @@ See [docs/osc.md](docs/osc.md) for the address spec.
 
 ```bash
 hapbeat scan                       # list devices on the LAN
-hapbeat play impact.hit --gain 0.3
+hapbeat play sample-kit.sine_100hz --gain 0.3
 hapbeat stop-all
 hapbeat launchpad                  # browser UI for all of the above
 ```

{hapbeat_python_sdk-0.1.0 → hapbeat_python_sdk-0.2.0}/README.md

@@ -38,10 +38,10 @@ a tiny stdlib HTTP server that relays button presses to the device over UDP
 ```python
 import hapbeat
 
-hb = hapbeat.connect(app_name="MyExperiment")  # opens UDP broadcast + keep-alive
-hb.play("impact.hit", gain=0.3)   # fire event "impact.hit" at gain 0.3
-hb.play("impact.hit")             # gain omitted -> kit baseline intensity
-hb.stop("impact.hit")
+hb = hapbeat.connect(app_name="MyExperiment")  # opens the UDP socket + keep-alive
+hb.play("sample-kit.sine_100hz", gain=0.3)   # fire event "sample-kit.sine_100hz" at gain 0.3
+hb.play("sample-kit.sine_100hz")             # gain omitted -> kit baseline intensity
+hb.stop("sample-kit.sine_100hz")
 hb.stop_all()
 hb.close()
 ```
@@ -50,10 +50,10 @@ or as a context manager:
 
 ```python
 with hapbeat.connect(app_name="MyExperiment") as hb:
-    hb.play("impact.hit")
+    hb.play("sample-kit.sine_100hz")
 ```
 
-`"impact.hit"` must be an event id present in the **kit deployed to the
+`"sample-kit.sine_100hz"` must be an event id present in the **kit deployed to the
 device** (via [Hapbeat Studio](https://devtools.hapbeat.com)). The SDK sends
 the *instruction*; the waveform lives in the kit on the device.
 
@@ -64,6 +64,19 @@ for dev in hb.discover(timeout=1.5):
     print(dev.ip, dev.address, dev.firmware_version)
 ```
 
+### How packets are sent
+
+Commands and clip streams are **unicast** to every device that answered a PING,
+and broadcast only while no device is known. Wi-Fi APs hold broadcast frames
+until their next DTIM beacon (100–300 ms) whenever any client on the AP is
+power-saving, which is heard as late haptics and stuttering streams; unicast is
+not batched that way. The 5-second keep-alive PING keeps that table current, so
+leave `keepalive=True`.
+
+Pass `connect(unicast=False)` to always broadcast — worth it when many devices
+must fire in lockstep, since one broadcast reaches them all at once while N
+unicasts go out one after another.
+
 ## EventMap — the tuning side (optional)
 
 Keep per-event default gains in one place and let `play("id")` resolve them,
@@ -72,11 +85,11 @@ so firing code never hard-codes intensities:
 ```python
 em = hapbeat.EventMap.from_manifest("my-kit/my-kit-manifest.json")
 hb = hapbeat.connect(event_map=em)
-hb.play("impact.hit")        # uses the kit manifest's intensity for this event
+hb.play("sample-kit.sine_100hz")        # uses the kit manifest's intensity for this event
 ```
 
 `EventMap` reads the kit manifest (schema 2.0.0) `intensity` as the baseline
-gain. You can also build one by hand: `EventMap.from_dict({"impact.hit": 0.5})`.
+gain. You can also build one by hand: `EventMap.from_dict({"sample-kit.sine_100hz": 0.5})`.
 
 ### Haptic file — add targeting on top of the kit
 
@@ -90,15 +103,23 @@ resolves the target without the caller passing it:
 {
   "kit": "kits/my-kit",
   "events": {
-    "impact.hit": { "target": "player_1/chest", "gain": 0.8 },
-    "rain.loop":  { "target": "*/back" }
+    "sample-kit.sine_100hz": { "target": "player_1/pos_neck", "gain": 0.8 },
+    "rain.loop":  { "target": "*/pos_back" }
   }
 }
 ```
 
+Targets are matched **positionally**: segment *i* of the target is compared
+with segment *i* of the device address, `*` stands for one **whole** segment
+(`pos_*` is compared literally — use `player_1/*`), and a short target
+front-matches. Device addresses are always `player_<N>/<position>/group_<M>`,
+defaulting to `player_1` / `group_1`, so a group has to be written
+`*/*/group_2`: plain `group_2` is compared against the *player* slot and never
+matches.
+
 ```python
 hb = hapbeat.connect(app_name="MyApp", haptics="haptics.json")
-hb.play("impact.hit")     # goes to player_1/chest at gain 0.8 — from the file
+hb.play("sample-kit.sine_100hz")     # goes to player_1/pos_neck at gain 0.8 — from the file
 ```
 
 ## Two playback modes: command and clip
@@ -125,7 +146,7 @@ my-app/
 ```python
 import hapbeat
 hb = hapbeat.connect(app_name="MyApp", kit="kits/my-kit")
-hb.play("impact.hit")     # command -> device plays its installed clip
+hb.play("sample-kit.sine_100hz")     # command -> device plays its installed clip
 hb.play("rain.loop")      # clip    -> SDK streams stream-clips/<wav> over UDP
 hb.stop("rain.loop")      # ends the active stream
 ```
@@ -156,7 +177,7 @@ See [docs/osc.md](docs/osc.md) for the address spec.
 
 ```bash
 hapbeat scan                       # list devices on the LAN
-hapbeat play impact.hit --gain 0.3
+hapbeat play sample-kit.sine_100hz --gain 0.3
 hapbeat stop-all
 hapbeat launchpad                  # browser UI for all of the above
 ```

{hapbeat_python_sdk-0.1.0 → hapbeat_python_sdk-0.2.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 # Distribution name (pip/pipx). The import package stays `import hapbeat`.
 name = "hapbeat-python-sdk"
-version = "0.1.0"
+version = "0.2.0"
 description = "Python SDK for driving Hapbeat haptic devices over Wi-Fi UDP"
 readme = "README.md"
 requires-python = ">=3.10"

{hapbeat_python_sdk-0.1.0 → hapbeat_python_sdk-0.2.0}/src/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()
 
@@ -28,9 +28,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.2.0+local"
 except ImportError:  # pragma: no cover
-    __version__ = "0.1.0+local"
+    __version__ = "0.2.0+local"
 
 __all__ = [
     "connect",

{hapbeat_python_sdk-0.1.0 → hapbeat_python_sdk-0.2.0}/src/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
@@ -72,6 +72,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
 

{hapbeat_python_sdk-0.1.0 → hapbeat_python_sdk-0.2.0}/src/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).
@@ -19,7 +21,7 @@ import logging
 import socket
 import threading
 import time
-from typing import Callable, Optional
+from typing import Callable, Iterable, Optional
 
 from . import protocol
 
@@ -61,6 +63,20 @@ class UdpClient:
             return
         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
@@ -129,6 +145,19 @@ class UdpClient:
             logger.warning("UDP send to %s:%d failed: %s", dst, self.port, exc)
             return False
 
+    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,8 +168,17 @@ 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

{hapbeat_python_sdk-0.1.0 → hapbeat_python_sdk-0.2.0}/src/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" }
               }
             }

{hapbeat_python_sdk-0.1.0 → hapbeat_python_sdk-0.2.0}/src/hapbeat/hapbeat.py

@@ -11,14 +11,14 @@ Typical use::
     import hapbeat
 
     hb = hapbeat.connect(app_name="MyExperiment")
-    hb.play("impact.hit", gain=0.3)
-    hb.stop("impact.hit")
+    hb.play("sample-kit.sine_100hz", gain=0.3)
+    hb.stop("sample-kit.sine_100hz")
     hb.close()
 
 or as a context manager::
 
     with hapbeat.connect() as hb:
-        hb.play("impact.hit")
+        hb.play("sample-kit.sine_100hz")
 """
 
 from __future__ import annotations
@@ -55,7 +55,11 @@ def _now_us() -> int:
 
 
 class Hapbeat:
-    """A connection to Hapbeat devices over Wi-Fi UDP broadcast."""
+    """A connection to Hapbeat devices over Wi-Fi UDP.
+
+    Commands go out by unicast to every device that answered a recent PING,
+    and by broadcast until one does (see ``unicast`` in :func:`connect`).
+    """
 
     def __init__(
         self,
@@ -72,6 +76,8 @@ class Hapbeat:
         bind_port: int = 0,
         clip_base: Optional[Union[str, Path]] = None,
         stream_send_ahead: float = 0.15,
+        unicast: bool = True,
+        device_ttl: Optional[float] = None,
     ) -> None:
         self._client = UdpClient(port=port, broadcast_addr=broadcast_addr,
                                  bind_port=bind_port)
@@ -92,6 +98,23 @@ class Hapbeat:
         self._keepalive_stop: Optional[threading.Event] = None
         self._keepalive_thread: Optional[threading.Thread] = None
         self._opened = False
+        # Send PLAY/STOP/STOP_ALL/STREAM_* straight to devices we have heard a
+        # PONG from, instead of broadcasting. See _command_destinations.
+        self.unicast = unicast
+        # How long a device stays a unicast destination after its last PONG.
+        # Default: three keep-alive PINGs' worth (min 5 s), the same window the
+        # Unity SDK uses. Too short and every command falls back to broadcast;
+        # too long and we keep unicasting at a device that was powered off,
+        # never returning to broadcast for the rest of the session.
+        self.device_ttl = (
+            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)
@@ -106,7 +129,7 @@ class Hapbeat:
         self._opened = True
         self._client.add_pong_listener(self._on_pong)
         self._client.open()
-        if self._keepalive and self.app_name:
+        if self._keepalive:
             self._start_keepalive()
         return self
 
@@ -149,6 +172,50 @@ class Hapbeat:
             return ev.target
         return self.default_target
 
+    # ── Send routing (unicast vs broadcast) ─────────────────────────
+    #
+    # Wi-Fi broadcast is held back by the AP: whenever any client on the AP is
+    # power-saving, group-addressed frames are buffered until the next DTIM
+    # beacon (100-300 ms). That shows up as a late haptic on one-shot commands
+    # and as periodic dropouts in a clip stream, and the device cannot avoid it
+    # (the delay is caused by *other* clients). Unicast frames are not batched,
+    # and they get MAC-level ACK/retry as a bonus. Measured and confirmed on
+    # the Unity SDK before being ported here.
+    def _alive_devices(self) -> list[Device]:
+        cutoff = time.monotonic() - self.device_ttl
+        with self._devices_lock:
+            return [d for d in self._devices.values() if d.last_seen >= cutoff]
+
+    def _matching_ips(self, target: str) -> list[str]:
+        """Alive devices whose address accepts ``target``.
+
+        A device that has not reported an address (older firmware, or no PONG
+        parsed yet) is kept — fail open. Worst case is one extra unicast
+        packet that the device itself filters out; the opposite mistake would
+        silently drop a command the device would have accepted.
+        """
+        return [
+            d.ip for d in self._alive_devices()
+            if not d.address or protocol.address_matches(target, d.address)
+        ]
+
+    def _send_routed(self, packet: bytes, target: str) -> bool:
+        """Send one PLAY/STOP/STOP_ALL, unicast when we can.
+
+        Falls back to broadcast when unicast is off, when no device has PONGed
+        recently, *and* when every alive device's address mismatches — never
+        skipping the send. The device re-applies the same target filter on
+        receipt, so a broadcast can never fire a device the target did not
+        address; whereas skipping would silently lose the packet whenever our
+        cached address is stale (a STOP lost that way leaves a loop running).
+        """
+        if not self.unicast:
+            return self._client.send(packet)
+        dests = self._matching_ips(target)
+        if not dests:
+            return self._client.send(packet)
+        return self._client.send_many(packet, dests)
+
     # ── Fire API (level-1) ──────────────────────────────────────────
     def play(
         self,
@@ -186,7 +253,7 @@ class Hapbeat:
             target_time_us=target_time_us,
             gain=gain,
         )
-        return self._client.send(pkt)
+        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
@@ -195,18 +262,16 @@ class Hapbeat:
         if ev is not None and ev.streaming:
             self._clip.stop()
             return True
-        pkt = protocol.build_stop(
-            self._next_seq(), event_id, target=self._effective_target(ev, target)
-        )
-        return self._client.send(pkt)
+        target_eff = self._effective_target(ev, target)
+        pkt = protocol.build_stop(self._next_seq(), event_id, target=target_eff)
+        return self._send_routed(pkt, target_eff)
 
     def stop_all(self, *, target: Optional[str] = None) -> bool:
         """Stop every event on matching devices (and any active clip stream)."""
         self._clip.stop()
-        pkt = protocol.build_stop_all(
-            self._next_seq(), target=self._resolve_target(target)
-        )
-        return self._client.send(pkt)
+        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)."""
@@ -335,19 +400,53 @@ class Hapbeat:
         return wav
 
     # ── StreamSink (called by ClipStreamer) ─────────────────────────
+    def _snapshot_stream_destinations(self, target: str) -> None:
+        """Pick the destinations for one stream session.
+
+        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).
+
+        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 _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_begin(self, *, sample_rate: int, channels: int,
                      total_samples: int, gain: float, target: str) -> None:
-        self._client.send(protocol.build_stream_begin(
+        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,
         ))
 
     def stream_data(self, offset: int, data: bytes) -> None:
-        self._client.send(protocol.build_stream_data(self._next_seq(), offset, data))
+        self._send_stream(protocol.build_stream_data(self._next_seq(), offset, data))
 
     def stream_end(self) -> None:
-        self._client.send(protocol.build_stream_end(self._next_seq()))
+        self._send_stream(protocol.build_stream_end(self._next_seq()))
 
     # ── Discovery ───────────────────────────────────────────────────
     def discover(self, timeout: float = 1.0) -> list[Device]:
@@ -374,12 +473,24 @@ class Hapbeat:
 
     # ── Keep-alive thread ───────────────────────────────────────────
     def _start_keepalive(self) -> None:
+        """Periodic PING (+ CONNECT_STATUS when an app name is set).
+
+        The PING is what keeps unicast working: the device answers PONG *only*
+        to a PING (CONNECT_STATUS gets no reply), so without this every device
+        would age out of the destination table after ``device_ttl`` and the
+        session would silently fall back to broadcast forever. It doubles as
+        discovery for devices that join late.
+        """
         self._keepalive_stop = threading.Event()
-        self.connect_status(connected=True)
+        self.ping()
+        if self.app_name:
+            self.connect_status(connected=True)
 
         def loop(stop: threading.Event) -> None:
             while not stop.wait(self._keepalive_interval):
-                self.connect_status(connected=True)
+                self.ping()
+                if self.app_name:
+                    self.connect_status(connected=True)
 
         self._keepalive_thread = threading.Thread(
             target=loop, args=(self._keepalive_stop,),
@@ -410,6 +521,8 @@ def connect(
     haptics: Optional[Union[str, Path]] = None,
     clip_base: Optional[Union[str, Path]] = None,
     stream_send_ahead: float = 0.15,
+    unicast: bool = True,
+    device_ttl: Optional[float] = None,
 ) -> Hapbeat:
     """Open a connection and return a ready :class:`Hapbeat`.
 
@@ -425,6 +538,16 @@ def connect(
       - ``kit`` — a kit folder; ``EventMap.from_kit`` (intensity/clip only,
         no targeting).
     ``clip_base`` overrides where clip WAVs are read (default ``<kit>/stream-clips/``).
+
+    ``unicast=True`` (default) sends PLAY/STOP/STOP_ALL and clip streams
+    straight to the devices that answered a PING, instead of broadcasting —
+    Wi-Fi APs hold broadcast frames until the next DTIM beacon (100-300 ms),
+    which is heard as late haptics and stuttering streams. It falls back to
+    broadcast until a device replies. Set ``unicast=False`` to always
+    broadcast (e.g. many devices that must fire in lockstep, where one
+    broadcast beats N sequential unicasts). ``device_ttl`` is how long a
+    device stays a destination after its last PONG (default: 3 keep-alive
+    intervals, min 5 s).
     """
     if event_map is None:
         if haptics is not None:
@@ -443,4 +566,6 @@ def connect(
         bind_port=bind_port,
         clip_base=clip_base,
         stream_send_ahead=stream_send_ahead,
+        unicast=unicast,
+        device_ttl=device_ttl,
     ).open()

{hapbeat_python_sdk-0.1.0 → hapbeat_python_sdk-0.2.0}/src/hapbeat/launchpad.py

@@ -449,7 +449,7 @@ PAGE = r"""<!doctype html>
   <div class="bar">
     <div class="field" style="flex:2; min-width:220px;">
       <label>Default event id (used when a card's field is blank)</label>
-      <input id="defEvent" class="mono" placeholder="e.g. impact.hit" value="">
+      <input id="defEvent" class="mono" placeholder="e.g. sample-kit.sine_100hz" value="">
     </div>
     <div class="field">
       <label>Target (blank = all)</label>