波形エディターとシーン確認（ベータ）

このページは、ゲームのイベント（足音・咆哮など）に 音と触覚の素材 を割り当て、ゲームの録画に合わせて確認する機能の概要です。AI エージェントと一緒に素材を作る場合の手順と前提もまとめています。

AI エージェントで使う（最短手順）

helper を MCP 付きで入れて起動する
```
pipx install "hapbeat-helper[mcp]"
hapbeat-helper start
```
すでに入っている場合は pipx install --force "hapbeat-helper[mcp]"。helper 全般は Helper をインストールを参照。
エージェントに MCP サーバーを登録する
- Claude Code: claude mcp add hapbeat -s user -- hapbeat-helper mcp
- Codex: ~/.codex/config.toml に次を追加（daemon が 7703 以外なら args に --port N）
```
[mcp_servers.hapbeat]
command = "hapbeat-helper"
args = ["mcp"]
```
Studio を開く: Chrome または Edge で https://studio.hapbeat.com を開き、波形エディターの「フォルダを開く」で 編集フォルダ を選ぶ。空のフォルダを選ぶと「このフォルダを編集フォルダにしますか？」と聞かれるので、はいで初期化する。エージェントが動いている間、このタブを開いたままにする。
シーン確認も使う場合: シーン確認タブの「プロジェクト」で ゲームプロジェクト のフォルダを開く。cue 表と録画（Saved/HapticViewer/、プロジェクトの録画スクリプトで作る。下記「録画の置き場所」）が必要。
エージェントが最初にすること: status で helper と Studio につながっているか確認し、get_guide で手順と書式を読む。試行（AI 提案）の書式の正本は get_guide の内容（ここに書く項目は概要）。

依頼の例:

hapbeat MCP を使って、ゲームプロジェクト my-game の footstep（足音）の触覚を作ってください。
まず status と get_guide を確認し、get_knowledge を読んでから、作り方の違う候補を 3〜4 個 submit_trial してください。
音はすでに決まっています。scene に cue を入れ、評価は wait_for_rating で受け取って次の候補に反映してください。

2 つのフォルダ

フォルダ	中身	開く場所
編集フォルダ	波形エディターの作業場所と記録（下表）。全プロジェクトで 1 つを共用し、プロジェクトはクリップの「プロジェクト」名で分かれます	波形エディターの「フォルダを開く」
ゲームプロジェクト	cue 表（イベントごとの音・触覚の割り当て）、素材の WAV、録画（通し映像とイベントの発生時刻）	シーン確認タブの「プロジェクト」

ゲームプロジェクトを波形エディターで開かないでください。開いたフォルダは編集フォルダとして初期化され、.hapbeat-editor/ などが作られます。
決めた割り当てと素材（cue 表と WAV）は、ゲームが実行時に読むので ゲームプロジェクト に書き込まれます。編集フォルダには、作業途中のものと記録だけが残ります。

編集フォルダの中身

場所	中身
`materials/<project>/`	入手したままの元素材（効果音など）
`adjust/<project>/<sound\|haptic>/`	「調整」した素材のエフェクト設定と、調整前の音声
`scene-overrides/<project>.json`	シーン確認タブで加えた変更（発生の振り分け変更など）
`haptic-knowledge/`	AI 提案と評価の記録（知識ベース）。全プロジェクト共通
`hapbeat-agent/`	AI エージェントとの受け渡し（提案の依頼、エージェントが作った音源、Studio からの依頼）
`exports/`	手動で書き出したファイル
`.hapbeat-editor/`	Studio の内部キャッシュと表示設定。読み書きしないでください（消えても再構築されます）

録画の置き場所

録画はゲームプロジェクトの Saved/HapticViewer/（Unreal Engine の場合）に作られます。通し映像（full_replay.mp4）、イベントごとの短い動画、発生時刻とレベルのデータ（viewer-data.json）、cue 表と WAV の場所（viewer-lib.json）です。

録画はゲームのリプレイを固定フレームレートで撮って作ります（プロジェクトの録画スクリプト）。撮り直せば同じものができるので、バージョン管理しません（Saved/ は Unreal Engine の生成物の置き場で、通常 Git から除外します）。
ゲームはこの録画を読みません。シーン確認タブが、cue 表・WAV と同じフォルダから読み書きできるよう、ゲームプロジェクトに置いています。

AI エージェントとの連携（MCP）

hapbeat-helper の hapbeat-helper mcp を MCP サーバーとして登録すると、AI エージェントは次の流れで Studio と協働できます。

status で接続を確認し、get_guide で手順と書式を読む（編集フォルダの hapbeat-agent/GUIDE.md と同じ内容）
get_knowledge で過去の評価を読む
submit_trial で候補（AI 提案）を出す
ユーザーが Studio で評価して保存する（保存が合図。別途「送信」はありません）。評価を書くのはユーザーだけです
wait_for_rating で評価を受け取り、次の候補を作る

Studio からエージェントへの依頼（音の依頼・再作成・触覚へ進む・振り分けの変更）は、編集フォルダの hapbeat-agent/outbox/ に書かれます。

提案の書式（エージェント向けの要点）

正本は get_guide です。シーンに合わせて作るときに使う主な項目:

項目	意味
`target`	`"sound"`（効果音）または `"haptic"`（既定）。イベントごとに音を先に決め、その音に合わせて触覚を作る
`scene.project` / `scene.cues`	対象のゲームプロジェクト名と cue（`"footstep:approach"` のように variant も可）。先頭の cue が採用先のイベント
`scene.context`	ゲームで対象の周りに鳴る cue（例: 一緒に始まるループ）。試聴で、その cue の決定済みの素材を候補と一緒に鳴らす。同時に鳴るとまとめられたイベントは書かなくても鳴る
候補の `sound`	触覚の候補を合わせた音（cue の★の音の名前、`.wav` なし）。試聴でその音を一緒に鳴らす
候補の `intensity`	評価フォームの強さスライダーの初期値（0 < x ≤ 1、省略 = 1）。WAV はフルスケールのまま書き、小さく書き出さない
候補の `method`	触覚の作り方（`synth` / `sfx` / `envelope` / `layered` / `onset` / `bandsplit`）。知識ベースは作り方ごとに集計される

AI 提案と評価

候補ごとに ★（1〜5）とコメントを付け、提案全体にもコメントを書けます。コメントが主な情報源です。
場面のあるイベントは、録画の通し映像から代表の区間を切り出し、イベントの発生時刻どおりに試聴できます。scene.context の cue や同時に鳴るイベントも一緒に鳴ります（「周りのイベントも鳴らす」で切り替え）。
「保存して次へ」で確定します。★4 以上の候補はイベントの ★なしの候補（alternates）に自動で追加され、イベントに★の素材がまだ無いときだけ★になります。★3 は控えに入ります。入力中の内容は自動で下書き保存されます。

イベントパネル

ゲームの cue ごとに、音と触覚の素材を管理します。

★（鳴らす素材）と★なしの候補: ゲームと Studio が鳴らすのは★を付けた素材だけです（cue 表の sfx.sounds / route の clips）。★の先頭が代表で、エディタの試聴と単発の場面で使います。★が複数あれば毎回どれかを鳴らします（足音など）。★なしの候補（cue 表の alternates）はイベントに残しますが鳴らしません。行ごとの★をクリックで切り替えます（最後の★は外せません。鳴らさないなら「なし」）。
控え: cue 表に入れていない、エディタ側だけの素材です（★3 の AI 候補と、イベントを「未定」にしたときに外れた素材）。控えからイベントに戻せます。
状態: 音・触覚ごとに 未定 / なし仮 / なし OK / 仮 / OK を表示します。「なし OK」は素材なしで確認済み。割り当てた素材は「仮」から始まり、確認したら「OK」にします。cue 表の変更はすべて自動保存されます。
同時に鳴るイベント: 録画で同じ瞬間（0.2 秒以内）に鳴るイベントはまとめて表示されます（表示だけで、cue 表は変わりません）。⋯ メニューの「グループに入れる」「グループから外す」で手動で直せます。どれかを試聴すると、ほかのイベントも一緒に鳴ります。
調整: 素材をその場でエフェクト（LPF など）と 強さスライダー で調整します。変更はすぐイベントの WAV に反映され、元の音声とエフェクトは編集フォルダの adjust/ に残ります。
波形パネル: 既定では素材のファイルを 1 本だけ表示します。「発生に合わせて並べる」をオンにすると、試聴を場面のタイミングどおりに並べて描きます（試聴はどちらでも場面のタイミングで鳴ります）。音は青、触覚はオレンジで表示します。
試聴の触覚は、その cue の装着位置（首・手首など）に合うデバイスだけに送られます。

シーン確認タブ

録画に合わせて、cue ごとの全発生を確認します。

場面の倍率（触覚の route gain・音の sfx.volume）は、このタブでだけ編集します（既定 1）。
揺らぎ（素材の選び方、強さ・高さ・速さの揺らぎ）と variant（状況別の鳴らし分け）を編集できます。variant は「倍率だけ」（素材は親から引き継ぐ）か「素材を上書き」を選べます。倍率だけの variant は、一続きの発生の間に倍率を変える だんだん変える（形: 線形・後半で急に・早めに・S 字・急な S 字）や 1 発ずつ決める も持てます。
距離で弱める（distanceFalloff）: プレイヤーとの距離で音と触覚の両方を弱めます（近い所で ×1、遠い所で遠くの倍率）。録画に距離が無い発生は ×1 です。
音と触覚を組にする（paired）: 音ごとに長さが違う場合、選ばれた音と同じ番号の触覚を鳴らします。
ループ cue の入力 → 出力（levelMap）: ゲームがループに渡す値（録画のレベル。送りの速さなど）を入力、倍率を出力とする関数です。(0, 切片) と各点を入力の順に結び、区間の形を直線・下に凸・上に凸・S 字・急な S 字（linear / easeIn / easeOut / easeInOut / sigmoid）から選びます。再生して今の入力のところで出力を決め、「点を置く」で点を置きます（時間には結び付きません）。最後の点より先は最後の区間の傾きで延長し、出力は 0〜4 に収まります。入力 0（ループ停止中）は常に 0、点が無いときは出力 = 入力です。今の入力と録画の最大も表示します。
自動で鳴らす間隔（emit）: ループ cue が鳴っている間にゲームが自分で鳴らす単発 cue の、間隔（秒）と揺らぎ（%）を決めます。このタブでは録画の発生ではなく、ループ cue の入力が 0 より大きい区間から同じ規則で発生を作って鳴らします（「乱数を引き直す」で作り直し）。
発生の付け替え: 左の一覧の各行の「変更」で、その発生を別のイベント／状況にする依頼をエージェントに送ります（cue 表には場面ごとの値を持ちません。新しい variant 名なら、倍率だけの variant をすぐ作ります）。
キー操作: タイムラインのクリックで移動、Ctrl+クリック（Mac は Cmd+クリック）でそのイベントに切り替え。F で全編に戻って続きを再生、O で選んだイベントをエディタで開きます。

cue 表

cue 表（JSON）は、ゲームが実行時に読む イベント → 音・触覚 の対応表です。Studio のイベントパネルとシーン確認タブはこの表を編集し、ゲームのビルド時に取り込まれます。Studio の外（エージェントなど）で書き換えられた場合は、項目単位で取り込まれます。

キーが無い = 未定、"sfx": null / "haptics": [] = なし（決定済み）。ゲームでは未定もなしも鳴らしません。
★の素材は sfx.sounds / route の clips、★なしの候補は sfx.alternates / route の alternates です。

強さの 3 層

層	置き場所	編集する場所
形	WAV（常にフルスケール、ピーク約 −0.5 dBFS）	エフェクト（イベントパネルの「調整」）
素材の強さ	素材ごとの intensity（0〜1）	強さスライダー（イベントパネルの「調整」）
場面の倍率	route gain / sfx.volume（既定 1）	シーン確認タブ

最終的な出力は WAV × intensity × 場面の倍率 × デバイス音量 です。ループ cue では、さらに入力 → 出力（levelMap）の出力が掛かります。エディタの試聴は WAV × intensity（場面の倍率は掛けない）、シーン確認タブの再生は場面の倍率まで掛けて鳴らします。