AudioStreamPlayer in Godot – Complete Guide

Welcome to our exploration of the AudioStreamPlayer class in Godot 4! If you’re venturing into the realm of game development with Godot, understanding how to control audio is crucial. Sound adds depth, emotion, and clarity to player actions, making it an indispensable part of any game’s atmosphere. Whether you’re a beginner or an experienced coder, this tutorial will guide you through the ins and outs of non-positional audio playback in Godot, ensuring that your games sound as good as they look.

What Is AudioStreamPlayer?

The AudioStreamPlayer is a Godot node for playing audio streams. Unlike its cousins, AudioStreamPlayer2D and AudioStreamPlayer3D, which play audio with positional data, AudioStreamPlayer handles sound playback that doesn’t require a position in space. Think of background music or a user interface click – sounds that are integral to the user experience but don’t originate from a specific location in the game world.

What Is It For?

AudioStreamPlayer fills an essential role in game development by managing sounds that maintain a consistent volume and quality, regardless of the player’s position or actions. This is perfect for elements like:

  • Game soundtracks
  • Menu confirmations and alerts
  • Global sound effects, such as win or loss jingles

Why Should I Learn About It?

Manipulating audio effectively can dramatically improve your game’s immersion and polish. Learning to use the AudioStreamPlayer will give you the ability to:

  • Enhance player feedback through sound
  • Adjust sound properties like volume and pitch to fit your game’s mood
  • Control the flow of audio with playback features such as autoplay, pause, and stop

Let’s dive into harnessing the power of sound in Godot, with engaging and practical examples to ensure you can apply these concepts directly to your own game projects.

CTA Small Image

Setting Up AudioStreamPlayer

Before you start working with audio in Godot, you need to add an AudioStreamPlayer node to your scene. Here’s how you do it through the Godot Editor:

var audio_player =

This creates a new AudioStreamPlayer node and adds it as a child to the current node. Once your AudioStreamPlayer is part of the scene tree, you can load an audio file into it.

var stream = preload("res://path_to_your_audio_file.ogg") = stream

You can also set the audio stream through Godot’s Inspector once you select the AudioStreamPlayer node. Drag and drop your audio file into the “Stream” property field.

Playing and Stopping Sounds

To play a sound, simply call the `play()` method on your AudioStreamPlayer node. Here’s how:

Similarly, you can stop the sound by using the `stop()` method:


Remember that calling `stop()` will end the playback entirely, and replaying the sound with `play()` will start it from the beginning. If you want to pause the sound, and later resume it from the same position, use `pause()` and `play()` accordingly.

Controlling Playback Properties

In addition to starting and stopping audio, you can adjust various properties such as volume (gain) and pitch (pitch_scale). Let’s say you want to set the volume to half its original level and double the pitch:

audio_player.volume_db = -6 # Volume is half of the original.
audio_player.pitch_scale = 2.0 # Pitch is doubled.

Setting the volume_db property to -6 will reduce the amplitude by half (since the volume is measured in decibels), while setting pitch_scale to 2.0 will raise the pitch by an octave.

Using Autoplay

Sometimes you want a sound to play as soon as the scene starts. For this, Godot provides the autoplay feature. Enable it directly in the Godot Editor by selecting the AudioStreamPlayer node and checking the “Autoplay” property, or do it via code:

audio_player.autoplay = true

This will trigger the audio to play automatically when the scene is loaded. Remember that to use autoplay effectively, the AudioStreamPlayer must be active and in the scene tree at the scene’s start.

Loading and Playing Different Sounds

If your game requires multiple sounds, you can dynamically load and assign them to your AudioStreamPlayer. This flexibility allows you to play different sounds in response to game events. Here’s how you might switch between different sounds:

var sound_one = preload("res://sound_one.ogg")
var sound_two = preload("res://sound_two.ogg")

func play_sound_one(): = sound_one

func play_sound_two(): = sound_two

With these basics covered, you now have the tools to incorporate immersive audio into your Godot projects. Sound design is not only about the quality of the audio, but also about when and how it’s played in your game – mastery of AudioStreamPlayer gives you that control.As we dive deeper into the capabilities of AudioStreamPlayer, let’s explore how to handle more advanced tasks such as looping sounds, responding to sound completion, and setting up audio buses for even more control over your game’s soundscape.

Looping a Sound

Looping a sound with AudioStreamPlayer is perfect for background music or continuous effects. Here’s how you can make a sound loop: = preload("res://background_music.ogg")
audio_player.loop = true

By setting the loop property to true, the audio will automatically restart once it ends, creating a seamless loop.

Detecting Sound Completion

Sometimes you need to perform an action when a sound finishes playing. Godot emits a signal called “finished” when an AudioStreamPlayer completes playback. Let’s connect this signal to perform a custom function:

audio_player.connect("finished", self, "_on_AudioStreamPlayer_finished")

func _on_AudioStreamPlayer_finished():
    print("Sound has finished playing!")

Connecting the “finished” signal to a function allows you to respond to the end of the sound playback, which can be useful for things like timing game events to audio cues.

Adjusting Audio On The Fly

Dynamic control over audio properties can add a lot to your game. Suppose you want to fade out your music dynamically. You could achieve this by decreasing the volume over time using Godot’s `tween` node:

var tween =
tween.interpolate_property(audio_player, "volume_db", -20, -80, 2, Tween.TRANS_LINEAR, Tween.EASE_IN_OUT)

This code snippet creates a new Tween node, which will interpolate the volume of the AudioStreamPlayer from -20 decibels to -80 decibels over a span of 2 seconds, effectively creating a fade-out effect.

Using Audio Buses

Godot provides an extensive audio bus system allowing for complex audio mixing and effects. By default, every AudioStreamPlayer is routed to the “Master” bus, but you can route it to any bus you’ve created in the audio bus layout.

To route an AudioStreamPlayer to a different bus, simply set the bus property to the name of your custom bus:

audio_player.bus = "Effects"

If you also want to adjust the effects applied to that bus through code, you can access the bus directly via `AudioServer`:

var bus_idx = AudioServer.get_bus_index("Effects")
AudioServer.set_bus_effect_enabled(bus_idx, 0, true) # Enable the first effect on the 'Effects' bus

Playing Random Sounds from an Array

Randomizing sounds can make your game feel more dynamic and less repetitive. Let’s set up an array of sounds and play one at random:

var sounds = [

func play_random_sound():
    var random_sound = sounds[randi() % sounds.size()] = random_sound

Make sure to call `randomize()` once during the initialization of your game to ensure that the `randi()` function produces a different sequence each time the game runs.

With these tools and techniques, you’re well-equipped to create a rich and interactive audio experience in your Godot projects. Sound can often be an afterthought in game development, but with the functionality of AudioStreamPlayer in Godot, you can make it a centerpiece of your player’s experience. Happy coding!If you’re aiming for an even more responsive audio experience in your game, understanding how to queue sounds and manage audio levels based on game logic is crucial. Let’s examine some additional functionalities that will give you finer control over your audio implementation in Godot.

Queuing Sounds for Sequential Playback

Sometimes you’ll want to ensure that one sound plays right after another. To do this, you can queue the next audio stream to play once the current one finishes:

var sound_queue = []

func add_to_queue(sound):

func play_next_in_queue():
    if sound_queue.size() > 0: = sound_queue.pop_front()

# Connect to the 'finished' signal to automatically play the next queued sound
audio_player.connect("finished", self, "play_next_in_queue")

When a sound finishes playing, the connected `play_next_in_queue` function retrieves and plays the next sound from the queue.

Mixing Sounds with Volume Adjustments

You may want to adjust the volumes of individual sounds programmatically, especially in dynamic gameplay scenarios. For example, here’s how you could change the volume based on a game event:

func adjust_volume_for_event(is_event_active: bool):
    if is_event_active:
        audio_player.volume_db = -10 # Reduce volume during the event
        audio_player.volume_db = 0 # Restore volume after the event

This function takes a boolean indicating the occurrence of an event and adjusts the volume to complement the game’s current state.

Adjusting Audio Playback Speed

You might also want to control the speed of audio playback. Here’s an example of how to do that by adjusting the pitch_scale, which affects both pitch and playback speed:

func set_playback_speed(speed_factor: float):
    audio_player.pitch_scale = speed_factor

Increasing the pitch_scale will speed up playback, making the sound play at a higher pitch and faster pace. Conversely, decreasing the value will lower the pitch and slow down the sound.

Creating a Simple Sound Manager

In more complex games, it is common to create a dedicated sound manager that handles all audio-related functionality. This centralizes control and simplifies sound management across different scenes:

class SoundManager:
    var audio_players = {}

    func _init():
        audio_players["background_music"] =
        audio_players["effects"] =
        # Add players as children to a Node2D, for example.
    func play_sound(type: String, stream):
        var player = audio_players[type] = stream

    # More sound manager methods here...

# Instantiate and use the sound manager:
var sound_manager =
sound_manager.play_sound("background_music", preload("res://music.ogg"))
sound_manager.play_sound("effects", preload("res://click.ogg"))

A simple sound manager like this allows you to have different AudioStreamPlayer instances for various sound types, such as background music and sound effects, managing them through a centralized API.

By understanding and utilizing these advanced features, you can craft an aurally engaging environment that players will want to immerse themselves in time and time again. The possibilities are vast, and these tools provide the foundation you need to start optimizing and expanding the auditory dimension of your games built with Godot.

Take Your Godot Skills Further

Congratulations on advancing your understanding of the AudioStreamPlayer in Godot! Now, you might be wondering, “What’s next?”

Continuing your journey in game development is all about expanding your skill set and tackling new challenges. If you’re keen to dive deeper into the world of Godot and game development, our Godot Game Development Mini-Degree is the perfect next step. This comprehensive program will guide you through the process of creating various types of games, covering both 2D and 3D development within the Godot engine.

By embarking on this Mini-Degree, you’ll build up your knowledge incrementally, moving from learner to practitioner, and eventually, to a confident game developer. With the flexible learning schedule and practical projects, you’ll gain valuable experience that goes beyond theory, equipping you with a professional portfolio to show off to potential employers or for your personal projects.

For those who want to explore a broader range of Godot topics, check out our full collection of Godot courses. Here, you’ll find content that can refine your existing skills or help you discover new aspects of game development that you might not have considered.

Join us at Zenva, where learning is a journey with no limits, and every step you take is a leap towards mastering game development with Godot. Whether you’re just getting started or you’re looking to polish specific skills, we’re here to support your growth and celebrate your achievements. Let’s create, learn, and grow together!


Delving into Godot’s AudioStreamPlayer has unveiled the potential for us to craft captivating auditory experiences in our games. Remember, sound in games isn’t just about noise; it’s about establishing atmosphere, providing feedback, and enhancing the storytelling. Armed with your new knowledge, you’re now more equipped than ever to bring your game worlds to life with rich, dynamic audio that keeps players engaged and immersed.

Don’t let the learning stop here. Continue to refine your expertise with our Godot Game Development Mini-Degree and explore the vast universe of game creation with confidence. Every game you build, every line of code, and every node you master is a step towards realizing your vision as a game developer. So, play on, and let’s see what incredible gaming experiences you’ll create next!

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.