Audio Resource API

Contents

Audio Resource API#

FmodAudioStream#

Inherits: Resource

Resource representing an audio stream for FMOD playback.

Description#

FmodAudioStream is a resource for playing audio data through the FMOD audio engine. It supports loading audio from files, including res:// paths, and provides configurable creation modes for streamed or sample-based playback.

The stream can be played with FmodAudioStreamPlayer or used directly with FMOD’s channel system. The underlying FmodSound object is created lazily the first time get_sound() is requested.

Properties#

Type

Name

Default

Description

PackedByteArray

audio_data

PackedByteArray()

Raw audio data loaded from a file. This is usually set by the audio importer or by load_from_file(). The data is stored in memory and used to create the FMOD sound object when get_sound() is called.

int

mode_flags

1

Creation mode flags that determine how the audio is loaded and played. This is a bitmask of CreateMode values. When the flags change, the internal FmodSound is released and recreated with the new flags on the next get_sound() call.

Methods#

void set_audio_data(data: PackedByteArray)#

Sets audio. usually importer, file or when load; sets after will updates load state.

PackedByteArray get_audio_data() const#

Returns current audio.

void set_mode_flags(flags: int)#

Sets the mode flags used when creating the FmodSound. Changing this invalidates the cached sound, and the next get_sound() call recreates it with the new flags.

int get_mode_flags() const#

Returns current creation mode.

FmodSound get_sound()#

Returns this stream’s FmodSound object, creating it lazily if needed. The sound is created with the current mode_flags. If no audio data is loaded or the FMOD system is unavailable, an empty reference is returned.

bool preload()#

Immediately creates and caches the internal FmodSound to reduce first-play latency. Returns true if creation succeeds.

bool is_preloaded() const#

Returns true if the internal FmodSound has already been created and cached.

float get_length() const#

Returns the audio length in seconds. If no sound has been created or no data has been loaded, returns 0.0.

bool is_data_loaded() const#

Returns true if audio data is loaded into this stream; otherwise returns false.

FmodAudioStream load_from_file(path: String, flags: int = 1) static#

Loads an audio stream from a file path. The path can be a Godot resource path, such as "res://audio/music.mp3", or an absolute file path.

flags parameter specified creation mode (CreateMode). default as MODE_STREAM.

If file or, returns reference.

void clear()#

Audio data and releases internal FmodSound. releases memory and as state.

Enumerations#

CreateMode#

Member

Value

Description

MODE_DEFAULT

0

Default creation mode. sets.

MODE_STREAM

1

Streams audio from memory. Audio data is read progressively instead of being fully decoded at once. This can reduce memory usage for large files, but may increase CPU cost during playback.

MODE_SAMPLE

2

Loads the entire audio file into memory as a sample. This can provide faster playback and lower CPU usage, but consumes more memory. Best for short sound effects.

MODE_LOOP

4

Enables normal looping. When playback reaches the end, it returns to the beginning and plays again.

MODE_LOOP_BIDI

8

Enables bidirectional (ping-pong) looping. When playback reaches the end, it plays backward to the start position, then forward again, creating a seamless back-and-forth loop.

Example#

File load.#

var stream: FmodAudioStream = FmodAudioStream.load_from_file("res://music/background.ogg", FmodAudioStream.MODE_STREAM)

var player: FmodAudioStreamPlayer = $FmodAudioStreamPlayer
player.stream = stream
player.play()

File load.#

var sfx: FmodAudioStream = FmodAudioStream.load_from_file("res://sfx/explosion.wav", FmodAudioStream.MODE_SAMPLE)

var player: FmodAudioStreamPlayer = $FmodAudioStreamPlayer
player.stream = sfx
player.play()

Memory load.#

var stream: FmodAudioStream = FmodAudioStream.new()
stream.audio_data = loaded_bytes
stream.mode_flags = FmodAudioStream.MODE_SAMPLE

FmodSound#

Inherits: RefCounted

FMOD::Sound reference, represents load audio resource.

Description#

FmodSound is a RefCounted wrapper around FMOD::Sound. It represents a loaded audio resource and provides access to metadata, format information, raw audio data, tracker music controls (MOD/S3M/XM/IT/MIDI), and metadata tags.

load_from_file() load audio, or through FmodSystem creates audio. load after, can queries audio, audio data, or and FmodChannel used for.

Methods#

Validity Check#

bool sound_is_null() const#

Returns true if sound instance or.

bool sound_is_valid() const#

Returns true if the sound instance has been initialized successfully and is available. This means the sound is ready for audio operations.

Format Information#

Dictionary get_format() const#

Returns sound,:.

Key Name

Type

Description

type

FmodSoundType

Audio.

format

FmodSoundFormat

Sample Format

channels

int

Channel Count

bits

int

Bits Per Sample
String get_name() const#

Returns sound name. usually file or in audio file name.

float get_length(time_unit: FmodSystem.FmodTimeUnit = 1) const#

Returns the sound length in the specified time unit. When milliseconds (FMOD_TIME_UNIT_MS) are used, the result is returned in seconds. For other units such as bytes or PCM samples, the raw value is returned.

See also

FmodSystem.FmodTimeUnit lists the available time unit options.

Dictionary get_num_tags() const#

Returns label:.

Key Name

Type

Description

num_tags

int

Sound label.

num_tags_updated

int

Updates label ().

See also

get_tag() gets label.

Dictionary get_tag(index: int, name: String = “”) const#

Retrieves metadata tags from the sound. Tags can be retrieved by index or by name. If the name is not empty, a tag with that name is searched; otherwise, the tag at the specified index is returned.

Returns :.

Key Name

Type

Description

type

FmodTagType

Label.

datatype

FmodTagDataType

Label.

name

String

Label name.

data

Variant

Label (datatype).

data_len

int

Data length in bytes.

updated

bool

true if the tag has been updated, which is mainly used for streaming sources.

Data Reading#

Dictionary get_open_state() const#

Returns sound current state. for sound or state. returns,:.

Key Name

Type

Description

open_state:

FmodOpenState

Current state.

percent_buffered

int

Stream buffer fill percentage.

starving

bool

If in (), as true

disk_busy

bool

If current in, as true
PackedByteArray read_data(length: int) const#

FMOD internal sound audio data to PackedByteArray. for after PCM or.

Note

In before seek_data().

void seek_data(pcm: int)#

In sound to PCM position. position PCM as unit specified.

Note

Will read_data() position, will playback position.

FmodSoundLock lock(offset: int, length: int) const#

Sound. or PCM. returns FmodSoundLock object, object provides memory.

Note

FmodSoundLock releases ().

var lock = sound.lock(0, sound.get_length(FmodSystem.FMOD_TIME_UNIT_PCM))
# Access data through lock object

Music#

int get_music_num_channels() const#

Returns MOD/S3M/XM/IT/MIDI file channel. channel file /.

Note

Used for ().

void set_music_channel_volume(channel: int, volume_db: float) const#

Sets MOD/S3M/XM/IT/MIDI file channel volume, as unit. / controls.

Note

Used for. channel index range as 0 to get_music_num_channels() - 1.

float get_music_channel_volume(channel: int) const#

Returns MOD/S3M/XM/IT/MIDI file channel volume, unit as.

Note

This only applies to module music formats. Use get_music_num_channels() to get the number of available channels.

void set_music_speed(speed: float)#

Sets MOD/S3M/XM/IT/MIDI velocity. 1.0 as velocity, 0.5 as, 2.0 as velocity.

Note

Used for ().

float get_music_speed() const#

Returns MOD/S3M/XM/IT/MIDI velocity. 1.0 represents velocity, 1.0 represents, 1.0 represents.

Note

Used for.

Synchronizes /.#

int get_sync_point(index: int) const#

Returns the sync point handle at the specified index. Sync points are embedded markers in an audio file, such as loop points or cue points in a WAV file.

Note

get_sync_point_info() gets returns synchronizes handle.

Dictionary get_sync_point_info(point: int, time_unit: FmodSystem.FmodTimeUnit = 1) const#

Returns synchronizes. point parameter as get_sync_point() gets handle. returns,:.

Key Name

Type

Description

name

String

Synchronizes name.

offset

int

Synchronizes in specified when unit position.

time_unit

FmodSystem.FmodTimeUnit

Used for when unit.

pointer

int

Synchronizes handle.
int get_num_sub_sounds() const#

Returns sound file sound. for FSB (FMOD sound) or DLS (can sound) audio.

Note

MP3 or WAV audio file usually returns as 0.

Callback.#

void set_pcmread_callback(callback: Callable)#

Sets PCM callback. FMOD needs audio data and when, will callback.

Callback: func callback(data: PackedByteArray, data_len: int) -> int

  • data —— FMOD provides used for audio data.

  • data_len —— needs ().

  • Returns as 0 represents successfully, or.

Provides audio data, audio or.

Important

Callback in audio, returns audio. in callback.

Callable get_pcmread_callback() const#

Returns current sets PCM callback. if sets callback, returns Callable.

void set_pcmsetpos_callback(callback: Callable)#

Sets PCM callback. FMOD needs sound internal position when (loop or), will callback.

Callback: func callback(position: int, time_unit: int) -> int

  • position —— position.

  • time_unit —— position when unit (FmodSystem.FmodTimeUnit).

  • Returns as 0 represents successfully, or.

For needs when position.

Callable get_pcmsetpos_callback() const#

Returns current sets PCM callback. if sets callback, returns Callable.

void set_nonblock_callback(callback: Callable)#

Sets load callback. (FMOD_NONBLOCKING) sound load when, will callback.

Callback: func callback(sound: FmodSound, result: int) -> int

  • sound —— load sound object.

  • result —— load, 0 represents successfully, or.

  • Returns as 0.

In sound load after to, get_open_state()

sound.set_nonblock_callback(func(s: FmodSound, result: int) -> void:
    if result == 0:
        print("Sound loading complete!")
        channel = system.play_sound(s, master_group, false)
)

See also

get_open_state() used for load state.

Callable get_nonblock_callback() const#

Returns current sets load callback. if sets callback, returns Callable.

Other#

FmodSound load_from_file(path: String) static#

Used for file path load sound. path file path or Godot path (res://).

var sound = FmodSound.load_from_file("res://music.mp3")

Enumerations#

FmodSoundType#

Member

Value

Description

FMOD_SOUND_TYPE_UNKNOWN

0

Or audio.

FMOD_SOUND_TYPE_AIFF

1

Audio file (.aif,.aiff). compression.

FMOD_SOUND_TYPE_ASF

2

Microsoft (.asf,.wma,.wmv). provides, in Windows can.

FMOD_SOUND_TYPE_DLS

3

Can audio (.dls). MIDI (.mid) sound.

FMOD_SOUND_TYPE_FLAC

4

Audio (.flac).

FMOD_SOUND_TYPE_FSB

5

FMOD (.fsb). sound.: PCM16, FADPCM, Vorbis, AT9, XMA, Opus.

FMOD_SOUND_TYPE_IT

6

Impulse Tracker.

FMOD_SOUND_TYPE_MIDI

7

Musical Instrument Digital Interface

FMOD_SOUND_TYPE_MOD

8

Protracker / Fasttracker file.

FMOD_SOUND_TYPE_MPEG

9

(.mp2,.mp3)..wav (RIFF).

FMOD_SOUND_TYPE_OGGVORBIS

10

Ogg Vorbis（.ogg）

FMOD_SOUND_TYPE_PLAYLIST

11

(.asx,.pls,.m3u,.wax). audio, label.

FMOD_SOUND_TYPE_RAW

12

Compression PCM (.raw).

FMOD_SOUND_TYPE_S3M

13

ScreamTracker 3 (.s3m).

FMOD_SOUND_TYPE_USER

14

Sound.

FMOD_SOUND_TYPE_WAV

15

Microsoft audio file (.wav).: compression PCM, IMA ADPCM. provides in Windows can ACM.

FMOD_SOUND_TYPE_XM

16

FastTracker 2 (.xm).

FMOD_SOUND_TYPE_XMA

17

Microsoft XMA, FSB (.fsb). provides, in Xbox can.

FMOD_SOUND_TYPE_AUDIOQUEUE

18

Apple audio (.mp4,.m4a,.mp3).: AAC, ALAC, MP3. provides, in iOS/tvOS.

FMOD_SOUND_TYPE_AT9

19

ATRAC9FSB (.fsb). provides, in PlayStation can.

FMOD_SOUND_TYPE_VORBIS

20

Vorbis FSB (.fsb).

FMOD_SOUND_TYPE_MEDIA_FOUNDATION

21

Microsoft Media Foundation (.asf,.wma,.wmv,.mp4,.m4a). provides, in UWP can.

FMOD_SOUND_TYPE_MEDIACODEC

22

Google Media (.m4a,.mp4). provides, in provides.

FMOD_SOUND_TYPE_FADPCM

23

FMOD, FSB (.fsb).

FMOD_SOUND_TYPE_OPUS

24

Opus, FSB (.fsb). provides, Xbox Series X|S, PS5 and Switch.

FMOD_SOUND_TYPE_MAX

25

Maximum supported sound type.

FmodSoundFormat#

Member

Value

Description

FMOD_SOUND_FORMAT_NONE

0

Unknown

FMOD_SOUND_FORMAT_PCM8

1

8-bit integer PCM data.

FMOD_SOUND_FORMAT_PCM16

2

16-bit integer PCM data.

FMOD_SOUND_FORMAT_PCM24

3

24-bit integer PCM data.

FMOD_SOUND_FORMAT_PCM32

4

32-bit integer PCM data.

FMOD_SOUND_FORMAT_PCMFLOAT

5

32-bit floating-point PCM data.

FMOD_SOUND_FORMAT_BITSTREAM

6

Sound as compression.

FMOD_SOUND_FORMAT_MAX

7

Maximum supported sound format.

FmodTagType#

Member

Value

Description

FMOD_TAG_TYPE_UNKNOWN

0

FMOD label.

FMOD_TAG_TYPE_ID3V1

1

MP3 ID3 label 1.0. usually 1 label in MP3 file 128.

FMOD_TAG_TYPE_ID3V2

2

MP3 ID3 label 2.0. can label, can 1.

FMOD_TAG_TYPE_VORBISCOMMENT

3

Used for Vorbis, FLAC, Theora, Speex and Opus file.

FMOD_TAG_TYPE_SHOUTCAST

4

SHOUTcast internet stream metadata.

FMOD_TAG_TYPE_ICECAST

5

Can in Icecast.

FMOD_TAG_TYPE_ASF

6

Usually and Windows Media (WMA).

FMOD_TAG_TYPE_MIDI

7

In MIDI file.

FMOD_TAG_TYPE_PLAYLIST

8

Playlist files such as PLS, M3U, ASX, and WAX use this tag type to provide playlist information.

FMOD_TAG_TYPE_FMOD

9

FMOD MIDI, MOD, S3M, XM, IT used for () label.

FMOD_TAG_TYPE_USER

10

For, label can FMOD_CODEC_METADATA_FUNC

FMOD_TAG_TYPE_MAX

11

Maximum supported tag type count.

FmodTagDataType#

Member

Value

Description

FMOD_TAG_DATA_TYPE_BINARY

0

Raw binary data

FMOD_TAG_DATA_TYPE_INT

1

Integer

FMOD_TAG_DATA_TYPE_FLOAT

2

Floating-point number

FMOD_TAG_DATA_TYPE_STRING

3

8-bit ASCII character string.

FMOD_TAG_DATA_TYPE_STRING_UTF16

4

16-bit UTF string.

FMOD_TAG_DATA_TYPE_STRING_UTF16BE

5

16-bit UTF string, big-endian byte order.

FMOD_TAG_DATA_TYPE_STRING_UTF8

6

8UTF.

FMOD_TAG_DATA_TYPE_MAX

7

Maximum supported tag data type count.

FmodOpenState#

Member

Value

Description

FMOD_OPEN_STATE_READY

0

Ready

FMOD_OPEN_STATE_LOADING

1

In load.

FMOD_OPEN_STATE_ERROR

2

Usually to file, memory.

FMOD_OPEN_STATE_CONNECTING

3

Connection to (in sound when).

FMOD_OPEN_STATE_BUFFERING

4

Buffered data

FMOD_OPEN_STATE_SEEKING

5

In and.

FMOD_OPEN_STATE_PLAYING

6

Ready for playback, but cannot be released yet without stalling the main thread.

FMOD_OPEN_STATE_SETPOSITION

7

In position.

FMOD_OPEN_STATE_MAX

8

Maximum open state type count.

FmodSoundLock#

Inherits: RefCounted

provides sound, or.

Description#

FmodSoundLock used for sound. or sound.

Sound when, FMOD will provides or (if sound,).

Important

In after, unlock(), or RAII (object).

Note

Locking a sound can be expensive because it blocks the mixer thread. Use it sparingly and only for short periods.

Methods#

PackedByteArray get_data1() const#

PackedByteArray returns before, in.

PackedByteArray get_data2() const#

Returns as PackedByteArray, sound when.

bool is_locked() const#

Returns true if sound current and can.

void unlock()#

Sound, FMOD resume, in after.

Note

If, will.

Contents