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.

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

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


信号

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

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

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

PlaybackType PLAYBACK_TYPE_STREAM = 1

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

Force the playback to be considered as a stream.

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

PlaybackType PLAYBACK_TYPE_MAX = 3

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

Represents the size of the PlaybackType enum.


属性说明

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_idxAudioEffect


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。


PackedStringArray get_input_device_list() 🔗

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

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


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) 🔗

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

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

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

注意:之后记得解锁。


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

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


void register_stream_as_sample(stream: AudioStream) 🔗

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

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) 🔗

移除索引 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 的总线处于独奏模式。