madmom: A Python MIR Library With Two Licences and a 2018 Release Tag

The problem madmom addresses: MIR algorithms that usually exist only as papers

Music information retrieval has a reproducibility problem. A paper describes a beat tracker or an onset detector, the authors publish MATLAB or unversioned Python, and nobody can rerun it. madmom exists to package a set of those algorithms as importable Python modules with pretrained models attached. The README describes it as an audio signal processing library "with a strong focus on music information retrieval (MIR) tasks" and states that it includes reference implementations for some MIR algorithms. The intended audience is narrow and identifiable: researchers and engineers who need onset detection, beat tracking or similar tasks and want a working baseline rather than a from-scratch implementation. The README names the two institutions that use it internally, the Department of Computational Perception at Johannes Kepler University in Linz and the Austrian Research Institute for Artificial Intelligence in Vienna. That origin explains the shape of the project. It is a research group's toolkit that was published, not a product with a roadmap.

Package layout: audio, features, ml, models and the Cython boundary

The repository splits into folders with clear responsibilities, and the README documents each one. /madmom/audio holds low level features such as audio file handling and the STFT. /madmom/features holds higher level features such as onsets and beats. /madmom/ml holds machine learning components, described as RNNs and HMMs. /madmom/utils covers MIDI and general file handling, /madmom/evaluation holds evaluation code, and /tests holds tests. The pretrained model files live outside the main tree, referenced in the README as /madmom/models and pulled in as a Git submodule pointing at a separate madmom_models repository. That split is the single most important structural fact about the project, because it is also the licence boundary. The package itself is Python, but the topics list includes Cython, and the README confirms it: the prerequisites require Cython, and the source upgrade path says that if any .pyx or .pxd files changed you must recompile with python setup.py build_ext --inplace. So part of the signal processing is compiled, not pure Python. Installing from PyPI hides that step; working from source exposes it, and it means a C toolchain is part of your build environment whether or not the README lists it as a prerequisite.

Installation: pip for users, a recursive clone for developers

The README is explicit that you should not install from the .zip files GitHub provides. Two supported paths exist. For users, pip install madmom, optionally with --user for a local install. The README notes that pip will also place the executable programs somewhere on your PATH, typically /usr/local/bin, and warns that a --user install puts them in a location that may not be on your PATH, giving ~/Library/Python/2.7/bin on macOS and ~/.local/bin on Ubuntu as examples, with export PATH='path/to/scripts':$PATH as the fix. For developers, the clone must be recursive because the models are a submodule: git clone --recursive https://github.com/CPJKU/madmom.git, or the equivalent three-step sequence of clone, cd, and git submodule update --init --remote. Development installs use python setup.py develop --user, and the test suite runs through python setup.py pytest. Prerequisites are Python 2.7 or 3.5+, numpy, scipy, Cython and mido. Optional additions are pytest for testing, pyaudio for live audio input, and pyfftw for improved FFT performance. Audio format support beyond .wav at 44.1 kHz and 16 bit requires ffmpeg, and the README specifically advises against avconv on Ubuntu because of decoding bugs. It also warns that outdated numpy, scipy or Cython versions can produce "unexpected errors or false computations", which is a stronger statement than the usual version-pin boilerplate and worth taking literally.

The executable programs and their single and batch modes

Beyond the library API, madmom ships command line programs in /bin. The README shows the invocation pattern DBNBeatTracker single [-o OUTFILE] INFILE, and states that all scripts run in two modes: single file mode, which processes one audio file and writes to STDOUT or a named output file, and batch mode, which processes multiple files and writes each output to its own file. The README text is truncated mid-sentence at the batch mode description, so the exact batch flag is not visible in the supplied material. That matters for evaluation: the CLI is the easiest way to check whether the package works on your audio before committing to it, but you will need the online documentation at madmom.readthedocs.io to get the full argument set. The naming convention is worth noting too. The example program is called DBNBeatTracker, which tells you the beat tracker is built on a dynamic Bayesian network, consistent with the ml folder's HMM components. These are not thin wrappers around a single neural network; the architecture mixes learned models with probabilistic sequence decoding.

Two licences, and the one that decides commercial use

This is the part most teams get wrong. madmom is not a single-licence project. The README states that unless indicated otherwise, all source code files are published under the BSD licence, and that unless indicated otherwise, all model and data files are distributed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0. The README then adds that if you want to include any of these files, a variation or modification of them, or technology which utilises them in a commercial product, you should contact Gerhard Widmer. The word "utilises" is doing a lot of work in that sentence. It suggests the restriction is not limited to redistributing the model files themselves; a commercial product that runs inference through those models may fall inside the stated scope. The repository metadata reports the licence as NOASSERTION, which is consistent with a project that has two licences and no single SPDX identifier for the whole thing. I am not giving legal advice here, and the README's own instruction is to make contact rather than to interpret. The practical consequence is that madmom's BSD label is misleading if you stop reading at the top-level licence field. The models are where the trained value sits, and they carry a non-commercial condition plus a share-alike obligation.

Release cadence and the maintenance question

The most recent tagged release is v0.16.1, dated 2018-11-14. Before that, v0.16 on 2018-11-13 and v0.15.1 on 2017-07-07. The repository's last push is 2026-03-20, so commits are still landing on main, but no release has been tagged in roughly seven years. Those two facts are not contradictory and both matter. Ongoing commits suggest someone is keeping the code alive against newer Python and numpy versions. The absence of releases means there is no versioned artifact that certifies that work, and no changelog entry you can point at when something breaks. For a team pinning dependencies, that is an awkward position: you either pin to a 2018 sdist and accept whatever bit rot has accumulated, or you install from a moving main branch with no release boundary. The README's upgrade instructions assume releases exist. It tells you to check the CHANGELOG when programs or models change, and to uninstall and reinstall rather than upgrade in place in that case. That guidance is sound but presupposes a release process that the tag history does not show. Treat the source repository, not PyPI, as the thing you are actually depending on.

Where madmom is the wrong tool, and what to use instead

madmom is a poor fit when your task is general audio classification rather than music-specific analysis, or when you need a maintained release cadence with published compatibility guarantees. It is also a poor fit if you cannot ship the pretrained models, since the algorithms are only useful with weights attached and the weights are the non-commercial part. The clearest alternative is librosa, and the difference is architectural rather than a matter of quality. librosa is a pure-Python analysis library built on numpy and scipy that gives you the building blocks: STFT, mel spectrograms, chroma, tempo estimation, onset strength. It does not ship pretrained task models for beat tracking or downbeat detection, and it does not bundle a dynamic Bayesian network decoder. madmom goes the other way. It packages complete task pipelines with models and sequence decoding included, which is why its install pulls Cython, mido, and optionally pyfftw and pyaudio, and why its model files are a separate licensed submodule. If you want primitives to build your own pipeline, librosa's approach fits better. If you want a reference implementation of a published MIR algorithm to compare against, madmom's approach is the one that gives you something runnable. Choosing between them is really choosing whether you want components or finished tasks.

Who should adopt madmom, and what to check before you do

Adopt it for academic work, for reproducing published MIR results, or for internal prototyping where the non-commercial model licence is not a constraint. The CLI in /bin gives you a fast way to confirm the package runs on your audio before you write any code, and the folder split makes it straightforward to import only the layer you need. Do not adopt it if you need a commercially shippable beat tracker, if you require tagged releases with dated changelogs, or if your audio is not 44.1 kHz 16-bit wav and you are unwilling to install and depend on ffmpeg. Before committing, verify four concrete things. Confirm ffmpeg decodes your file formats, avoiding avconv as the README advises. Confirm your numpy, scipy and Cython versions satisfy requirements.txt, since the README warns that stale versions cause false computations rather than clean errors. Confirm whether you are installing from PyPI or from a recursive clone, because the model submodule only arrives with the latter. And confirm with your legal contact whether the phrase "technology which utilises them" in the model licence reaches your use case, since that is the sentence that determines whether this library is BSD or non-commercial for you.

Editorial conclusion

Adopt madmom if you need reference implementations of MIR algorithms (beat tracking, onset detection) in Python and can live with a 2018 release tag, a Cython build step, and model files under CC BY-NC-SA 4.0. Do not adopt it for a commercial product that ships the pretrained models without contacting Gerhard Widmer as the README instructs, and do not adopt it if you expect active tagged releases. Verify three things first: that ffmpeg is installed if you need anything beyond 44.1 kHz 16-bit wav, that pyfftw is present if FFT throughput matters to you, and that your dependency pins in requirements.txt still resolve against numpy, scipy and Cython versions current in 2026.

Official sources

1. CPJKU/madmom on GitHub
2. Issues
3. Project website
4. README
5. Releases