librosa 怎样估算音频节拍位置

我在把一段音频切成节拍片段时，最容易误解的是“节拍位置”这个结果：librosa.beat.beat_track 给出的不是逐采样确认的真值，而是根据起音强度、估计速度和节拍一致性推断出的事件位置。实际使用时，先用统一的采样率和 hop_length 读取音频，再把返回的帧索引换成秒，通常就能得到可用于标记、切片和同步的节拍时间点。

官方文档入口：https://librosa.org/doc/main/api/generated/librosa.beat.beat_track.html。本文只讨论 librosa 的节拍估算与结果解释，不把估算位置当成人工标注或逐采样级别的测量。

先把“节拍位置”拆成三个结果

节拍跟踪通常同时关心三个量：全局速度 tempo、节拍事件的帧索引 beats，以及把帧索引换算成秒后的 beat_times。其中 tempo 是每分钟节拍数，beats 默认是帧位置，beat_times 才是可以直接放进音频时间轴的秒数。

librosa 的官方说明把这个过程概括为三部分：测量起音强度、从起音相关性估计速度，再选择大致符合该速度的起音峰值。因此，鼓点清晰的音乐和节奏自由、弱起音的录音，得到的稳定程度不会相同。

先固定采样率和帧步长

节拍位置最终要落到时间轴上，所以输入阶段的采样率和帧步长要明确。librosa.load 默认会把音频重采样到 22050 Hz；如果要保留文件的原生采样率，可以传入 sr=None。对一篇教程或一条稳定的处理流水线来说，关键不是哪个采样率“最好”，而是后续换算和再次处理时保持同一组参数。

from pathlib import Path

import librosa

# 把输入路径集中管理，避免调试时误把不同音频混在同一组结果里。
audio_path = Path("assets/song.wav")

# 固定采样率便于复现实验；需要保留原始采样率时改成 sr=None。
y, sr = librosa.load(audio_path, sr=22050, mono=True)
hop_length = 512

# 这里的 y 是浮点音频序列，sr 与 hop_length 会参与帧到秒的换算。
print(f"samples={len(y)} sr={sr} hop_length={hop_length}")

mono=True 会把多声道内容合并为单声道，适合先估算一条整体节奏。若后续业务需要分别处理左右声道，不要在读取阶段直接假设多声道节拍结果可以按单声道逻辑解释。

最小调用：直接得到 BPM 和节拍帧

最短路径是把音频序列和采样率交给 beat_track。默认 units="frames"，所以第二个返回值是帧索引；在这个阶段不要把它误打印成秒。

import librosa

# 估算全局 BPM，并返回节拍所在的帧索引。
tempo, beats = librosa.beat.beat_track(
    y=y,
    sr=sr,
    hop_length=hop_length,
)

# 单声道输入的 tempo 在当前 API 中可能是单元素数组；统一取成普通浮点数便于记录。
tempo_value = float(tempo[0]) if getattr(tempo, "ndim", 0) else float(tempo)
print(f"tempo={tempo_value:.2f} BPM")
print(f"beat_frames={beats[:10]}")

官方 API 还允许传入预先计算好的 onset_envelope，也可以用 units="samples" 或 units="time" 改变事件位置的单位。默认的稀疏结果是一个事件索引数组；如果需要按每一帧保存布尔标记，可以设置 sparse=False。

把帧索引换成可用的秒数

更容易调试的方式是保留“帧结果”和“时间结果”两层数据。显式调用 frames_to_time 时，要把同一套 sr 和 hop_length 传进去；如果这些参数与节拍跟踪时不同，时间点就会出现系统性偏移。

# 用节拍跟踪时的同一组参数做帧到秒的换算。
beat_times = librosa.frames_to_time(
    beats,
    sr=sr,
    hop_length=hop_length,
)

# 只展示前几个事件，实际项目可以把完整数组写入时间轴或切片计划。
for index, seconds in enumerate(beat_times[:8], start=1):
    print(f"beat_{index}: {seconds:.3f}s")

如果你的下游只接受秒，也可以直接调用 beat_track(..., units="time")。我更倾向于在中间结果中保留帧索引，因为帧索引能和起音包络、频谱图的列直接对应；在最后一步再转换成秒，排错时更容易判断偏移来自算法还是单位换算。

结果为空或 BPM 为 0 时先看起音强度

官方文档明确说明：如果没有检测到起音强度，节拍跟踪会估算出 0 BPM 并返回空列表。遇到这个现象，不要先把 start_bpm 或 tightness 调成很大的数；先确认音频确实读到了有效样本，再检查起音包络是否有变化。

import numpy as np

# 先构造起音强度包络，观察输入是否包含可供节拍跟踪使用的变化。
onset_env = librosa.onset.onset_strength(
    y=y,
    sr=sr,
    hop_length=hop_length,
)

# 这些统计只用于判断“有没有信号”，不代表节拍检测已经正确。
finite = np.isfinite(onset_env)
print(f"frames={onset_env.size} finite={finite.all()}")
print(f"min={onset_env.min():.4f} max={onset_env.max():.4f}")

# 复用同一包络可以把问题分成“起音提取”与“节拍跟踪”两层。
tempo, beats = librosa.beat.beat_track(
    onset_envelope=onset_env,
    sr=sr,
    hop_length=hop_length,
)
print(f"detected_beats={len(beats)}")

onset_strength 默认从音频计算对数功率 Mel 频谱的谱流起音包络。若包络全为零、包含非有限值，或者输入音频过于安静，就应该先处理输入或确认音频内容，而不是把空结果包装成“没有节拍”。

三个最常见的偏移来源

第一，读取和换算使用了不同采样率。例如读取时使用 sr=22050，转换时却拿文件原始采样率计算，所有节拍都会按同一个比例偏移。把 sr 作为同一条处理链里的变量传递，最简单也最可靠。

第二，hop_length 没有保持一致。起音包络的列间距由 hop_length 决定，帧转秒时也要使用它。若为了绘图临时改了 hop length，却继续复用旧的帧数组，时间轴自然对不上。

第三，把估算结果当成精确标注。节拍跟踪是基于起音峰值与速度一致性的估算。弱拍、切分节奏、现场录音、变速和没有明显鼓点的片段都可能让结果落在邻近帧，必要时应把它作为初始候选，再结合业务规则或人工标注修正。

节拍结果怎样接到下游任务

如果只想在播放器或波形图上画竖线，直接使用 beat_times 即可；如果要按拍切片，建议先把时间点转换为单调递增的区间边界，并处理首尾不足一个拍子的片段；如果要做节拍同步，除了 BPM 还要保留第一拍的相位信息，不能只用平均速度推算整段音频。

工程上可以把结果记录为一个小对象：输入文件标识、sr、hop_length、估算 BPM、帧索引、秒数和算法参数。这样下一次换音频或换参数时，能明确知道两组节拍差异来自输入、参数还是估算本身。

常见问题

怎样让 beat_track 直接返回秒数？

在调用中传入 units="time"。如果还需要和频谱图或起音包络对齐，保留默认帧索引，再用 frames_to_time 转换通常更方便。

为什么同一段音频每次得到的 BPM 不同？

先检查音频读取、采样率、hop_length 和输入通道是否一致。若这些都一致，差异通常来自片段本身的弱起音、变速或全局速度并不唯一；不要只用一个 BPM 判断所有节拍事件。

多声道音频可以直接得到稀疏节拍数组吗？

官方接口对多声道输入的稀疏和密集返回形式有约束；如果需要保留多声道维度，应先按文档选择合适的 sparse 形式，或在进入节拍跟踪前明确合并策略。

结论：用 librosa 估算音频节拍位置时，先稳定输入采样率和 hop_length，再从 tempo、帧索引和秒数三个层面解释结果；遇到空数组或 BPM 为 0，先检查起音强度和输入数据，最后才调整节拍参数。