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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hapbeat-python-sdk
-Version: 0.1.0
+Version: 0.3.0
 Summary: Python SDK for driving Hapbeat haptic devices over Wi-Fi UDP
 Author-email: Hapbeat <yus988@hapbeat.com>
 License: MIT
@@ -71,10 +71,11 @@ 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.play("sample-kit.sine_100hz", pan=-1)     # pan: -1 left / 0 centre / +1 right
+hb.stop("sample-kit.sine_100hz")
 hb.stop_all()
 hb.close()
 ```
@@ -83,10 +84,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 +98,21 @@ for dev in hb.discover(timeout=1.5):
     print(dev.ip, dev.address, dev.firmware_version)
 ```
 
+### How packets are sent
+
+Commands are unicast to devices that answered a PING and use broadcast only
+while no device is known. Clip streams are stricter: they start only on exact
+PONG-reported endpoints and remain `Deferred` while none matches; stream packets
+are never broadcast. 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 +121,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 +139,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,26 +182,31 @@ 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("rain.loop")      # clip    -> SDK streams stream-clips/<wav> over UDP
-hb.stop("rain.loop")      # ends the active stream
+hb.play("sample-kit.sine_100hz")     # command -> device plays its installed clip
+rain = hb.play("rain.loop")  # clip -> returns a StreamPlayback
+rain.pan = -0.5
+rain.stop()                  # stops only this logical source
 ```
 
 You can also stream an ad-hoc PCM16 buffer (e.g. a synthesized stereo cue where
 L/R amplitude conveys direction):
 
 ```python
-hb.stream_pcm(pcm_bytes, sample_rate=16000, channels=2)
+left = hb.stream_pcm(pcm_bytes, sample_rate=16000, channels=2,
+                     target="player_1/left", loop=True)
+right = hb.stream_pcm(other_pcm, target="player_1/right", loop=True)
+left.gain = 0.5
 ```
 
-Author clips as **16 kHz mono PCM16** (the device plays at 16 kHz; the SDK does
-not resample). A full runnable example is in
+PCM16 input is normalized to **16 kHz stereo** inside the shared endpoint mixer.
+Sources aimed at one endpoint are mixed into one wire session; sources aimed at
+different endpoints run independently. A full runnable example is in
 [examples/clip_project/](examples/clip_project/).
 
 ## Generic OSC bridge
 
 Any OSC tool (TouchOSC, Max/MSP, TouchDesigner, a DAW) can drive Hapbeat
-without code. Run the bridge and send `/hapbeat/play <event_id> [target] [time] [gain]`:
+without code. Run the bridge and send `/hapbeat/play <event_id> [target] [time] [gain] [pan]`:
 
 ```bash
 hapbeat osc-bridge --listen 7702
@@ -189,7 +218,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.3.0}/README.md

@@ -38,10 +38,11 @@ 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.play("sample-kit.sine_100hz", pan=-1)     # pan: -1 left / 0 centre / +1 right
+hb.stop("sample-kit.sine_100hz")
 hb.stop_all()
 hb.close()
 ```
@@ -50,10 +51,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 +65,21 @@ for dev in hb.discover(timeout=1.5):
     print(dev.ip, dev.address, dev.firmware_version)
 ```
 
+### How packets are sent
+
+Commands are unicast to devices that answered a PING and use broadcast only
+while no device is known. Clip streams are stricter: they start only on exact
+PONG-reported endpoints and remain `Deferred` while none matches; stream packets
+are never broadcast. 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 +88,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 +106,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,26 +149,31 @@ 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("rain.loop")      # clip    -> SDK streams stream-clips/<wav> over UDP
-hb.stop("rain.loop")      # ends the active stream
+hb.play("sample-kit.sine_100hz")     # command -> device plays its installed clip
+rain = hb.play("rain.loop")  # clip -> returns a StreamPlayback
+rain.pan = -0.5
+rain.stop()                  # stops only this logical source
 ```
 
 You can also stream an ad-hoc PCM16 buffer (e.g. a synthesized stereo cue where
 L/R amplitude conveys direction):
 
 ```python
-hb.stream_pcm(pcm_bytes, sample_rate=16000, channels=2)
+left = hb.stream_pcm(pcm_bytes, sample_rate=16000, channels=2,
+                     target="player_1/left", loop=True)
+right = hb.stream_pcm(other_pcm, target="player_1/right", loop=True)
+left.gain = 0.5
 ```
 
-Author clips as **16 kHz mono PCM16** (the device plays at 16 kHz; the SDK does
-not resample). A full runnable example is in
+PCM16 input is normalized to **16 kHz stereo** inside the shared endpoint mixer.
+Sources aimed at one endpoint are mixed into one wire session; sources aimed at
+different endpoints run independently. A full runnable example is in
 [examples/clip_project/](examples/clip_project/).
 
 ## Generic OSC bridge
 
 Any OSC tool (TouchOSC, Max/MSP, TouchDesigner, a DAW) can drive Hapbeat
-without code. Run the bridge and send `/hapbeat/play <event_id> [target] [time] [gain]`:
+without code. Run the bridge and send `/hapbeat/play <event_id> [target] [time] [gain] [pan]`:
 
 ```bash
 hapbeat osc-bridge --listen 7702
@@ -156,7 +185,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.3.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.3.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.3.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()
 
@@ -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_python_sdk-0.1.0 → hapbeat_python_sdk-0.3.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
@@ -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":