AudioStreamInteractive

继承： AudioStream < Resource < RefCounted < Object

以可交互的形式播放音乐的音频流，包含若干剪辑和一张过渡表。

描述

这是一种能够以可交互的形式播放音乐的音频流，包含若干剪辑和一张过渡表。必须先添加剪辑，再使用 add_transition 添加过渡规则。这种音频流还导出了一个用于控制 AudioStreamPlayer、AudioStreamPlayer2D、AudioStreamPlayer3D 播放的属性参数。

用法是先填充一些剪辑，然后配置过渡表。音频流会根据过渡表选择要播放的剪辑，并根据表中定义的对应过渡规则平滑地将当前音乐过渡到新的剪辑。

属性

方法

枚举

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

过渡至目标剪辑的开头。

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 🔗

如果存在给定的过渡则返回 true（通过 add_transition 添加）。

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。