変更履歴 — Hapbeat JavaScript SDK

This content is not available in your language yet.

@hapbeat/sdk の主要な変更点をまとめます。形式は Keep a Changelog に、バージョン付けは Semantic Versioning に従います。

0.3.0 - 2026-08-03

Node / React Native transport（直接 UDP）のみが対象です。Browser transport は hapbeat-helper 経由のため、送信経路は helper 側が決めます。

変更（Changed）

PLAY / STOP / STOP_ALL とクリップストリームを、PING に応答した既知デバイスへユニキャスト送信するようになりました（{ unicast: false } で従来のブロードキャストに戻せます）。Wi-Fi AP は、同じ AP に省電力状態の端末が 1 台でもいるとブロードキャストフレームを次の DTIM ビーコン（100〜300 ms 周期）まで保留します。これが単発コマンドの発火遅れ、連続ストリームの周期的な途切れとして出ていました。デバイス側の設定では回避できない（原因は無関係な他端末）ため、送信側で対処します。 Unity SDK で実測・検証済みの方針をそのまま移植したものです。
- 応答があったデバイスが 1 台も無い間はブロードキャストで送ります（起動直後など）。
- ユニキャストとブロードキャストの二重送信はしません。
- target に一致しないデバイスは宛先から外します。アドレス未報告のデバイスは宛先に残します（デバイス側で同じ判定をするため、外すと取りこぼしになる）。
- 既知デバイスがいて全て target 不一致だった場合、コマンドはブロードキャストにフォールバックします（キャッシュしたアドレスが古いときに STOP が消えてループ再生が止まらなくなるのを防ぐため）。ストリームは送信しません（数百パケット分の電波を無駄にするため。取りこぼしても何も残らない）。
- PING と CONNECT_STATUS はデバイス検出のためブロードキャストのままです。
キープアライブが PING も送るようになりました（従来は CONNECT_STATUS のみ）。デバイスが PONG を返すのは PING に対してだけなので、これが無いとユニキャストの宛先表が deviceTtlMs で空になり、以後ずっとブロードキャストに戻ってしまいます。 appName を渡していない接続でもキープアライブが動くようになりました。

追加（Added）

unicast（既定 true）/ deviceTtlMs（既定 15000）オプション — ユニキャストの有効・無効と、最後の PONG から何 ms デバイスを宛先として保持するか。
protocol.addressMatches(target, deviceAddress) — ファームウェアの addressMatch() と同一セマンティクスの判定関数。contracts §4.2 の例表をそのままテストに移植しています。

注意

部分ワイルドカードは使えません。 * はセグメント全体が * のときだけワイルドカードとして働きます（player_1/pos_* は不一致、player_1/* は一致）。 contracts の例表に誤りがあったため、仕様側も併せて訂正しました。

0.2.1 - 2026-06-29

変更（Changed）

Node / React Native transport の受信ソケットを、既定で ephemeral （OS 任せ）ポートに bind するよう変更しました（従来は well-known の 7700 を先に試す挙動）。DEC-036 の方針に整合させたものです。7700 を bind するのはデーモン（hapbeat-helper）だけにすべきで、SDK が先に 7700 を奪うと、後から起動した helper（および Studio）が壊れる恐れがありました。送信は従来どおり 7700 宛てで、PONG は送信元 ephemeral ポートに返るため discovery は影響を受けません。これにより Python / Unity SDK と挙動が揃います。

追加（Added）

bindPort オプション — ローカルの受信ポートを明示的に bind する opt-in （例: 非要求のブロードキャストを受けたいデーモン用途で bindPort: 7700）。指定ポートが使用中なら ephemeral にフォールバックします。既定は 0（ephemeral）。

0.2.0 - 2026-06-29

追加（Added）

React Native transport — connect() の 3 つ目のビルド。package の exports の "react-native" 条件で解決されます（dist/react-native.js）。 optional peer dependency の react-native-udp 経由で実 UDP ソケットを開き、スマホから Wi-Fi で直接ブロードキャストします — hapbeat-helper は不要 （スマホはブラウザのようにサンドボックス化されていない）。wire 形式は Node と同一。
- react-native-udp は optional peer dependency。アプリ側でインストールします。
- TextDecoder の polyfill（fast-text-encoding）が必要です。RN Hermes （0.86 含む）は TextEncoder は持つが TextDecoder は持たないため。 examples/react-native/ 参照。
- 実機 Android で検証済み（RN 0.86 / Hermes / New Architecture）: UDP ソケット bind・Hapbeat の discovery・command + streaming の発火を helper なしで確認。
examples/react-native/ — 最小の Android デモ。ボタンタップで command （play）と 1 秒の合成ストリーミングバッファを送信します。

変更（Changed）

内部: Node と React Native transport が UdpTransportBase を共有するようになりました（protocol / keepalive / discovery のロジックすべて）。差分はソケット実装のみ。Node / Browser ビルドの公開 API 変更はありません。

修正（Fixed）

src/index.ts の wire レイヤ再エクスポートを export * as protocol から import * as protocol; export { protocol } に変更。React Native の Metro が @babel/plugin-transform-export-namespace-from プラグインなしでバンドルできるようになります。

0.1.0 - 2026-06-25

初回公開リリース。1 つの API・2 つの transport。

追加（Added）

connect(options?) — Node（@hapbeat/sdk → dist/node.js、UDP ブロードキャスト直送）と Browser（dist/browser.js、hapbeat-helper の WebSocket ws://localhost:7703 経由）。バンドラ / ランタイムが package の exports マップから自動でビルドを選択します。
Hapbeat ファサード — level-1 の「fire」面:
- play(eventId, opts?) — EventMap（kit manifest）がモードを決定。 command（events）はデバイスにインストール済みの clip を再生、 clip（stream_events）はイベントの WAV をホストからストリームします。
- streamPcm(pcm, opts?) — その場の PCM16 バッファをストリーム（L/R 方向性触覚向けにステレオ可）。
- openStream(opts?) → LiveStream — 連続変調する触覚向けの永続ストリーム（STREAM_BEGIN を 1 回、以降 handle.write() でチャンク送出、 handle.close()）。チャンクごとの teardown が不要。
- preloadClips(), stop(), stopAll(), ping(), discover(), close()。
EventMap — 直交する調整側。fromManifest()（kit manifest schema 2.0.0）、 fromGains()、および get / gainFor / has / ids / size。
parseWav, ClipStreamer, LiveStream を advanced 用途向けの named export として公開。さらに protocol.*（Layer-1 wire の builder / parser）。
デバイス discovery（ブロードキャスト PING/PONG）と target addressing （"player_1/chest" / "*/chest" / "" = ブロードキャスト）。
サンプル: examples/node-minimal.mjs、examples/browser-minimal.html、および examples/games/ 配下のブラウザ触覚デモ集。