AudioStreamPlayer

繼承： Node < Object

用於音訊播放的節點。

說明

AudioStreamPlayer 節點可播放非定位的音訊，適合用於 UI、選單或背景音樂。

使用時請先將 stream 設為有效的 AudioStream 資源。本節點也支援同時播放多段音訊，詳見 max_polyphony。

若需在特定位置播放，請改用 AudioStreamPlayer2D 或 AudioStreamPlayer3D。

教學

屬性

bool	autoplay	`false`
StringName	bus	`&"Master"`
int	max_polyphony	`1`
MixTarget	mix_target	`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() 🔗

當音效自然播放完畢且未被打斷時發出。呼叫 stop() 或離開場景樹時不會觸發。

列舉

enum MixTarget: 🔗

MixTarget MIX_TARGET_STEREO = 0

音訊僅會在第一個聲道播放（預設值）。

MixTarget MIX_TARGET_SURROUND = 1

音訊將在所有環繞聲聲道播放。

MixTarget MIX_TARGET_CENTER = 2

音訊將在第二個聲道（通常為中央聲道）播放。

屬性說明

bool autoplay = false 🔗

void set_autoplay(value: bool)
bool is_autoplay_enabled()

若為 true，該節點進入場景樹時會自動呼叫 play()。

StringName bus = &"Master" 🔗

void set_bus(value: StringName)
StringName get_bus()

目標匯流排名稱。此節點的所有音效將於該匯流排播放。

注意： 執行時若找不到同名匯流排，將退回至 "Master"。另見 AudioServer.get_bus_name()。

int max_polyphony = 1 🔗

void set_max_polyphony(value: int)
int get_max_polyphony()

此節點可同時播放的最大音效數量。達上限後再次呼叫 play() 會截斷最早播放的音效。

MixTarget mix_target = 0 🔗

void set_mix_target(value: MixTarget)
MixTarget get_mix_target()

混音目標聲道。若僅偵測到兩個或更少揚聲器時無效（參見 SpeakerMode）。

float pitch_scale = 1.0 🔗

void set_pitch_scale(value: float)
float get_pitch_scale()

音訊的音高與節奏倍率，相對於 stream 的取樣率。2.0 代表音高變兩倍，0.5 則為一半。

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() 或 stop() 效果相同。

AudioStream stream 🔗

void set_stream(value: AudioStream)
AudioStream get_stream()

要播放的 AudioStream 資源。設定時會停止目前所有正在播放的音效。若留空，此 AudioStreamPlayer 將無法運作。

bool stream_paused = false 🔗

void set_stream_paused(value: bool)
bool get_stream_paused()

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

注意： 離開／進入場景樹或節點被暫停（見 Node.process_mode）時，此屬性會自動變更。

float volume_db = 0.0 🔗

void set_volume_db(value: float)
float get_volume_db()

音量（dB），為 stream 音量的偏移量。

注意： 若需在分貝與線性能量間轉換，可使用 volume_linear，或 @GlobalScope.db_to_linear() / @GlobalScope.linear_to_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 中的位置（秒）。若目前無任何音效播放則回傳 0.0。

注意： 由於 AudioServer 並非每個處理影格都進行混音，該位置不一定精確。若需更精準，請將 AudioServer.get_time_since_last_mix() 加到回傳值上。

注意： 若 stream 為 AudioStreamInteractive（可能同時播放多段片段），本方法恒回傳 0.0。

AudioStreamPlayback get_stream_playback() 🔗

回傳此節點最新產生的 AudioStreamPlayback（通常由 play() 建立）。若無音效播放則回傳空播放實例。

bool has_stream_playback() 🔗

若有任何音效處於活動狀態則回傳 true，即使 stream_paused 為 true。另見 playing 與 get_stream_playback()。

void play(from_position: float = 0.0) 🔗

從開頭或指定的 from_position（秒）開始播放音效。

void seek(to_position: float) 🔗

將所有正在播放的音效重新定位至 to_position（秒）並繼續播放；若無音效播放則不動作。

void stop() 🔗

停止此節點的所有音效。