Index · Object → AudioServer

AudioServer

Server interface for low-level audio access.

Class 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.

Properties

var bus_count: int = 1

Number of available audio buses.

var input_device: String = "Default"

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.

var output_device: String = "Default"

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".

var playback_speed_scale: float = 1.0

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.

Methods

func add_bus(at_position: int = -1) -> void

Adds a bus at at_position.

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

Adds an AudioEffect effect to the bus bus_idx at at_position.

func generate_bus_layout() -> AudioBusLayout

Generates an AudioBusLayout using the available buses and effects.

func get_bus_channels(bus_idx: int) -> int

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

func get_bus_effect(bus_idx: int, effect_idx: int) -> AudioEffect

Returns the AudioEffect at position effect_idx in bus bus_idx.

func get_bus_effect_count(bus_idx: int) -> int

Returns the number of effects on the bus at bus_idx.

func get_bus_effect_instance(bus_idx: int, effect_idx: int, channel: int = 0) -> AudioEffectInstance

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

func get_bus_index(bus_name: StringName) -> int

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

func get_bus_name(bus_idx: int) -> String

Returns the name of the bus with the index bus_idx.

func get_bus_peak_volume_left_db(bus_idx: int, channel: int) -> float

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

func get_bus_peak_volume_right_db(bus_idx: int, channel: int) -> float

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

func get_bus_send(bus_idx: int) -> StringName

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

func get_bus_volume_db(bus_idx: int) -> float

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

func get_bus_volume_linear(bus_idx: int) -> float

Returns the volume of the bus at index bus_idx as a linear value.

Note: The returned value is equivalent to the result of db_to_linear() on the result of get_bus_volume_db().

func get_driver_name() -> String

Returns the name of the current audio driver. The default usually depends on the operating system, but may be overridden via the --audio-driver command line argument. --headless also automatically sets the audio driver to Dummy. See also ProjectSettings.audio/driver/driver.

func get_input_buffer_length_frames() -> int

Returns the absolute size of the microphone input buffer. This is set to a multiple of the audio latency and can be used to estimate the minimum rate at which the frames need to be fetched.

func get_input_device_list() -> PackedStringArray

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.

func get_input_frames(frames: int) -> PackedVector2Array

Returns a PackedVector2Array containing exactly frames audio samples from the internal microphone buffer if available, otherwise returns an empty PackedVector2Array.

The buffer is filled at the rate of get_input_mix_rate() frames per second when set_input_device_active() has successfully been set to true.

The samples are signed floating-point PCM values between -1 and 1.

func get_input_frames_available() -> int

Returns the number of frames available to read using get_input_frames().

func get_input_mix_rate() -> float

Returns the sample rate at the input of the AudioServer.

func get_mix_rate() -> float

Returns the sample rate at the output of the AudioServer.

func get_output_device_list() -> PackedStringArray

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

func get_output_latency() -> float

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.

func get_speaker_mode() -> AudioServer.SpeakerMode

Returns the speaker configuration.

func get_time_since_last_mix() -> float

Returns the relative time since the last mix occurred, in seconds.

func get_time_to_next_mix() -> float

Returns the relative time until the next mix occurs, in seconds.

func is_bus_bypassing_effects(bus_idx: int) -> bool

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

func is_bus_effect_enabled(bus_idx: int, effect_idx: int) -> bool

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

func is_bus_mute(bus_idx: int) -> bool

If true, the bus at index bus_idx is muted.

func is_bus_solo(bus_idx: int) -> bool

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

func is_stream_registered_as_sample(stream: AudioStream) -> bool

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().

func lock() -> void

Locks the audio driver's main loop.

Note: Remember to unlock it afterwards.

func move_bus(index: int, to_index: int) -> void

Moves the bus from index index to index to_index.

func register_stream_as_sample(stream: AudioStream) -> void

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.

func remove_bus(index: int) -> void

Removes the bus at index index.

func remove_bus_effect(bus_idx: int, effect_idx: int) -> void

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

func set_bus_bypass_effects(bus_idx: int, enable: bool) -> void

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

func set_bus_effect_enabled(bus_idx: int, effect_idx: int, enabled: bool) -> void

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

func set_bus_layout(bus_layout: AudioBusLayout) -> void

Overwrites the currently used AudioBusLayout.

func set_bus_mute(bus_idx: int, enable: bool) -> void

If true, the bus at index bus_idx is muted.

func set_bus_name(bus_idx: int, name: String) -> void

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

func set_bus_send(bus_idx: int, send: StringName) -> void

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

func set_bus_solo(bus_idx: int, enable: bool) -> void

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

func set_bus_volume_db(bus_idx: int, volume_db: float) -> void

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

func set_bus_volume_linear(bus_idx: int, volume_linear: float) -> void

Sets the volume as a linear value of the bus at index bus_idx to volume_linear.

Note: Using this method is equivalent to calling set_bus_volume_db() with the result of linear_to_db() on a value.

func set_enable_tagging_used_audio_streams(enable: bool) -> void

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.

func set_input_device_active(active: bool) -> Error

If active is true, starts the microphone input stream specified by input_device or returns an error if it failed.

If active is false, stops the input stream if it is running.

func swap_bus_effects(bus_idx: int, effect_idx: int, by_effect_idx: int) -> void

Swaps the position of two effects in bus bus_idx.

func unlock() -> void

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

Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

signal bus_layout_changed()

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

signal 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.

Inherited from Object (2)

Enums & Constants

enum SpeakerMode
SPEAKER_MODE_STEREO = 0

Two or fewer speakers were detected.

SPEAKER_SURROUND_31 = 1

A 3.1 channel surround setup was detected.

SPEAKER_SURROUND_51 = 2

A 5.1 channel surround setup was detected.

SPEAKER_SURROUND_71 = 3

A 7.1 channel surround setup was detected.

enum PlaybackType
PLAYBACK_TYPE_DEFAULT = 0

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

PLAYBACK_TYPE_STREAM = 1

Force the playback to be considered as a stream.

PLAYBACK_TYPE_SAMPLE = 2

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.

PLAYBACK_TYPE_MAX = 3

Represents the size of the PlaybackType enum.