GFAudioBeatClock

API Reference / Standard / 类索引

• 路径：addons/gf/standard/utilities/audio/gf_audio_beat_clock.gd
• 模块：Standard
• 继承：RefCounted
• API：public
• 类别：运行时句柄 (runtime_handle)
• 首次版本：4.2.0

通用音频节拍时钟。 将任意播放时间映射为 beat、measure 和进度快照，并在手动 update() 时发出越过的节拍边界。 它不持有播放器、不创建节点，也不规定节奏玩法、字幕或演出语义。

成员概览

类型	名称	签名
信号	position_updated	signal position_updated(snapshot: Dictionary)
信号	beat_reached	signal beat_reached(beat_index: int, beat_in_measure: int, position_seconds: float)
信号	measure_reached	signal measure_reached(measure_index: int, beat_index: int, position_seconds: float)
枚举	QuantizeMode	enum QuantizeMode
常量	DEFAULT_BPM	const DEFAULT_BPM: float = 120.0
常量	DEFAULT_BEATS_PER_MEASURE	const DEFAULT_BEATS_PER_MEASURE: int = 4
常量	DEFAULT_MAX_EMITTED_STEPS_PER_UPDATE	const DEFAULT_MAX_EMITTED_STEPS_PER_UPDATE: int = 64
属性	bpm	var bpm: float = DEFAULT_BPM
属性	beats_per_measure	var beats_per_measure: int = DEFAULT_BEATS_PER_MEASURE
属性	offset_seconds	var offset_seconds: float = 0.0
属性	emit_initial_events	var emit_initial_events: bool = false
属性	max_emitted_steps_per_update	var max_emitted_steps_per_update: int = DEFAULT_MAX_EMITTED_STEPS_PER_UPDATE
属性	position_source	var position_source: Callable = Callable()
属性	metadata	var metadata: Dictionary = {}
方法	configure	func configure( next_bpm: float, next_beats_per_measure: int = DEFAULT_BEATS_PER_MEASURE, next_offset_seconds: float = 0.0, should_reset: bool = true ) -> void:
方法	set_position_source	func set_position_source(source: Callable) -> void:
方法	clear	func clear() -> void:
方法	reset	func reset(position_seconds: float = 0.0) -> Dictionary:
方法	update_from_source	func update_from_source() -> Dictionary:
方法	update	func update(position_seconds: float) -> Dictionary:
方法	sample	func sample(position_seconds: float) -> Dictionary:
方法	get_bpm	func get_bpm() -> float:
方法	get_beats_per_measure	func get_beats_per_measure() -> int:
方法	get_seconds_per_beat	func get_seconds_per_beat() -> float:
方法	get_seconds_per_measure	func get_seconds_per_measure() -> float:
方法	seconds_to_beats	func seconds_to_beats(duration_seconds: float) -> float:
方法	beats_to_seconds	func beats_to_seconds(beat_count: float) -> float:
方法	position_to_beats	func position_to_beats(position_seconds: float) -> float:
方法	beat_to_position_seconds	func beat_to_position_seconds(beat_index: int) -> float:
方法	quantize_position	func quantize_position( position_seconds: float, subdivisions_per_beat: int = 1, mode: QuantizeMode = QuantizeMode.NEAREST ) -> float:
方法	get_last_snapshot	func get_last_snapshot() -> Dictionary:
方法	get_last_position_seconds	func get_last_position_seconds() -> float:
方法	has_last_position	func has_last_position() -> bool:

信号

position_updated

• API：public

signal position_updated(snapshot: Dictionary)

update() 采样时间并刷新快照后发出。

参数：

名称	说明
snapshot	当前节拍快照。

结构：

• snapshot: Dictionary，包含 position_seconds、adjusted_seconds、beat_index、measure_index、beat_progress 和 measure_progress 等字段。

beat_reached

• API：public

signal beat_reached(beat_index: int, beat_in_measure: int, position_seconds: float)

update() 检测到新的 beat 边界后发出。

参数：

名称	说明
beat_index	从 0 开始的全局 beat 索引。
beat_in_measure	当前小节内的 beat 索引。
position_seconds	该 beat 边界对应的播放时间。

measure_reached

• API：public

signal measure_reached(measure_index: int, beat_index: int, position_seconds: float)

update() 检测到新的 measure 边界后发出。

参数：

名称	说明
measure_index	从 0 开始的小节索引。
beat_index	该小节起点对应的全局 beat 索引。
position_seconds	该小节边界对应的播放时间。

枚举

QuantizeMode

• API：public

enum QuantizeMode { ## 量化到最近的网格点。 NEAREST, ## 量化到不大于当前时间的网格点。 FLOOR, ## 量化到不小于当前时间的网格点。 CEIL, }

量化时间时使用的舍入方式。

常量

DEFAULT_BPM

• API：public

const DEFAULT_BPM: float = 120.0

默认 BPM。

DEFAULT_BEATS_PER_MEASURE

• API：public

const DEFAULT_BEATS_PER_MEASURE: int = 4

默认每小节 beat 数。

DEFAULT_MAX_EMITTED_STEPS_PER_UPDATE

• API：public

const DEFAULT_MAX_EMITTED_STEPS_PER_UPDATE: int = 64

每次 update() 默认最多补发的 beat 边界数量。

属性

bpm

• API：public

var bpm: float = DEFAULT_BPM

当前 BPM。小于等于 0 时会按极小正数处理，避免除零。

beats_per_measure

• API：public

var beats_per_measure: int = DEFAULT_BEATS_PER_MEASURE

每小节 beat 数。小于 1 时按 1 处理。

offset_seconds

• API：public

var offset_seconds: float = 0.0

时间偏移，单位秒。采样时使用 position_seconds + offset_seconds 计算节拍。

emit_initial_events

• API：public

var emit_initial_events: bool = false

首次 update() 是否立刻发出当前 beat 和 measure 边界事件。

max_emitted_steps_per_update

• API：public

var max_emitted_steps_per_update: int = DEFAULT_MAX_EMITTED_STEPS_PER_UPDATE

每次 update() 最多补发的 beat 边界数量。小于等于 0 时不补发边界事件。

position_source

• API：public

var position_source: Callable = Callable()

可选播放位置来源。update_from_source() 会调用它并期望得到秒数。

metadata

• API：public

var metadata: Dictionary = {}

项目自定义元数据。框架不解释该字段。

结构：

• metadata: Dictionary metadata for tooling or project-specific routing.

方法

configure

• API：public

func configure( next_bpm: float, next_beats_per_measure: int = DEFAULT_BEATS_PER_MEASURE, next_offset_seconds: float = 0.0, should_reset: bool = true ) -> void:

配置节拍参数。

参数：

名称	说明
next_bpm	BPM。
next_beats_per_measure	每小节 beat 数。
next_offset_seconds	时间偏移，单位秒。
should_reset	为 true 时清除上一帧边界状态。

set_position_source

• API：public

func set_position_source(source: Callable) -> void:

设置播放位置来源。

参数：

名称	说明
source	返回播放秒数的回调。

clear

• API：public

func clear() -> void:

清除上一帧状态。

reset

• API：public

func reset(position_seconds: float = 0.0) -> Dictionary:

将时钟状态重置到指定播放时间，不发出边界事件。

参数：

名称	说明
position_seconds	播放时间，单位秒。

返回：重置后的快照。

结构：

• return: Dictionary，结构同 sample()。

update_from_source

• API：public

func update_from_source() -> Dictionary:

从 position_source 采样并更新时钟。

返回：当前节拍快照；来源无效或返回非数字时返回空字典。

结构：

• return: Dictionary，结构同 sample()。

update

• API：public

func update(position_seconds: float) -> Dictionary:

采样指定播放时间、刷新状态并发出越过的边界事件。

参数：

名称	说明
position_seconds	播放时间，单位秒。

返回：当前节拍快照。

结构：

• return: Dictionary，包含 position_seconds、adjusted_seconds、bpm、seconds_per_beat、beats_per_measure、beat_float、beat_index、beat_in_measure、beat_progress、measure_index、measure_progress 和 measure_start_beat。

sample

• API：public

func sample(position_seconds: float) -> Dictionary:

采样指定播放时间但不修改时钟状态。

参数：

名称	说明
position_seconds	播放时间，单位秒。

返回：节拍快照。

结构：

• return: Dictionary，包含 position_seconds、adjusted_seconds、bpm、seconds_per_beat、beats_per_measure、beat_float、beat_index、beat_in_measure、beat_progress、measure_index、measure_progress 和 measure_start_beat。

get_bpm

• API：public

func get_bpm() -> float:

获取经过安全收窄的 BPM。

返回：BPM。

get_beats_per_measure

• API：public

func get_beats_per_measure() -> int:

获取经过安全收窄的每小节 beat 数。

返回：每小节 beat 数。

get_seconds_per_beat

• API：public

func get_seconds_per_beat() -> float:

获取每个 beat 的秒数。

返回：秒数。

get_seconds_per_measure

• API：public

func get_seconds_per_measure() -> float:

获取每小节的秒数。

返回：秒数。

seconds_to_beats

• API：public

func seconds_to_beats(duration_seconds: float) -> float:

将持续时间秒数转换为 beat 数，不应用 offset_seconds。

参数：

名称	说明
duration_seconds	持续时间，单位秒。

返回：beat 数。

beats_to_seconds

• API：public

func beats_to_seconds(beat_count: float) -> float:

将 beat 数转换为持续时间秒数，不应用 offset_seconds。

参数：

名称	说明
beat_count	beat 数。

返回：持续时间秒数。

position_to_beats

• API：public

func position_to_beats(position_seconds: float) -> float:

将播放时间转换为 beat 数，会应用 offset_seconds。

参数：

名称	说明
position_seconds	播放时间，单位秒。

返回：beat 数。

beat_to_position_seconds

• API：public

func beat_to_position_seconds(beat_index: int) -> float:

获取指定 beat 边界对应的播放时间，会反向应用 offset_seconds。

参数：

名称	说明
beat_index	beat 索引。

返回：播放时间，单位秒。

quantize_position

• API：public

func quantize_position( position_seconds: float, subdivisions_per_beat: int = 1, mode: QuantizeMode = QuantizeMode.NEAREST ) -> float:

量化播放时间到 beat 网格。

参数：

名称	说明
position_seconds	播放时间，单位秒。
subdivisions_per_beat	每个 beat 的细分数量。
mode	量化方式。

返回：量化后的播放时间，单位秒。

get_last_snapshot

• API：public

func get_last_snapshot() -> Dictionary:

获取上一帧快照副本。

返回：快照副本。

结构：

• return: Dictionary，结构同 sample()；尚未 update/reset 时为空。

get_last_position_seconds

• API：public

func get_last_position_seconds() -> float:

获取上一帧播放位置。

返回：播放时间，单位秒。

has_last_position

• API：public

func has_last_position() -> bool:

检查时钟是否已经有上一帧状态。

返回：已有状态时返回 true。