🚨 诚招维护者

该项目已经发展到超出一个人能够维护的规模。

由于时间限制，原作者已无法继续进行定期的代码审查。 我们正在寻找能够协助以下工作的贡献者：

• 代码审查
• 问题分类与处理
• 持续维护

如果您感兴趣，请在此议题下留言自我介绍。

nnAudio

nnAudio 是一个基于 PyTorch 卷积神经网络的音频处理工具箱。通过这种方式，可以在神经网络训练过程中实时生成频谱图，并且可以对傅里叶核（例如 CQT 核）进行训练。nnAudio 的详细信息请参阅我们的论文。您可以免费使用 nnAudio，但如果您使用该库，请按照下方提供的参考文献引用该论文。

Kapre 具有类似的概念，它也使用一维卷积神经网络来提取基于 Keras 的频谱图。其他 GPU 音频处理工具包括 torchaudio 和 tf.signal。然而，这些工具并未采用神经网络方法，因此无法训练傅里叶基。截至 PyTorch 1.6.0 版本，由于 sox 的原因，torchaudio 在 Windows 环境下的安装仍然非常困难。相比之下，nnAudio 更加兼容不同操作系统，因为它主要依赖于 PyTorch 卷积神经网络。nnAudio 这个名字来源于 torch.nn。

安装

pip install git+https://github.com/KinWaiCheuk/nnAudio.git#subdirectory=Installation

或者

pip install nnaudio==0.3.4

文档

https://kinwaicheuk.github.io/nnAudio/index.html

与其他库的比较

特性	nnAudio	torch.stft	kapre	torchaudio	tf.signal	torch-stft	librosa
可训练	✅	❌	✅	❌	❌	✅	❌
可微分	✅	✅	✅	✅	✅	✅	❌
线性频率 STFT	✅	✅	✅	✅	✅	✅	✅
对数频率 STFT	✅	❌	✅	❌	❌	❌	❌
逆 STFT	✅	✅	✅	✅	✅	✅	✅
Griffin-Lim	✅	❌	❌	✅	✅	❌	✅
Mel	✅	❌	✅	✅	✅	❌	✅
MFCC	✅	❌	❌	✅	✅	❌	✅
CQT	✅	❌	❌	❌	❌	❌	✅
VQT	✅	❌	❌	❌	❌	❌	✅
Gammatone	✅	❌	❌	❌	❌	❌	❌
CFP1	✅	❌	❌	❌	❌	❌	❌
GPU 支持	✅	✅	✅	✅	✅	✅	❌

✅: 完全支持 ☑️: 正在开发中（仅在开发版本中可用） ❌: 不支持

¹ 结合频谱与时域表示用于多音音乐的多音高估计

新闻与变更日志

要查看完整的变更日志，请访问 CHANGELOG.md

版本 0.3.1 (2021年12月24日):

1. 添加了 VQT 功能 #113

版本 0.3.0 (2021年11月19日):

1. 更改了模块命名。未来版本中，nnAudio.Spectrogram 将被 nnAudio.features 取代。目前，各种频谱图类型仍可通过两种方式访问。

如果您使用 nnAudio，请务必引用其论文

描述 nnAudio 发布的论文可在 IEEE Access 上找到。

K. W. Cheuk, H. Anderson, K. Agres 和 D. Herremans, “nnAudio：一个利用一维卷积神经网络实现 GPU 实时音频到频谱图转换的工具箱”，载于 IEEE Access，第 8 卷，第 161981–162003 页，2020 年，doi: 10.1109/ACCESS.2020.3019084。

BibTex

@ARTICLE{9174990,
  author={K. W. {Cheuk} and H. {Anderson} and K. {Agres} and D. {Herremans}},
  journal={IEEE Access}, 
  title={nnAudio：一个利用一维卷积神经网络实现 GPU 实时音频到频谱图转换的工具箱}, 
  year={2020},
  volume={8},
  number={},
  pages={161981-162003},
  doi={10.1109/ACCESS.2020.3019084}}

欢迎贡献

nnAudio 是一个快速发展的软件包。随着功能请求的不断增加，我们欢迎任何熟悉数字信号处理和神经网络的人士为 nnAudio 做出贡献。当前待办的功能列表包括：

1. 可逆常数 Q 变换 (CQT)

（单元测试小提示：进入 Installation 文件夹后，输入 pytest。要通过所有单元测试，至少需要 1931 MiB 的 GPU 内存）

此外，您也可以通过以下方式做出贡献：

1. 编写更好的演示代码或教程

依赖项

Numpy >= 1.14.5

Scipy >= 1.2.0

PyTorch >= 1.6.0（Griffin-Lim 仅在 1.6.0 及以上版本中可用）

Python >= 3.6

librosa = 0.7.0（理论上 nnAudio 依赖于 librosa。但我们只需要使用 librosa.filters 中的单个函数 mel。为了省去用户为这个单一函数安装 librosa 的麻烦，我直接将对应 mel 的函数片段复制到我的代码中，这样 nnAudio 就无需安装 librosa 也能运行）

其他类似库

Kapre

torch-stft

nnAudio 快速上手指南

nnAudio 是一个基于 PyTorch 卷积神经网络（CNN）的音频处理工具箱。它支持在 GPU 上实时将音频转换为频谱图，且其傅里叶核（如 STFT、CQT 等）是可训练的。相比 torchaudio 或 librosa，nnAudio 具有更好的跨平台兼容性（尤其在 Windows 上无需安装 sox），并支持更多可微分的音频特征提取功能。

环境准备

在使用 nnAudio 之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows, Linux, macOS (跨平台兼容性好)
• Python 版本：>= 3.6
• 核心依赖：
  • PyTorch >= 1.6.0 (若需使用 Griffin-Lim 功能)
  • Numpy >= 1.14.5
  • Scipy >= 1.2.0
• 硬件要求：
  • 支持 CUDA 的 GPU（推荐，用于加速计算）
  • 运行完整单元测试至少需要 1931 MiB 显存

注意：nnAudio 内部复用了 librosa 的部分旋律过滤函数，因此无需单独安装 librosa 即可直接使用。

安装步骤

您可以通过 PyPI 直接安装稳定版，或通过 GitHub 安装最新版。

方式一：通过 PyPI 安装（推荐）

pip install nnaudio==0.3.4

方式二：通过 GitHub 安装（获取最新代码）

pip install git+https://github.com/KinWaiCheuk/nnAudio.git#subdirectory=Installation

国内加速提示：如果下载速度较慢，建议使用国内镜像源（如清华源）：

pip install nnaudio==0.3.4 -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

nnAudio 的使用方式与 PyTorch 原生层非常相似。以下是一个最简单的示例，展示如何使用 STFT 层将音频波形转换为频谱图。

示例：提取线性频率 STFT 频谱图

import torch
from nnAudio import features

# 1. 初始化 STFT 层
# 参数可根据需求调整，此处使用默认配置
stft_layer = features.STFT(n_fft=2048, hop_length=512, win_length=2048)

# 2. 准备输入音频数据
# 假设 audio_waveform 形状为 [Batch_Size, Channels, Time_Steps]
# 这里创建一个随机张量作为示例：[1, 1, 16000] (1秒，16kHz)
audio_waveform = torch.randn(1, 1, 16000)

# 3. 将数据移至 GPU (可选，但推荐)
if torch.cuda.is_available():
    stft_layer = stft_layer.cuda()
    audio_waveform = audio_waveform.cuda()

# 4. 执行前向传播，生成频谱图
# 输出形状通常为 [Batch, Channels, Freq_Bins, Time_Frames]
spectrogram = stft_layer(audio_waveform)

print(f"输入形状：{audio_waveform.shape}")
print(f"输出频谱图形状：{spectrogram.shape}")

其他可用特征

除了 STFT，nnAudio 还支持多种可训练的特征提取层，只需替换类名即可：

• features.MelSpectrogram：梅尔频谱图
• features.CQT：常数 Q 变换
• features.MFCC：梅尔频率倒谱系数
• features.Gammatone：伽马通滤波器组
• features.VQT：可变 Q 变换

所有层均支持 .cuda() 加速，并且由于基于神经网络构建，这些操作都是可微分的，可以直接嵌入端到端的深度学习模型中进行反向传播训练。