godot-audio-systems

オーディオシステム

Godotのオーディオエンジン向けの、ミキシング、空間化、プーリング、インタラクティブミュージックに関する専門的なパターンです。

絶対に避けること（オーディオの専門ルール）

ミキシングとバス

• バスの音量に線形値を絶対に設定しないでください — set_bus_volume_db() は対数スケールです。スライダーには linear_to_db() を使用してください。そうしないと、最後の5％に達するまで音が大きすぎます。
• 「バスルーティング」を絶対に省略しないでください — 「SFX」バスで音楽を再生すると、音量メニューが役に立たなくなります。すべてのプレイヤーを専用のサブバス（Music、SFX、UI、Voice）に必ずルーティングしてください。
• ゲームプレイのサウンドに「Master」を絶対に使用しないでください — 最終的なリミッティング用にMasterを確保してください。すべてのゲームプレイ音声をサブグループにルーティングし、カテゴリーごとにミュートやダッキングができるようにします。

位置と空間化

• 減衰モデルなしで3Dプレイヤーを絶対に使用しないでください — デフォルトはNONEです。Inverse Distance に設定しないと、マップの反対側のささやき声も全体音量で再生されます。
• リスナーとまったく同じ位置で3Dサウンドを絶対に再生しないでください — サウンドが左右のスピーカー間で切り替わる「パンニングの揺れ」が発生します。0.1 単位ずらしてください。
• 高速オブジェクトのドップラー効果を絶対に忘れないでください — DOPPLER_TRACKING_PHYSICS_STEP を使用せずに車が通り過ぎると、平坦で静的に感じられます。

パフォーマンスと仕上げ

• 同じフレーム内で同じサウンドを連続再生しないでください — 50個の爆発を一度に再生すると、建設的干渉（クリッピング／歪み）が発生します。Limiter（audio_voice_limiter_manager.gd）を使用してください。
• ワンショット再生のためにノードをインスタンス化しないでください — ノードを作成し、0.5秒の拍手音を再生してから queue_free() すると、フレームタイムの急増を引き起こします。プールを使用してください。
• クロスフェードやトランジションを絶対に省略しないでください — 音楽が突然切り替わると没入感が損なわれます。トラック間をつなぐため、必ず0.5～1.0秒の Tween を使用してください。

---

判断表：どのAudioStreamPlayerを使うべきか？

機能	AudioStreamPlayer	AudioStreamPlayer2D	AudioStreamPlayer3D
空間化	全体	2Dパンニング	3D位置指定
ドップラー効果	なし	なし	あり
減衰	なし	距離ベース	3D減衰
リバーブセンド	なし	なし	あり
用途	音楽、UI、VO	2Dゲーム	3Dゲーム
パフォーマンス	最速	中程度	最遅

ゴールデンパス → スクリプト

必須 — 行に合致するスクリプトのみを開いてください。プール、ダッカー、インタラクティブグラフを記憶に頼って作り直さないでください。

1 つのミックスタスクで、以下のスクリプトをすべて読み込まないでください。

必要な機能	スクリプト
単発 SFX の連打／ボイスの強制停止	必須 audio_voice_pool_manager.gd
同一 SFX の上限（耳障りな音の防止）	必須 audio_voice_limiter_manager.gd
音楽に重ねるダイアログ	必須 audio_bus_ducker_logic.gd
バスレイアウト／実行時のミュート	audio_bus_manager.gd
線形 UI スライダー → dB	audio_linear_volume_interpolator.gd
壁によるこもり	必須 audio_occlusion_raycast.gd
ルームリバーブゾーン	audio_environmental_reverb_zone.gd
垂直方向の強度ステム	必須 audio_interactive_music_manager.gd
水平方向のクリップグラフ	interactive_music_graph.gd + references/interactive-music-deep-dive.md
バス／プールの理由	references/audio-pooling-and-buses.md
クロスフェード／BPM／ダッキング	references/music-transitions.md
アダプティブミュージックプレイヤーのラッパー	audio_adaptive_music_player.gd
オートロード SFX エントリ	audio_manager.gd
足音のサーフェスバンク	audio_footstep_surface_selector.gd
プロシージャルなハム音／エンジン音	audio_procedural_generator_synth.gd
スペクトラム → ゲームプレイ／VFX	audio_reactive_visualizer_component.gd, audio_visualizer.gd
ダイアログの字幕同期	subtitle_sync_system.gd

利用可能なスクリプト（カタログ）

audio_voice_pool_manager.gd

優先度付きボイスプールです。最も優先度が低く、最も古いボイスを強制停止します（ヒーローのボイスは保護されます）。

audio_voice_limiter_manager.gd

同一 SFX インスタンスの同時再生数に上限を設けます。

audio_bus_ducker_logic.gd

サイドチェーン方式で、音楽に重ねるダイアログに合わせて音量を下げます。

audio_bus_manager.gd

Music／SFX／UI／Voice グループのバス音量とミュートを実行時に操作するヘルパーです。

audio_manager.gd

オートロードのエントリです。単発再生をプールにルーティングします。

audio_linear_volume_interpolator.gd

音楽的に適切な、線形値と dB 間の UI スライダーマッピングです。

audio_occlusion_raycast.gd

減衰フィルターのカットオフを使って、レイキャストで音をこもらせます。

audio_environmental_reverb_zone.gd

Area3D によって駆動するリバーブ／バス上書きゾーンです。

audio_interactive_music_manager.gd

AudioStreamSynchronized による垂直方向のステム強度です。

interactive_music_graph.gd

AudioStreamInteractive による水平方向のクリップグラフです。

audio_adaptive_music_player.gd

強度に応じてステムを切り替えるアダプティブミュージックプレイヤーのラッパーです。

audio_footstep_surface_selector.gd

物理情報に基づいて、サーフェスに応じたサウンドバンクを選択します。

audio_procedural_generator_synth.gd

ハム音／エンジン音／信号音のリアルタイムなプロシージャルトーンを生成します。

audio_reactive_visualizer_component.gd

FFT スペクトラムをゲームプレイ／ビジュアルの駆動に使用します。

audio_visualizer.gd

スペクトラムアナライザーの可視化ヘルパーです。

subtitle_sync_system.gd

再生位置に正確に同期する字幕システムです（レイテンシー補正済み）。

高度なオーディオパターン

プーリング（理由）

60 FPS で足音ごとに AudioStreamPlayer.new() を生成すると、1 分あたり 3600 個のノードが作成され、フレームスパイクが発生します。audio_voice_pool_manager.gd は必須です。audio_voice_limiter_manager.gd で重複する効果音を制限してください。同一フレームに 50 個の爆発音が鳴ると、ミックスがクリップします。

詳しくは → audio-pooling-and-buses.md。

バスのアーキテクチャ

Master は最終リミッター専用です。ゲームプレイ → Music / SFX / UI / Voice。set_bus_volume_db(0.5) は誤りです。スライダーには linear_to_db() を使用してください。

音楽のトランジション

トラックを急に切り替えてはいけません。0.5〜2.0 秒の Tween クロスフェード、または BPM に合わせた切り替えを使用してください。垂直／水平に適応するスコアについては、interactive-music-deep-dive.md、music-transitions.md を参照してください。

オクルージョンによるこもり

音源からリスナーに向けてレイを飛ばし、遮られている場合は attenuation_filter_cutoff_hz を Tween で下げます — audio_occlusion_raycast.gd。

字幕同期（タイマーのずれなし）

pos = get_playback_position() + AudioServer.get_time_since_last_mix() - AudioServer.get_output_latency() — subtitle_sync_system.gd。

参考資料

段階的開示：特定の API を調べる場合にのみ公式ドキュメントのリンクを開き、関連分野に進む場合にのみ関連スキルを読み込んでください。スキルの一覧全体を事前に読み込まないでください。

公式ドキュメント

• オーディオ（チュートリアル一覧） — バス、ストリーム、エフェクト、同期、マイク、TTS の各クラスのページを調べる前の入り口です。
• オーディオバス — デシベルスケール、Master／サブバスのルーティング、スライダーの線形値でミキシングが崩れる理由について説明しています。
• オーディオストリーム — AudioStreamPlayer／2D／3D の役割、ランダマイザー、ストリームがバスに届く仕組みについて説明しています。
• オーディオエフェクト — ダッキングや環境ゾーンに使用するバスの FX チェーン（EQ、フィルター、リバーブ、コンプレッサー、リミッター）について説明しています。
• ゲームプレイをオーディオと音楽に同期する — BPM や字幕の同期に使う再生位置ヘルパー（get_time_since_last_mix、レイテンシー）について説明しています。
• オーディオサンプルのインポート — 効果音の連続再生におけるプールサイズと CPU コストを左右する WAV／Ogg／MP3 のトレードオフについて説明しています。
• AudioServer — 実行時のバス音量、ミュート、エフェクトの追加／削除、スペクトラムアナライザーのインスタンスについて説明しています。
• AudioStreamPlayer — プールやクロスフェードマネージャーで使われる、位置に依存しない音楽／UI／音声プレーヤーの API です。
• AudioStreamPlayer3D — 空間的な効果音やオクルージョンに使う、減衰モデル、ドップラー効果、フィルターのカットオフについて説明しています。
• AudioStreamInteractive — 水平型の戦闘↔探索音楽トランジションに使う、クリップグラフ／切り替えモードについて説明しています。
• AudioStreamSynchronized — 垂直型の強度ミックスに使う、ステムレイヤー API（set_sync_stream_volume）について説明しています。

関連スキル

前提条件

• godot-project-foundations — ランタイムのミックスコードを実装する前に、バス名、インポートのデフォルト設定、プロジェクトのオーディオレイテンシ設定が必要です。
• godot-autoload-architecture — 音楽／効果音のプールとバスマネージャーは、ほぼ常に Autoload です。シングルトンの所有権と起動順序にはこちらを使用してください。
• godot-gdscript-mastery — 型付きリソース、シグナル、await／Tween のパターンは、プーリング、ダッキング、インタラクティブな音楽グラフの基盤となります。

補完するスキル

• godot-tweening — クロスフェード、サイドチェーンのダッキングランプ、遮蔽によるカットオフのスイープは、フレームごとの lerp ではなく Tween で制御してください。
• godot-animation-player — Audio Playback トラックと Call Method トラックを使うと、ロケールをまたいで台詞の VO と字幕をフレーム単位で同期できます。
• godot-dialogue-system — 音声の台詞を Voice/Dialog バスにルーティングし、このスキルのバスヘルパーから音楽のダッキングをトリガーする必要があります。
• godot-raycasting-queries — 遮蔽によるこもり効果を正しく適用するには、音源からリスナーまでの PhysicsRayQueryParameters3D マスクを適切に設定する必要があります。
• godot-shaders-basics — スペクトラムアナライザーの振幅は、オーディオに反応する VFX のシェーダーユニフォームやライトのエネルギーを駆動するためによく使われます。
• godot-ui-containers — 音量メニューでは、生のスライダー値ではなく、線形値から dB へのマッピング（linear_to_db）をバスインデックスに接続する必要があります。
• godot-save-load-systems — バスレイアウトを書き換えずに、再起動後もミキサーの設定を維持できるよう、バスごとの音量／ミュート状態を保存します。

下流／利用側

• godot-performance-optimization — プーリング後もボイスプール、ポリフォニー、ミックスコールバックのコストがプロファイラーに現れる場合は、こちらを参照してください。
• godot-monte-carlo-balancer — 効果音の同時再生数の上限、「ラウドネス予算」、連続再生と明瞭さのトレードオフについて、シミュレーションによるバランス調整が必要な場合に使用します（ボイスリミッターと併用します）。
• godot-genre-rhythm — ノート判定ウィンドウや BPM に合わせたトランジションに、オーディオ同期のタイミングヘルパーを使用します。
• godot-combat-system — ヒットや爆発のレイヤーでは、効果音のバスルーティングとボイススティーリングを共有し、戦闘中もミックスがクリップしないようにする必要があります。

マスター

• godot-master — ライブラリのルーター兼ミラー化されたモジュールのエントリです。横断的なオーディオ関連の課題を担当するドメインスキルを確認する際に開いてください。