Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

AudioServer

继承： Object

低级音频访问的服务器接口。

描述

AudioServer 是用于音频访问的底层服务器接口。它负责创建样本数据（可播放的音频）以及通过语音接口进行播放。

教程

属性

int	bus_count	`1`
String	input_device	`"Default"`
String	output_device	`"Default"`
float	playback_speed_scale	`1.0`

方法

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
float	get_bus_volume_linear(bus_idx: int) const
String	get_driver_name() const
PackedStringArray	get_input_device_list()
float	get_input_mix_rate() const
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_bus_volume_linear(bus_idx: int, volume_linear: 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()

信号

bus_layout_changed() 🔗

添加、修改、删除音频总线时发出。

bus_renamed(bus_index: int, old_name: StringName, new_name: StringName) 🔗

当索引为 bus_index 的音频总线的名称从 old_name 更改为 new_name 时发出。

枚举

enum SpeakerMode: 🔗

SpeakerMode SPEAKER_MODE_STEREO = 0

检测到两个或更少的扬声器。

SpeakerMode SPEAKER_SURROUND_31 = 1

检测到 3.1 声道环绕声设置。

SpeakerMode SPEAKER_SURROUND_51 = 2

检测到 5.1 声道环绕声设置。

SpeakerMode SPEAKER_SURROUND_71 = 3

检测到 7.1 声道环绕声设置。

enum PlaybackType: 🔗

PlaybackType PLAYBACK_TYPE_DEFAULT = 0

实验性： 未来版本中可能会修改或移除该常量。

播放将被视为在 ProjectSettings.audio/general/default_playback_type 处声明的类型。

PlaybackType PLAYBACK_TYPE_STREAM = 1

实验性： 未来版本中可能会修改或移除该常量。

强制将播放视为流。

PlaybackType PLAYBACK_TYPE_SAMPLE = 2

实验性： 未来版本中可能会修改或移除该常量。

强制将播放视为样本。这可以提供更低的延迟和更稳定的播放（音频噼啪声的风险更小），但代价是灵活性较低。

注意：目前仅支持 Web 平台。

注意：将播放视为样本时不支持 AudioEffect。

PlaybackType PLAYBACK_TYPE_MAX = 3

实验性： 未来版本中可能会修改或移除该常量。

代表 PlaybackType 枚举的大小。

属性说明

int bus_count = 1 🔗

void set_bus_count(value: int)
int get_bus_count()

可用音频总线的数量。

String input_device = "Default" 🔗

void set_input_device(value: String)
String get_input_device()

当前音频输入设备的名称（见 get_input_device_list()）。在具有多个音频输入（例如模拟、USB、HDMI 音频）的系统中，可用于选择音频输入设备。为 "Default" 时会从系统默认的音频输入录制音频。如果设置了无效的设备名称，该值会被恢复为 "Default"。

注意：ProjectSettings.audio/driver/enable_input 必须为 true 音频输入才能正常工作。另见该设置项的描述，了解权限和操作系统隐私设置相关的说明。

String output_device = "Default" 🔗

void set_output_device(value: String)
String get_output_device()

当前音频输出设备的名称（见 get_output_device_list()）。在具有多个音频输出（例如模拟、USB、HDMI 音频）的系统中，可用于选择音频输出设备。为 "Default" 时会从系统默认的音频输出播放音频。如果设置了无效的设备名称，该值会被恢复为 "Default"。

float playback_speed_scale = 1.0 🔗

void set_playback_speed_scale(value: float)
float get_playback_speed_scale()

音频播放的缩放速率（即将其设置为 0.5 将使音频以其一半的速度播放）。另见 Engine.time_scale 影响一般模拟速度，它独立于 playback_speed_scale。

方法说明

void add_bus(at_position: int = -1) 🔗

在 at_position 处添加一条总线。

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

为在 at_position 处索引为 bus_idx 的总线添加 AudioEffect 效果。

AudioBusLayout generate_bus_layout() const 🔗

使用可用的总线和效果来生成 AudioBusLayout。

int get_bus_channels(bus_idx: int) const 🔗

返回索引为 bus_idx 的总线的通道数。

AudioEffect get_bus_effect(bus_idx: int, effect_idx: int) 🔗

返回索引为 bus_idx 的总线中位于 effect_idx 的 AudioEffect。

int get_bus_effect_count(bus_idx: int) 🔗

返回索引为 bus_idx 的总线上的效果数。

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

返回分配给给定总线和效果索引（以及可选的通道）的AudioEffectInstance。

int get_bus_index(bus_name: StringName) const 🔗

返回名称为 bus_name 的总线的索引。如果不存在指定名称的总线，则返回 -1。

String get_bus_name(bus_idx: int) const 🔗

返回索引为 bus_idx 的总线的名称。

float get_bus_peak_volume_left_db(bus_idx: int, channel: int) const 🔗

返回总线索引为 bus_idx 且通道索引为 channel 处的左扬声器的峰值音量。

float get_bus_peak_volume_right_db(bus_idx: int, channel: int) const 🔗

返回总线索引为 bus_idx 且通道索引为 channel 处的右扬声器的峰值音量。

StringName get_bus_send(bus_idx: int) const 🔗

返回索引为 bus_idx 的总线的发送目标总线的名称。

float get_bus_volume_db(bus_idx: int) const 🔗

返回索引为 bus_idx 的总线的音量，单位为 dB。

float get_bus_volume_linear(bus_idx: int) const 🔗

返回索引为 bus_idx 处的总线音量对应的线性值。

注意：返回的值等价于使用 get_bus_volume_db() 的结果调用 @GlobalScope.db_to_linear() 的结果。

String get_driver_name() const 🔗

返回当前音频驱动的名称。默认值通常与操作系统相关，但可以被 --audio-driver 命令行参数覆盖。--headless 也会自动将音频驱动设置为 Dummy。另见 ProjectSettings.audio/driver/driver。

PackedStringArray get_input_device_list() 🔗

返回系统中检测到的所有音频输入设备的名称。

注意：ProjectSettings.audio/driver/enable_input 必须为 true 音频输入才能正常工作。另见该设置的说明，了解与权限和操作系统隐私设置相关的注意事项。

float get_input_mix_rate() const 🔗

返回 AudioServer 输入的采样率。

float get_mix_rate() const 🔗

返回 AudioServer 输出的采样率。

PackedStringArray get_output_device_list() 🔗

返回系统中检测到的所有音频输出设备的名称。

float get_output_latency() const 🔗

返回音频驱动的实际输出延迟。基于 ProjectSettings.audio/driver/output_latency，但实际的返回值取决于操作系统和音频驱动。

注意：可能开销较大；不建议每帧都调用 get_output_latency()。

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 🔗

如果为 true，则索引为 bus_idx 的总线会绕过效果。

bool is_bus_effect_enabled(bus_idx: int, effect_idx: int) const 🔗

如果为 true，则索引为 bus_idx 的总线上启用了索引为 effect_idx 的效果。

bool is_bus_mute(bus_idx: int) const 🔗

如果为 true，则索引为 bus_idx 的总线已静音。

bool is_bus_solo(bus_idx: int) const 🔗

如果为 true，则索引为 bus_idx 的总线处于独奏模式。

bool is_stream_registered_as_sample(stream: AudioStream) 🔗

实验性： 未来版本中可能会修改或移除该方法。

如果为 true，则该流已被注册为样本。引擎无需在播放样本之前对其进行注册。

如果为 false，则必须在播放之前注册该流。为防止延迟峰值，请使用 register_stream_as_sample() 将流注册为样本。

void lock() 🔗

锁定音频驱动程序的主循环。

注意：之后记得解锁。

void move_bus(index: int, to_index: int) 🔗

将总线从索引 index 移动到索引 to_index。

void register_stream_as_sample(stream: AudioStream) 🔗

实验性： 未来版本中可能会修改或移除该方法。

强制将流注册为样本。

注意：调用该方法时可能会出现延迟峰值，尤其是在单线程构建中。建议在加载资产时调用该方法，这样可以掩盖延迟峰值，而不是在需要播放样本之前才注册样本。

void remove_bus(index: int) 🔗

移除索引 index 处的总线。

void remove_bus_effect(bus_idx: int, effect_idx: int) 🔗

将索引 effect_idx 的效果从索引 bus_idx 的总线上移除。

void set_bus_bypass_effects(bus_idx: int, enable: bool) 🔗

如果为 true，则索引为 bus_idx 的总线会绕过效果。

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

如果为 true，则索引为 bus_idx 的总线上启用了索引为 effect_idx 的效果。

void set_bus_layout(bus_layout: AudioBusLayout) 🔗

覆盖当前使用的 AudioBusLayout。

void set_bus_mute(bus_idx: int, enable: bool) 🔗

如果为 true，则索引为 bus_idx 的总线已静音。

void set_bus_name(bus_idx: int, name: String) 🔗

将索引为 bus_idx 的总线的名称设为 name。

void set_bus_send(bus_idx: int, send: StringName) 🔗

将索引为 bus_idx 处的总线输出连接到名为 send 的总线。

void set_bus_solo(bus_idx: int, enable: bool) 🔗

如果为 true，则索引为 bus_idx 的总线处于独奏模式。

void set_bus_volume_db(bus_idx: int, volume_db: float) 🔗

将索引为 bus_idx 的总线的音量设为 volume_db，单位为分贝。

void set_bus_volume_linear(bus_idx: int, volume_linear: float) 🔗

将索引bus_idx处的总线容量线性值设置为volume_linear。

注意：使用该方法，与对某个值执行@GlobalScope.linear_to_db()并基于所得结果调用set_bus_volume_db()，是等价的。

void set_enable_tagging_used_audio_streams(enable: bool) 🔗

如果设置为 true，AudioStreamPlayback 的所有实例将在每个混音步骤调用 AudioStreamPlayback._tag_used_streams()。

注意：这在编辑器中默认启用，因为编辑器插件将其用于音频流预览。

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

在索引为 bus_idx 的总线中交换两个效果的位置。

void unlock() 🔗

解锁音频驱动程序的主循环。（锁定后，你始终需要手动解锁它。）