コンテンツにスキップ
Hapbeat devtools
JA

Getting Started

Python から Hapbeat を Wi-Fi UDP で駆動する SDK です。研究（PsychoPy / Jupyter / ROS）・メディアアート・プロトタイピング向け。起点（いつ・どこで鳴らすか）と 触覚の編集（何を・どう鳴らすか）を分け、event id だけで結びます。

インストール

Section titled “インストール”
pip install hapbeat-python-sdk          # ライブラリ + CLI
pipx install hapbeat-python-sdk         # CLI / launchpad だけを隔離環境に

pipx は CLI（hapbeat scan / launchpad など）を隔離環境に入れる用途向けです。 自分のスクリプトから import hapbeat する場合は、venv の中で pip install を 使ってください。

最初のイベント

Section titled “最初のイベント”
import hapbeat


hb = hapbeat.connect(app_name="MyApp")
hb.play("sample-kit.sine_100hz", gain=0.5)
hb.close()
  • connect() が UDP ソケットを開き、keep-alive（5 秒間隔の PING + アプリ名の CONNECT_STATUS）を送ってデバイス OLED にアプリ名を表示します。送信は PING に 応答したデバイスへの unicast が標準で、1 台も応答していない間だけ ブロードキャストになります（Wi-Fi の AP がブロードキャストを最大 1 ビーコン 間隔＝100〜300 ms 保留するため）。
  • play(event_id, gain) は再生指示を送ります。gain は 0..1 で、省略すると後述の EventMap が既定値（kit の intensity）を補います。

"sample-kit.sine_100hz" は、デバイスに配備した kit（Hapbeat Studio で書き込み）に含まれる event id である必要があります。SDK は指示を送るだけで、 波形はデバイス上の kit にあります（command モード。別経路の clip モードは command と clip の使い分け を参照）。

デバイスを探す

Section titled “デバイスを探す”
with hapbeat.connect() as hb:
    for d in hb.discover(timeout=1.5):
        print(d.ip, d.address, d.firmware_version)

起点と編集を分ける（EventMap）

Section titled “起点と編集を分ける（EventMap）”

強度などの「触覚の調整値」を発火コードに書かず、**触覚ファイル（kit manifest = EventMap）**にまとめます。play("id") がそこから既定値を解決します。

em = hapbeat.EventMap.from_manifest("kits/my-kit/my-kit-manifest.json")
with hapbeat.connect(event_map=em) as hb:
    hb.play("sample-kit.sine_100hz")     # kit manifest の intensity で発火

「いつ鳴らすか（コード）」と「どれくらいの強さか（kit）」を独立して差し替えられます。 詳しくは EventMap リファレンス を参照。

ターゲットを指定する

Section titled “ターゲットを指定する”
hb.play("sample-kit.sine_100hz", target="player_1/chest")  # 1 台
hb.play("sample-kit.sine_100hz", target="*/chest")         # chest の全台
hb.play("sample-kit.sine_100hz")                            # 全台

AI コーディングエージェントに渡す

Section titled “AI コーディングエージェントに渡す”

Claude / Cursor / Copilot などにこの SDK を使わせるなら、SDK に同梱の AGENTS.md を渡してください。仕様・使い方・落とし穴を 1 ファイルにまとめてあり、 これだけで全体像を把握できます。

  • 場所: SDK リポジトリ直下の AGENTS.md
  • 渡し方の例（そのままエージェントへ）:
Hapbeat Python SDK を使います。AGENTS.md を読んで、その仕様とベストプラクティスに従ってください。

次に読む

Section titled “次に読む”