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

AudioStreamPlayer2D

繼承： Node2D < CanvasItem < Node < Object

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

說明

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

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

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

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

教學

• 音訊流

屬性

int	area_mask	0
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 = 0 🔗

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

停止音訊。