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 為低階音訊存取伺服器介面，負責建立樣本資料（可播放音訊）並透過語音介面進行播放。
教學
屬性
|
||
|
||
|
||
|
方法
訊號
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
實驗性： 此常數可能在未來版本中變更或移除。
強制將播放視為樣本，可降低延遲並提升穩定性（減少爆音風險），但靈活度較低。
注意：目前僅網頁平台支援此功能。
注意：當播放被視為樣本時，不支援 AudioEffect。
PlaybackType PLAYBACK_TYPE_MAX = 3
實驗性： 此常數可能在未來版本中變更或移除。
代表 PlaybackType 列舉的大小。
屬性說明
可用音訊匯流排數量。
String input_device = "Default" 🔗
目前音訊輸入裝置名稱（參見 get_input_device_list()）。當系統具有多個輸入（例如類比、USB、HDMI）時，可藉此選擇輸入裝置；"Default" 會使用系統預設輸入。若設定無效名稱，將還原為 "Default"。
注意：必須將 ProjectSettings.audio/driver/enable_input 設為 true 才能啟用音訊輸入。隱私與權限相關限制請參閱該設定說明。
String output_device = "Default" 🔗
目前音訊輸出裝置名稱（參見 get_output_device_list()）。當系統具有多個輸出（例如類比、USB、HDMI）時，可藉此選擇輸出裝置；"Default" 會使用系統預設輸出。若設定無效名稱，將還原為 "Default"。
float playback_speed_scale = 1.0 🔗
調整音訊播放速度比例（如設為 0.5 則音訊以半速播放）。如需改變整體模擬速度，請參閱 Engine.time_scale；兩者彼此獨立。
方法說明
void add_bus(at_position: int = -1) 🔗
在 at_position 處新增匯流排。
void add_bus_effect(bus_idx: int, effect: AudioEffect, at_position: int = -1) 🔗
於索引 bus_idx 的匯流排上、位置 at_position 新增 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。
int get_input_buffer_length_frames() 🔗
實驗性： 此方法可能在未來版本中變更或移除。
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.
PackedStringArray get_input_device_list() 🔗
返回系統偵測到的所有音訊輸入裝置名稱。
注意：必須將 ProjectSettings.audio/driver/enable_input 設為 true 才能啟用音訊輸入。更多權限與作業系統隱私限制請參閱該設定說明。
PackedVector2Array get_input_frames(frames: int) 🔗
實驗性： 此方法可能在未來版本中變更或移除。
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.
int get_input_frames_available() 🔗
實驗性： 此方法可能在未來版本中變更或移除。
Returns the number of frames available to read using get_input_frames().
float get_input_mix_rate() const 🔗
返回 AudioServer 輸入的取樣率。
返回 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 🔗
Returns the relative time since the last mix occurred, in seconds.
float get_time_to_next_mix() const 🔗
Returns the relative time until the next mix occurs, in seconds.
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) 🔗
實驗性： 此方法可能在未來版本中變更或移除。
強制將串流註冊為樣本。
注意：在單執行緒版本中呼叫此方法可能造成延遲尖峰。建議於載入資源階段執行，以避免在播放前才註冊造成卡頓。
移除索引 index 的匯流排。
void remove_bus_effect(bus_idx: int, effect_idx: int) 🔗
自索引 bus_idx 的匯流排移除索引 effect_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 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()。
注意：編輯器預設啟用此選項，以供外掛進行音訊預覽。
Error set_input_device_active(active: bool) 🔗
實驗性： 此方法可能在未來版本中變更或移除。
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.
void swap_bus_effects(bus_idx: int, effect_idx: int, by_effect_idx: int) 🔗
交換索引 bus_idx 匯流排中兩個效果的位置。
void unlock() 🔗
解鎖音訊驅動主迴圈。（鎖定後務必解鎖。）