====== madmom

Madmom 是一个用 Python 编写的音频信号处理库，主要专注于音乐信息检索（MIR）任务。

该库由奥地利林茨约翰内斯·开普勒大学计算感知系（http://www.cp.jku.at）和维也纳奥地利人工智能研究所（OFAI，http://www.ofai.at）内部使用。

可能的缩写包括：

• Madmom 分析音乐家的数字化音乐
• 主要面向音频/以音乐为主的模块

它包含一些音乐信息检索算法的参考实现，请参阅 References_ 部分。

文档

该软件包的文档可以在在线找到 http://madmom.readthedocs.org

许可证

该软件包有两种许可证，一种用于源代码，另一种用于模型/数据文件。

源代码

除非另有说明，所有源代码文件均采用 BSD 许可证发布。详情请参阅 LICENSE <LICENSE>_ 文件。

模型和数据文件

除非另有说明，所有模型和数据文件均采用 知识共享署名-非商业性使用-相同方式共享 4.0 <http://creativecommons.org/licenses/by-nc-sa/4.0/legalcode>_ 许可证进行分发。

如果您希望在商业产品中包含这些文件（或其变体、修改版）或利用它们的技术，请联系 Gerhard Widmer <http://www.cp.jku.at/people/widmer/>_。

安装

请勿尝试从 GitHub 提供的 .zip 文件进行安装。建议您按照以下说明，通过软件包（仅需使用时）或源代码（计划开发时）进行安装。无论选择哪种方式，请确保已安装所有先决条件。

先决条件

要安装 madmom 软件包，您必须拥有 Python 2.7 或 Python 3.5 及以上版本，并安装以下软件包：

• numpy <http://www.numpy.org>_
• scipy <http://www.scipy.org>_
• cython <http://www.cython.org>_
• mido <https://github.com/olemb/mido>_

为了测试您的安装、处理实时音频输入或提升 FFT 性能，还需额外安装以下软件包：

• pytest <https://www.pytest.org/>_
• pyaudio <http://people.csail.mit.edu/hubert/pyaudio/>_
• pyfftw <https://github.com/pyFFTW/pyFFTW/>_

如果您需要支持除 .wav 格式之外的其他音频文件，且采样率为 44.1kHz、位深度为 16 位，则需要 ffmpeg（Ubuntu Linux 上的 avconv 存在一些解码错误，因此不建议使用！）。

请参阅 requirements.txt <requirements.txt>_ 文件，了解所需的最低版本，并确保这些模块均为最新版本，否则可能导致意外错误或计算结果不准确！

通过软件包安装

此处提供的说明适用于仅需安装软件包的情况，例如运行附带的程序或将部分功能用于自己的项目。如果您打算对 madmom 软件包进行任何更改，请遵循下一节中的步骤。

最简单的安装方式是通过 PyPI (Python 包索引) <https://pypi.python.org/pypi>_ 使用 pip 命令进行安装：

pip install madmom

这将包含最新的代码和训练好的模型，并自动安装所有依赖项。

您可能需要更高的权限（使用 su 或 sudo）才能将软件包、模型文件和脚本全局安装。或者，您也可以通过添加 --user 参数将其本地安装（即仅供您使用）：

pip install --user madmom

这也会将可执行程序安装到一个公共位置（如 /usr/local/bin），通常该路径已经包含在您的 $PATH 中。如果您是本地安装，程序可能会被复制到一个未包含在 $PATH 中的文件夹（例如，在 Mac OS X 上可能是 ~/Library/Python/2.7/bin，而在 Ubuntu Linux 上则是 ~/.local/bin，pip 会提示您）。因此，您需要显式调用这些程序，或者将它们的安装路径添加到您的 $PATH 环境变量中：

export PATH='path/to/scripts':$PATH

通过源代码安装

如果您计划以开发者身份使用该软件包，请克隆 Git 仓库：

git clone --recursive https://github.com/CPJKU/madmom.git

由于预训练的模型/数据文件并未包含在该仓库中，而是作为 Git 子模块添加，因此您必须递归地克隆仓库。这等同于以下步骤：

git clone https://github.com/CPJKU/madmom.git
cd madmom
git submodule update --init --remote

然后您可以直接以开发模式安装软件包：

python setup.py develop --user

要运行附带的测试：

python setup.py pytest

现有安装的升级

要升级软件包，请使用与安装时相同的机制（pip 或源代码）。如果您想从软件包切换到源代码，请先卸载软件包。

升级软件包

只需通过 pip 升级软件包即可：

    pip install --upgrade madmom [--user]

如果其中一些提供的程序或模型发生了变化（请参阅 CHANGELOG），您应该先卸载软件包，再重新安装：

    pip uninstall madmom
    pip install madmom [--user]

从源代码升级

只需拉取最新的源代码：

git pull

要更新子模块中包含的模型：

git submodule update

如果任何 .pyx 或 .pxd 文件发生了变化，您需要使用 Cython 重新编译这些模块：

python setup.py build_ext --inplace

软件包结构

该软件包结构非常简单，分为以下几个文件夹：

/bin <bin>_ 该文件夹包含示例程序（即可执行算法） /docs <docs>_ 软件包文档 /madmom <madmom>_ 实际的 Python 软件包 /madmom/audio <madmom/audio>_ 低级特征（例如音频文件处理、STFT） /madmom/evaluation <madmom/evaluation>_ 评估代码 /madmom/features <madmom/features>_ 高级特征（例如起始点、节拍） /madmom/ml <madmom/ml>_ 机器学习相关内容（例如 RNN、HMM） /madmom/models <../../../madmom_models>_ 预训练的模型/数据文件（详见许可证部分） /madmom/utils <madmom/utils>_ 其他工具（例如 MIDI 和通用文件处理） /tests <tests>_ 测试

可执行程序

该软件包在 /bin <bin>_ 文件夹中包含可执行程序。如果您已安装软件包，这些程序已被复制到一个公共位置。

所有脚本均可在不同模式下运行：在 single 文件模式下，可处理单个音频文件并将输出写入 STDOUT 或指定的输出文件：

DBNBeatTracker single [-o OUTFILE] INFILE

如果需要处理多个音频文件，也可以以batch模式运行脚本，将输出写入带有指定后缀的文件中：

DBNBeatTracker batch [-o OUTPUT_DIR] [-s OUTPUT_SUFFIX] FILES

如果没有指定输出目录，程序会将输出文件保存到与音频文件相同的目录中。

某些程序还可以在online模式下运行，即对实时音频信号进行处理。这需要安装pyaudio <http://people.csail.mit.edu/hubert/pyaudio/>_：

DBNBeatTracker online [-o OUTFILE] [INFILE]

使用pickle模式可以保存所使用的参数，以便精确地重现实验。

请注意，程序本身以及各个模式都提供了帮助信息：

DBNBeatTracker -h

DBNBeatTracker single -h

DBNBeatTracker batch -h

DBNBeatTracker online -h

DBNBeatTracker pickle -h

这些命令会分别显示不同的帮助信息。

附加资源

邮件列表

请使用邮件列表 <https://groups.google.com/d/forum/madmom-users>_ 与开发者及其他用户取得联系。

维基

维基页面地址为：https://github.com/CPJKU/madmom/wiki

常见问题解答

常见问题解答请参见：https://github.com/CPJKU/madmom/wiki/FAQ

引用

如果您在工作中使用了madmom，请考虑对其进行引用：

.. code-block:: latex

@inproceedings{madmom, Title = {{madmom: 一个全新的 Python 音频与音乐信号处理库}}, Author = {B{"o}ck, Sebastian 和 Korzeniowski, Filip 和 Schl{"u}ter, Jan 和 Krebs, Florian 和 Widmer, Gerhard}, Booktitle = {第24届 ACM 国际多媒体大会论文集}, Month = {10}, Year = {2016}, Pages = {1174--1178}, Address = {阿姆斯特丹，荷兰}, Doi = {10.1145/2964284.2973795} }

参考文献

.. [1] Florian Eyben、Sebastian Böck、Björn Schuller 和 Alex Graves， 基于双向长短时记忆神经网络的通用节拍检测， 第11届国际音乐信息检索会议（ISMIR）论文集，2010年。 .. [2] Sebastian Böck 和 Markus Schedl， 利用上下文感知神经网络增强节拍跟踪， 第14届数字音频效果会议（DAFx）论文集，2011年。 .. [3] Sebastian Böck 和 Markus Schedl， 利用循环神经网络进行复音钢琴音符转录， 第37届国际声学、语音与信号处理会议（ICASSP）论文集，2012年。 .. [4] Sebastian Böck、Andreas Arzt、Florian Krebs 和 Markus Schedl， 利用循环神经网络实现在线实时节拍检测， 第15届数字音频效果会议（DAFx）论文集，2012年。 .. [5] Sebastian Böck、Florian Krebs 和 Markus Schedl， 评估节拍检测方法的在线能力， 第13届国际音乐信息检索会议（ISMIR）论文集，2012年。 .. [6] Sebastian Böck 和 Gerhard Widmer， 用于节拍检测的最大值滤波器颤音抑制， 第16届数字音频效果会议（DAFx）论文集，2013年。 .. [7] Sebastian Böck 和 Gerhard Widmer， 基于局部群延迟的颤音和震音抑制用于节拍检测， 第13届国际音乐信息检索会议（ISMIR）论文集，2013年。 .. [8] Florian Krebs、Sebastian Böck 和 Gerhard Widmer， 用于音乐音频中节拍和强拍跟踪的节奏模式建模， 第14届国际音乐信息检索会议（ISMIR）论文集，2013年。 .. [9] Sebastian Böck、Jan Schlüter 和 Gerhard Widmer， 利用循环神经网络改进节拍检测中的峰值提取， 第6届机器学习与音乐国际研讨会（MML）论文集，2013年。 .. [10] Sebastian Böck、Florian Krebs 和 Gerhard Widmer， 一种考虑异质音乐风格的多模型节拍跟踪方法， 第15届国际音乐信息检索会议（ISMIR）论文集，2014年。 .. [11] Filip Korzeniowski、Sebastian Böck 和 Gerhard Widmer， 从节拍激活函数中概率性提取节拍位置， 第15届国际音乐信息检索会议（ISMIR）论文集，2014年。 .. [12] Sebastian Böck、Florian Krebs 和 Gerhard Widmer， 基于循环神经网络和共振梳状滤波器的准确节拍速度估计， 第16届国际音乐信息检索会议（ISMIR）论文集，2015年。 .. [13] Florian Krebs、Sebastian Böck 和 Gerhard Widmer， 用于联合节拍和拍号跟踪的有效状态空间模型， 第16届国际音乐信息检索会议（ISMIR）论文集，2015年。 .. [14] Sebastian Böck、Florian Krebs 和 Gerhard Widmer， 利用循环神经网络进行联合节拍和强拍跟踪， 第17届国际音乐信息检索会议（ISMIR）论文集，2016年。 .. [15] Filip Korzeniowski 和 Gerhard Widmer， 用于和弦识别的特征学习：深度色度提取器， 第17届国际音乐信息检索会议（ISMIR）论文集，2016年。 .. [16] Florian Krebs、Sebastian Böck、Matthias Dorfer 和 Gerhard Widmer， 利用节拍同步特征和循环网络进行强拍跟踪， 第17届国际音乐信息检索会议（ISMIR）论文集，2016年。 .. [17] Filip Korzeniowski 和 Gerhard Widmer， 用于音乐和弦识别的全卷积深度听觉模型， IEEE 国际信号处理机器学习研讨会（MLSP）论文集，2016年。 .. [18] Filip Korzeniowski 和 Gerhard Widmer， 不分流派的调性分类，基于卷积神经网络， 第19届国际音乐信息检索会议（ISMIR）论文集，2018年。 .. [19] Rainer Kelz、Sebastian Böck 和 Gerhard Widmer， 深度复音 ADSR 钢琴音符转录， 第44届国际声学、语音与信号处理会议（ICASSP）论文集，2019年。

致谢

本项目得到了欧盟委员会通过GiantSteps 项目 <http://www.giantsteps-project.eu>（FP7 资助协议编号 610591）和Phenicx 项目 <http://phenicx.upf.edu>（FP7 资助协议编号 601166）的支持，以及奥地利科学基金会（FWF）项目 Z159 的资助。

madmom 快速上手指南

madmom 是一个专注于音乐信息检索（MIR）任务的 Python 音频信号处理库，由奥地利约翰内斯·开普勒大学计算感知系开发。它提供了节拍跟踪、起始点检测、节奏分析等算法的参考实现。

环境准备

在开始安装之前，请确保您的系统满足以下要求：

系统要求

• Python 版本：Python 2.7 或 Python 3.5 及以上版本
• 操作系统：支持 Linux, macOS, Windows

前置依赖

必须安装以下核心依赖包：

• numpy
• scipy
• cython
• mido

可选依赖（用于测试、实时音频输入或提升性能）：

• pytest (运行测试)
• pyaudio (处理实时音频流)
• pyfftw (提升 FFT 计算性能)
• ffmpeg (支持除 .wav 以外的更多音频格式，注意：Ubuntu 用户请勿使用 avconv，因其存在解码 bug)

提示：国内用户建议使用清华源或阿里源加速 pip 安装，例如在命令后添加 -i https://pypi.tuna.tsinghua.edu.cn/simple。

安装步骤

推荐通过 pip 进行安装，这将自动获取最新代码、预训练模型及所有依赖。

方法一：全局安装（需要管理员权限）

pip install madmom

方法二：用户本地安装（推荐，无需 sudo）

如果您没有 root 权限，或希望仅在当前用户环境下安装：

pip install --user madmom

注意：本地安装后，可执行脚本可能位于 ~/.local/bin (Linux) 或 ~/Library/Python/x.x/bin (macOS)。如果提示命令未找到，请将上述路径添加到您的 $PATH 环境变量中。

方法三：源码安装（开发者模式）

如果您计划修改源码或参与开发：

git clone --recursive https://github.com/CPJKU/madmom.git
cd madmom
python setup.py develop --user

注：--recursive 参数至关重要，因为预训练模型是通过 Git 子模块管理的。

基本使用

安装完成后，您可以直接使用内置的可执行程序。madmom 支持三种主要运行模式：

1. 单文件处理模式 (single)

处理单个音频文件并将结果输出到终端或指定文件。以下示例展示如何使用深度信念网络（DBN）进行节拍追踪：

DBNBeatTracker single audio_file.wav

将结果保存到新文件：

DBNBeatTracker single -o beats.txt audio_file.wav

2. 批量处理模式 (batch)

一次性处理多个音频文件，结果将保存为同名但带有特定后缀的文件：

DBNBeatTracker batch *.wav

指定输出目录和后缀：

DBNBeatTracker batch -o ./results -s .beats *.wav

3. 实时在线模式 (online)

对实时音频信号进行处理（需预先安装 pyaudio）：

DBNBeatTracker online

按 Ctrl+C 停止处理。

查看帮助

任何命令均可通过 -h 参数查看详细用法和可用选项：

DBNBeatTracker -h
DBNBeatTracker single -h

---

如需在商业产品中使用 madmom 的模型或数据文件，请联系作者获取授权。学术引用请参考项目文档中的 Citation 部分。