librosa.filters 深入解析：Mel、Chroma、常Q小波基等滤波器组与窗函数工具

音频处理科研【免费下载链接】librosaPython library for audio and music analysis项目地址https://gitcode.com/gh_mirrors/li/librosa点击查看免费下载librosa.filters是 librosa 中负责滤波器组构建、窗函数处理及相关工具的模块是几乎所有谱类特征Mel 谱、Chroma、CQT、VQT、重复矩阵平滑背后的底层支撑。本篇围绕参考文档 docs/filters.rst 列出的全部公开 API——mel、chroma、wavelet、semitone_filterbank、window_bandwidth、get_window、wavelet_lengths、cq_to_chroma、mr_frequencies、window_sumsquare、diagonal_filter——逐一讲解其参数、默认值与源码实现要点并给出可直接运行的调用示例帮助你理解每种滤波器组的适用场景并正确配置参数。一、模块总览与缓存机制参考文档 docs/filters.rst 通过automodule与autosummary指令声明了该模块的文档骨架模块说明来自 librosa/filters.py 的 docstringlibrosa.filters provides functionality for filter bank construction, window function processing, and related utilities随后按功能分组列出 11 个公开函数。从源码结构看该模块有以下值得注意的设计特征分组清晰__all__中列出的 11 个公开 APIlibrosa/filters.py可分为四组线性滤波器组melMel 三角滤波器、chroma音高类滤波器、semitone_filterbank/mr_frequencies多速率 IIR 半音滤波器组时频小波基wavelet、wavelet_lengths是librosa.cqt与librosa.vqt的构建基础映射矩阵cq_to_chroma把常QCQT分音折叠到 12或 n个音高类窗函数工具get_window、window_bandwidth、window_sumsquare以及用于平滑自相似矩阵的diagonal_filter。结果缓存除semitone_filterbank外的公开函数均标注cache(level10)即结果按 level 10 级别缓存重复调用相同参数时直接命中缓存这对n_fft较大、构建开销高的滤波器组尤为明显缓存级别定义可参见 docs/cache.rst。依赖复用频率坐标转换全部复用librosa.core.convert中的fft_frequencies、hz_to_midi、hz_to_octs、mel_frequencies、midi_to_hz、note_to_hzlibrosa/filters.py保证滤波器组与其他特征函数使用同一套频率刻度。二、Mel 滤波器组librosa.filters.melmel(sr, n_fft, n_mels128, fmin0.0, fmaxNone, htkFalse, normslaney, dtypenp.float32)创建一个把 FFT 分音投影到 Mel 频率分音的线性变换矩阵librosa/filters.py。参数说明参数默认值说明sr必填输入信号的采样率n_fft必填FFT 帧长滤波器组共有1 n_fft // 2个频率分音n_mels128Mel 频带数量fmin0.0最低频率Hzfmaxsr / 2.0最高频率Hz为None时取奈奎斯特频率htkFalse使用 HTK 公式而非 Slaney 公式计算 Mel 刻度normslaney归一化方式slaney按频带宽度做面积归一化数字则按librosa.util.normalize做单位 l_p 范数None保持三角形峰值为 1.0dtypenp.float32输出数据类型返回值为形状(n_mels, 1 n_fft/2)的矩阵M通常与librosa.stft的幅度谱相乘得到 Mel 谱。实现要点librosa/filters.py用fft_frequencies(sr, n_fft)计算各 FFT 分音的中心频率用mel_frequencies(n_mels 2, ...)计算n_mels 2个 Mel 刻度端点对每个 Mel 频带通过ramps np.subtract.outer(mel_f, fftfreqs)外减构造上下斜坡再取np.maximum(0, np.minimum(lower, upper))得到截断三角形权重normslaney时按2.0 / (mel_f[2:] - mel_f[:n_mels])缩放使各通道近似恒定能量源自 Slaney 的做法若某些频带权重全零如n_mels太大、fmax太低会触发warnings.warn提示Empty filters detected in mel frequency basis建议提高采样率/fmax或减小n_mels。示例取自源码 docstring可直接运行import librosa # 基本用法128 个 Mel 频带 melfb librosa.filters.mel(sr22050, n_fft2048) # 将最高频率限制在 8 kHz melfb librosa.filters.mel(sr22050, n_fft2048, fmax8000) # 使用 2 范数归一化 melfb librosa.filters.mel(sr22050, n_fft2048, norm2) # 可视化 import matplotlib.pyplot as plt import librosa.display fig, ax plt.subplots() img librosa.display.specshow(melfb, x_axislinear, axax) ax.set(ylabelMel filter, titleMel filter bank) fig.colorbar(img, axax)对应的行为验证见 tests/test_filters.py 中的test_melfb参数化覆盖不同sr、n_fft、n_mels、fmin、fmax、htk、test_mel_norm归一化模式与test_mel_badnorm非法norm抛出ParameterError。三、Chroma 滤波器组librosa.filters.chromachroma(sr, n_fft, n_chroma12, tuning0.0, ctroct5.0, octwidth2, norm2, base_cTrue, dtypenp.float32)创建把 FFT 分音投影到音高类pitch class分音的线性变换矩阵librosa/filters.py。参数说明参数默认值说明sr必填音频采样率n_fft必填FFT 帧长滤波器组共1 n_fft // 2个分音n_chroma12音高分音数量如 24 表示四分之一音tuning0.0相对 A440 的调音偏差以音高分音的分数表示ctroct5.0倍频程主导窗的中心以八度为单位A0 27.5 Hzoctwidth2以ctroct为中心的高斯权重半宽设为None则各倍频程等权norm2每个滤波器的归一化因子base_cTrueTrue时滤波器组从 C 开始False时从 A 开始返回形状(n_chroma, 1 n_fft/2)的矩阵供librosa.feature.chroma_stft等函数使用。实现要点librosa/filters.py先用hz_to_octs(frequencies, tuningtuning, bins_per_octaven_chroma)把各 FFT 分音频率换算到以音高分音为单位的刻度0 Hz 分音则人为补一个低 1.5 个八度分音宽的值避免 0 频率处的奇异计算每个 FFT 分音与各音高类中心的周期距离D映射到[-n_chroma/2, n_chroma/2]以np.exp(-0.5 * (2*D/binwidthbins)**2)生成高斯峰形——即每个 FFT 分音按其局部分音宽度向最近的音高类倾倒权重octwidth非None时再乘以exp(-0.5 * ((frqbins/n_chroma - ctroct)/octwidth)**2)实现以ctroct倍频程为中心的高斯主导窗默认 5.0 倍频程附近权重最大即中频区主导最后按norm对列归一化base_cTrue时整体向左滚动3 * (n_chroma // 12)个分音使 C 落在第 0 行。示例docstring 原例# 常规 12 分音 chroma 滤波器组 chromafb librosa.filters.chroma(sr22050, n_fft4096) # 四分之一音24 分音 chroma_quarter librosa.filters.chroma(sr22050, n_fft4096, n_chroma24) # 各倍频程等权关闭主导窗 chroma_flat librosa.filters.chroma(sr22050, n_fft4096, octwidthNone)测试侧 tests/test_filters.py 的test_chroma_shape、test_chroma_norm、test_chroma_basec、test_chroma_tuning、test_chroma_ctroct、test_chroma_dtype分别验证了分音数、归一化、C/A 起始、调音偏差与主导窗中心对输出形状和数值的影响test_chroma_issue1295则验证了极低频率处的鲁棒性。四、小波基wavelet_lengths与wavelet4.1wavelet_lengths(freqs, sr22050, windowhann, filter_scale1, gamma0, alphaNone)返回小波基中每个滤波器的分数长度及截止频率librosa/filters.py输入freqs为升序的中心频率数组Hz每个滤波器的带宽为B[k] alpha[k] * freqs[k] gamma其中相对带宽alpha[k]由相邻频率中心差分推出alpha[k] (freqs[k1]-freqs[k-1]) / (freqs[k1]freqs[k-1])见内部函数_relative_bandwidthlibrosa/filters.py当freqs构成几何级数CQT、VQT 场景时alpha为常数gamma0默认使偶数与奇数滤波器交错恰好填满频谱空隙gammaNone时按 Glasberg Moore (1990) 的 ERB 模型推导gamma[k] 24.7 * alpha[k] / 0.108使带宽与听觉滤波器形状对齐Q filter_scale / alpha滤波器长度lengths Q * sr / (freqs gamma/alpha)即频率越高滤波器越短——这正是常Q变换对数频率刻度 恒定 Q的核心第二返回值f_cutoff为最高分音主瓣衰减 3 dB 前的最低截止频率librosa.cqt/librosa.vqt用它确保所有小波分音不越过奈奎斯特频率。参数校验上filter_scale 0、gamma 0、任一freqs 0、freqs非严格升序都会抛出ParameterErrorlen(freqs) 1时无法从频率数组推断带宽必须显式提供alpha。4.2wavelet(freqs, sr22050, windowhann, filter_scale1, pad_fftTrue, norm1, dtypenp.complex64, gamma0, alphaNone, **kwargs)在wavelet_lengths基础上逐滤波器构建时域复数正弦窗librosa/filters.pyfor ilen, freq in zip(lengths, freqs): sig util.phasor(np.arange(-ilen // 2, ilen // 2, dtypefloat) * 2 * np.pi * freq / sr) sig * __float_window(window)(len(sig)) # 加窗 sig util.normalize(sig, normnorm) # 归一化关键细节__float_window装饰器librosa/filters.py让窗函数支持分数长度ceil(x)长度输出、floor(x)之后的样本置零整数长度时行为不变filter_scale控制时频分辨率权衡小于 1 使用更短窗、时间分辨率更高pad_fftTrue默认把所有滤波器中心补零到最近的 2 的幂长度pad_fftFalse则只补到ceil(max_len)**kwargs会透传给np.pad以自定义补零模式返回(filters, lengths)filters[i]是第 i 个复数时域滤波器lengths为各滤波器的分数样本长度。示例构建一个 84 分音的常Q基并可视化一个八度freqs librosa.cqt_frequencies(n_bins84, fminlibrosa.note_to_hz(C1)) basis, lengths librosa.filters.wavelet(freqsfreqs, sr22050)参数化测试test_wavelettests/test_filters.py覆盖了不同sr、fmin、bins_per_octave、filter_scale、pad_fft、norm、gamma组合下的输出长度与数值正确性test_wavelet_lengths_badscale/badgamma/badfreqs/badfreqsorder/noalpha则验证了上述参数错误路径。五、CQT 到 Chroma 的线性映射cq_to_chromacq_to_chroma(n_input, *, bins_per_octave12, n_chroma12, fminNone, windowNone, base_cTrue, dtypenp.float32)构造把常Q分音折叠到音高分音的变换矩阵librosa/filters.pyn_input输入 CQT 分音数必须是n_chroma的整数倍否则抛出ParameterError(Incompatible CQ merge: ...)fmin第一个常Q通道的中心频率默认C1≈ 32.7 Hzwindow若提供输出矩阵会与该一维窗口做scipy.signal.convolve(..., modesame)卷积用于平滑相邻音高分音的折叠base_cTrue时第 0 个 chroma 分音为 CFalse时为 A——实现上通过hz_to_midi(fmin) % 12求出首分音的 MIDI 音级再按(n_chroma / 12.0)比例滚动行返回形状(n_chroma, n_input)的矩阵满足Chroma np.dot(cq_to_chroma, CQT)。示例docstring 原例y, sr librosa.load(trumpet) CQT np.abs(librosa.cqt(y, srsr)) chroma_map librosa.filters.cq_to_chroma(CQT.shape[0]) chromagram chroma_map.dot(CQT) chromagram librosa.util.normalize(chromagram, axis0)test_cq_to_chroma在多倍频程数、每八度分音数semitones、fmin、base_c、window的组合下验证了折叠矩阵的周期性与对齐关系。六、多速率 IIR 半音滤波器组mr_frequencies与semitone_filterbank这一组函数实现了 Müller《Information Retrieval for Music and Motion》(2007) 描述的半音滤波器组pitch filterbank常用于librosa.iirt等 IIR 时域滤波场景。6.1mr_frequencies(tuning0.0)生成中心频率与采样率配对librosa/filters.py中心频率取自midi_to_hz(np.arange(24 tuning, 109 tuning))即从 C0而非 MIDI 标准的 A0开始的 85 个十二平均律音高对应采样率按三段分配前 36 个滤波器用 8820 Hz、中间 34 个用 44100 Hz、后 15 个用 220500 Hz目的是让每个滤波器在其子带内保持相近的相对带宽多速率思想tuning以半音分数表示相对 A440 的偏差如 1/12 对应 A441 左右的常用乐队调音。6.2semitone_filterbank(*, center_freqsNone, tuning0.0, sample_ratesNone, flayoutba, **kwargs)基于scipy.signal.iirdesign构建多速率带通滤波器组librosa/filters.py若center_freqs与sample_rates都为None则自动调用mr_frequencies(tuning)生成默认配置对应 88 键钢琴键的基频十二平均律、A440 基准频率按 2^(1/12) 指数增长内部_multirate_fblibrosa/filters.py对每个分音按passband [f0 - 0.5*bw, f0 0.5*bw]、stopband [f0 - bw, f0 bw]bw f0 / Q调用iirdesign关键参数Q25.0品质因数决定滤波器带宽passband_ripple1dB通带最大纹波stopband_attenuation50dB阻带最小衰减ftypeellip默认椭圆EllipticIIR 设计可选butter、cheby1、cheby2flayoutba | sosba返回差分方程系数配scipy.signal.filtfilt高阶时可能不稳定sos返回二阶节配scipy.signal.sosfiltfilt数值更稳但更慢其余**kwargs如自定义Q、ftype透传给_multirate_fb。示例docstring 原例绘制 12 个半音滤波器的幅频响应import scipy.signal semitone_filterbank, sample_rates librosa.filters.semitone_filterbank( center_freqslibrosa.midi_to_hz(np.arange(60, 72)), sample_ratesnp.repeat(4410.0, 12), flayoutsos, ) for cur_sr, cur_filter in zip(sample_rates, semitone_filterbank): w, h scipy.signal.sosfreqz(cur_filter, fscur_sr, worN1025) magnitudes.append(20 * np.log10(np.abs(h)))注意semitone_filterbank本身不带cache缓存装饰器其内部_multirate_fb带 level 10 缓存重复调用时缓存收益来自内部函数。test_semitone_filterbank、test_semitone_filterbank_defaults、test_semitone_filterbank_layout验证了默认频率/采样率对、ba/sos两种输出的形状与滤波行为。七、窗函数工具get_window与window_bandwidth7.1get_window(window, Nx, *, fftbinsTrue)scipy.signal.get_window的封装额外支持可调用对象与预计算窗口librosa/filters.py。window支持五种形态形态行为字符串如hann窗函数名称元组如(kaiser, 4.0)名称 参数数值视为kaiser窗的 beta 参数与 scipy 一致可调用对象直接调用window(Nx)列表/数组预计算窗长度必须恰为Nx否则抛出ParameterError(Window size mismatch: ...)fftbinsTrue默认生成周期窗用于 FFTFalse生成对称窗用于滤波器设计。7.2window_bandwidth(window, n1000)返回窗函数的等效噪声带宽ENBW定义为Harris 1978, 式 11enbw n * sum(window**2) / sum(window)**2实现上librosa/filters.py内置WINDOW_BANDWIDTHS字典librosa/filters.py预存了 30 余种常见窗的带宽值例如boxcar/rect/ones 1.0、hann ≈ 1.500、hamming ≈ 1.363、blackman ≈ 1.727、nuttall ≈ 1.976、flattop ≈ 2.776且为不同别名如bart/bartlett/brt设置了同值映射字典中不存在的窗如自定义可调用窗会现场用n1000个系数估计并写回字典——test_window_bandwidth_dynamic/test_window_bandwidth_missing正是验证了这一动态估计路径ENBW 直接参与wavelet_lengths的f_cutoff计算f_cutoff max(freqs * (1 0.5 * window_bandwidth(window) / Q) 0.5 * gamma)因此窗函数的选择会影响常Q变换可用的最高分音。test_get_window/test_get_window_func/test_get_window_pre/test_get_window_fail覆盖了字符串、可调用对象、预计算窗及错误规格四类输入。八、窗能量包络window_sumsquarewindow_sumsquare(*, window, n_frames, hop_length512, win_lengthNone, n_fft2048, dtypenp.float32, normNone)计算给定跳长下窗函数的平方和包络librosa/filters.py用于估计 STFT 加窗引入的调制效应——若包络在信号内部趋于常数则幅度谱不会被窗的周期性起落调制。实现分两步get_window(window, win_length)取窗按norm归一化后平方再util.pad_center到n_fft长度numba 编译的内核__window_ss_filljit(nopythonTrue, cacheTrue)librosa/filters.py按hop_length步长把win_sq累加到长度为n_fft hop_length * (n_frames - 1)的零向量上输出即各样本被窗平方加权的总和。win_length缺省等于n_fft注意norm只影响窗的构造不影响随后的平方操作。示例比较不同 hop_length 的调制效应docstring 原例n_frames 50 wss_256 librosa.filters.window_sumsquare(windowhann, n_framesn_frames, hop_length256) wss_512 librosa.filters.window_sumsquare(windowhann, n_framesn_frames, hop_length512) wss_1024 librosa.filters.window_sumsquare(windowhann, n_framesn_frames, hop_length1024)从源码结构看librosa.feature.rms等按能量加权的特征内部即依赖类似的窗平方和做补偿因此该函数也是理解 STFT 特征归一化的一条线索。九、二维对角滤波器diagonal_filterdiagonal_filter(window, n, *, slope1.0, angleNone, zero_meanFalse)构建一个二维对角滤波器核主要用于平滑重复矩阵 / 自相似矩阵librosa/filters.pywindow非负窗函数同get_window规格构成一条对角线np.diag(get_window(window, n, fftbinsFalse))slope对角线斜率angle未给定时取angle arctan(slope)显式给angle弧度则忽略slope若非 45 度用scipy.ndimage.rotate将核旋转45 - angle*180/pi度5 次样条插值随后np.clip(win, 0, None)去除旋转产生的负瓣并归一化使总和为 1得到非负平均滤波器zero_meanTrue时减去均值得到零均值核——官方注释指出若要增强路径、抑制块即突出时间偏移一致的重复片段应启用此项。返回形状(m, m)的核可直接用于scipy.ndimage.convolve等卷积平滑。test_diagonal_filter参数化了n、window、angle、slope、zero_mean的组合。十、参数配置速查与测试入口综合上述讲解日常使用时的关键配置决策目标函数关键参数决策Mel 频谱meln_mels128语音/哼唱类信号可设fmax8000截断高频能量均衡用默认normslaney音高类特征chroma默认ctroct5.0, octwidth2聚焦中频需要全倍频程平权时octwidthNone非标准调音设tuning常Q/变Q基waveletfilter_scale1换更高时间分辨率gammaNone采用 ERB 听觉带宽CQT 折叠cq_to_chroman_input必须是n_chroma整数倍fmin需与实际 CQT 起点一致时域半音滤波semitone_filterbank高阶时优先flayoutsos非 A440 调音用tuning以半音分数计窗行为分析window_bandwidth/window_sumsquareENBW 决定小波截止频率hop_length 越小包络越平坦重复结构平滑diagonal_filter突出重复路径用zero_meanTrue非 1:1 对齐场景设slope/angle模块级行为缓存、参数校验、数值正确性由 tests/test_filters.py 的 40 余个测试用例系统覆盖可作为参数语义的第二手依据。所有公开函数除semitone_filterbank外均带cache(level10)在特征管线中反复构建同一滤波器组时可获得直接命中缓存的性能收益需要说明的是缓存命中依赖参数完全一致且默认dtype下输出为单精度滤波器组或复数单精度wavelet如需更高精度请显式指定dtype。赞分享音频处理科研【免费下载链接】librosaPython library for audio and music analysis项目地址https://gitcode.com/gh_mirrors/li/librosa点击查看免费下载相关推荐深入理解Mel滤波器组音乐可视化的核心技术深入理解Mel滤波器组音乐可视化的核心技术 Mel滤波器组是音乐可视化项目中的核心技术它能够将音频信号转换为人耳感知更自然的频谱表示。在audio reac音频处理智能硬件嵌入式Maths, CS AI Compendium数字信号处理全解——从声波、采样与 FFT 到 Mel 滤波器组与 MFCC 特征管线Maths, CS AI Compendium数字信号处理全解——从声波、采样与 FFT 到 Mel 滤波器组与 MFCC 特征管线 本文为《Maths,文档教程知识库上一篇推荐开源项目futures-signals - 零成本FRP信号库下一篇codelibrary高级匹配算法匈牙利算法与一般图匹配创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考