AudioStreamMP3 in Godot – Complete Guide

Welcome to the exciting world of audio programming in Godot 4, where we bring life and ambience to games just by understanding and using the AudioStreamMP3 class. Whether you’re developing a rhythm game, adding background music to your platformer, or simply looking to improve your game’s auditory experience, this tutorial is geared towards demystifying the process and breaking down how you can manipulate audio streams. With easy-to-follow examples and guidance, we’ll delve into the practical applications that can elevate your game and provide a richer experience for your players. So, let’s hit play on this learning track and dive into the harmonious realm of audio with Godot 4!

What is AudioStreamMP3?

AudioStreamMP3 is a class in Godot 4 tailored to handle the specifics of MP3 audio streams. It manages the playback of MP3 files which can be used for various audio elements in your games. Furthermore, it extends the basic AudioStream setup, which itself is part of the powerful audio management framework that Godot provides.

What is it for?

The primary goal of the AudioStreamMP3 class is to enable developers to work with MP3 files within their games quickly. From simple sound effects to intricate musical layers, this class provides the functionality you need to incorporate audio without the cumbersome process of extensive audio engineering.

Why Should I Learn It?

Understanding AudioStreamMP3 opens up a range of creative possibilities for your games. Sound is a critical component of game design that can greatly influence player experience. Learning to wield this tool effectively will not only improve the overall polish of your projects but will also provide you with the flexibility to implement dynamic audio features, custom behaviors, and seamless sound integration, enhancing both the immersion and interactivity of your games.

CTA Small Image

Loading an MP3 File

To begin working with an AudioStreamMP3 in Godot, we first need to load an MP3 file into our project. Make sure your MP3 file is added to your project folder, and then you can load it using the following code example:

var my_mp3 = preload("res://path/to/your/sound.mp3")

This will preload the MP3 file, making it ready for use as soon as the game starts.

Playing an MP3 Stream

Once an MP3 file is loaded, it’s time to play it. Create an AudioStreamPlayer node and set the stream property to your loaded MP3 file:

var audio_player = = my_mp3

This sequence will add a new AudioStreamPlayer to the scene, assign it the MP3 we loaded earlier, and start the playback.

Controlling Playback

Control over playback is vital for a good audio experience. Below are examples of how to pause, resume, and stop your MP3 stream:

// To pause playback

// To resume playback

// To stop playback

These commands allow you to integrate audio control based on game events or user input.

Adjusting Volume and Looping

To adjust the volume or make your audio loop, you can modify the volume_db and loop properties:

// To set the volume to half (note that volume_db is in decibels)
audio_player.volume_db = -6

// To loop the audio = true

Remember that the volume_db uses a logarithmic scale, where 0 dB is the original volume and negative values make the sound quieter.

Using Signals for Audio Events

Godot’s signal system can be used to trigger events when the audio starts or stops. Here’s how you can connect a finished signal to know when your MP3 has ended:

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

func _on_AudioStreamPlayer_finished():
    print("MP3 playback finished")

This function will print to the console when the audio has finished playing, allowing you to perform actions such as triggering the next song or sound effect.

Manipulating Audio in Real-time

Lastly, you may want to manipulate MP3 files while they are playing. Let’s adjust pitch in real-time:

// Increase pitch to make the sound play faster
audio_player.pitch_scale = 1.5

// Restore normal pitch
audio_player.pitch_scale = 1.0

Adjusting the pitch allows you to quickly create variated sounds from a single audio asset, useful for dynamic soundscapes or responsive audio feedback.

And with that, we’ve covered the basics of loading, playing, and controlling MP3 audio streams in Godot 4. Stay tuned for the next part of the tutorial where we’ll dive into advanced features like spatial audio with AudioStreamPlayer3D. Remember, audio design can greatly enhance the immersive experience of your games, so take the time to experiment and refine your audio elements with these foundational tools provided by Godot!

Delving deeper into the audio capabilities of Godot 4, let’s explore how to utilize advanced audio features to create a more dynamic and engaging game environment. Remember, tweaking these audio details can transform a good game into a great one!

Creating Spatial Sound with AudioStreamPlayer3D

If you’re working on a 3D game, you want the audio to reflect the three-dimensional space. Godot 4 provides the AudioStreamPlayer3D node for this purpose. Here’s how you can set up a 3D sound that will change based on the player’s position:

var audio_player_3d = = my_mp3

This snippet adds a 3D audio player to the scene, assigns the MP3, and begins playback. As the player moves through the game, the sound will feel like it is coming from the position of the AudioStreamPlayer3D node.

Now, let’s modify some properties to optimize the 3D audio effect:

// Set the unit size to match your game world scale
audio_player_3d.unit_size = 1

// Adjust the max distance for the audio to be heard
audio_player_3d.max_distance = 20

// Set the attenuation model
audio_player_3d.attenuation_model = AudioStreamPlayer3D.ATTENUATION_INVERSE_SQUARE_DISTANCE

These adjustments help you to fine-tune how the audio behaves within the game world, adapting the sound to the environmental scale and the player’s position.

Doppler Effect in 3D Sound

For increased realism, you might want to apply the Doppler effect, so the sound changes pitch relative to the player’s movement. Here’s how you can set it up:

audio_player_3d.doppler_tracking = AudioStreamPlayer3D.DOPPLER_TRACKING_PHYSICS_STEP

This line tells Godot to track the Doppler effect at each physics step, making the pitch shift naturally as the source and listener move relative to each other.

Integrating Random Pitch Variation

To add variety to your sounds and avoid repetitive audio, you can introduce random pitch variations each time the sound is played:

func play_random_pitch(audio_player, min_pitch, max_pitch):
    var pitch = rand_range(min_pitch, max_pitch)
    audio_player.pitch_scale = pitch

With this function, you create natural variations for repetitive sounds, such as footsteps or ambient loops, improving the audio landscape of your game.

Using Audio Buses for Advanced Mixing

Godot allows you to create and manipulate audio buses for complex audio mixing scenarios. Here’s how you can route your audio player to a specific bus and modify its effects in real-time:

// Route the audio player to a bus named "Effects"
audio_player.bus = "Effects"

// Then, you can adjust the volume of that bus like so:
AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Effects"), -10)

You can also add effects to the bus:

// Add a reverb effect to the "Effects" bus
var reverb =
AudioServer.add_bus_effect(AudioServer.get_bus_index("Effects"), reverb)

By routing different sounds to distinct buses and playing with their individual effects, you create a rich and nuanced audio mix that can respond to game dynamics.

Exploring these advanced audio features can make a world of difference in game development. As you’ve seen in these examples, Godot 4 provides an extensive suite of tools to fine-tune every aspect of your game’s audio. We at Zenva encourage you to experiment with these techniques, as a solid understanding of audio functionality will not only bolster your technical skillset but also enhance the player’s immersion and emotional connection to your game. So take these snippets, play around, and let your game’s soundscape blossom!

When crafting a game, one can leverage the ambiance and mood through the strategic use of audio. Let’s forge ahead and learn more advanced techniques that can set your game’s audio apart. We’ll explore conditional sound playback, synchronous sound layering, real-time audio adjustments, and the integration of audio effects into your Godot project.

Conditional Sound Playback

Sometimes, you want a sound to play only under certain conditions, like when an item is picked up or an enemy is defeated. This requires a simple conditional structure:

if player.has_item("RareGem"):

Add your logic as needed and ensure your game reacts with suitable sound cues.

Synchronous Sound Layering

Creating depth in your soundtrack can involve layering sounds that play in tandem. Say you have ambient music that needs to coexist with a sound of wind:

var ambient_music = preload("res://music/ambient.ogg")
var wind_sound = preload("res://sounds/wind.mp3")

var ambient_player =
var wind_player =

func _ready(): = ambient_music = wind_sound


This code sets up two audio players and initiates them together, creating an immersive environment.

Continuing with immersion, let’s explore adjusting sound parameters based on in-game events, such as changing game states:

func adjust_music_for_battle(is_in_battle):
    var new_volume_db = is_in_battle ? -10 : 0  // Quieter during battle
    ambient_player.volume_db = new_volume_db

This function changes the volume of the ambient music based on whether the player is in battle or not, paving the way for a dynamic audio experience.

Now, let’s implement real-time reverb while entering a cave:

func enter_cave():
    var cave_reverb =
    cave_reverb.room_size = 0.8  // A larger room size for echo feeling
    AudioServer.add_bus_effect(AudioServer.get_bus_index("Ambient"), cave_reverb)

func exit_cave():
    AudioServer.remove_bus_effect(AudioServer.get_bus_index("Ambient"), 0)

With these methods, you trigger specific reverb settings when entering or leaving a cave, enhancing the environmental sound texture.

Another powerful technique in audio programming is to mute all sounds quickly. This can be vital, especially in pause menus or when audio settings are toggled:

// A function to mute all audio
func set_mute_state(is_muted):
    AudioServer.set_bus_mute(AudioServer.get_bus_index("Master"), is_muted)

Executing this function can instantly mute all ongoing sounds or restore them, relying on a master audio bus setup.

Lastly, custom fading in and out of music offers a polished transition, be it entering a different game level or concluding a cinematic:

// A coroutine for fading out the music over time
func fade_out_music():
    var start_volume = ambient_player.volume_db
    var fade_time = 2.0
    var elapsed_time = 0.0
    while elapsed_time < fade_time:
        yield(get_tree().create_timer(0.1), "timeout")
        elapsed_time += 0.1
        var volume = lerp(start_volume, -80, elapsed_time / fade_time)
        ambient_player.volume_db = volume

    ambient_player.volume_db = start_volume

We have just scratched the surface of what you can achieve with Godot 4’s audio management tools. Armed with these examples, you’re well on your way to crafting a complete and compelling soundscape for your game. At Zenva, we understand the key role of audio in gameplay experience, and we’re here to help you navigate these technical complexities. So blend these snippets with your creativity and let the audio in your game make a powerful statement.

Continue Your Godot Development Journey

Congratulations on taking your first steps into audio programming with Godot 4! There’s always more to learn, and the journey has just begun. If you’re eager to keep building on the skills you’ve acquired, our Godot Game Development Mini-Degree is a fantastic next step. From the comfort of starting with the basics to gradually tackling more advanced game development topics, you’ll have the opportunity to create cross-platform games and truly refine your craft alongside our rich curriculum and project-based learning.

Our Mini-Degree is crafted for both novices and seasoned developers alike, ensuring a comfortable and challenging progression through 2D and 3D game development, all within the versatile orbit of the Godot 4 engine. By engaging with our courses, you can build a deep understanding of GDScript, intricate gameplay mechanics, and much more, while working on projects that mirror real-world applications.

For those who wish to explore an even broader scope of content and solidify their expertise in various domains of Godot, we also provide an extensive collection of Godot courses. These courses are designed to finesse your abilities and guide you from beginner to professional with over 250 supported classes available, ensuring no skill is left unmastered. Start your game development journey with Zenva, learn coding, create games and change your career with the power of learning that adapts to your pace and your goals.


As you’ve seen, mastering the art of audio in Godot 4 can transform your game from a simple interactive experience to a rich, immersive world that players will remember. Your journey doesn’t end here; it’s just getting started. Whether your aim is to design the next indie hit or to advance your skills for professional game development, the control over audio you’ve grasped today is a pivotal step towards realizing your vision.

We at Zenva are excited to see what you’ll create with these new skills and how far you’ll go in your development endeavors. Continue your education with our comprehensive Godot Game Development Mini-Degree, where every lesson is another cornerstone in the foundation of your game development mastery. Don’t just play games—make them, shape them, and bring your ideas to life with Zenva.

Python Blog Image

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