hapbeat-python-sdk 0.1.0__py3-none-any.whl → 0.2.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()
 
@@ -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/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/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/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/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/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>

hapbeat/protocol.py

@@ -196,6 +196,51 @@ def build_stream_end(seq: int) -> bytes:
     return build_packet(CMD_STREAM_END, seq, b"")
 
 
+# ── Device addressing ───────────────────────────────────────────────
+def address_matches(target: Optional[str], device_address: Optional[str]) -> bool:
+    """Does ``device_address`` accept a packet aimed at ``target``?
+
+    A port of the firmware's ``addressMatch()``
+    (hapbeat-device-firmware/src/address_match.cpp), which is the authority:
+    the device re-applies this filter on receipt, so the SDK only uses it to
+    pick unicast destinations, never to decide what plays.
+
+    Rules (contracts/specs/device-addressing.md §4.3):
+
+    - an empty target matches every address;
+    - both strings are split on ``/`` and compared **positionally**, so
+      ``group_2`` alone is compared against the *player* slot and never
+      matches — write ``*/*/group_2``;
+    - a ``*`` target segment matches any single address segment;
+    - fewer target segments than address segments is a front-match (extra
+      address segments do not cause a mismatch);
+    - more target segments than address segments is a mismatch;
+    - a single trailing ``/`` is ignored (``"player_1/" == "player_1"``),
+      because firmware's pointer walk exits on the terminator rather than
+      producing an empty segment. Splitting naively here would drop a device
+      the firmware *would* have accepted.
+    """
+    if not target:
+        return True
+
+    target_segments = target.split("/")
+    address_segments = (device_address or "").split("/")
+
+    # Only the last empty segment is dropped, and only once: "a//" really does
+    # compare an empty segment in firmware, and still mismatches.
+    count = len(target_segments)
+    if count > 1 and target_segments[count - 1] == "":
+        count -= 1
+
+    for i in range(count):
+        if i >= len(address_segments):
+            return False  # target longer than address = mismatch
+        if target_segments[i] != "*" and target_segments[i] != address_segments[i]:
+            return False
+
+    return True  # front-match or exact match
+
+
 # ── Response parsers ────────────────────────────────────────────────
 def _read_cstr(buf: bytes) -> tuple[str, bytes]:
     idx = buf.find(b"\x00")

hapbeat/update_check.py

@@ -0,0 +1,213 @@
+"""Update notice — 「新しい hapbeat-python-sdk が出ています」を 1 回だけ伝える。
+
+情報源は Hapbeat の release feed (``https://devtools.hapbeat.com/releases.json``)。
+仕様は hapbeat-contracts ``specs/release-feed.md`` (DEC-053)。feed は GitHub の
+タグではなく **PyPI に実際に上がっている版** を載せているので、ここに出る版は
+必ず ``pip install -U`` で取得できる。
+
+守っている作法 (spec §5):
+
+* **``import hapbeat`` では絶対にネットワークへ出ない。** チェックするのは
+  ``hapbeat`` コマンドを実行したときだけ。ライブラリの import が外部通信を
+  するのは、CI・オフライン環境・サンドボックスで有害な副作用になる。
+* **24 時間に 1 回**まで (§5.1 B)。閉じる操作を要求しない 1 行なので版ごとの永続
+  抑制はしないが、``hapbeat play`` のような短命コマンドは連続実行され得るため
+  時間で間引く。**新しい版が出たら間隔を待たずに出す**。
+* 取得失敗は**完全にサイレント**。「最新版を確認できませんでした」は出さない。
+* CLI の実行を**待たせない**。キャッシュがあればそれを使い、無ければ裏で取りに
+  行くだけで、その回は何も出さない (次回の実行で出る)。
+* 出力は英語 (この CLI の他の出力に合わせる)。
+* ``HAPBEAT_NO_UPDATE_CHECK=1`` で無効化できる。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import threading
+import time
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+FEED_URL = "https://devtools.hapbeat.com/releases.json"
+PRODUCT_ID = "python-sdk"
+TIMEOUT_S = 3.0
+CACHE_TTL_S = 24 * 60 * 60
+#: 同じ版について再通知するまでの最短間隔。`hapbeat play` のような短命コマンドが
+#: 連続実行されても 1 日 1 行に収める。版が変われば間隔を待たずに出す。
+NOTIFY_INTERVAL_S = 24 * 60 * 60
+STATE_FILENAME = "update-check.json"
+
+
+def config_dir() -> Path:
+    if sys.platform == "win32":
+        base = Path(os.environ.get("APPDATA", str(Path.home())))
+        return base / "hapbeat"
+    return Path.home() / ".config" / "hapbeat"
+
+
+def opted_out() -> bool:
+    return os.environ.get("HAPBEAT_NO_UPDATE_CHECK", "").strip() not in ("", "0", "false")
+
+
+# --------------------------------------------------------------------------
+# version compare
+
+
+def parse_version(v: str | None) -> tuple[int, ...]:
+    """``0.2.0`` / ``v0.2.0`` / ``0.2.0dev1`` → ``(0, 2, 0)``。解釈不能なら ``()``。"""
+    if not v:
+        return ()
+    s = str(v).strip().lstrip("vV")
+    head = s.split("-", 1)[0].split("+", 1)[0]
+    out: list[int] = []
+    for part in head.split("."):
+        digits = ""
+        for ch in part:
+            if ch.isdigit():
+                digits += ch
+            else:
+                break
+        if not digits:
+            return ()
+        out.append(int(digits))
+    return tuple(out)
+
+
+def is_newer(candidate: str | None, baseline: str | None) -> bool:
+    """比較不能なら False (黙る側に倒す)。"""
+    a, b = parse_version(candidate), parse_version(baseline)
+    if not a or not b:
+        return False
+    return a > b
+
+
+# --------------------------------------------------------------------------
+# state
+
+
+def _state_path() -> Path:
+    return config_dir() / STATE_FILENAME
+
+
+def _load_state() -> dict[str, Any]:
+    try:
+        return json.loads(_state_path().read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _save_state(state: dict[str, Any]) -> None:
+    try:
+        p = _state_path()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(json.dumps(state), encoding="utf-8")
+    except Exception:
+        pass
+
+
+# --------------------------------------------------------------------------
+# feed
+
+
+def _fetch_entry() -> dict[str, Any] | None:
+    req = urllib.request.Request(FEED_URL, headers={"User-Agent": "hapbeat-python-sdk"})
+    with urllib.request.urlopen(req, timeout=TIMEOUT_S) as res:  # noqa: S310 (fixed https URL)
+        feed = json.loads(res.read().decode("utf-8"))
+    if feed.get("schema_version") != 1:
+        return None
+    entry = feed.get("products", {}).get(PRODUCT_ID)
+    return entry if isinstance(entry, dict) else None
+
+
+def cached_entry() -> dict[str, Any] | None:
+    """ネットワークを叩かずに、生きているキャッシュだけを返す。"""
+    state = _load_state()
+    entry = state.get("entry")
+    if entry and (time.time() - state.get("checked_at", 0)) < CACHE_TTL_S:
+        return entry
+    return None
+
+
+def refresh(*, use_cache: bool = True) -> dict[str, Any] | None:
+    """feed を取得 (or キャッシュ) する。取得できなければ None。"""
+    if use_cache:
+        cached = cached_entry()
+        if cached:
+            return cached
+    try:
+        entry = _fetch_entry()
+    except Exception:
+        return None
+    if not entry:
+        return None
+    state = _load_state()
+    state["entry"] = entry
+    state["checked_at"] = time.time()
+    _save_state(state)
+    return entry
+
+
+def _refresh_in_background() -> None:
+    threading.Thread(
+        target=lambda: refresh(use_cache=False),
+        name="hapbeat-update-check",
+        daemon=True,
+    ).start()
+
+
+# --------------------------------------------------------------------------
+# public API
+
+
+def pending_notice(current: str, entry: dict[str, Any] | None = None,
+                   *, respect_interval: bool = True) -> str | None:
+    """通知すべきなら 1 行のメッセージを返す。無ければ None。"""
+    if opted_out():
+        return None
+    if entry is None:
+        entry = cached_entry()
+    if not entry:
+        return None
+    latest = entry.get("latest")
+    if not is_newer(latest, current):
+        return None
+    if respect_interval:
+        state = _load_state()
+        # 同じ版を 24h 以内に出していたら黙る。版が変わっていれば即出す。
+        if (state.get("notified") == latest
+                and (time.time() - state.get("notified_at", 0)) < NOTIFY_INTERVAL_S):
+            return None
+    upgrade = entry.get("upgrade") or "pip install -U hapbeat-python-sdk"
+    return f"note: hapbeat-python-sdk {latest} is available ({upgrade})"
+
+
+def mark_notified(latest: str) -> None:
+    state = _load_state()
+    state["notified"] = latest
+    state["notified_at"] = time.time()
+    _save_state(state)
+
+
+def notify_cli(current: str, *, stream=None) -> None:
+    """CLI 実行時のフック。**待たせない**のが最優先。
+
+    キャッシュがあればその場で判定して出す。無ければ裏で取りに行くだけで、
+    その回は黙る (次に CLI を使ったときに出る)。コマンドの実行を数秒
+    ブロックしてまで伝えるほどの用件ではない。
+    """
+    if opted_out():
+        return
+    try:
+        entry = cached_entry()
+        if entry is None:
+            _refresh_in_background()
+            return
+        msg = pending_notice(current, entry)
+        if msg:
+            print(msg, file=stream if stream is not None else sys.stderr)
+            mark_notified(entry["latest"])
+    except Exception:
+        pass  # 更新通知が原因で CLI を壊さない

{hapbeat_python_sdk-0.1.0.dist-info → hapbeat_python_sdk-0.2.0.dist-info}/METADATA

@@ -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.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+hapbeat/__init__.py,sha256=I2L0uVH60jLt69p92jn4xgoXc_n1n8mbVy9biSC2F-8,1279
+hapbeat/__main__.py,sha256=ji2N-J5BX8XSUrihVzwQuttefiOYsu3pTzuYAsgMIUU,120
+hapbeat/cli.py,sha256=-et9uHi__I8x32uhV5gjzebmEOUngVdB5fOMs30uq3A,5027
+hapbeat/client.py,sha256=fMePjstmtvFyfhVhhZ8uXKPXxJRWEQlMOlGiZjNp3pw,8222
+hapbeat/clip.py,sha256=PpVPht61HWiHolLkpCFBXdL7d_3syraaaJUwgF_2J0o,4892
+hapbeat/eventmap.py,sha256=9PfjuEV6BpxYosMpQ2Nk3DZww2rsvP58v7ICUmvi6_k,8397
+hapbeat/hapbeat.py,sha256=0NdNvyxXrD970NB3hQvmxHklicRr1suiZ5D9wPg4ey4,23247
+hapbeat/launchpad.py,sha256=biom1d8ioJQ0tXT7olGyAfpj1I-w7rkPRy582rE7ong,26803
+hapbeat/osc.py,sha256=cD0_QA6M1Km7VhXvPGYLHyWFj_V5uUQAfPG1myYvYxw,4589
+hapbeat/protocol.py,sha256=H8GKFOxFCzfG44s2OhTBt20bpEMxRO0-cC9JxsFZN70,11006
+hapbeat/update_check.py,sha256=0KTYpzXe-WfNR3A3mXXFIHVVzDzZKSbRf4rrnoNBIng,7395
+hapbeat/wav.py,sha256=zAxCWLEliCclFhiOtWlgfqra3Eua89VfwsDOCFtk3lY,1716
+hapbeat_python_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=iaWGp90FSWArzrtS2s0C-hGqRlguPdFt8vxkPT4SEj8,1064
+hapbeat_python_sdk-0.2.0.dist-info/METADATA,sha256=qdi5Yns9lfIiCe2FQSHtQaU7gSB0mdtCoxOJmy3Cl_4,8519
+hapbeat_python_sdk-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+hapbeat_python_sdk-0.2.0.dist-info/entry_points.txt,sha256=6GpFtyk5e9Kh3Y_lDOGPp1jQqYL5eiCK9kbz08cdiek,45
+hapbeat_python_sdk-0.2.0.dist-info/top_level.txt,sha256=FLePhbdKs48thuuow2Z1_X_3V-2oxhDdeOX_bu5to8M,8
+hapbeat_python_sdk-0.2.0.dist-info/RECORD,,

{hapbeat_python_sdk-0.1.0.dist-info → hapbeat_python_sdk-0.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.1)
+Generator: setuptools (83.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

hapbeat_python_sdk-0.1.0.dist-info/RECORD

@@ -1,17 +0,0 @@
-hapbeat/__init__.py,sha256=6FABLnQeXm1nxqiiGLQWyDko1h5Nhr3RuF-vYEBW8n0,1268
-hapbeat/__main__.py,sha256=ji2N-J5BX8XSUrihVzwQuttefiOYsu3pTzuYAsgMIUU,120
-hapbeat/cli.py,sha256=FMCggde6NeWMNXbw5v939dQQ1X0kkY0HUno8TA5L3YE,4624
-hapbeat/client.py,sha256=MGwTbtn6j4uAw0pDLWBDDuOi_u5nyWT3k1IiWu67TPo,5995
-hapbeat/clip.py,sha256=PpVPht61HWiHolLkpCFBXdL7d_3syraaaJUwgF_2J0o,4892
-hapbeat/eventmap.py,sha256=odDRXGt2CmcQsMed7NHlz0pbmQLRqxjti2T9uXxsyCg,8386
-hapbeat/hapbeat.py,sha256=IqNIrKp2j17y4QLse80Wb98BSTGLJ7wGBtDKuUmdgVM,16858
-hapbeat/launchpad.py,sha256=wvnIFLtrux_PzdR7TrsCqIhtOLhLJzXuOdfam7e2tQ4,26792
-hapbeat/osc.py,sha256=cD0_QA6M1Km7VhXvPGYLHyWFj_V5uUQAfPG1myYvYxw,4589
-hapbeat/protocol.py,sha256=WNjjgxO_RP25WF2qZDtC_p_69lUyJ9WGjAMn77i6ITY,8928
-hapbeat/wav.py,sha256=zAxCWLEliCclFhiOtWlgfqra3Eua89VfwsDOCFtk3lY,1716
-hapbeat_python_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=iaWGp90FSWArzrtS2s0C-hGqRlguPdFt8vxkPT4SEj8,1064
-hapbeat_python_sdk-0.1.0.dist-info/METADATA,sha256=3lBi5pbXGtVQdl0P2ca6FwM8G2LbWcvolv1dmtCeFhY,7278
-hapbeat_python_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-hapbeat_python_sdk-0.1.0.dist-info/entry_points.txt,sha256=6GpFtyk5e9Kh3Y_lDOGPp1jQqYL5eiCK9kbz08cdiek,45
-hapbeat_python_sdk-0.1.0.dist-info/top_level.txt,sha256=FLePhbdKs48thuuow2Z1_X_3V-2oxhDdeOX_bu5to8M,8
-hapbeat_python_sdk-0.1.0.dist-info/RECORD,,