Hapbeat Web Runtime 利用ガイド

Hapbeat Web Runtime は、Web アプリが出す意味イベントを Runtime Console で触覚設定へ解決するための仕組みです。Web アプリには hapbeat.emit() だけを組み込み、Hapbeat の Event ID、gain、target、helper の通信は Console に分離します。

Web アプリ ──意味イベント──> Session Relay ──> Runtime Console (PC) ──> hapbeat-helper ──> Hapbeat

Session Relay は JSON の意味イベントと設定だけを中継します。音声 PCM、Kit、asset bytes は Relay を通りません。CLIP の音源は Runtime Console が HTTPS から取得し、PC の音声出力を使わずに helper へ渡します。

必要なもの

• Node.js 22 以降（Runtime Console をローカル起動する PC）
• Runtime Console と同じ PC で動く hapbeat-helper
• 触覚を実際に再生する場合だけ、helper が検出できる Hapbeat

Web アプリと Runtime Console は別の PC で構いません。実際の再生を担当するのは Runtime Console の PC なので、helper と Hapbeat はその PC から接続可能なネットワークに置きます。

ローカルで試す

1. Runtime Console を起動する

リポジトリのルートで次を実行します。

cd repos-tools/hapbeat-web-runtime
npm install
npm run dev

http://localhost:8171 を開くと Runtime Console が表示されます。Console は初期状態で触覚送信が OFF、選択デバイスが 0 台です。この状態ではイベントを受け取っても Hapbeat へ送信しません。

2. helper を起動する

Runtime Console を開く PC で helper をインストール済みでなければ、別のターミナルで次を実行します。

pipx install hapbeat-helper
hapbeat-helper start

Console は ws://localhost:7703 の helper に接続し、online のデバイスだけを表示します。helper のローカル開発版を使う場合は、hapbeat-helper の README の手順で起動してください。

3. Session を作成する

Console の Create session を押します。画面に app 用の sessionId、token、clientId を含む credential が表示されます。Session の有効期間は作成から約 15 分です。期限後は Console で新しく作成してください。

credential は対象アプリだけに渡します。URL の query parameter や公開リポジトリには保存しません。この v1 relay は認証付きの本番テナントではなく、短期 credential を使うデモ用途です。

4. Web アプリから意味イベントを送る

アプリでは、Console に表示された app credential を使って接続し、意味イベント名だけを送ります。ローカル確認時は、Console とアプリの URL をいずれも http://localhost:8171 にします。

<script type="module">
  import { HapbeatClient } from "http://localhost:8171/hapbeat-runtime-client.js";

  const hapbeat = await HapbeatClient.connectHapbeat({
    relayUrl: "http://localhost:8171",
    sessionId: "Console に表示された sessionId",
    token: "Console に表示された token",
    clientId: "Console に表示された clientId"
  });

  hapbeat.emit("player.jump", { height: 1.2 });
</script>

公開 Worker を使う場合は、module URL と relayUrl の両方を同じ Worker URL に置き換えます。

const relayUrl = "https://hapbeat-web-runtime.yus3594.workers.dev";
// import URL: `${relayUrl}/hapbeat-runtime-client.js`

イベント名は Console の Event catalog に追加されます。未設定のイベントは既定で無効であり、触覚送信されません。

Event catalog を設定する

Event catalog の各行で、イベント名ごとに再生方法を選びます。設定は Console から Session に公開され、Web アプリ側で Event ID や送信先を持つ必要はありません。

項目	設定内容
fire	インストール済み Kit の Event ID を指定して発火します。Event ID が空のまま有効化できません。
clip	https:// の音源 URL を指定してストリーミングします。asset server は Console からの CORS fetch を許可する必要があります。
gain	master gain と掛け合わせるイベントごとの係数です。
delay	Runtime Console 上で適用する遅延（ms）です。
override	ON のときだけ、そのイベント固有の player / position / group target を使います。OFF では master target を使います。

CLIP は Console の OfflineAudioContext で無音 decode・16 kHz mono PCM16 への変換をしてから helper に渡します。ブラウザのスピーカーには接続しません。

実機へ送信する

実機送信は次の 3 条件をすべて満たした時だけ行われます。

1. Session の runtime 接続が完了している。
2. Enable haptic transmission を ON にする。
3. online と表示されたデバイスを少なくとも 1 台選択する。

送信先は選択した online IP への明示的な unicast です。0 台選択時は送信せず、broadcast にフォールバックしません。Session を作り直すと送信 ON と選択デバイスはリセットされます。

Console の Emitter demo はアプリ統合前の確認用です。event 名と JSON payload を入力して Emit を押すと、その意味イベントを送れます。設定が無効、送信 OFF、または送信先未選択なら触覚は再生されません。

時刻指定と遅延

アプリは任意で targetTime（UNIX epoch ミリ秒）を指定できます。

hapbeat.emit("game.countdown", {}, { targetTime: Date.now() + 500 });

v1 では targetTime と event の delay を Runtime Console の PC 上で解決します。Hapbeat 端末までの end-to-end 同期再生を保証するものではありません。過去または現在の targetTime は即時再生として扱われます。

よくある問題

Event catalog にイベントが現れない

Web アプリが Session 作成時に表示された app credential で接続しているかを確認します。Session は約 15 分で期限切れになります。期限切れ後は Console で Session を作り直し、アプリにも新しい credential を設定します。

helper 接続中のまま、またはデバイスが 0 台

Runtime Console と同じ PC で hapbeat-helper start が動いているか確認します。helper が検出した online デバイスだけが選択候補になります。0 台では安全のため送信されません。

CLIP が再生されない

asset URL が https:// であること、Runtime Console の origin から CORS fetch できることを確認します。CLIP の音源を Relay にアップロードしたり、JSON payload に埋め込んだりすることはできません。

音が PC から出ない

仕様です。CLIP は触覚変換専用の無音処理であり、ブラウザの音声出力には接続されません。

設定の保存と確認

Export で現在の Runtime config を JSON として取り出し、Import で読み込めます。import 時の revision は Console が管理するため、JSON 内の値ではなく次の revision が割り当てられます。

ローカルの自動確認では、実機を選択せず送信を OFF にしたまま次を実行します。

npm test
npm run typecheck
npm run build

API と設定形式の規範は Web Runtime v1 仕様 を参照してください。