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

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

停止此節點的所有音效。