AudioStreamPolyphonic in Godot – Complete Guide

Welcome to this in-depth tutorial where we delve into the world of audio in game development using the Godot 4 engine. Imagine creating games without limitation: your characters can speak, your environments can echo with sounds of life, and your gameplay can pulse with an original score. This is all achievable through the power of manipulating audio streams, and that’s where Godot’s AudioStreamPolyphonic class comes in. Join us as we explore how to orchestrate an immersive audio experience in your games, making them resonate with audiences in ways that visuals alone cannot. Ready to amplify your Godot skills?

What is AudioStreamPolyphonic?

The AudioStreamPolyphonic class is a powerful tool within the Godot 4 engine designed to give you vast control over audio playback. It’s essentially a resource that enables you to play custom audio streams simultaneously from code – all through a single audio player node. Imagine a pianist having the ability to press multiple keys at once to create a chord; similarly, this class allows multiple sounds to play at the same time, adding depth and richness to your game’s audio.

What is it for?

The ingenious use of AudioStreamPolyphonic is that it provides the opportunity to layer sounds and create complex audio effects in-game. This is particularly useful in scenarios where concurrent sound effects are needed, such as footsteps while a character is talking, or background music that interacts with sound cues in the environment.

Why Should I Learn It?

For game developers, sound is not just an afterthought—it’s an essential part of the game design that can make or break a player’s experience. Learning how to manipulate the AudioStreamPolyphonic class can help you create dynamic soundscapes that keep players engaged and immersed in your game. With the knowledge of polyphonic audio streams, you can craft intricate audio designs that will set your games apart from the rest.

CTA Small Image

Setting Up Our Project with AudioStreamPolyphonic

To get started with AudioStreamPolyphonic in Godot 4, we first need to set up a project and import or record the audio files we wish to use. This can involve importing WAV or OGG files into our project folder. Here’s an example of how to load an audio stream in Godot:

# First, load your audio file.
var my_sound = load("res://path_to_your_sound.ogg")

# Now, create an AudioStreamPlayer node.
var audio_player =

# Add it as a child of the current node.

# Set the stream to be your previously loaded sound. = my_sound

# Finally, play the sound.

With this code snippet, you’ve created an AudioStreamPlayer and loaded your sound, ready to be played in your game.

Playing Multiple Sounds with AudioStreamPolyphonic

Now that we have our basic sound playing, let’s use AudioStreamPolyphonic to play multiple sounds at once. To do that, you’ll need to create an AudioStreamPlayerPolyphonic node.

# Create an AudioStreamPlayerPolyphonic node
var polyphonic_player =

# Add it as a child of the current node

Next, we need to connect audio streams to the polyphonic player:

# Load multiple sounds
var sound1 = load("res://sound1.ogg")
var sound2 = load("res://sound2.ogg")

# Create AudioStreamPolyphonicData resources
var poly_sound1 =
var poly_sound2 =

# Assign our sounds to the polyphonic data resources = sound1 = sound2

# Mix the sounds into one polyphonic stream
var mixed_sounds = [poly_sound1, poly_sound2]

# Connect the mixed sounds to the polyphonic player stream
polyphonic_player.stream_data = mixed_sounds

After setting up the polyphonic data and player, it’s time to play the sounds together:

# Play the mixed sounds

This code will result in both sounds playing simultaneously, creating a layered audio effect.

Controlling Individual Sounds

Once you have multiple sounds playing, you may want to control them individually—perhaps to adjust volume or to stop a particular sound without affecting others. Here’s how you can manage this with AudioStreamPolyphonic:

# Assuming you have already set up your `polyphonic_player` and `mixed_sounds`

# Let's say you want to adjust the volume of the first sound
polyphonic_player.set_polyphony_voice_volume_db(0, -10) # 0 refers to the first sound, -10 lowers the volume by 10dB.

# To stop the second sound
polyphonic_player.stop_polyphony_voice(1) # 1 refers to the second sound

By using these methods, you can have fine-tuned control over each sound in your polyphonic setup, allowing for dynamic audio landscapes. You’re really starting to see the benefits of AudioStreamPolyphonic now, as it lets you manipulate individual elements in a complex audio environment.

Looping and Fading Sounds

For game soundtracks or certain long effects, you may need to loop your audio. Additionally, fading sounds in and out can create smooth transitions. Let’s incorporate these functionalities:

# Looping a sound

# Set the loop_mode of the polyphonic stream data to true
poly_sound1.loop_mode = true

# Fading in a sound

# Fade in the first sound over 2 seconds.
polyphonic_player.set_polyphony_voice_fade_in_time(0, 2.0)

# Fading out a sound

# Fade out the second sound over 3 seconds
polyphonic_player.set_polyphony_voice_fade_out_time(1, 3.0)

These controls give life to your sounds, turning simple audio clips into a living component of the game world. With fading and looping, you’re equipped to create a sophisticated sonic tapestry for your players.

With these foundational techniques in your toolkit, you’re well on your way to elevating your games’ auditory dimension. In the next part, we’ll build upon these essentials to explore more advanced features of Godot’s AudioStreamPolyphonic. Stay tuned to master the symphony of sounds in game development!

Advanced Manipulation of Sounds

In addition to basic playback and volume control, Godot’s AudioStreamPolyphonic class allows developers to get creative with sound manipulation. Let’s explore some of these advanced techniques:

Adjusting the Pitch

Sometimes, you might want to alter the pitch of your sound to match the mood or the event in your game. Here’s how to adjust the pitch for a polyphonic sound:

# Adjusting the pitch of the first sound to be higher (positive value)
polyphonic_player.set_polyphony_voice_pitch_scale(0, 1.5)

# If you want to lower the pitch (negative value)
polyphonic_player.set_polyphony_voice_pitch_scale(1, 0.5)

Applying an Audio Effect

If you’re looking to add reverb, distortion, or any other effects to your sounds, you can easily apply an AudioEffect resource to your polyphonic sounds:

# First, create an audio effect like reverb.
var reverb =

# Configure the reverb parameters as required
reverb.room_size = 0.8

# Next, create an AudioEffectInstance.
var reverb_instance =
reverb_instance.base_effect = reverb

# Finally, assign the effect to your audio player.
polyphonic_player.set_polyphony_voice_audio_effect_instance(0, reverb_instance)

Synchronizing Sounds

To synchronize sounds (such as playing a sound exactly when another finishes), you can check the playing status of a sound and trigger another:

# Let's say sound1 is currently playing and you want to play sound2 the moment sound1 finishes

if not polyphonic_player.is_polyphony_voice_active(0): # Check if the first sound is active
    polyphonic_player.play_polyphony_voice(1) # Play the second sound

Managing Audio Buses

Godot’s audio engine uses buses to manage different audio channels. You can route your polyphonic sounds through various buses for even more control, such as separate buses for music, SFX, and dialogue:

# Let's define a separate bus for music and set our polyphonic player to use it
AudioServer.set_bus_name(1, "MusicBus")

# Assign the polyphonic player to the "MusicBus"

Playing Random Sounds from A Pool

For non-repetitive audio effects (like footsteps on different surfaces), it’s useful to play random sounds from an array of sounds:

# Assume we have an array holding different footstep sounds
var footstep_sounds = [sound3, sound4, sound5]

# Now, write a function to play a random footstep sound
func play_random_footstep():
    var random_index = randi() % footstep_sounds.size() = footstep_sounds[random_index]

With all these code snippets and techniques, you’re now equipped to produce sophisticated and interactive audio systems within your Godot games. The power of Godot 4’s AudioStreamPolyphonic means that you’re limited only by your creativity. So go ahead, experiment with these tools, and create auditory experiences that enhance your game’s atmosphere and storytelling. Remember, at Zenva, we’re always here to help elevate your coding and game creation skills to the next level. Explore, learn, and most importantly, have fun on your game development journey!Continuing our exploration into the advanced uses of Godot 4’s AudioStreamPolyphonic class, let’s look into more coding examples and creative ways to incorporate these into your game audio systems. Engage with these examples to fine-tune the audio behavior to match your gameplay dynamics.

Dynamic Volume Control Based on Distance

One common technique in games is to adjust the volume of sounds based on the player’s distance from the source:

# Assuming 'player' is the player's node and 'sound_source' is the position of the audio source

# Calculate the distance between the player and the sound source
var distance = player.global_position.distance_to(sound_source.global_position)

# Define a max distance at which the sound should be inaudible
var max_distance = 1000

# Calculate volume based on distance (linearly scales with distance)
var volume = clamp(1.0 - distance / max_distance, 0.0, 1.0)

# Set the volume of the first sound. Assuming 0dB is the original volume
polyphonic_player.set_polyphony_voice_volume_db(0, linear2db(volume))

Audio Cues with Area Detection

Trigger audio effects when the player enters specific areas, such as a cave or a haunted house:

# Assuming 'Area2D' is set up to detect the player's entrance

# Connect an Area2D signal to run a function when the player enters the area
area2D.connect("body_entered", self, "_on_Area2D_body_entered")

# When the player enters the area, apply a specific sound or echo effect
func _on_Area2D_body_entered(body):
    if == "Player":
        polyphonic_player.set_polyphony_voice_audio_effect_instance(0, echo_effect_instance)

Sequential Sound Playback

To play sounds in sequence, such as a combo or a series of dialogue lines:

# We'll use a coroutine to play sounds one after another

# Start the sequence with a function call

# Define the play_sequence function
func play_sequence():
    yield(polyphonic_player.play_polyphony_voice(0), "finished") # Wait for first sound to finish
    yield(polyphonic_player.play_polyphony_voice(1), "finished") # Then play second sound
    # Repeat as needed for additional sounds

Interactive Music Layers

In games, music can change dynamically to reflect gameplay states. Let’s add and remove layers from the music as the game progresses:

# Let's say we have different layers of music for different game scenarios
var music_layers = [layer1, layer2, layer3]

# Start with just the background layer
polyphonic_player.stream_data = [music_layers[0]]

# Function to add intensity layer when an enemy is spotted
func add_combat_layer():

# Function to calm music back down after the threat is eliminated
func remove_combat_layer():

Switching Sounds for Different Environments

Games often require the sound effects to change to match the environmental context, such as moving from the city to the forest:

# Define different environmental sound pools
var city_sounds = [city_sound1, city_sound2]
var forest_sounds = [forest_sound1, forest_sound2]

# Function to switch sounds based on the environment
func switch_environment_sounds(environment):
    if environment == "city":
        polyphonic_player.stream_data = city_sounds
    elif environment == "forest":
        polyphonic_player.stream_data = forest_sounds

# Call this function when the environment changes

With these examples, our musical journey through the realm of game audio in Godot broadens. Visualize your game audio not just as a static layer, but as a responsive, interactive element that reacts to the player’s actions and the world around them. Through the power of AudioStreamPolyphonic, make your game not only heard but also felt.

At Zenva, we’re passionate about empowering you to weave incredible audio narratives into the fabric of your games. Dive deep, practice these techniques, and soon you’ll be designing soundscapes that resonate with every move, every decision, and every heartbeat of your game’s experience. Now, go ahead and make some noise—programmatically sophisticated noise!

Where to Go Next with Godot Game Development

Congratulations on taking these steps to master audio manipulation with Godot 4! The journey doesn’t end here; there are always new skills to learn and techniques to perfect in the world of game development. To continue honing your abilities and expanding your game development toolkit, we invite you to explore the Godot Game Development Mini-Degree at Zenva Academy.

This comprehensive program is tailored to guide you through the many facets of game creation using Godot’s rich features. Whether it’s diving into 2D and 3D game development, scripting with GDScript, or crafting intricate game mechanics, our Mini-Degree offers a structured learning path from the ground up. Designed for both novices and seasoned developers, the courses allow you to progress at your own pace, building a robust portfolio of Godot projects and preparing you for a career in game development.

For a wider array of Godot tutorials covering different topics and levels, don’t forget to check out our complete collection of Godot courses. With over 250 supported courses at Zenva, you’ll have the opportunity to continually level up your skills and stay updated with the latest game development practices. Keep learning, stay motivated, and let Zenva assist you on your path to becoming a professional game developer.


As you’ve seen, mastering audio with Godot’s AudioStreamPolyphonic opens a new dimension in game development, allowing you to create richer, more immersive experiences. We hope these tutorials encourage you to experiment with the myriad of possibilities that Godot 4 offers. Remember, what you’ve learned here is just the beginning—there’s a whole universe of sound waiting for your unique touch. Keep pushing the boundaries of creativity and let your games speak volumes!

Whether you’re just starting out or looking to sharpen your game development prowess, we at Zenva are here to support your educational journey. Explore the Godot Game Development Mini-Degree and unlock your full potential as a game developer. With Zenva, your game development adventure is always just beginning. Embrace the challenge, and let’s create together!

Python Blog Image

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