API リファレンス

C++ ランタイム（namespace ToneBeyond / #include <tonebeyond/tonebeyond.h>）、モバイル用ファサード、 各ファイル形式の仕様。「RTセーフ」= ゲーム中いつ呼んでもよい （ヒープ確保・ロック・ファイル I/O なし）。「ロード時」= ロード画面等で呼ぶ（確保あり）。

EngineConfig — 初期化パラメータ

Engine::Initialize() に渡す構造体。省略時は既定値。

ライフサイクル

サウンドとバンク

再生 — イベント / 3D / ボイスハンドル

イベント名はコンパイル時に FNV-1a 32bit へハッシュされます（HashEvent("name")）。 文字列のオーバーロードはどれもリテラルを渡せばゼロコストです。

RTPC — 動的パラメータ

カーブは折れ線（最大8点、x昇順、範囲外は端の値でクランプ）。 ターゲットは RtpcTarget::Volume（ゲイン倍率）か RtpcTarget::Pitch（再生速度倍率。ストリーミングボイスには効きません）。 値は rtpcSmoothingMs の指数平滑で補間されます。

// 例: 危険度 0→1 で BGM 緊迫ステムが立ち上がる（カーブはエディタ製）
ToneBeyond::Engine::SetParameter("Danger", dangerLevel);  // 毎フレームOK

バス — カテゴリ音量とマスター

イベントはエディタ（プロパティの「バス」欄）か bank.json の "bus" キーで カテゴリバス（"BGM"、"SFX" など）に割り当てられます。バス音量とマスター音量は RTPC と同じ平滑化がかかるため、設定画面のスライダーに直結してもクリックノイズが出ません。

// 例: 設定画面の音量スライダー
ToneBeyond::Engine::SetBusVolume("BGM", bgmSlider);   // BGM だけ下げる
ToneBeyond::Engine::SetMasterVolume(masterSlider);     // 全体
ToneBeyond::Engine::StopEvent("BGM_Main", 400.0f);     // 400ms かけてフェード停止

ダッキング（自動音量回避） — bank.json のトップレベル "duck" で 「ソースバスの再生中はターゲットバスを下げる」ルールをバンクに焼けます（エディタの 「ダッキング」ボタンで編集）。ゲーム側のコードは不要 — 例えばボイスを Voice バスに割り当てておけば、再生のたびに BGM が自動で沈み、止まると戻ります （attack/release ms 指定、ランタイムはサンプル精度のリニアランプ）。

ループポイント（イントロ→ループ本体） — 各イベントの "loopStartMs"（エディタではループ有効時の「ループ開始 ms」欄）で、ループが 先頭ではなくその位置へ巻き戻ります。イントロは一度だけ再生され、以後は本体が シームレスに回り続けます。メモリ/ストリーミング PCM/ストリーミング QOA すべて対応。

バイノーラル 3D — ヘッドホン向け立体音響

3D ボイス（PostEvent3D）の描画を、通常のステレオパンから 構造 HRTF モデル（両耳時間差 + 頭部遮蔽ローパス + 耳介の仰角ノッチ）に 切り替えられます。ヘッドホンで上下・前後の方向感が出ます。既定は OFF （従来のパンのまま）。係数はブロック単位で計算され、コールバックは アロケーションフリーのままです。現状はメモリ再生の 3D ボイスのみ （ストリーミングは従来パン）。

優先度と仮想化 — 発音数が足りないとき

各イベントの優先度（0〜100、既定50。エディタの「優先度」欄 / bank.json の "priority"）で、ボイスプールが満杯のときの振る舞いが決まります: 新しい音は「仮想化済み → 低優先 → 最古」の順に既存ボイスを奪い、 自分より高優先のボイスは決して奪いません。BGM を 90、足音を 20 のようにしておけば、 弾幕の密度がどれだけ上がっても音楽は途切れません。

仮想化 — 聞こえないボイス（ミュートされたバス・フルダッキング・距離減衰）は ミックス処理をスキップしつつ再生位置だけ進み続けるので、再び聞こえるようになった 瞬間も完全に同期しています（CPU 節約 + 奪われ候補の筆頭になる）。 DebugVirtualVoiceCount() で確認できます。

ステート — 曲面切替（ミュージックスイッチ）

同じステートグループに属する複数のイベント（それぞれ別のステート値）は、 ビルド時に1つのスイッチコンテナになります。ゲームはグループ名を1回 postEvent し、 あとは SetState で値を切り替えるだけ — 再生中のボイスが stateFadeMs（既定500ms）でクロスフェードします。ループポイントと併用すれば 「通常ループ ⇄ ボスループ」のシームレス切替になります。

ToneBeyond::Engine::PostEvent("Music_Stage01");         // 既定値（最初に並べた曲）で開始
ToneBeyond::Engine::SetState("Music_Stage01", "Boss");  // ボス曲へクロスフェード
ToneBeyond::Engine::StopEvent("Music_Stage01", 800.0f); // グループ名で停止も可

Live Profiler と診断

TBAudio — Swift / Kotlin ファサード

組み込みキットが生成するモバイル向け API。C++ API の主要部を1対1で包みます。

bank.json — バンク定義

エディタの「bank.json を書き出し」が生成（手書きも可）。bankc の入力。

{
  "sampleRate": 48000,
  "events": [
    { "name": "sword_swing",          // 英数字と _ のみ（= イベント名）
      "file": "sword_swing.wav",      // JSON からの相対 or 絶対パス
      "looping": false,
      "streaming": false,              // true: ディスクから直接再生（BGM）
      "compress": false,               // true: QOA 圧縮（約1/10）
      "gainDb": 0.0,                   // 既定ゲイン
      "chain": [                       // 非破壊編集（焼き込み）
        { "type": "trim", "inMs": 0, "outMs": 500 },
        { "type": "gain", "db": -3 },
        { "type": "fadein", "ms": 10 },
        { "type": "fadeout", "ms": 120 },
        { "type": "reverse" } ],
      "files": ["hit1.wav", "hit2.wav"],  // 2..8個でバリエーション化（"file" の代わり）
      "variation": "random",           // random（既定・直前回避）| roundrobin
      "bus": "SFX",                    // カテゴリ音量バス（省略可）
      "loopStartMs": 1000,             // ループ開始位置（イントロ→本体、省略可）
      "stateGroup": "Music_Stage01",   // ステートグループ（省略可）
      "stateValue": "Boss",            // グループ内の値（stateGroup とペア）
      "stateFadeMs": 800,              // 切替クロスフェード（省略時 500）
      "priority": 90,                  // ボイス優先度 0-100（省略時 50）
      "rtpc": [                        // RTPC カーブ（焼き込み）
        { "param": "Danger", "target": "volume",   // volume | pitch
          "points": [[0, 0], [1, 1]] } ] }          // [値, 倍率] 最大8点
  ],
  "duck": [                            // ダッキングルール（省略可・バンク全体）
    { "source": "Voice", "target": "BGM", "db": -6, "attackMs": 100, "releaseMs": 400 } ]
}

tb_sound_requests.json — サウンド発注書

ゲームリポジトリ直下に置く制作依頼シート。postEvent 追加と同じコミットで更新します。

CLI ツール