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

过渡至目标剪辑的开头。

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。