サンプルの歩き方
SDK の examples/
は、読んでコピーして自分のものにすることを前提にした単体ファイル／フォルダ集です。
ここでは「どれを土台にすればよいか」と「コピーして使うときの注意」をまとめます。
- minimal.py —
connect → play → stopの最小形。まずこれ。 - clip_project/ — kit をプロジェクトに同梱する構成。同じ
play(id)が command と clip に自動で分かれることが分かる、いちばんのお手本。 - osc_remote/ — 触覚ファイルと、外部（スマホ等）からの起動。
- 用途別の応用例（下表）。
サンプル早見表
Section titled “サンプル早見表”| サンプル | 向き | 何が学べる | 必要な kit |
|---|---|---|---|
| minimal.py | 全員 | discover / play / stop の最小形 | 短い one-shot 1 つ |
| clip_project/ | アプリ作成者 | プロジェクト構成、command/clip 自動分岐、stream_pcm | kit フォルダ |
| osc_remote/ | ライブ・展示 | 触覚ファイル、スマホ（TouchOSC）から起動 | kit + 触覚ファイル |
| task_notifier.py | 開発・ML | 任意コマンドの成否を触覚で通知 | 短い one-shot 1 つ |
| metronome.py | 音楽・ランニング | 触覚メトロノーム（テンポ操作・変拍子） | 短い one-shot 1 つ |
| breathing_pacer.py | ウェルビーイング | 呼吸ガイド（強度ランプ・計測ログ） | 短く柔らかい one-shot |
| psychophysics_experiment.py | 研究 | 検出実験（恒常法・階段法・CSV） | 短い one-shot 1 つ |
| morse_text.py | アクセシビリティ | テキスト → モールス（play/stop で長短） | ループ buzz（または 2 つの one-shot） |
| haptic_pad.py | ライブ・WoZ | キーボードのトリガーパッド（記録・再生） | マッピング元（下記） |
表の「既定の event id」（
sample-kit.sine_100hzなど）はプレースホルダで、必ず自分の kit に 含まれる id に置き換えてください。
コピーして使うときの再利用性
Section titled “コピーして使うときの再利用性”- 単体ファイルの例（minimal / task_notifier / metronome / breathing_pacer / psychophysics_experiment / morse_text / haptic_pad）はそのままコピーして使えます。
- clip_project/ はフォルダごと丸ごとコピーできます。kit の場所を
__file__基準で 解決するので、フォルダを移動しても自分の kit を見つけます。kits/を自分の kit に 差し替えるだけで土台になります。 - osc_remote/ もフォルダごとコピーして使います。中の
kits/demo-kit/を自分の kit に 差し替え、haptics.jsonのkitをそのフォルダに向けてください。
起点（コード）と触覚設定（ファイル）の分離
Section titled “起点（コード）と触覚設定（ファイル）の分離”サンプルは、この分離を段階的に見せています。
- minimal.py — コードに
gainを直接書く最小形。 - clip_project/ — 強度や mode は kit（
connect(kit=...)）に。 - osc_remote/ — target や強度は 触覚ファイル（
connect(haptics=...)）に。
詳しくは プロジェクト構成 と EventMap リファレンス を参照。
つまずきどころ
Section titled “つまずきどころ”- scan では見えるのに鳴らない — いちばん多い原因は、配備した kit に無い event id を
指定していること。Studio で kit の id を確認。
task_notifier.py --testで疎通を確認できます。 - command の例が鳴らない — command の波形は Studio でデバイスに書き込む必要があります
（SDK は
install-clips/を読みません）。clip の例（WAV を送る）は書き込み不要で動きます。 - target が自分のデバイスと合っていない —
targetが一致しないと鳴りません。まず空 （全台ブロードキャスト）で確認し、その後デバイスのアドレスに合わせます。 - clip の音がおかしい — clip WAV は 16 kHz モノ PCM16 で用意してください（SDK は resample しません）。
- gain が想定と違う — gain は 0..1 の絶対値です。ただし
haptic_pad.pyの--masterだけは各パッドへの倍率なので注意。