Skip to main content

Python audio signal processing library

Project description

Madmom is an audio signal processing library written in Python.

The library is used internally by the Department of Computational Perception, Johannes Kepler University, Linz, Austria ( and the Austrian Research Institute for Artificial Intelligence (OFAI), Vienna, Austria (

Possible acronyms are:

  • Madmom Analyzes Digitized Music Of Musicians

  • Mostly Audio / Dominantly Music Oriented Modules

It includes reference implementations for some music information retrieval algorithms, please see the References section.


The package has two licenses, one for source code and one for model/data files.

Source code

Unless indicated otherwise, all source code files are published under the BSD license. For details, please see the LICENSE file.

Model and data files

Unless indicated otherwise, all model and data files are distributed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 license.

If you want to include any of these files (or a variation or modification thereof) or technology which utilises them in a commercial product, please contact Gerhard Widmer.



To install the madmom package, you must have Python version 2.7 and the following packages installed:

If you need support for audio files other than .wav with a sample rate of 44.1kHz and 16 bit depth, you need ffmpeg (or avconv on Ubuntu Linux).

Please refer to the requirements.txt file for the minimum required versions and make sure that these modules are up to date, otherwise it can result in unexpected errors or false computations!

Install from package

The easiest way to install the package is via pip from the PyPI (Python Package Index):

pip install madmom

This includes the latest code and trained models and will install all dependencies automatically. It will also install the executable scripts to a common place (e.g. /usr/local/bin) which should be in your $PATH already. pip will output the install location.

You might need higher privileges (use su or sudo) to install the package, model files and scripts globally. Alternatively you can install the package locally (i.e. only for you) by adding the --user argument:

pip install –user madmom

Depending on your platform, the scripts will be copied to a folder which might not be included in your $PATH (e.g. ~/Library/Python/2.7/bin on Mac OS X or ~/.local/bin on Ubuntu Linux), so please call the scripts directly or add their path to your $PATH environment variable:

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

Install from source

If you plan to use the package as a developer, cloning the Git repository is the best option, e.g.:

git clone

Since the pre-trained model/data files are not included in this repository but rather added as a Git submodule, you either have to clone the repo recursively:

git clone –recursive

or init the submodule and fetch the data manually:

cd /path/to/madmom

git submodule update –init –remote

You can then build and install this package by running:

python build

python install

You might need higher privileges (use su or sudo) to install the files to a common place like /usr/local or similar. Alternatively you can install the package locally by adding the --user argument:

python install –user

To run the included tests:

python test

Install for development

If you want to actively work on the package, please follow the git cloning instructions from the Install from source section.

You can then either include the package directory in your $PYTHONPATH, e.g. by the following command (if your are in the directory containing this README file):


or you can install the package in development mode:

python develop

If you are not using the development variant or if you change any .pyx or .pxd files, you have to (re-)compile some modules with Cython. To do so, please run:

python build_ext –inplace

Again, you can install the package locally by adding the --user argument:

python develop –user

To run the included tests:

python test

Package structure

The package has a very simple structure, divided into the following folders:


this folder includes example programs (i.e. executable algorithms)


the actual Python package


low level features (e.g. audio file handling, STFT)


evaluation code


higher level features (e.g. onsets, beats)


machine learning stuff (e.g. RNNs, HMMs)


pre-trained model/data files (see the License section)


misc stuff (e.g. MIDI and general file handling)



Almost all low level features (i.e. everything under /madmom/audio) are divided into a data class and a corresponding processor class. The data class refers always to a certain instance (e.g. the STFT of an audio file), whereas the processor classes are used to define processing chains through which the audio is processed (i.e. most stuff in /madmom/features).

Executable programs

The package includes executable programs in the /bin folder. If you installed the package, they were copied to a common place.

All scripts can be run in different modes: in single file mode to process a single audio file and write the output to STDOUT or the given output file.

SuperFlux single [-o OUTFILE] INFILE

If multiple audio files should be processed, the scripts can also be run in batch mode to write the outputs to files with the given suffix.


If no output directory is given, the program writes the output files to same location as the audio files.

The pickle mode can be used to store the used parameters to be able to exactly reproduce experiments.

Please note that the program itself as well as the modes have help messages:

SuperFlux -h

SuperFlux single -h

SuperFlux batch -h

SuperFlux pickle -h

will give different help messages.


Although we try to keep the API stable, the features are considered work in progress and thus can change without prior notice. Do NOT expect these to stay the same forever! If you need stable features, clone or fork this project, set the parameters accordingly and/or pickle the processors.

Additional resources

Mailing list

The mailing list should be used to get in touch with the developers and other users. Please ask any questions there before opening an issue.


The wiki can be found here:


Frequently asked questions can be found here:


Issue tracker

If you find any bugs, please check if it is a known issue. If not, please try asking on the mailing list first, before opening a new issue.

Fork the project

Please feel encouraged to fork this project, fix bugs, add new features, enhance documentation or contribute to this project in any other way. Pull requests are welcome!


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

madmom-0.12.1.tar.gz (3.8 MB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page