Quick Start

This guide walks you through the smallest useful playback flow: create a player, load audio, play it, pause it, and adjust the volume. Complete Installation Guide before starting.

Three Concepts You Need to Know

Name	Role
FmodAudioStreamPlayer	A playback node in the scene, suitable for background music, ambience, and regular 2D sounds.
FmodAudioStream	An FMOD audio resource that stores audio data and its loading mode.
FmodServer	The global entry point for the FMOD system. Use it to access the main system, master channel group, and performance data.

Tip

If you only want to play a piece of music, you usually only need FmodAudioStreamPlayer and FmodAudioStream. Lower-level objects such as FmodSystem, FmodChannel, and FmodDSP can wait until you need mixing, DSP, or finer control.

Play Your First Audio in the Editor

Create a Scene

1. Create a new Godot scene.

2. Add a Node as the root node.

3. Add a FmodAudioStreamPlayer child node.

4. Save the scene, for example as main.tscn.

Import Audio

1. Place an audio file in the project, for example res://music/background.mp3.

2. In Godot’s Import panel, set the import type to FMOD Audio.

3. Choose an import preset based on how the audio will be used:

   • Stream (Low memory): suitable for background music and longer audio.

   • Sample (High quality): suitable for short sound effects and sounds that need low latency.

   • Loop Sample: suitable for short sound effects that need to loop.

4. Click Reimport.

Play Audio

1. Select the FmodAudioStreamPlayer node.

2. In the Inspector, assign the imported FmodAudioStream resource to the Stream property.

3. Enable Playing, or enable Auto Play so it starts when it enters the scene tree.

If you cannot hear anything, first make sure the FMOD runtime library is in the plugin directory, and check Godot’s Output panel for GDExtension or FMOD initialization errors.

Load and Play from Code

If you do not want to create a resource through the importer, you can also load an audio file directly from a path.

extends Node

@onready var player: FmodAudioStreamPlayer = $FmodAudioStreamPlayer

func _ready() -> void:
    var stream := FmodAudioStream.load_from_file(
        "res://music/background.mp3",
        FmodAudioStream.MODE_STREAM | FmodAudioStream.MODE_LOOP
    )

    if stream == null:
        push_error("Failed to load audio file")
        return

    player.stream = stream
    player.play()

MODE_STREAM is suitable for long audio. MODE_LOOP makes the audio loop. Short sound effects are usually better with MODE_SAMPLE, which can reduce latency when triggered frequently.

Control Playback

The following example uses the keyboard to control playback, pause, and volume. You can attach the script to the scene root node.

extends Node

@onready var player: FmodAudioStreamPlayer = $FmodAudioStreamPlayer

func _unhandled_input(event: InputEvent) -> void:
    if event.is_action_pressed("ui_accept"):
        player.playing = not player.playing

    if event.is_action_pressed("ui_cancel"):
        player.stream_paused = not player.stream_paused

    if event.is_action_pressed("ui_up"):
        player.volume_db += 3.0

    if event.is_action_pressed("ui_down"):
        player.volume_db -= 3.0

Common Properties

Property	Description
stream	The FmodAudioStream to play.
playing	Starts or stops playback.
stream_paused	Pauses or resumes playback without resetting the playback position.
volume_db	Playback volume, in dB.
pitch	Playback speed and pitch. 1.0 is the original pitch.
bus	Outputs to the specified audio bus. The default is Master.

Play a One-Shot Sound Effect

If you only need to play a short sound effect, you can also create and play a sound directly through FmodSystem.

func play_click_sound() -> void:
    var system: FmodSystem = FmodServer.get_main_system()
    var sound: FmodSound = system.create_sound_from_file(
        "res://sfx/click.wav",
        FmodSystem.FMOD_MODE_CREATESAMPLE
    )

    if sound == null:
        push_error("Failed to load sound")
        return

    var master: FmodChannelGroup = system.get_master_channel_group()
    system.play_sound(sound, master, false)

If you need to play the same sound effect frequently, preload and reuse FmodAudioStream or FmodSound instead of reading the file again on every input event.

Add a Simple DSP Effect

The following example adds reverb to the master channel group. All sounds that pass through the main output will have reverb.

func add_reverb_to_master() -> void:
    var system: FmodSystem = FmodServer.get_main_system()
    var reverb: FmodDSP = system.create_dsp_by_type(FmodDSP.DSP_TYPE_SFXREVERB)

    if reverb == null:
        push_error("Failed to create reverb DSP")
        return

    var master: FmodChannelGroup = system.get_master_channel_group()
    master.add_dsp(-1, reverb)

Note

-1 means adding the DSP to the end of the chain. In real projects, it is usually better to add effects to a specific bus or channel group so they do not affect every sound.

View Performance Data

Godot-FmodPlayer registers FMOD performance data in Godot’s performance monitors. After running the project, you can view FmodCPUUsage and FmodFileUsage metrics in Debugger > Monitors.

You can also read them from code:

func _process(_delta: float) -> void:
    var system: FmodSystem = FmodServer.get_main_system()
    var cpu_usage: Dictionary = system.get_cpu_usage()
    var channels: Dictionary = system.get_channels_playing()

    print("DSP CPU: %.2f%%" % cpu_usage["dsp"])
    print("Real channels: %d" % channels["real_channels"])

Next Steps

• Read Audio Resources to understand when to choose MODE_STREAM or MODE_SAMPLE.

• Read Playback Control to learn playback, pause, seeking, and channel control.

• Read Mixing System to learn about buses and the mixing system.

• Read DSP Effects to learn how to use DSP effects.

• If you run into problems, see FAQ.