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

hapbeat/__init__.py

@@ -0,0 +1,49 @@
+"""Hapbeat SDK for Python — drive Hapbeat haptic devices over Wi-Fi UDP.
+
+Quick start::
+
+    import hapbeat
+
+    hb = hapbeat.connect(app_name="MyExperiment")
+    hb.play("impact.hit", gain=0.3)
+    hb.stop_all()
+    hb.close()
+
+The fire side (``play``/``stop``) and the tuning side (:class:`EventMap`) are
+kept orthogonal and linked only by event id, matching the Hapbeat Unity SDK.
+"""
+
+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 .wav import WavPcm, read_wav_pcm16
+
+try:  # populated from installed package metadata
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        __version__ = version("hapbeat-python-sdk")
+    except PackageNotFoundError:  # running from a source checkout
+        __version__ = "0.1.0+local"
+except ImportError:  # pragma: no cover
+    __version__ = "0.1.0+local"
+
+__all__ = [
+    "connect",
+    "Hapbeat",
+    "Device",
+    "EventMap",
+    "EventDef",
+    "ClipStreamer",
+    "WavPcm",
+    "read_wav_pcm16",
+    "UdpClient",
+    "protocol",
+    "DEFAULT_PORT",
+    "DEFAULT_BROADCAST",
+    "__version__",
+]

hapbeat/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m hapbeat``."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

hapbeat/cli.py

@@ -0,0 +1,124 @@
+"""``hapbeat`` command-line interface.
+
+Examples::
+
+    hapbeat scan
+    hapbeat play impact.hit --gain 0.3
+    hapbeat stop impact.hit
+    hapbeat stop-all
+    hapbeat osc-bridge --listen 7702
+    hapbeat launchpad
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .eventmap import EventMap
+from .hapbeat import connect
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--port", type=int, default=7700, help="UDP port (default 7700)")
+    p.add_argument("--target", default="", help="device address; empty = all (broadcast)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="hapbeat", description="Drive Hapbeat devices.")
+    parser.add_argument("--version", action="version", version=f"hapbeat {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    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)")
+    _add_common(p_play)
+
+    p_stop = sub.add_parser("stop", help="stop one event id")
+    p_stop.add_argument("event_id")
+    _add_common(p_stop)
+
+    p_stop_all = sub.add_parser("stop-all", help="stop everything")
+    _add_common(p_stop_all)
+
+    p_ping = sub.add_parser("ping", help="broadcast a keep-alive ping")
+    _add_common(p_ping)
+
+    p_scan = sub.add_parser("scan", help="discover devices on the LAN")
+    p_scan.add_argument("--timeout", type=float, default=1.5)
+    _add_common(p_scan)
+
+    p_osc = sub.add_parser("osc-bridge", help="relay /hapbeat/* OSC to devices")
+    p_osc.add_argument("--listen", type=int, default=7702, help="OSC listen port (default 7702)")
+    p_osc.add_argument("--haptics", default=None,
+                       help="haptic file (overlay) so OSC events route command/clip + use per-event targets")
+    p_osc.add_argument("--kit", default=None,
+                       help="kit folder (alternative to --haptics; intensity/clip only, no targeting)")
+    _add_common(p_osc)
+
+    p_lp = sub.add_parser(
+        "launchpad",
+        help="serve a local web page to try features from the browser",
+    )
+    p_lp.add_argument("--host", default="127.0.0.1", help="HTTP bind host (default 127.0.0.1)")
+    p_lp.add_argument("--http-port", type=int, default=7100, help="HTTP port (default 7100)")
+    p_lp.add_argument("--no-open", action="store_true", help="do not open a browser")
+    _add_common(p_lp)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.command == "osc-bridge":
+        from .osc import OscBridge
+
+        event_map = None
+        if args.haptics:
+            event_map = EventMap.from_file(args.haptics)
+        elif args.kit:
+            event_map = EventMap.from_kit(args.kit)
+        hb = connect(port=args.port, app_name="hapbeat-osc",
+                     default_target=args.target, event_map=event_map)
+        try:
+            mode = "command+clip" if event_map else "command only"
+            print(f"OSC bridge: listening on :{args.listen}, relaying to UDP {args.port} ({mode})")
+            OscBridge(hb, listen_port=args.listen).serve_forever()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            hb.close()
+        return 0
+
+    if args.command == "launchpad":
+        from .launchpad import serve
+
+        return serve(host=args.host, port=args.http_port, udp_port=args.port,
+                     target=args.target, open_browser=not args.no_open)
+
+    hb = connect(port=args.port, default_target=getattr(args, "target", ""), keepalive=False)
+    try:
+        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'}")
+        elif args.command == "stop":
+            print("sent" if hb.stop(args.event_id) else "FAILED")
+        elif args.command == "stop-all":
+            print("sent" if hb.stop_all() else "FAILED")
+        elif args.command == "ping":
+            print("sent" if hb.ping() else "FAILED")
+        elif args.command == "scan":
+            devices = hb.discover(timeout=args.timeout)
+            if not devices:
+                print("no devices replied")
+            for d in devices:
+                print(f"{d.ip:<16} {d.address or '?':<20} {d.name or '?':<16} fw={d.firmware_version or '?'}")
+    finally:
+        hb.close()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hapbeat/client.py

@@ -0,0 +1,152 @@
+"""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.
+
+Design note — port binding:
+    The standard transport is Wi-Fi UDP broadcast (see workspace CLAUDE.md).
+    To receive PONG replies we bind the well-known port 7700. If that port is
+    already taken (e.g. hapbeat-helper is running on the same machine) we fall
+    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.
+"""
+
+from __future__ import annotations
+
+import logging
+import socket
+import threading
+import time
+from typing import Callable, Optional
+
+from . import protocol
+
+logger = logging.getLogger("hapbeat")
+
+DEFAULT_PORT = 7700
+DEFAULT_BROADCAST = "255.255.255.255"
+
+PongCallback = Callable[[dict, str], None]
+
+
+class UdpClient:
+    """Broadcast-capable UDP socket plus a PONG receive loop."""
+
+    def __init__(
+        self,
+        port: int = DEFAULT_PORT,
+        broadcast_addr: str = DEFAULT_BROADCAST,
+        bind_port: int = 0,
+    ) -> None:
+        self.port = port  # destination port (the device listens here)
+        # Local receive bind. Default 0 = ephemeral: this leaves the
+        # well-known device port (7700) to the single host daemon that owns
+        # it (hapbeat-helper, serving Hapbeat Studio) so an SDK script and
+        # Studio coexist. PING replies still arrive at the ephemeral source
+        # port, so discovery keeps working. Pass ``bind_port=port`` only to
+        # also receive the device's unsolicited broadcasts (daemon use).
+        self.bind_port = bind_port
+        self.broadcast_addr = broadcast_addr
+        self._sock: Optional[socket.socket] = None
+        self._thread: Optional[threading.Thread] = None
+        self._running = False
+        self._bound_well_known = False
+        self._pong_callbacks: list[PongCallback] = []
+
+    # ── Lifecycle ───────────────────────────────────────────────────
+    def open(self) -> None:
+        if self._sock is not None:
+            return
+        sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+        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
+            # port another process owns.
+            try:
+                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            except OSError:
+                pass
+        try:
+            sock.bind(("0.0.0.0", self.bind_port))
+            self._bound_well_known = self.bind_port == self.port
+        except OSError as exc:
+            logger.warning(
+                "port %d busy (%s); binding ephemeral port (discovery still "
+                "works, async broadcast pushes are not received)",
+                self.bind_port,
+                exc,
+            )
+            try:
+                sock.bind(("0.0.0.0", 0))
+            except OSError:
+                pass
+            self._bound_well_known = False
+        sock.settimeout(0.2)
+        self._sock = sock
+        self._running = True
+        self._thread = threading.Thread(
+            target=self._recv_loop, name="hapbeat-recv", daemon=True
+        )
+        self._thread.start()
+
+    def close(self) -> None:
+        self._running = False
+        sock, self._sock = self._sock, None
+        if sock is not None:
+            try:
+                sock.close()
+            except OSError:
+                pass
+        if self._thread is not None:
+            self._thread.join(timeout=1.0)
+            self._thread = None
+
+    # ── Listeners ───────────────────────────────────────────────────
+    def add_pong_listener(self, cb: PongCallback) -> None:
+        self._pong_callbacks.append(cb)
+
+    def remove_pong_listener(self, cb: PongCallback) -> None:
+        try:
+            self._pong_callbacks.remove(cb)
+        except ValueError:
+            pass
+
+    # ── Send ────────────────────────────────────────────────────────
+    def send(self, packet: bytes, addr: Optional[str] = None) -> bool:
+        """Send a prebuilt packet. ``addr=None`` -> broadcast."""
+        sock = self._sock
+        if sock is None:
+            logger.error("send before open()")
+            return False
+        dst = self.broadcast_addr if not addr else addr
+        try:
+            sock.sendto(packet, (dst, self.port))
+            return True
+        except OSError as exc:
+            logger.warning("UDP send to %s:%d failed: %s", dst, self.port, exc)
+            return False
+
+    # ── Recv loop ───────────────────────────────────────────────────
+    def _recv_loop(self) -> None:
+        while self._running:
+            sock = self._sock
+            if sock is None:
+                break
+            try:
+                data, addr = sock.recvfrom(4096)
+            except socket.timeout:
+                continue
+            except OSError:
+                break
+            pong = protocol.parse_pong(data)
+            if pong is None:
+                continue
+            ip = addr[0]
+            for cb in list(self._pong_callbacks):
+                try:
+                    cb(pong, ip)
+                except Exception:  # noqa: BLE001 — never let a listener kill the loop
+                    logger.exception("pong listener raised")

hapbeat/clip.py

@@ -0,0 +1,121 @@
+"""ClipStreamer — pace a PCM16 clip out as STREAM_BEGIN / STREAM_DATA* / END.
+
+The device ring buffer holds only ~256 ms (4096 frames @ 16 kHz), so a whole
+clip cannot be burst at once. Data is sent in frame-aligned chunks, each
+scheduled ~``send_ahead_sec`` before its playback time, so the device buffer
+never overflows. STREAM_END is deferred until the clip has fully drained.
+
+A stream is session-level (one at a time): starting a new clip cancels the
+previous one, matching the "1 session = 1 stream" rule in the protocol. Pacing
+runs on a daemon thread; ``stop()`` cancels it and sends STREAM_END exactly
+once. This mirrors the web SDK's ClipStreamer (TypeScript) one-for-one.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Protocol
+
+DEFAULT_SEND_AHEAD = 0.15  # seconds (< 0.256 s device ring)
+MAX_DATA_BYTES = 1024      # per STREAM_DATA payload (well under the 1472 cap)
+_END_DRAIN_PAD = 0.08      # extra wait after last frame's playback before END
+
+
+class StreamSink(Protocol):
+    """The subset of the transport a ClipStreamer needs."""
+
+    def stream_begin(self, *, sample_rate: int, channels: int,
+                     total_samples: int, gain: float, target: str) -> None: ...
+
+    def stream_data(self, offset: int, data: bytes) -> None: ...
+
+    def stream_end(self) -> None: ...
+
+
+class _Session:
+    __slots__ = ("stop", "ended")
+
+    def __init__(self) -> None:
+        self.stop = threading.Event()
+        self.ended = False
+
+
+class ClipStreamer:
+    def __init__(self, sink: StreamSink, *, send_ahead_sec: float = DEFAULT_SEND_AHEAD) -> None:
+        self._sink = sink
+        self._send_ahead = send_ahead_sec
+        self._lock = threading.Lock()
+        self._active: _Session | None = None
+        self._thread: threading.Thread | None = None
+
+    # ── Public API ──────────────────────────────────────────────────
+    def play(self, pcm: bytes, *, sample_rate: int, channels: int,
+             gain: float = 1.0, target: str = "") -> None:
+        """Stream a PCM16 byte buffer, real-time paced. Cancels any active clip."""
+        self.stop()
+        channels = max(1, channels)
+        sample_rate = sample_rate or 16000
+        bytes_per_frame = channels * 2
+        chunk_bytes = max(bytes_per_frame, MAX_DATA_BYTES - (MAX_DATA_BYTES % bytes_per_frame))
+        total_frames = len(pcm) // bytes_per_frame
+
+        session = _Session()
+        with self._lock:
+            self._active = session
+
+        # STREAM_BEGIN goes out synchronously, before the pacing thread starts.
+        self._sink.stream_begin(
+            sample_rate=sample_rate, channels=channels,
+            total_samples=total_frames, gain=gain, target=target,
+        )
+
+        def run() -> None:
+            t0 = time.perf_counter()
+            offset = 0
+            n = len(pcm)
+            while offset < n:
+                if session.stop.is_set():
+                    return  # stop() owns the END in this case
+                played_sec = (offset / bytes_per_frame) / sample_rate
+                wait = t0 + played_sec - self._send_ahead - time.perf_counter()
+                if wait > 0 and session.stop.wait(wait):
+                    return
+                end = min(offset + chunk_bytes, n)
+                self._sink.stream_data(offset, pcm[offset:end])
+                offset = end
+            # all data queued -- END after the clip has fully played out
+            total_sec = total_frames / sample_rate
+            end_wait = max(0.0, t0 + total_sec + _END_DRAIN_PAD - time.perf_counter())
+            session.stop.wait(end_wait)
+            self._end_session(session)
+
+        thread = threading.Thread(target=run, name="hapbeat-clip", daemon=True)
+        with self._lock:
+            self._thread = thread
+        thread.start()
+
+    def stop(self) -> None:
+        """Cancel the active clip (if any) and tell the device to stop."""
+        with self._lock:
+            session = self._active
+            thread = self._thread
+        if session is not None:
+            self._end_session(session)
+        if thread is not None and thread is not threading.current_thread():
+            thread.join(timeout=1.0)
+
+    def is_active(self) -> bool:
+        with self._lock:
+            return self._active is not None and not self._active.ended
+
+    # ── Internals ───────────────────────────────────────────────────
+    def _end_session(self, session: _Session) -> None:
+        with self._lock:
+            if session.ended:
+                return
+            session.ended = True
+            if self._active is session:
+                self._active = None
+        session.stop.set()
+        self._sink.stream_end()

hapbeat/eventmap.py

@@ -0,0 +1,203 @@
+"""EventMap — the *tuning* side of the SDK, kept orthogonal to the fire side.
+
+Mirrors the Unity SDK's EventMap concept at level-1: a catalog that maps an
+event id to its per-event haptic settings (default gain, loop, mode, and -- for
+clip events -- which WAV to stream). It is linked to the fire side only by
+event id, so *when/where* to fire (the caller) and *what/how* to play (this
+catalog) stay mutually independent.
+
+The canonical source is the kit manifest (schema 2.0.0, see
+hapbeat-contracts/specs/kit-format.md). It has two event buckets:
+
+  - ``events``        — **command** mode: the device plays a clip already
+    installed on it; the SDK just sends a PLAY with the event id.
+  - ``stream_events`` — **clip** mode: the SDK reads the event's WAV from the
+    kit's ``stream-clips/`` folder and UDP-streams it to the device.
+
+``play(event_id)`` branches on which bucket the event came from, so the caller
+writes the same one-liner either way.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Union
+
+
+@dataclass
+class EventDef:
+    """Per-event haptic settings resolved from a kit manifest (or by hand)."""
+
+    event_id: str
+    intensity: float = 1.0
+    loop: bool = False
+    device_wiper: Optional[int] = None
+    streaming: bool = False  # True => clip mode (manifest stream_events bucket)
+    clip: str = ""           # WAV filename (clip mode), relative to stream-clips/
+    target: str = ""         # device address (overlay/app side); "" = broadcast
+    note: str = ""
+
+    @property
+    def mode(self) -> str:
+        """``"clip"`` for stream events, ``"command"`` otherwise."""
+        return "clip" if self.streaming else "command"
+
+
+class EventMap:
+    """A catalog of event definitions keyed by event id.
+
+    ``kit_dir`` (when known) is the folder that holds the manifest; clip-mode
+    WAVs are resolved relative to ``<kit_dir>/stream-clips/``.
+    """
+
+    def __init__(
+        self,
+        events: Optional[dict[str, EventDef]] = None,
+        *,
+        kit_dir: Optional[Union[str, Path]] = None,
+    ) -> None:
+        self._events: dict[str, EventDef] = dict(events or {})
+        self.kit_dir: Optional[Path] = Path(kit_dir) if kit_dir else None
+
+    # ── Construction ────────────────────────────────────────────────
+    @classmethod
+    def from_dict(cls, gains: dict[str, float]) -> "EventMap":
+        """Build from a simple ``{event_id: gain}`` mapping (all command mode)."""
+        return cls({k: EventDef(event_id=k, intensity=float(v)) for k, v in gains.items()})
+
+    @classmethod
+    def from_manifest(
+        cls,
+        manifest: Union[str, Path, dict],
+        *,
+        kit_dir: Optional[Union[str, Path]] = None,
+    ) -> "EventMap":
+        """Build from a kit manifest (path, JSON string, or parsed dict).
+
+        Reads schema 2.0.0 ``events`` (command) and ``stream_events`` (clip)
+        buckets. When ``manifest`` is a file path and ``kit_dir`` is not given,
+        the manifest's parent folder becomes the kit dir (so clip WAVs resolve).
+        """
+        src_dir: Optional[Path] = Path(kit_dir) if kit_dir else None
+        if isinstance(manifest, (str, Path)) and not _looks_like_json(manifest):
+            path = Path(manifest)
+            if src_dir is None:
+                src_dir = path.parent
+            manifest = json.loads(path.read_text(encoding="utf-8"))
+        elif isinstance(manifest, str):
+            manifest = json.loads(manifest)
+
+        events: dict[str, EventDef] = {}
+        # events first, then stream_events: for an id authored in BOTH buckets
+        # (Studio "BOTH" mode) the clip variant wins, matching the web SDK.
+        for bucket, streaming in (("events", False), ("stream_events", True)):
+            for event_id, entry in (manifest.get(bucket) or {}).items():
+                entry = entry or {}
+                params = entry.get("parameters") or {}
+                events[event_id] = EventDef(
+                    event_id=event_id,
+                    intensity=float(params.get("intensity", 1.0)),
+                    loop=bool(params.get("loop", False)),
+                    device_wiper=params.get("device_wiper"),
+                    streaming=streaming,
+                    clip=entry.get("clip", ""),
+                    note=entry.get("note", ""),
+                )
+        return cls(events, kit_dir=src_dir)
+
+    @classmethod
+    def from_kit(cls, kit_dir: Union[str, Path]) -> "EventMap":
+        """Build from a kit folder, discovering ``*-manifest.json`` inside it.
+
+        The recommended project layout is::
+
+            kits/<kit-name>/
+                <kit-name>-manifest.json
+                install-clips/   (command clips, deployed to the device)
+                stream-clips/    (clip-mode WAVs the SDK streams)
+        """
+        d = Path(kit_dir)
+        candidates = sorted(d.glob("*-manifest.json")) or sorted(d.glob("manifest.json"))
+        if not candidates:
+            raise FileNotFoundError(f"no *-manifest.json found in kit folder {d}")
+        return cls.from_manifest(candidates[0], kit_dir=d)
+
+    @classmethod
+    def from_file(cls, path: Union[str, Path]) -> "EventMap":
+        """Build from a *haptic file* — an authored overlay that references a kit.
+
+        The Studio-generated manifest holds kit content (intensity / clip /
+        mode). App-side, per-event settings that the manifest does NOT carry --
+        targeting, a gain override -- live here, so ``play(id)`` resolves them
+        without the caller passing ``target`` every time. Mirrors the Unity
+        SDK's EventMap asset (which references the kit and adds target/gain).
+
+        File format (JSON)::
+
+            {
+              "kit": "kits/my-kit",          # kit folder, relative to this file
+              "events": {
+                "impact.hit": { "target": "player_1/chest", "gain": 0.8 },
+                "rain.loop":  { "target": "*/back" }
+              }
+            }
+
+        ``kit`` is optional (omit it for a pure target/gain overlay with no
+        clip resolution). Per-event keys: ``target``, ``gain`` (overrides the
+        manifest intensity; ``intensity`` is also accepted), ``loop``, ``note``.
+        """
+        p = Path(path)
+        spec = json.loads(p.read_text(encoding="utf-8"))
+        kit = spec.get("kit")
+        if kit:
+            kit_path = Path(kit)
+            if not kit_path.is_absolute():
+                kit_path = p.parent / kit_path
+            em = cls.from_kit(kit_path)
+        else:
+            em = cls()
+
+        for event_id, raw in (spec.get("events") or {}).items():
+            o = raw or {}
+            ev = em._events.get(event_id)
+            if ev is None:  # overlay-only event (not in the kit): command mode
+                ev = EventDef(event_id=event_id)
+                em._events[event_id] = ev
+            if "target" in o:
+                ev.target = str(o["target"])
+            if "gain" in o:
+                ev.intensity = float(o["gain"])
+            elif "intensity" in o:
+                ev.intensity = float(o["intensity"])
+            if "loop" in o:
+                ev.loop = bool(o["loop"])
+            if "note" in o:
+                ev.note = str(o["note"])
+        return em
+
+    # ── Lookup ──────────────────────────────────────────────────────
+    def gain_for(self, event_id: str) -> float:
+        """Default gain for an event (its manifest intensity), or 1.0."""
+        ev = self._events.get(event_id)
+        return ev.intensity if ev is not None else 1.0
+
+    def get(self, event_id: str) -> Optional[EventDef]:
+        return self._events.get(event_id)
+
+    def add(self, event_id: str, intensity: float = 1.0, **kw) -> None:
+        self._events[event_id] = EventDef(event_id=event_id, intensity=intensity, **kw)
+
+    def ids(self) -> list[str]:
+        return list(self._events.keys())
+
+    def __contains__(self, event_id: str) -> bool:
+        return event_id in self._events
+
+    def __len__(self) -> int:
+        return len(self._events)
+
+
+def _looks_like_json(s: Union[str, Path]) -> bool:
+    return isinstance(s, str) and s.lstrip().startswith("{")