librosa beat_track 的速度估计与节拍时刻有什么区别

先给结论：librosa.beat.beat_track() 返回的 tempo 和 beats 不是同一种结果。tempo 是对整段音频节奏速度的估计，单位通常是每分钟节拍数（BPM）；beats 是算法认为发生节拍事件的位置，默认以帧索引返回。一个回答“整体有多快”，另一个回答“每个节拍落在哪里”。

官方地址：https://librosa.org/

实际使用时，做速度标签、歌曲节奏分类或选择点击速度，读取 tempo；做字幕、鼓点标记、切片和时间轴对齐，读取 beats。两者应该一起保存，但不要拿一个替代另一个。

先看 beat_track 的两个返回值

函数内部会先得到起音强度，再估计速度，最后在起音曲线上挑出与速度大致一致的峰值。因此返回值天然分成“节奏率”和“事件序列”两个层次：

当前版本的文档说明，单声道输入即使只有一个速度值，tempo 也可能以只有一个元素的一维 NumPy 数组返回。代码中不要假定它永远是 Python float，用 np.asarray(...).squeeze() 取出标量更稳妥。

import numpy as np
import librosa

# 读取一小段音频；实际项目也可以直接传入已有的 y 和 sr
y, sr = librosa.load("drum-loop.wav", sr=None, mono=True)

# units 默认是 frames，所以这里的 beats 还是特征帧位置
tempo, beats = librosa.beat.beat_track(y=y, sr=sr)

# tempo 可能是单元素 ndarray，先转成稳定的标量用于展示
tempo_bpm = float(np.asarray(tempo).squeeze())
print(f"整体速度约为 {tempo_bpm:.1f} BPM")
print(f"检测到 {len(beats)} 个节拍帧")

节拍时刻为什么不能从 BPM 直接推出来

如果只知道 120 BPM，只能计算理想情况下约每 0.5 秒一个节拍，却不知道第一个节拍从哪里开始，也不知道真实音频中的起音会如何提前、延后或被 trim 去掉。beats 还要结合起音强度和动态规划路径，所以它不是把音频长度按 BPM 均匀切格子。

同一首歌中，节拍之间可能围绕平均间隔有小幅波动。tempo 是概括，beats 是定位；前者适合描述一段音乐，后者才适合把一个事件放到时间轴上。

另外，start_bpm 是速度估计的初始猜测，不等于最终返回值；tightness 控制节拍路径对估计速度的贴合程度；trim=True 会裁掉起点或终点附近较弱的节拍。因此调参后，tempo 可能变化不大，但 beats 的首尾数量和具体位置可能发生变化。

需要秒数时优先使用 units="time"

默认的 beats 是帧索引，帧索引只有结合 sr、hop_length 才能解释成时间。最直接的方式是在调用时指定 units="time"：

import librosa

# 直接让 beat_track 返回秒数，便于和字幕、标注或视频时间轴对齐
tempo, beat_times = librosa.beat.beat_track(
    y=y,
    sr=sr,
    units="time",
)

# 这里的 beat_times 已经是秒，不要再次调用 frames_to_time
print(beat_times[:5])

也可以保留默认帧索引，再显式转换：

# 保留帧索引，适合和谱图的列直接对应
tempo, beat_frames = librosa.beat.beat_track(y=y, sr=sr, units="frames")

# 使用同一套采样率和 hop_length 把帧位置换算成秒
beat_times = librosa.frames_to_time(beat_frames, sr=sr, hop_length=512)

两种写法的关键不是哪一种更“准确”，而是单位要与后续数据一致。画起音包络或梅尔谱时，帧索引往往更方便；写入时间轴、切视频或导出标注时，秒数更直观。

稀疏 beats 与稠密布尔时间线有什么区别

默认 sparse=True 时，beats 只列出被检测为节拍的位置，例如 [3, 21, 40, ...]。这适合遍历事件、绘制竖线或生成点击声。

如果设置 sparse=False，返回值会变成与帧轴等长的布尔数组，节拍帧为 True，其余帧为 False。这适合和每一帧的特征、标签或掩码逐项相乘。多通道输入也要求使用稠密形式。

# 稠密结果与 onset envelope 的帧轴对齐，每个位置只有 True 或 False
tempo, beat_mask = librosa.beat.beat_track(
    y=y,
    sr=sr,
    sparse=False,
)

# 用布尔掩码挑出节拍帧；这里假设 onset_env 与 beat_mask 使用同一 hop_length
onset_env = librosa.onset.onset_strength(y=y, sr=sr, hop_length=512)
beat_strength = onset_env[beat_mask]
print(f"节拍帧数量：{beat_mask.sum()}")

遇到速度变化时，tempo 仍然不是 beats

普通调用倾向于估计整段音频的一个全局速度，适合速度大致稳定的片段。如果音频有明显加速、减速或不同段落速度差异，文档提供了按时间变化的 BPM 输入方式：

import numpy as np

# 先得到起音包络，后面的动态 BPM 与它共享同一帧轴
onset_env = librosa.onset.onset_strength(y=y, sr=sr)

# 每个起音帧给出一个速度估计；真实项目可替换为随时间变化的数组
tempo_dynamic = np.full(onset_env.shape, 128.0, dtype=float)

# 把时变 BPM 约束传给节拍跟踪器，并直接返回秒数
tempo_result, beat_times = librosa.beat.beat_track(
    onset_envelope=onset_env,
    sr=sr,
    bpm=tempo_dynamic,
    units="time",
    trim=False,
)

# 提供 bpm 后，返回的 tempo 主要是输入速度的回传，不是新的独立速度结论
print(beat_times)

真正使用时，tempo_dynamic 的形状要和起音包络的时间轴对应；只构造一个与音频无关的常量数组，并不能解决速度变化问题。可以把这类调用理解为：你提供“每个时刻的节奏约束”，beat_track 负责在起音峰值上选出事件位置。

五项检查，避免把两个结果混在一起

1. 先看单位：确认是否使用了 units="time"，不要把帧号直接写成秒。
2. 再看返回值形状：tempo 可能是单元素数组，beats 则是一组位置或布尔掩码。
3. 检查 hop_length：手动转换帧时，要和生成起音包络时使用相同的 hop_length。
4. 检查空结果：如果没有检测到起音，文档定义的结果可能是 0 BPM 和空节拍列表，这不应被当成“节拍在第 0 秒”。
5. 对齐后续任务：做速度统计读取 tempo，做时间轴标注读取 beats；需要逐帧处理时再用 sparse=False。

常见问题

tempo 是每个节拍的时间间隔吗？

不是。tempo 是速度估计，通常用 BPM 表示；每个节拍的实际位置在 beats 中。

beats 默认返回秒数吗？

不是，默认单位是帧。需要秒数时传入 units="time"，或用与特征相同的 hop_length 显式转换。

为什么按 BPM 计算的等间隔和 beat_times 对不上？

BPM 是整体或局部速度概括，而节拍位置还受起音强度、首个节拍相位、tightness 和 trim 影响，真实检测结果不必是严格等间隔。

什么时候使用 sparse=False？

当你需要与每帧特征逐项对齐、构造布尔标签或处理多通道输入时使用；如果只是遍历节拍事件，默认稀疏数组更轻便。

记住一句话即可：tempo 告诉你“节奏有多快”，beats 告诉你“节拍发生在哪里”。先确定后续任务需要速度还是位置，再选择返回值和单位。