AudioStreamPlayer2D

繼承： Node2D < CanvasItem < Node < Object

在 2D 空間播放具位置感的音訊。

說明

播放隨與接收者距離衰減的音訊。

預設情況下，聲音自螢幕中心傳來。可在場景中加入 AudioListener2D 並呼叫 AudioListener2D.make_current() 來變更此位置。

若需非定位播放，請參考 AudioStreamPlayer。

注意： 隱藏 AudioStreamPlayer2D 節點不會停止其音訊輸出。若要暫時關閉輸出，請將 volume_db 設為如 -100 的極低值（人耳聽不見）。

教學

• 音訊流

屬性

int	area_mask	1
float	attenuation	1.0
bool	autoplay	false
StringName	bus	&"Master"
float	max_distance	2000.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	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() 🔗

當音訊停止播放時發出。

---

屬性說明

int area_mask = 1 🔗

• void set_area_mask(value: int)

• int get_area_mask()

決定哪些 Area2D 分層會影響混響及匯流排效果。可利用區域將 AudioStream 重新導向至特定匯流排，例如建立「水域」區域，使水中播放的聲音經過專用匯流排處理，聽起來像在水下。

---

float attenuation = 1.0 🔗

• void set_attenuation(value: float)

• float get_attenuation()

以此值為指數，使音量隨距離衰減。

---

bool autoplay = false 🔗

• void set_autoplay(value: bool)

• bool is_autoplay_enabled()

若為 true，加入場景樹時即開始播放音訊。

---

StringName bus = &"Master" 🔗

• void set_bus(value: StringName)

• StringName get_bus()

此音訊所屬匯流排。

注意： 設定時不會檢查名稱是否存在，因為匯流排佈局可能稍後才載入。若運行時無法解析名稱，將退回至 "Master"。

---

float max_distance = 2000.0 🔗

• void set_max_distance(value: float)

• float get_max_distance()

音訊仍可聽見的最遠距離。

---

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/2d_panning_strength 乘以此係數。值越大，左右聲像移動越顯著。

---

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

回傳與此 AudioStreamPlayer2D 相關聯的 AudioStreamPlayback 物件。

---

bool has_stream_playback() 🔗

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

---

void play(from_position: float = 0.0) 🔗

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

---

void seek(to_position: float) 🔗

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

---

void stop() 🔗

停止音訊。