Up to date

This page is up to date for Godot 4.3. If you still find outdated information, please open an issue.

AudioServerΒΆ

Inherits: Object

Server interface for low-level audio access.

DescriptionΒΆ

AudioServer is a low-level server interface for audio access. It is in charge of creating sample data (playable audio) as well as its playback via a voice interface.

TutorialsΒΆ

PropertiesΒΆ

int

bus_count

1

String

input_device

"Default"

String

output_device

"Default"

float

playback_speed_scale

1.0

MethodsΒΆ

void

add_bus(at_position: int = -1)

void

add_bus_effect(bus_idx: int, effect: AudioEffect, at_position: int = -1)

AudioBusLayout

generate_bus_layout() const

int

get_bus_channels(bus_idx: int) const

AudioEffect

get_bus_effect(bus_idx: int, effect_idx: int)

int

get_bus_effect_count(bus_idx: int)

AudioEffectInstance

get_bus_effect_instance(bus_idx: int, effect_idx: int, channel: int = 0)

int

get_bus_index(bus_name: StringName) const

String

get_bus_name(bus_idx: int) const

float

get_bus_peak_volume_left_db(bus_idx: int, channel: int) const

float

get_bus_peak_volume_right_db(bus_idx: int, channel: int) const

StringName

get_bus_send(bus_idx: int) const

float

get_bus_volume_db(bus_idx: int) const

PackedStringArray

get_input_device_list()

float

get_mix_rate() const

PackedStringArray

get_output_device_list()

float

get_output_latency() const

SpeakerMode

get_speaker_mode() const

float

get_time_since_last_mix() const

float

get_time_to_next_mix() const

bool

is_bus_bypassing_effects(bus_idx: int) const

bool

is_bus_effect_enabled(bus_idx: int, effect_idx: int) const

bool

is_bus_mute(bus_idx: int) const

bool

is_bus_solo(bus_idx: int) const

bool

is_stream_registered_as_sample(stream: AudioStream)

void

lock()

void

move_bus(index: int, to_index: int)

void

register_stream_as_sample(stream: AudioStream)

void

remove_bus(index: int)

void

remove_bus_effect(bus_idx: int, effect_idx: int)

void

set_bus_bypass_effects(bus_idx: int, enable: bool)

void

set_bus_effect_enabled(bus_idx: int, effect_idx: int, enabled: bool)

void

set_bus_layout(bus_layout: AudioBusLayout)

void

set_bus_mute(bus_idx: int, enable: bool)

void

set_bus_name(bus_idx: int, name: String)

void

set_bus_send(bus_idx: int, send: StringName)

void

set_bus_solo(bus_idx: int, enable: bool)

void

set_bus_volume_db(bus_idx: int, volume_db: float)

void

set_enable_tagging_used_audio_streams(enable: bool)

void

swap_bus_effects(bus_idx: int, effect_idx: int, by_effect_idx: int)

void

unlock()


SignalsΒΆ

bus_layout_changed() πŸ”—

Emitted when an audio bus is added, deleted, or moved.


bus_renamed(bus_index: int, old_name: StringName, new_name: StringName) πŸ”—

Emitted when the audio bus at bus_index is renamed from old_name to new_name.


EnumerationsΒΆ

enum SpeakerMode: πŸ”—

SpeakerMode SPEAKER_MODE_STEREO = 0

Two or fewer speakers were detected.

SpeakerMode SPEAKER_SURROUND_31 = 1

A 3.1 channel surround setup was detected.

SpeakerMode SPEAKER_SURROUND_51 = 2

A 5.1 channel surround setup was detected.

SpeakerMode SPEAKER_SURROUND_71 = 3

A 7.1 channel surround setup was detected.


enum PlaybackType: πŸ”—

PlaybackType PLAYBACK_TYPE_DEFAULT = 0

Experimental: This constant may be changed or removed in future versions.

The playback will be considered of the type declared at ProjectSettings.audio/general/default_playback_type.

PlaybackType PLAYBACK_TYPE_STREAM = 1

Experimental: This constant may be changed or removed in future versions.

Force the playback to be considered as a stream.

PlaybackType PLAYBACK_TYPE_SAMPLE = 2

Experimental: This constant may be changed or removed in future versions.

Force the playback to be considered as a sample. This can provide lower latency and more stable playback (with less risk of audio crackling), at the cost of having less flexibility.

Note: Only currently supported on the web platform.

Note: AudioEffects are not supported when playback is considered as a sample.

PlaybackType PLAYBACK_TYPE_MAX = 3

Experimental: This constant may be changed or removed in future versions.

Represents the size of the PlaybackType enum.


Property DescriptionsΒΆ

int bus_count = 1 πŸ”—

  • void set_bus_count(value: int)

  • int get_bus_count()

Number of available audio buses.


String input_device = "Default" πŸ”—

  • void set_input_device(value: String)

  • String get_input_device()

Name of the current device for audio input (see get_input_device_list). On systems with multiple audio inputs (such as analog, USB and HDMI audio), this can be used to select the audio input device. The value "Default" will record audio on the system-wide default audio input. If an invalid device name is set, the value will be reverted back to "Default".

Note: ProjectSettings.audio/driver/enable_input must be true for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings.


String output_device = "Default" πŸ”—

  • void set_output_device(value: String)

  • String get_output_device()

Name of the current device for audio output (see get_output_device_list). On systems with multiple audio outputs (such as analog, USB and HDMI audio), this can be used to select the audio output device. The value "Default" will play audio on the system-wide default audio output. If an invalid device name is set, the value will be reverted back to "Default".


float playback_speed_scale = 1.0 πŸ”—

  • void set_playback_speed_scale(value: float)

  • float get_playback_speed_scale()

Scales the rate at which audio is played (i.e. setting it to 0.5 will make the audio be played at half its speed). See also Engine.time_scale to affect the general simulation speed, which is independent from playback_speed_scale.


Method DescriptionsΒΆ

void add_bus(at_position: int = -1) πŸ”—

Adds a bus at at_position.


void add_bus_effect(bus_idx: int, effect: AudioEffect, at_position: int = -1) πŸ”—

Adds an AudioEffect effect to the bus bus_idx at at_position.


AudioBusLayout generate_bus_layout() const πŸ”—

Generates an AudioBusLayout using the available buses and effects.


int get_bus_channels(bus_idx: int) const πŸ”—

Returns the number of channels of the bus at index bus_idx.


AudioEffect get_bus_effect(bus_idx: int, effect_idx: int) πŸ”—

Returns the AudioEffect at position effect_idx in bus bus_idx.


int get_bus_effect_count(bus_idx: int) πŸ”—

Returns the number of effects on the bus at bus_idx.


AudioEffectInstance get_bus_effect_instance(bus_idx: int, effect_idx: int, channel: int = 0) πŸ”—

Returns the AudioEffectInstance assigned to the given bus and effect indices (and optionally channel).


int get_bus_index(bus_name: StringName) const πŸ”—

Returns the index of the bus with the name bus_name. Returns -1 if no bus with the specified name exist.


String get_bus_name(bus_idx: int) const πŸ”—

Returns the name of the bus with the index bus_idx.


float get_bus_peak_volume_left_db(bus_idx: int, channel: int) const πŸ”—

Returns the peak volume of the left speaker at bus index bus_idx and channel index channel.


float get_bus_peak_volume_right_db(bus_idx: int, channel: int) const πŸ”—

Returns the peak volume of the right speaker at bus index bus_idx and channel index channel.


StringName get_bus_send(bus_idx: int) const πŸ”—

Returns the name of the bus that the bus at index bus_idx sends to.


float get_bus_volume_db(bus_idx: int) const πŸ”—

Returns the volume of the bus at index bus_idx in dB.


PackedStringArray get_input_device_list() πŸ”—

Returns the names of all audio input devices detected on the system.

Note: ProjectSettings.audio/driver/enable_input must be true for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings.


float get_mix_rate() const πŸ”—

Returns the sample rate at the output of the AudioServer.


PackedStringArray get_output_device_list() πŸ”—

Returns the names of all audio output devices detected on the system.


float get_output_latency() const πŸ”—

Returns the audio driver's effective output latency. This is based on ProjectSettings.audio/driver/output_latency, but the exact returned value will differ depending on the operating system and audio driver.

Note: This can be expensive; it is not recommended to call get_output_latency every frame.


SpeakerMode get_speaker_mode() const πŸ”—

Returns the speaker configuration.


float get_time_since_last_mix() const πŸ”—

Returns the relative time since the last mix occurred.


float get_time_to_next_mix() const πŸ”—

Returns the relative time until the next mix occurs.


bool is_bus_bypassing_effects(bus_idx: int) const πŸ”—

If true, the bus at index bus_idx is bypassing effects.


bool is_bus_effect_enabled(bus_idx: int, effect_idx: int) const πŸ”—

If true, the effect at index effect_idx on the bus at index bus_idx is enabled.


bool is_bus_mute(bus_idx: int) const πŸ”—

If true, the bus at index bus_idx is muted.


bool is_bus_solo(bus_idx: int) const πŸ”—

If true, the bus at index bus_idx is in solo mode.


bool is_stream_registered_as_sample(stream: AudioStream) πŸ”—

Experimental: This method may be changed or removed in future versions.

If true, the stream is registered as a sample. The engine will not have to register it before playing the sample.

If false, the stream will have to be registered before playing it. To prevent lag spikes, register the stream as sample with register_stream_as_sample.


void lock() πŸ”—

Locks the audio driver's main loop.

Note: Remember to unlock it afterwards.


void move_bus(index: int, to_index: int) πŸ”—

Moves the bus from index index to index to_index.


void register_stream_as_sample(stream: AudioStream) πŸ”—

Experimental: This method may be changed or removed in future versions.

Forces the registration of a stream as a sample.

Note: Lag spikes may occur when calling this method, especially on single-threaded builds. It is suggested to call this method while loading assets, where the lag spike could be masked, instead of registering the sample right before it needs to be played.


void remove_bus(index: int) πŸ”—

Removes the bus at index index.


void remove_bus_effect(bus_idx: int, effect_idx: int) πŸ”—

Removes the effect at index effect_idx from the bus at index bus_idx.


void set_bus_bypass_effects(bus_idx: int, enable: bool) πŸ”—

If true, the bus at index bus_idx is bypassing effects.


void set_bus_effect_enabled(bus_idx: int, effect_idx: int, enabled: bool) πŸ”—

If true, the effect at index effect_idx on the bus at index bus_idx is enabled.


void set_bus_layout(bus_layout: AudioBusLayout) πŸ”—

Overwrites the currently used AudioBusLayout.


void set_bus_mute(bus_idx: int, enable: bool) πŸ”—

If true, the bus at index bus_idx is muted.


void set_bus_name(bus_idx: int, name: String) πŸ”—

Sets the name of the bus at index bus_idx to name.


void set_bus_send(bus_idx: int, send: StringName) πŸ”—

Connects the output of the bus at bus_idx to the bus named send.


void set_bus_solo(bus_idx: int, enable: bool) πŸ”—

If true, the bus at index bus_idx is in solo mode.


void set_bus_volume_db(bus_idx: int, volume_db: float) πŸ”—

Sets the volume of the bus at index bus_idx to volume_db.


void set_enable_tagging_used_audio_streams(enable: bool) πŸ”—

If set to true, all instances of AudioStreamPlayback will call AudioStreamPlayback._tag_used_streams every mix step.

Note: This is enabled by default in the editor, as it is used by editor plugins for the audio stream previews.


void swap_bus_effects(bus_idx: int, effect_idx: int, by_effect_idx: int) πŸ”—

Swaps the position of two effects in bus bus_idx.


void unlock() πŸ”—

Unlocks the audio driver's main loop. (After locking it, you should always unlock it.)