Python audio signal processing library
Madmom is an audio signal processing library written in Python with a strong focus on music information retrieval (MIR) tasks.
The library is internally used by the Department of Computational Perception, Johannes Kepler University, Linz, Austria (http://www.cp.jku.at) and the Austrian Research Institute for Artificial Intelligence (OFAI), Vienna, Austria (http://www.ofai.at).
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.
Documentation of the package can be found online http://madmom.readthedocs.org
The package has two licenses, one for source code and one for model/data files.
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.
Please do not try to install from the .zip files provided by GitHub. Rather install it from package (if you just want to use it) or source (if you plan to use it for development) by following the instructions below. Whichever variant you choose, please make sure that all prerequisites are installed.
To install the madmom package, you must have either Python 2.7 or Python 3.3 or newer 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 (avconv on Ubuntu Linux has some decoding bugs, so we advise not to use it!).
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 instructions given here should be used if you just want to install the package, e.g. to run the bundled programs or use some functionality for your own project. If you intend to change anything within the madmom package, please follow the steps in the next section.
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.
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
This will also install the executable programs to a common place (e.g. /usr/local/bin), which should be in your $PATH already. If you installed the package locally, the programs 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, pip will tell you). Thus the programs need to be called explicitely or you can add their install path to your $PATH environment variable:
Install from source
If you plan to use the package as a developer, clone the Git repository:
git clone --recursive https://github.com/CPJKU/madmom.git
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. This is equivalent to these steps:
git clone https://github.com/CPJKU/madmom.git cd madmom git submodule update --init --remote
You can then either include the package directory in your $PYTHONPATH and compile the Cython extensions with:
python setup.py build_ext --inplace
or you can simply install the package in development mode:
python setup.py develop --user
To run the included tests:
python setup.py test
Upgrade of existing installations
To upgrade the package, please use the same machanism (pip vs. source / global vs. local install) as you did for installation. If you want to change from package to source, please uninstall the package first.
Upgrade a package
Simply upgrade the package via pip:
pip install --upgrade madmom [--user]
If some of the provided programs or models changed (please refer to the CHANGELOG) you should first uninstall the package and then reinstall:
pip uninstall madmom pip install madmom [--user]
Upgrade from source
Simply pull the latest sources:
To update the models contained in the submodule:
git submodule update
If any of the .pyx or .pxd files changes, you have to recompile the modules with Cython:
python setup.py build_ext --inplace
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)
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)
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:
SuperFlux batch [-o OUTPUT_DIR] [-s OUTPUT_SUFFIX] LIST OF INPUT FILES
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.
The mailing list should be used to get in touch with the developers and other users.
The wiki can be found here: https://github.com/CPJKU/madmom/wiki
Frequently asked questions can be found here: https://github.com/CPJKU/madmom/wiki/FAQ
Supported by the European Commission through the GiantSteps project (FP7 grant agreement no. 610591) and the Phenicx project (FP7 grant agreement no. 601166) as well as the Austrian Science Fund (FWF) project Z159.
Version 0.13.1 (release date: 2016-03-14)
This is a bugfix release.
Fix beat evaluation argument parsing (#116)
Version 0.13 (release date: 2016-03-07)
Python 3 support (3.3+) (#15)
Online documentation available at http://madmom.readthedocs.org (#60)
Fix nasty unsingend indexing bug (#88)
MIDI note timing could get corrupted if note_ticks_to_beats() was called multiple times (#90)
API relevant changes:
Renamed DownBeatTracker and all relevant classes to PatternTracker (#25)
Complete refactoring of the features.beats_hmm module (#52)
Unified negative index behaviour of FramedSignal (#72)
Removed pickling of data classes since it was not tested thoroughly (#81)
Reworked stacking of spectrogram differences (#82)
Renamed norm_bands argument of MultiBandSpectrogram to norm_filters (#83)
Added alignment evaluation (#12)
Added continous integration testing (#16)
Added -o option to both single/batch processing mode to not overwrite files accidentially in single mode (#18)
Removed block_size parameter from FilteredSpectrogram (#22)
Sample rate is always integer (#23)
Converted all docstrings to the numpydoc format (#48)
Batch processing continues if non-audio files are given (#53)
Added code quality checks (#61)
Added coverage measuring (#74)
Added –down` option to evaluate only downbeats (#76)
Removed option to normalise the observations (#95)
Moved filterbank related argument parser to FilterbankProcessor (#96)
Version 0.12.1 (release date: 2016-01-22)
Added Python 3 compatibility to setup.py (needed for the tutorials to work)
Version 0.12 (release date: 2015-10-16)
Initial public release of madmom
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.