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

AudioStreamInteractive

繼承： AudioStream < Resource < RefCounted < Object

可互動播放音樂的音訊串流，結合片段與轉場表。

說明

這是一種可互動播放音樂的音訊串流，能結合片段與轉場表。必須先加入片段，再透過 add_transition() 設定轉場規則。此外，此串流會匯出一個屬性，讓你可透過 AudioStreamPlayer、AudioStreamPlayer2D 或 AudioStreamPlayer3D 來控制播放。

使用方式為先填入多個片段，再設定轉場表。之後會依轉場表中定義的規則選擇片段播放，音樂將會從目前片段順暢地銜接到下一個片段。

教學

音訊流

屬性

int	clip_count	`0`
int	initial_clip	`0`

方法

void	add_transition(from_clip: int, to_clip: int, from_time: TransitionFromTime, to_time: TransitionToTime, fade_mode: FadeMode, fade_beats: float, use_filler_clip: bool = false, filler_clip: int = -1, hold_previous: bool = false)
void	erase_transition(from_clip: int, to_clip: int)
AutoAdvanceMode	get_clip_auto_advance(clip_index: int) const
int	get_clip_auto_advance_next_clip(clip_index: int) const
StringName	get_clip_name(clip_index: int) const
AudioStream	get_clip_stream(clip_index: int) const
float	get_transition_fade_beats(from_clip: int, to_clip: int) const
FadeMode	get_transition_fade_mode(from_clip: int, to_clip: int) const
int	get_transition_filler_clip(from_clip: int, to_clip: int) const
TransitionFromTime	get_transition_from_time(from_clip: int, to_clip: int) const
PackedInt32Array	get_transition_list() const
TransitionToTime	get_transition_to_time(from_clip: int, to_clip: int) const
bool	has_transition(from_clip: int, to_clip: int) const
bool	is_transition_holding_previous(from_clip: int, to_clip: int) const
bool	is_transition_using_filler_clip(from_clip: int, to_clip: int) const
void	set_clip_auto_advance(clip_index: int, mode: AutoAdvanceMode)
void	set_clip_auto_advance_next_clip(clip_index: int, auto_advance_next_clip: int)
void	set_clip_name(clip_index: int, name: StringName)
void	set_clip_stream(clip_index: int, stream: AudioStream)

列舉

enum TransitionFromTime: 🔗

TransitionFromTime TRANSITION_FROM_TIME_IMMEDIATE = 0

儘快開始轉場，不等待特定時間位置。

TransitionFromTime TRANSITION_FROM_TIME_NEXT_BEAT = 1

當播放位置到達下一拍時進行轉場。

TransitionFromTime TRANSITION_FROM_TIME_NEXT_BAR = 2

當播放位置到達下一小節時進行轉場。

TransitionFromTime TRANSITION_FROM_TIME_END = 3

當目前片段播放結束時進行轉場。

enum TransitionToTime: 🔗

TransitionToTime TRANSITION_TO_TIME_SAME_POSITION = 0

轉場到目的片段的相同位置。當兩片段長度完全相同且需要在它們之間淡化時很有用。

TransitionToTime TRANSITION_TO_TIME_START = 1

轉場到目的片段的開始。

TransitionToTime TRANSITION_TO_TIME_PREVIOUS_POSITION = 2

Transition to the last played position in the destination clip, if there was a previous transition from that clip. Otherwise, plays from the start of the destination clip.

enum FadeMode: 🔗

FadeMode FADE_DISABLED = 0

轉場時不使用淡入淡出。適用於片段結尾接片段開頭，且各片段本身已有開場／結尾的情況。

FadeMode FADE_IN = 1

讓目前片段播畢，並在下一個片段使用淡入。

FadeMode FADE_OUT = 2

在目前片段使用淡出，下一個片段將自行開始。

FadeMode FADE_CROSS = 3

在片段之間使用交叉淡化。

FadeMode FADE_AUTOMATIC = 4

依來源／目的自動選擇淡化邏輯。建議預設使用此模式。

enum AutoAdvanceMode: 🔗

AutoAdvanceMode AUTO_ADVANCE_DISABLED = 0

停用自動前進（預設）。

AutoAdvanceMode AUTO_ADVANCE_ENABLED = 1

啟用自動前進，必須指定片段。

AutoAdvanceMode AUTO_ADVANCE_RETURN_TO_HOLD = 2

啟用自動前進，但不指定片段，而是回到保持的片段（參見 add_transition()）。

常數

CLIP_ANY = -1 🔗

此常數表示在特定轉場中，任何片段都可作為來源或目的。

屬性說明

int clip_count = 0 🔗

void set_clip_count(value: int)
int get_clip_count()

此互動播放器包含的片段數量。

int initial_clip = 0 🔗

void set_initial_clip(value: int)
int get_initial_clip()

初始片段的索引，串流開始播放時會先播放此片段。

方法說明

void add_transition(from_clip: int, to_clip: int, from_time: TransitionFromTime, to_time: TransitionToTime, fade_mode: FadeMode, fade_beats: float, use_filler_clip: bool = false, filler_clip: int = -1, hold_previous: bool = false) 🔗

在兩個片段之間加入轉場。請傳入來源與目的片段的索引，或使用常數 CLIP_ANY 表示自/向任何片段的轉場。

* from_time：觸發後，轉場在目前片段的何時開始。

* to_time：下一個片段從何處開始播放。

* fade_mode：片段間的淡入淡出方式。如無特別需求，使用 FADE_AUTOMATIC 即可，這會依情況選擇最常用的淡化模式。

* fade_beats：淡入淡出將持續多少拍，可使用小數。

* use_filler_clip：是否在來源與目的片段之間插入填充片段。

* filler_clip：填充片段的索引。

* 若指定 hold_previous，則此片段會被記住，可與 AUTO_ADVANCE_RETURN_TO_HOLD 搭配，在其他片段播放完後回到此片段。

void erase_transition(from_clip: int, to_clip: int) 🔗

提供 from_clip 與 to_clip 的片段索引即可刪除轉場。兩者皆可使用 CLIP_ANY。

AutoAdvanceMode get_clip_auto_advance(clip_index: int) const 🔗

返回指定片段是否啟用自動前進。參見 set_clip_auto_advance()。

int get_clip_auto_advance_next_clip(clip_index: int) const 🔗

返回索引為 clip_index 的片段將自動前進到的目標片段索引。

StringName get_clip_name(clip_index: int) const 🔗

返回片段的名稱。

AudioStream get_clip_stream(clip_index: int) const 🔗

返回與片段關聯的 AudioStream。

float get_transition_fade_beats(from_clip: int, to_clip: int) const 🔗

返回轉場所需的時間（拍數）（參見 add_transition()）。

FadeMode get_transition_fade_mode(from_clip: int, to_clip: int) const 🔗

返回轉場的模式（參見 add_transition()）。

int get_transition_filler_clip(from_clip: int, to_clip: int) const 🔗

返回轉場所使用的填充片段（參見 add_transition()）。

TransitionFromTime get_transition_from_time(from_clip: int, to_clip: int) const 🔗

返回轉場的來源時間位置（參見 add_transition()）。

PackedInt32Array get_transition_list() const 🔗

返回轉場清單（來源與目的交錯排列）。

TransitionToTime get_transition_to_time(from_clip: int, to_clip: int) const 🔗

返回轉場的目的時間位置（參見 add_transition()）。

bool has_transition(from_clip: int, to_clip: int) const 🔗

若指定的轉場已存在（由 add_transition() 新增），則返回 true。

bool is_transition_holding_previous(from_clip: int, to_clip: int) const 🔗

返回轉場是否使用 保持前一片段 功能（參見 add_transition()）。

bool is_transition_using_filler_clip(from_clip: int, to_clip: int) const 🔗

返回轉場是否使用 填充片段 功能（參見 add_transition()）。

void set_clip_auto_advance(clip_index: int, mode: AutoAdvanceMode) 🔗

設定片段的自動前進模式。

void set_clip_auto_advance_next_clip(clip_index: int, auto_advance_next_clip: int) 🔗

設定此片段播畢後將自動前進到的下一個片段索引。若該片段會循環播放，則自動前進將被忽略。

void set_clip_name(clip_index: int, name: StringName) 🔗

設定目前片段的名稱（便於辨識）。

void set_clip_stream(clip_index: int, stream: AudioStream) 🔗

設定目前片段關聯的 AudioStream。