godot-audio

Godot Audio（4.x）

SFX や音楽を再生し、バスを通してルーティングし、デシベル単位で音量を制御して、ゲームプレイをビートに合わせます。対象は Godot 4.7 です。

使用する場面

• 効果音や音楽の再生、バス（Master/Music/SFX）へのオーディオのルーティング、コードからの音量調整やミュート、バスエフェクト（リバーブ、コンプレッサー）の追加、位置に応じた3Dオーディオ、音楽に合わせたイベント同期を行う場合に使用します。

使用しない場面： エンジンに依存しないオーディオの設計（アダプティブミュージックの構成、ミキシングの考え方、ダッキングのパターン）→ audio-design。Godot 以外でのアセットのインポート／エンコード。

基本的なワークフロー

1. プレイヤーノードを選びます。
   • AudioStreamPlayer — 位置に依存しない音声（音楽、UI、全体で使う効果音）。
   • AudioStreamPlayer2D / AudioStreamPlayer3D — 位置に依存し、音量／パンが距離に応じて変化します。
2. stream に AudioStream（音楽／ループには .ogg、短い効果音には .wav）を割り当てて、play() を呼び出します。シーン開始時に再生する音楽には autoplay を設定します。
3. バスにルーティングします。 プレイヤーの bus に名前付きバス（例："Music"、"SFX"）を設定します。バスは Audio パネル（下部ドック）で定義します。各バスには音量、ミュート、ソロ、エフェクトを設定できます。
4. 音量は線形値ではなく dB で制御します。（オーディオは対数スケールです。）0 dB = 変更なし、-80 dB ≈ 無音です。linear_to_db / db_to_linear で変換します。
5. AudioServer を使って、バスのインデックスからコードで音量／ミュートを制御します。
6. リズムに合わせる場合は、出力レイテンシを補正して正確な再生時刻を計算します。

パターン

1. ワンショット効果音（再生して終了）

@onready var sfx: AudioStreamPlayer = $Sfx   # stream assigned in the editor

func play_jump() -> void:
    sfx.pitch_scale = randf_range(0.95, 1.05)   # slight variation avoids fatigue
    sfx.play()

# For many overlapping copies, use an AudioStreamPlayer with an
# AudioStreamPolyphonic stream, or spawn short-lived players and free on `finished`.

2. AudioServer でバスの音量とミュートを設定する

func set_music_volume(linear_0_to_1: float) -> void:
    var bus := AudioServer.get_bus_index("Music")
    # Convert a 0..1 slider to decibels; clamp avoids -inf at 0.
    AudioServer.set_bus_volume_db(bus, linear_to_db(maxf(linear_0_to_1, 0.0001)))

func toggle_sfx(muted: bool) -> void:
    AudioServer.set_bus_mute(AudioServer.get_bus_index("SFX"), muted)

3. 2つの音楽トラック間でクロスフェードする

@onready var a: AudioStreamPlayer = $MusicA
@onready var b: AudioStreamPlayer = $MusicB

func crossfade_to(stream: AudioStream, secs := 1.5) -> void:
    b.stream = stream
    b.volume_db = -40.0
    b.play()
    var tw := create_tween().set_parallel(true)
    tw.tween_property(a, "volume_db", -40.0, secs)   # fade out current
    tw.tween_property(b, "volume_db", 0.0, secs)     # fade in next
    tw.chain().tween_callback(a.stop)
    var tmp := a; a = b; b = tmp                      # swap roles

4. ビートに正確に合わせる（出力レイテンシを補正）

@onready var music: AudioStreamPlayer = $Music

func get_playback_time() -> float:
    # Add time since the last audio mix, subtract output latency, for sub-frame accuracy.
    var t := music.get_playback_position() + AudioServer.get_time_since_last_mix()
    return t - AudioServer.get_output_latency()

注意点

• 音量を線形値として扱う。 volume_db / set_bus_volume_db はデシベルです。volume_db = 0.5 はほぼ最大音量であり、半分の音量ではありません。スライダーの値は linear_to_db で変換します。
• linear_to_db(0.0) は -inf になります。 変換前に線形値を小さな最小値（例：0.0001）に制限するか、0 の場合はミュートするよう個別に処理します。
• バス名の入力ミスは気づきにくい形で失敗します。 get_bus_index("Muisc") は -1 を返し、その後の呼び出しはエラーになるか何も行いません。Audio パネルに表示されている正確なバス名を指定してください。
• 同じプレイヤーを再度トリガーすると、短い効果音が途中で切れます。 プレイヤーを分ける、AudioStreamPolyphonic を使う、または再生ごとに AudioStreamPlayer を作成して finished 時に解放します。
• インポート設定／ストリームでループを有効にしないと、音楽はループしません。（.ogg のインポート設定には Loop オプションがあり、AudioStreamWAV には loop_mode があります。）
• get_playback_position() だけで同期すると、タイミングが不安定になります。 この値はフレームごとではなくオーディオミックスごとに更新されるため、get_time_since_last_mix() を加算し、get_output_latency() を差し引いてください。
• 3D オーディオが聞こえない場合 → 音を聞くための AudioListener3D / Camera3D がない、max_distance / 減衰範囲が狭すぎる、または誤ったバスがミュートされています。

参考資料

• バスのレイアウト（.tres）、エフェクト（リバーブ／コンプレッサー／EQ）の追加とサイドチェーンダッキング、AudioStreamPolyphonic / AudioStreamInteractive、マイク入力、AudioStreamGenerator を使ったプロシージャルオーディオについては、references/buses-and-effects.md を参照してください。

関連スキル

• audio-design — エンジンに依存しないアダプティブミュージック、ミキシング、ダッキングの実践。
• godot-animation — アニメーション／Tween を get_playback_position() に同期します。
• godot-ui-control — AudioServer に接続した音量スライダー。