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

AudioStreamPlayer3D

繼承： Node3D < Node < Object

在 3D 空間中播放與位置相關的聲音。

說明

根據聆聽者的相對位置播放具備空間化效果的音訊。位置效果包含距離衰減、方向性與多普勒效應。為了更逼真，系統會對遠處聲音套用低通濾波器；若要停用，將 attenuation_filter_cutoff_hz 設為 20500。

預設情況下，聲音從攝影機位置輸出。你可以在場景中新增 AudioListener3D 節點，並呼叫 AudioListener3D.make_current() 來啟用以改變聆聽位置。

若要播放非空間化音效，請參閱 AudioStreamPlayer。

注意： 隱藏 AudioStreamPlayer3D 節點不會停止音訊輸出。若需暫時靜音，可將 volume_db 設為極低值，例如 -100（人耳已無法聽見）。

教學

• 音訊流

屬性

int	area_mask	0
float	attenuation_filter_cutoff_hz	5000.0
float	attenuation_filter_db	-24.0
AttenuationModel	attenuation_model	0
bool	autoplay	false
StringName	bus	&"Master"
DopplerTracking	doppler_tracking	0
float	emission_angle_degrees	45.0
bool	emission_angle_enabled	false
float	emission_angle_filter_attenuation_db	-12.0
float	max_db	3.0
float	max_distance	0.0
int	max_polyphony	1
float	panning_strength	1.0
float	pitch_scale	1.0
PlaybackType	playback_type	0
bool	playing	false
AudioStream	stream
bool	stream_paused	false
float	unit_size	10.0
float	volume_db	0.0
float	volume_linear

方法

float	get_playback_position()
AudioStreamPlayback	get_stream_playback()
bool	has_stream_playback()
void	play(from_position: float = 0.0)
void	seek(to_position: float)
void	stop()

---

訊號

finished() 🔗

當音訊停止播放時發出。

---

列舉

enum AttenuationModel: 🔗

AttenuationModel ATTENUATION_INVERSE_DISTANCE = 0

依線性距離衰減響度。

AttenuationModel ATTENUATION_INVERSE_SQUARE_DISTANCE = 1

依平方距離衰減響度。

AttenuationModel ATTENUATION_LOGARITHMIC = 2

依對數距離衰減響度。

AttenuationModel ATTENUATION_DISABLED = 3

響度不隨距離衰減，但仍保留空間定位（不同於 AudioStreamPlayer）。可將 ATTENUATION_DISABLED 與大於 0.0 的 max_distance 搭配，以線性方式在指定球體範圍內衰減。

---

enum DopplerTracking: 🔗

DopplerTracking DOPPLER_TRACKING_DISABLED = 0

停用多普勒追蹤。

DopplerTracking DOPPLER_TRACKING_IDLE_STEP = 1

於邏輯處理影格期間執行多普勒追蹤（見 Node.NOTIFICATION_INTERNAL_PROCESS）。

DopplerTracking DOPPLER_TRACKING_PHYSICS_STEP = 2

於物理影格期間執行多普勒追蹤（見 Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS）。

---

屬性說明

int area_mask = 0 🔗

• void set_area_mask(value: int)

• int get_area_mask()

決定哪些 Area3D 分層影響混響與音訊匯流排效果。你可以利用區域將 AudioStream 重新導向至特定匯流排。例如建立「水域」區域，讓水中的聲音透過匯流排處理，聽起來像在水下播放。

---

float attenuation_filter_cutoff_hz = 5000.0 🔗

• void set_attenuation_filter_cutoff_hz(value: float)

• float get_attenuation_filter_cutoff_hz()

衰減低通濾波器的截止頻率（Hz）。高於此頻率的聲音會比低於此頻率的聲音被更大幅度衰減。若要停用，請設為 20500（高於人耳可聽極限）。

---

float attenuation_filter_db = -24.0 🔗

• void set_attenuation_filter_db(value: float)

• float get_attenuation_filter_db()

濾波器對響度影響的幅度，單位為分貝。

---

AttenuationModel attenuation_model = 0 🔗

• void set_attenuation_model(value: AttenuationModel)

• AttenuationModel get_attenuation_model()

決定音訊是否隨距離而線性、平方、對數衰減，或完全不受距離影響（即停用衰減）。

---

bool autoplay = false 🔗

• void set_autoplay(value: bool)

• bool is_autoplay_enabled()

若為 true，當 AudioStreamPlayer3D 節點加入場景樹時即開始播放。

---

StringName bus = &"Master" 🔗

• void set_bus(value: StringName)

• StringName get_bus()

此音訊播放所在的匯流排。

注意： 設定時不會驗證名稱是否存在，因為匯流排配置可能稍後才載入。若執行期間找不到對應匯流排，將回退至 "Master"。

---

DopplerTracking doppler_tracking = 0 🔗

• void set_doppler_tracking(value: DopplerTracking)

• DopplerTracking get_doppler_tracking()

Decides in which step the Doppler effect should be calculated.

Note: If doppler_tracking is not DOPPLER_TRACKING_DISABLED but the current Camera3D/AudioListener3D has doppler tracking disabled, the Doppler effect will be heard but will not take the movement of the current listener into account. If accurate Doppler effect is desired, doppler tracking should be enabled on both the AudioStreamPlayer3D and the current Camera3D/AudioListener3D.

---

float emission_angle_degrees = 45.0 🔗

• void set_emission_angle(value: float)

• float get_emission_angle()

聲音在此角度內傳至聽者時不會衰減。

---

bool emission_angle_enabled = false 🔗

• void set_emission_angle_enabled(value: bool)

• bool is_emission_angle_enabled()

若為 true，將依聲音方向進行衰減。

---

float emission_angle_filter_attenuation_db = -12.0 🔗

• void set_emission_angle_filter_attenuation_db(value: float)

• float get_emission_angle_filter_attenuation_db()

當聽者位於 emission_angle_degrees 之外且 emission_angle_enabled 啟用時，採用的衰減係數（分貝）。

---

float max_db = 3.0 🔗

• void set_max_db(value: float)

• float get_max_db()

設定聲音輸出的絕對最大值，單位為分貝。

---

float max_distance = 0.0 🔗

• void set_max_distance(value: float)

• float get_max_distance()

超過此距離後將完全聽不到聲音。僅在設為大於 0.0 時生效。max_distance 與 unit_size 協同運作；不同於 unit_size 受 attenuation_model 影響，max_distance 一律採線性模式。這可避免聽者距離過遠時仍需混音，節省 CPU。

---

int max_polyphony = 1 🔗

• void set_max_polyphony(value: int)

• int get_max_polyphony()

此節點同時可播放的最大音效數。超過後播放新音效會截斷最舊的音效。

---

float panning_strength = 1.0 🔗

• void set_panning_strength(value: float)

• float get_panning_strength()

將此節點的聲道平移強度設為 ProjectSettings.audio/general/3d_panning_strength 乘以本係數。若乘積為 0.0，則停用立體聲平移，所有聲道音量相同；若為 1.0，當聲源位於聽者正左或正右時，將靜音其中一個聲道。

兩聲道立體聲配置遵循 WebAudio StereoPannerNode 演算法，以耳朵方位角一半的餘弦值計算音量。

至於 5.1、7.1 等其他喇叭配置，則實作 SPCAP（Speaker-Placement Correction Amplitude）演算法。

---

float pitch_scale = 1.0 🔗

• void set_pitch_scale(value: float)

• float get_pitch_scale()

音訊的音高與節奏倍率，相對於其取樣率。

---

PlaybackType playback_type = 0 🔗

• void set_playback_type(value: PlaybackType)

• PlaybackType get_playback_type()

實驗性： 此屬性可能在未來版本中變更或移除。

串流播放器的播放型態。若設定為非預設值，將強制使用該型態。

---

bool playing = false 🔗

• void set_playing(value: bool)

• bool is_playing()

若為 true，音訊正在播放或已排入播放佇列（見 play()）。

---

AudioStream stream 🔗

• void set_stream(value: AudioStream)

• AudioStream get_stream()

要播放的 AudioStream 資源。

---

bool stream_paused = false 🔗

• void set_stream_paused(value: bool)

• bool get_stream_paused()

若為 true 則播放暫停，將 stream_paused 設為 false 可恢復。

---

float unit_size = 10.0 🔗

• void set_unit_size(value: float)

• float get_unit_size()

衰減係數。值越高，聲音可被聽見的距離越遠。

---

float volume_db = 0.0 🔗

• void set_volume_db(value: float)

• float get_volume_db()

衰減前的基礎聲級，單位為分貝。

---

float volume_linear 🔗

• void set_volume_linear(value: float)

• float get_volume_linear()

衰減前的基礎聲級，以線性值表示。

注意：此成員會同步修改 volume_db。傳回值等同於對 volume_db 執行 @GlobalScope.db_to_linear() 的結果。設定此成員則等同於將 volume_db 設為對該值執行 @GlobalScope.linear_to_db() 的結果。

---

方法說明

float get_playback_position() 🔗

回傳在 AudioStream 中的位置。

---

AudioStreamPlayback get_stream_playback() 🔗

返回與此 AudioStreamPlayer3D 關聯的 AudioStreamPlayback 物件。

---

bool has_stream_playback() 🔗

回傳此 AudioStreamPlayer 是否能取得 AudioStreamPlayback 物件。

---

void play(from_position: float = 0.0) 🔗

將音訊排入佇列，於下個物理影格自 from_position（秒）開始播放。

---

void seek(to_position: float) 🔗

設定音訊開始播放的位置（秒）。

---

void stop() 🔗

停止音訊。