How to add and play sound effects in Godot 4

Example tracks

These are real catalog tracks. The credit line under each row is the one Uncommon Ear generates.

Steps

1. Save the file in your project

   Put the sound in a folder such as res://audio/sfx/. If you can choose, use WAV for short effects that play often and Ogg Vorbis for long effects. The Godot manual recommends WAV for short, repetitive effects because it is cheap to play, and Ogg Vorbis for music, speech and long effects because it compresses more but costs more CPU.

2. Check the import settings

   Select the file in the FileSystem dock and open the Import dock. If the effect does not need stereo, turn on Force > Mono for a WAV file, which the manual says roughly halves the file size. For a one-shot WAV, set Edit > Loop Mode to Disabled, because Godot otherwise follows any loop points stored in the WAV file. Select Reimport to apply the change. Godot discards the change if you select another file first.

3. Add a player and play the sound

   Add an AudioStreamPlayer node, drag the file onto its Stream property, and name the node ClickPlayer. Then play it from a script. Leave Autoplay off for sounds you trigger yourself.

   Add a player and play the sound Copy

   extends Node
   
   @onready var click_player: AudioStreamPlayer = $ClickPlayer
   
   func _on_button_pressed() -> void:
   	click_player.play()

4. Use the 2D or 3D player for sounds in the world

   If the sound comes from a place in the scene, use AudioStreamPlayer2D or AudioStreamPlayer3D instead. Both position the sound, so it pans or changes with where the node is. Add the player as a child of the object that makes the sound, such as a character or a door.

   Use the 2D or 3D player for sounds in the world Copy

   extends CharacterBody2D
   
   @onready var step_player: AudioStreamPlayer2D = $StepPlayer
   
   func _on_step_timer_timeout() -> void:
   	step_player.play()

5. Let sounds overlap

   If one effect fires several times in quick succession, such as footsteps or gunfire, raise max_polyphony. It defaults to 1, and when a node reaches its limit, a new play() call cuts off the oldest sound. A small random pitch change also makes repeated sounds less obvious.

   Let sounds overlap Copy

   func _ready() -> void:
   	step_player.max_polyphony = 4
   
   func play_step() -> void:
   	step_player.pitch_scale = randf_range(0.9, 1.1)
   	step_player.play()

6. Send effects to their own bus

   To control all effects with one volume setting, create a bus named SFX in the Audio panel at the bottom of the editor, then set the player's Bus property to SFX. Buses are matched by name. If a bus does not exist, the player falls back to Master. To change the level from a script, look up the bus index first.

   Send effects to their own bus Copy

   func set_sfx_volume(volume_db: float) -> void:
   	var bus_index: int = AudioServer.get_bus_index(&"SFX")
   	AudioServer.set_bus_volume_db(bus_index, volume_db)

7. Loop an ambient sound

   If a sound should repeat, such as a dungeon ambience, import it as Ogg Vorbis and turn on Loop in the Import dock. Loop Offset sets, in seconds, where playback restarts, and 0 loops the whole file. You can also set it from a script before you play the stream.

   Loop an ambient sound Copy

   @onready var ambience_player: AudioStreamPlayer = $AmbiencePlayer
   
   func _ready() -> void:
   	var ambience := load("res://audio/sfx/dungeon_ambience.ogg") as AudioStreamOggVorbis
   	ambience.loop = true
   	ambience_player.stream = ambience
   	ambience_player.play()

Common mistakes

• Calling play() on a player with max_polyphony 1 for a rapid sound. Each call cuts off the previous one.
• Importing a long ambience or music track as WAV. The files are large; Ogg Vorbis suits long sounds.
• Renaming a bus without updating the players that use it. They silently fall back to Master.
• Using a non-positional AudioStreamPlayer for a sound that belongs to an object. It does not follow the object's position.
• Leaving a one-shot WAV on Detect From WAV when the file carries loop points. It can loop when you did not intend it to.
• Skipping the license check. CC0 sounds need no credit, but a CC BY sound needs its credit line in your game credits.