audio-system

Godot 4.3+ のオーディオシステム

すべての例は、非推奨の API を使わず、Godot 4.3+ を対象としています。まず GDScript を示し、続いて C# を示します。

関連スキル： 疎結合なオーディオトリガーには event-bus、オーディオ設定の永続化には save-load、オーディオデータ用コンテナには resource-pattern を参照してください。

---

1. 基本概念

オーディオノードの種類

ノード	次元	用途
AudioStreamPlayer	非位置指定	音楽、UI サウンド、グローバルな効果音
AudioStreamPlayer2D	2D 位置指定	足音、銃声、環境音
AudioStreamPlayer3D	3D 位置指定	2D と同じですが、3D 空間で使用

オーディオバスの構成

Godot はすべてのオーディオをバス（ミキシングコンソールのようなもの）経由でルーティングします。

Master (always exists)
├── Music          → volume, effects for background music
├── SFX            → volume, effects for sound effects
│   ├── Footsteps  → sub-bus for fine-tuning
│   └── Weapons    → sub-bus for fine-tuning
└── UI             → volume for menu sounds

設定方法： 下部パネル → Audio タブ → バスを追加し、名前を設定して出力先を指定します。

すべての AudioStreamPlayer には bus プロパティがあります。対象のバス名（例："SFX"、"Music"）を設定します。

---

2. 基本的なオーディオ再生

GDScript

extends Node2D

@onready var sfx_player: AudioStreamPlayer2D = $AudioStreamPlayer2D
@onready var music_player: AudioStreamPlayer = $MusicPlayer

func _ready() -> void:
    # Play background music (looping is set on the AudioStream resource)
    music_player.play()

func play_jump_sound() -> void:
    sfx_player.stream = preload("res://audio/sfx/jump.wav")
    sfx_player.play()

C#

using Godot;

public partial class AudioExample : Node2D
{
    private AudioStreamPlayer2D _sfxPlayer;
    private AudioStreamPlayer _musicPlayer;

    public override void _Ready()
    {
        _sfxPlayer = GetNode<AudioStreamPlayer2D>("AudioStreamPlayer2D");
        _musicPlayer = GetNode<AudioStreamPlayer>("MusicPlayer");
        _musicPlayer.Play();
    }

    public void PlayJumpSound()
    {
        _sfxPlayer.Stream = GD.Load<AudioStream>("res://audio/sfx/jump.wav");
        _sfxPlayer.Play();
    }
}

オーディオのループ再生

ループ再生はプレイヤーノードではなく、AudioStream リソースで設定します。

• WAV： Import タブ → Loop Mode → Forward（または Ping-Pong）
• OGG： Import タブ → Loop → On にして、Loop Offset を設定
• MP3： Import タブ → Loop → On

音楽には常に OGG Vorbis を使用してください（ファイルが小さく、音質も良好です）。短い効果音には WAV を使用してください（PCM または QOA はデコード負荷が低い形式です）。効果音には MP3 を使わないでください。エンコーダーによっては、冒頭に無音のパディングが入ることがあります。

---

3. オーディオバスの管理

コードから音量を設定する

Godot では音量に**デシベル（dB）**を使用します。スライダーにはリニア値から dB への変換が必要です。

GDScript

# Get bus index by name
var bus_index: int = AudioServer.get_bus_index("SFX")

# Set volume in dB directly
AudioServer.set_bus_volume_db(bus_index, -6.0)  # -6 dB ≈ half amplitude (db_to_linear(-6.0) ≈ 0.5)

# Convert linear (0.0–1.0) to dB — use for UI sliders
func set_bus_volume_linear(bus_name: String, linear: float) -> void:
    var index := AudioServer.get_bus_index(bus_name)
    AudioServer.set_bus_volume_db(index, linear_to_db(linear))

# Mute / unmute a bus
AudioServer.set_bus_mute(bus_index, true)

# Read current volume as linear (for displaying on a slider)
func get_bus_volume_linear(bus_name: String) -> float:
    var index := AudioServer.get_bus_index(bus_name)
    return db_to_linear(AudioServer.get_bus_volume_db(index))

C#

int busIndex = AudioServer.GetBusIndex("SFX");

// Set volume in dB
AudioServer.SetBusVolumeDb(busIndex, -6.0f);

// Linear to dB conversion for UI sliders
public void SetBusVolumeLinear(string busName, float linear)
{
    int index = AudioServer.GetBusIndex(busName);
    AudioServer.SetBusVolumeDb(index, Mathf.LinearToDb(linear));
}

// Mute / unmute
AudioServer.SetBusMute(busIndex, true);

// Read current volume as linear
public float GetBusVolumeLinear(string busName)
{
    int index = AudioServer.GetBusIndex(busName);
    return Mathf.DbToLinear(AudioServer.GetBusVolumeDb(index));
}

オーディオバスのエフェクト

Audio パネル（下部ドック）でバスにエフェクトを追加します。よく使われるエフェクトは次のとおりです。

エフェクト	用途
Reverb	洞窟、大聖堂、浴室の環境音
Delay	エコー効果
Compressor	大きな音と小さな音を均一化（マスターバス）
HardLimiter	マスターバスのクリッピングを防止（Limiter は非推奨です）
LowPassFilter	こもった音（水中、壁の向こう側）
HighPassFilter	細く高音寄りの音（ラジオ、電話）
Chorus	音に厚みを加える
Distortion	荒々しい音やオーバードライブ効果
EQ	周波数帯を細かく調整

エフェクトの動的な切り替え

# Enable/disable an effect on a bus at runtime
var bus_index := AudioServer.get_bus_index("SFX")
var effect_index := 0  # First effect on the bus
AudioServer.set_bus_effect_enabled(bus_index, effect_index, true)

# Apply low-pass filter for "underwater" feel
func set_underwater(enabled: bool) -> void:
    var index := AudioServer.get_bus_index("SFX")
    # Assumes a LowPassFilter is the first effect on the SFX bus
    AudioServer.set_bus_effect_enabled(index, 0, enabled)

---

4. 空間オーディオ（2D と 3D）

AudioStreamPlayer2D

現在の AudioListener2D（現在有効なものがない場合は画面中央）までの距離に応じて、音量とパンを自動的に調整します。

Enemy (CharacterBody2D)
├── Sprite2D
└── AudioStreamPlayer2D   ← positioned at enemy's location
    bus = "SFX"
    max_distance = 1000.0
    attenuation = 1.0

主なプロパティ：

プロパティ	説明	デフォルト
max_distance	この距離を超えると、音が聞こえなくなります	2000.0
attenuation	音量の減衰カーブ（1.0 = 線形。値が大きいほど急激に減衰します）	1.0
max_polyphony	このプレイヤーで同時に再生できるインスタンスの最大数	1
panning_strength	音が左右にパンする強さ	1.0

AudioStreamPlayer3D

同じ考え方ですが、3D で動作します。AudioListener3D（または Camera3D）と連携します。

主な追加プロパティ：

プロパティ	説明
unit_size	音量が 0 dB になる距離
max_db	音量の上限
attenuation_model	Inverse、InverseSquare、Logarithmic、Disabled
doppler_tracking	移動する音源のドップラー効果を有効にします

AudioListener

# Make a specific camera the audio listener
# 2D: add AudioListener2D as child of Camera2D, call make_current()
# 3D: add AudioListener3D as child of Camera3D, call make_current()

# By default, the current Camera2D/3D acts as the listener.
# Only add an explicit AudioListener if you need a different listening position.

// 2D spatial player
public partial class Footsteps : AudioStreamPlayer2D
{
    public override void _Ready()
    {
        Bus = "SFX";
        MaxDistance = 1000.0f;     // Pixels at which volume reaches zero
        Attenuation = 1.0f;         // Linear falloff (higher = sharper)
        MaxPolyphony = 4;           // Allow overlapping footstep sounds
    }

    public void PlayStep() => Play();
}

// 3D spatial player
public partial class EngineHum : AudioStreamPlayer3D
{
    public override void _Ready()
    {
        Bus = "SFX";
        UnitSize = 4.0f;            // Meters at which volume is 0 dB
        MaxDistance = 50.0f;
        AttenuationModel = AttenuationModelEnum.InverseDistance;
    }
}

// Custom listener — overrides the default Camera2D / Camera3D listener.
public partial class FollowCamListener : AudioListener3D
{
    public override void _Ready() => MakeCurrent();
}

⚠️ Godot 4.7で変更： AudioStreamPlayer2D／AudioStreamPlayer3D の area_mask のデフォルト値が 1 から 0（無効）に変更されました。そのため、デフォルトのままのプレイヤーでは、Area2D／Area3D の audio_bus_override 機能（水中バスなど）が動作しなくなります。復元するには area_mask をレイヤー1に戻してください。レイヤー1以外に明示的に設定されたマスクは引き続き動作します。（移行ガイドには「AudioStreamPlayer」とありますが、area_mask は2D／3Dのバリアントにのみ存在します。）詳しくは4.7移行ガイドを参照してください。

---

5. ミュージックマネージャー（Autoload）

2つの AudioStreamPlayer ノードを管理し、音量_dbをトゥイーンするシングルトンのAutoloadを使って、バックグラウンドトラックをクロスフェードします。設定メニューで音楽の音量を個別に調整できるよう、Music オーディオバスを設定します。

完全なGDScriptとC#のAutoload（クロスフェード、フェードアウトによる停止、ミュージックバスの音量）については、references/music-manager.mdを参照してください。

---

6. 効果音プール

AudioStreamPlayer ノードの固定プールを事前にインスタンス化します。play_sfx(stream) は次に空いているプレイヤーを見つけて再生します。大量に発生する効果音（銃声、足音、被弾音など）で、ショットごとのインスタンス化による負荷を回避できます。

GDScriptとC#のプール型プレイヤー、および2Dの位置指定バリアント（ターゲットを追従する AudioStreamPlayer2D ノードのプール）については、references/sfx-pooling.mdを参照してください。

---

7. オーディオ設定との連携

設定メニューのHSliderをオーディオバスの音量に接続するには、AudioServer.set_bus_volume_db(bus_idx, linear_to_db(value)) を使用します。ConfigFile で設定を保存します。linear_to_db／db_to_linear ヘルパーを使用し、対数を手動で計算しないでください。

設定の保存を含む、設定メニューとの完全な連携方法（GDScriptとC#）については、references/audio-settings.mdを参照してください。

---

8. インタラクティブ音楽とアダプティブ音楽（Godot 4.3以降）

アダプティブ音楽には3種類のストリームがあります。AudioStreamPlaylist（トラックを順番またはシャッフルして再生）、AudioStreamSynchronized（複数のステムを同期再生。戦闘の激しさに応じた垂直レイヤリング）、AudioStreamInteractive（トリガーによるクリップの切り替え。状態駆動型の音楽）です。Godot 4.4以降では、実行時にWAVを読み込む AudioStreamWAV.load_from_file() が追加されています。

Godot 4.7以降： AudioStreamInteractive で TRANSITION_TO_TIME_PREVIOUS_POSITION（TransitionToTime enum）がスクリプトから利用可能になりました。以前にそのクリップから遷移したことがあれば、遷移先のクリップは最後に再生した位置から再開します。そうでなければ、先頭から再生します。探索時と戦闘時の音楽が、中断した位置から再開するような用途に最適です。

ストリームタイプの比較、GDScriptのレシピ、4.7以降の再生位置を引き継ぐ遷移、および4.4以降の実行時読み込み例については、references/interactive-music.mdを参照してください。

---

9. オーディオインポートのベストプラクティス

形式	用途	ファイルサイズ	デコード遅延	ループ対応
WAV	短い効果音	大	なし（PCM）／軽量（QOA、4.4以降のデフォルト）	インポートで設定
OGG	音楽、長い効果音	小	最小限	インポートで設定
MP3	音楽（代替用）	小	パディングあり	インポートで設定

インポート設定

Importドックでオーディオファイルを選択します。

• Loop： 音楽やアンビエントのループで有効にします
• BPM / Beat Count / Bar Beats： リズムに同期するゲーム向けに設定します
• Force Mono（WAVのみ）：3Dの位置指定オーディオで有効にします（ステレオは適切に空間化されないため）。オーディオエディターからOGG／MP3をモノラルで書き出します

ヒント： 効果音は16ビット、44.1kHzのWAVにします。デコード処理をなくすには、WAVインポートの Compress > Mode をPCM（非圧縮）に設定します。4.4以降のデフォルトはQOAです（4.3のデフォルトはPCMで、「Disabled」というラベルが付いています）。音楽には、品質6～8のOGG Vorbisがバランスのよい選択です。

---

11. よくある落とし穴

症状	原因	解決策
音が再生されない	プレイヤーがシーンツリーにない	play() の前に AudioStreamPlayer を add_child() していることを確認します
音は再生されるが聞こえない	バスがミュートされている、または音量が下げられている	Audio パネルでバスを確認します。bus 名のスペルを間違えると Master にフォールバックし、指定したバスを経由しません
シーン変更時に音楽が最初から再生される	プレイヤーがオートロードではなくシーンの一部になっている	音楽プレイヤーをオートロード（MusicManager）に移動します
3D の定位音声が無音になる	現在の Camera3D または AudioListener3D がない（2D では画面の中央が使われます）	AudioListener3D を追加するか、Camera3D が現在のカメラになっていることを確認します
音にクリック音やポップ音が入る	オーディオファイルにフェードイン／フェードアウトがない	オーディオエディターで WAV の開始／終了にごく短いフェード（2～5ms）を追加します
一度に再生される音が多すぎる	同時発音数の上限がない	プレイヤーに max_polyphony を設定するか、SFX プールを使用します
音量スライダーの変化が直線的に感じられない	リニア変換せずに dB 値を直接使用している	スライダーの値には linear_to_db()／db_to_linear() を使用します
3D オーディオがモノラル／平坦に聞こえる	ステレオ音源ファイルを使用している	3D の空間化にはモノラルファイルを使用します（WAV の場合はインポートタブで「Force Mono」を選択します）
MP3 の冒頭に無音がある	ファイルにエンコーダーのパディングが含まれている	タイミングが重要な SFX には WAV、音楽には OGG を使用します

---

12. 実装チェックリスト

• オーディオバスを設定します：Master、Music、SFX（最低限）
• すべての AudioStreamPlayer ノードに正しい bus プロパティを割り当てます
• 音楽には OGG Vorbis 形式を、短い SFX には WAV を使用します
• 音楽プレイヤーをオートロードに配置します（シーン変更後も維持されます）
• 滑らかに切り替わるよう、音楽のクロスフェードを実装します
• AudioStreamPlayer ノードを動的に新規作成する代わりに、SFX プールを使用します
• 音量スライダーには linear_to_db()／db_to_linear() による変換を使用します
• linear_to_db(0.0) が -inf になるのを避けるため、スライダーの値がほぼゼロの場合はバスをミュートします
• 3D オーディオソースには、適切な空間化のためにモノラルのオーディオファイルを使用します
• ゲーム起動時にオーディオ設定を保存し、復元します（ConfigFile などを使用します）
• ループ再生はコードではなく AudioStream リソースで設定します
• インタラクティブ／アダプティブ音楽には、手動でトラックを切り替えるコードではなく AudioStreamPlaylist、AudioStreamSynchronized、または AudioStreamInteractive（Godot 4.3+）を使用します