播放控制 API#
FmodChannelControl#
继承自： RefCounted
Channel 和 ChannelGroup 的通用控制基类
描述#
FmodChannelControl 封装 FMOD::ChannelControl 的共享能力，为 FmodChannel 和 FmodChannelGroup 提供播放控制、音量、3D 空间化、声像矩阵、滤波、DSP 链和样本精确调度等功能。
该类主要作为基类使用，通常通过 FmodChannel 或 FmodChannelGroup 获取实例。
属性#
类型 |
名称 |
初始值 |
说明 |
|---|---|---|---|
pasued |
false |
暂停状态。注意当前绑定名称为 |
|
pitch |
1.0 |
相对音高和播放速率 |
|
volume_db |
0.0 |
音量，单位为分贝 |
|
volume_ramp |
false |
音量变化是否使用平滑斜坡 |
|
mute |
false |
静音状态 |
|
3d_custom_rolloff |
PackedVector3Array() |
自定义 3D 距离衰减曲线 |
|
3d_doppler_level |
1.0 |
多普勒效果缩放量 |
|
3d_level |
1.0 |
3D 平移与 2D 平移之间的混合比例 |
|
3d_min_distance |
1.0 |
3D 距离衰减的最小距离 |
|
3d_max_distance |
10000.0 |
3D 距离衰减的最大距离 |
|
3d_spread |
0.0 |
3D 声音在扬声器空间中的扩散角度 |
|
gain |
1.0 |
内置低通/距离滤波使用的干信号增益 |
信号#
信号 |
说明 |
|---|---|
callback_received(type: int) |
当 FMOD ChannelControl 回调触发时发出， |
方法#
有效性检查#
bool channel_control_is_valid() const#
如果底层 FMOD::ChannelControl 句柄有效，则返回 true。
bool channel_control_is_null() const#
如果底层 FMOD::ChannelControl 句柄为空或不可用，则返回 true。
播放控制#
bool is_playing() const#
返回该 Channel 或 ChannelGroup 当前是否正在播放。
void stop()#
停止该 Channel 的播放，或停止嵌套在 ChannelGroup 中的所有 Channel。
void set_paused(paused: bool)#
设置暂停状态。true 会暂停播放，false 会恢复播放。
bool get_paused() const#
返回当前暂停状态。
void set_mode(mode: FmodMode)#
设置 FMOD 播放模式标志，用于控制循环、2D/3D、距离衰减等行为。
FmodMode get_mode() const#
返回当前播放模式标志。
void set_pitch(pitch: float)#
设置相对音高和播放速率。1.0 为原始音高，2.0 为两倍速，0.5 为半速。
float get_pitch() const#
返回当前相对音高和播放速率。
音量控制#
float get_audibility() const#
返回综合音量、静音、3D 衰减和父级混音后的最终可听度。
void set_volume_db(volume: float)#
设置音量，单位为分贝。
float get_volume_db() const#
返回当前音量，单位为分贝。
void set_volume_ramp(ramp: bool)#
设置音量变化是否使用 FMOD 的平滑斜坡。启用后可减少突然变更音量时的爆音。
bool get_volume_ramp() const#
返回音量变化是否使用平滑斜坡。
void set_mute(mute: bool)#
设置静音状态。
bool get_mute() const#
返回当前静音状态。
空间化#
void set_3d_attributes(pos: Vector3, vel: Vector3)#
设置 3D 位置和速度，用于平移、距离衰减和多普勒计算。
Dictionary get_3d_attributes() const#
返回 3D 属性字典，包含 pos 和 vel。
void set_3d_cone_orientation(orientation: Vector3)#
设置 3D 声音锥体方向，用于方向性遮挡和衰减。
Vector3 get_3d_cone_orientation() const#
返回当前 3D 声音锥体方向。
void set_3d_cone_settings(inside_cone_angle: float, outside_cone_angle: float, outside_volume_db: float)#
设置方向性 3D 声音锥体的内角、外角和外部音量衰减。
Dictionary get_3d_cone_settings() const#
返回锥体设置字典，包含 inside_cone_angle、outside_cone_angle 和 outside_volume_db。
void set_3d_custom_rolloff(points: PackedVector3Array)#
设置自定义 3D 距离衰减曲线。通常需要配合 FMOD_MODE_3D_CUSTOMROLLOFF 使用。
PackedVector3Array get_3d_custom_rolloff() const#
返回当前自定义 3D 距离衰减曲线。
void set_3d_distance_filter(custom: bool, custom_level: float, center_freq: float)#
设置 3D 距离滤波器覆盖值，用于随距离改变低通/高通滤波表现。
Dictionary get_3d_distance_filter() const#
返回距离滤波器设置字典，包含 custom、custom_level 和 center_freq。
void set_3d_doppler_level(level: float)#
设置多普勒效果缩放量。该功能主要用于 Channel。
float get_3d_doppler_level() const#
返回多普勒效果缩放量。
void set_3d_level(level: float)#
设置 3D 平移与 2D 平移之间的混合比例。
float get_3d_level() const#
返回 3D 平移与 2D 平移之间的混合比例。
void set_3d_min_distance(min: float)#
设置 3D 距离衰减开始前的最小距离。
float get_3d_min_distance() const#
返回 3D 距离衰减的最小距离。
void set_3d_max_distance(max: float)#
设置 3D 距离衰减的最大距离。
float get_3d_max_distance() const#
返回 3D 距离衰减的最大距离。
void set_3d_occlusion(direct_occlusion: float, reverb_occlusion: float)#
设置直接声和混响路径的遮挡衰减因子，范围通常为 0.0 到 1.0。
Dictionary get_3d_occlusion() const#
返回遮挡字典，包含 direct_occlusion 和 reverb_occlusion。
void set_3d_spread(angle: float)#
设置 3D 声音在扬声器空间中的扩散角度。
float get_3d_spread() const#
返回 3D 声音扩散角度。
声像与电平#
void set_pan(pan: float)#
设置左右声像。-1.0 为左，0.0 为中间，1.0 为右。
void set_mix_levels_input(levels: PackedFloat32Array)#
为多声道输入信号的每个输入通道设置电平。该功能主要用于 Channel。
void set_mix_levels_output(front_left: float, front_right: float, center: float, lfe: float, surround_left: float, surround_right: float, back_left: float, back_right: float)#
为每个输出扬声器设置音量电平。
void set_mix_matrix(matrix: PackedFloat32Array, outchannels: int, inchannels: int, inchannel_hop: int = 0)#
设置二维声像矩阵，将输入通道列映射到输出扬声器行。matrix 的长度应至少覆盖 outchannels * inchannel_hop，当 inchannel_hop 为 0 时使用 inchannels。
参见
混音矩阵、上混音与下混音的说明和示例见 Mix Matrix。
Dictionary get_mix_matrix() const#
返回当前混音矩阵信息，包含矩阵数据、输出通道数、输入通道数和输入通道步长。
过滤#
void set_reverb_properties(instance: int, wet: float)#
设置指定全局混响实例的发送电平。
float get_reverb_properties(instance: int) const#
返回指定全局混响实例的发送电平。
void set_low_pass_gain(gain: float)#
设置内置低通/距离滤波应用时干信号的增益。
float get_low_pass_gain() const#
返回内置低通/距离滤波应用时干信号的增益。
DSP 链配置#
void add_dsp(index: int, dsp: FmodDSP)#
在 DSP 链指定索引处插入一个 DSP 单元。
void remove_dsp(dsp: FmodDSP)#
从 DSP 链中移除指定 DSP 单元。
int get_num_dsps() const#
返回 DSP 链中的 DSP 单元数量。
FmodDSP get_dsp(index: int) const#
返回 DSP 链中指定索引处的 DSP 单元。
void set_dsp_index(dsp: FmodDSP, index: int)#
设置指定 DSP 单元在 DSP 链中的索引。
int get_dsp_index(dsp: FmodDSP) const#
返回指定 DSP 单元在 DSP 链中的索引。
样本精准排程#
Dictionary get_dsp_clock() const#
返回当前 DSP 时钟信息，通常包含当前时钟和父级时钟。
void set_delay(start: int, end: int, stopchannels: bool = true)#
设置相对于父 ChannelGroup DSP 时钟的样本精确开始和停止时间。
Dictionary get_delay() const#
返回样本精确延迟设置，包含开始、结束时钟和停止行为。
void add_fade_point(dspclock: int, volume: float)#
在指定 DSP 时钟处添加一个音量淡变点。
void set_fade_point_ramp(dspclock: int, volume: float)#
添加从当前音量到指定 DSP 时钟音量的淡变斜坡。
void remove_fade_points(start: int, end: int)#
移除两个 DSP 时钟值之间的所有淡变点。
Dictionary get_fade_points() const#
返回当前存储的淡变点信息。
回调#
void set_callback()#
设置 ChannelControl 级别的 FMOD 回调，并通过 callback_received 信号转发回 Godot。
void clear_callback()#
清除 ChannelControl 回调。
FmodChannel#
继承自： FmodChannelControl
单个播放通道的控制对象
描述#
FmodChannel 表示 FMOD 中一次实际或虚拟的声音播放实例。它继承 FmodChannelControl 的通用控制能力，并额外提供播放频率、优先级、播放位置、循环点、所属 ChannelGroup、当前声音和通道索引等接口。
方法#
有效性检查#
bool channel_is_valid() const#
如果底层 FMOD::Channel 句柄有效，则返回 true。
bool channel_is_null() const#
如果底层 FMOD::Channel 句柄为空或不可用，则返回 true。
播放参数#
void set_frequency(frequency: float)#
设置播放频率，单位为赫兹。改变频率会影响播放速度和音高。
float get_frequency() const#
返回当前播放频率，单位为赫兹。
void set_priority(priority: int)#
设置虚拟语音排序优先级。数值越低优先级越高。
int get_priority() const#
返回当前虚拟语音排序优先级。
void set_position(position: int, timeunit: FmodTimeUnit = FMOD_TIME_UNIT_MS)#
设置当前播放位置。默认使用毫秒时间单位。
int get_position(timeunit: FmodTimeUnit = FMOD_TIME_UNIT_MS) const#
返回当前播放位置。默认使用毫秒时间单位。
void set_channel_group(channel_group: FmodChannelGroup)#
设置该 Channel 输出到的 ChannelGroup。
FmodChannelGroup get_channel_group() const#
返回该 Channel 当前输出到的 ChannelGroup。
void set_loop_count(loop_count: int)#
设置停止前的循环次数。-1 通常表示无限循环。
int get_loop_count() const#
返回停止前的循环次数。
void set_loop_points(start: int, end: int, timeunit: FmodTimeUnit = FMOD_TIME_UNIT_MS)#
设置循环起点和终点。
Dictionary get_loop_points(timeunit: FmodTimeUnit = FMOD_TIME_UNIT_MS) const#
返回循环点字典，包含 start 和 end。
状态与信息#
bool is_virtual() const#
返回该 Channel 是否当前由 FMOD 虚拟语音系统模拟。
FmodSound get_current_sound() const#
返回该 Channel 当前播放的声音。
int get_index() const#
返回该 Channel 在 FMOD 系统通道池中的索引。
FmodChannelGroup#
继承自： FmodChannelControl
用于组织和混合多个 Channel 的通道组
描述#
FmodChannelGroup 表示 FMOD 的 ChannelGroup，可作为多个 Channel 或子 ChannelGroup 的输入目标。它继承通用的播放、音量、DSP 和调度控制能力，适合用于分组混音、总线式控制和批量停止声音。
方法#
有效性检查#
bool channel_group_is_valid() const#
如果底层 FMOD::ChannelGroup 句柄有效，则返回 true。
bool channel_group_is_null() const#
如果底层 FMOD::ChannelGroup 句柄为空或不可用，则返回 true。
Channel 管理#
int get_num_channels() const#
返回汇入该组的 Channel 数量。
FmodChannel get_channel(index: int) const#
返回指定索引处的 Channel。
ChannelGroup 管理#
void add_group(channel_group: FmodChannelGroup, propagatedspclock: bool = true)#
将另一个 ChannelGroup 添加为当前组的输入。propagatedspclock 控制是否传播 DSP 时钟。
int get_num_groups() const#
返回汇入该组的子 ChannelGroup 数量。
FmodChannelGroup get_group(index: int) const#
返回组输入列表中指定索引处的 ChannelGroup。
FmodChannelGroup get_parent_group() const#
返回当前 ChannelGroup 输出到的父 ChannelGroup。
概述#
String get_name() const#
返回创建该 ChannelGroup 时使用的名称。
void release()#
释放 ChannelGroup。释放后底层句柄不应继续使用。
FmodSoundGroup#
继承自： RefCounted
用于限制和管理一组 FmodSound 播放行为的对象
描述#
FmodSoundGroup 封装 FMOD::SoundGroup，可为一组声音设置最大同时可听数量、超出限制时的处理策略、静音淡出速度和整体音量。
属性#
方法#
有效性检查#
bool sound_group_is_valid() const#
如果底层 FMOD::SoundGroup 句柄有效，则返回 true。
bool sound_group_is_null() const#
如果底层 FMOD::SoundGroup 句柄为空或不可用，则返回 true。
基础功能#
void set_max_audible(max_audible: int)#
设置 SoundGroup 中同时可听到的最大播放数量。
int get_max_audible() const#
返回 SoundGroup 中同时可听到的最大播放数量。
void set_max_audible_behavior(behavior: Behavior)#
设置超过最大可听数量时的处理方式。
Behavior get_max_audible_behavior() const#
返回超过最大可听数量时的处理方式。
void set_mute_fade_speed(speed: float)#
设置因最大可听数量限制而静音或恢复时的淡变速度。
float get_mute_fade_speed() const#
返回静音淡变速度。
void set_volume_db(volume_db: float)#
设置 SoundGroup 音量，单位为分贝。
float get_volume_db() const#
返回 SoundGroup 音量，单位为分贝。
音效功能#
int get_num_sounds() const#
返回 SoundGroup 中包含的 FmodSound 数量。
FmodSound get_sound(index: int) const#
返回 SoundGroup 中指定索引处的 FmodSound。
int get_num_playing() const#
返回 SoundGroup 当前正在播放的 Channel 数量。
void stop()#
停止 SoundGroup 中所有正在播放的声音。
概述#
String get_name() const#
返回 SoundGroup 的名称。
void release()#
释放 SoundGroup，并将其中的声音返回主 SoundGroup。
枚举#
Behavior#
成员 |
值 |
说明 |
|---|---|---|
BEHAVIOR_FAIL |
0 |
调用播放接口时，如果超过最大可听数量则播放失败 |
BEHAVIOR_MUTE |
1 |
超出的声音从静音开始，直到有足够声音停止后再变得可听 |
BEHAVIOR_STEAL_LOWEST |
2 |
超出限制时抢占当前最安静的声音 |
BEHAVIOR_MAX |
3 |
行为枚举数量 |