madmom

Madmom is an audio signal processing library written in Python with a strong focus on music information retrieval (MIR) tasks.

The library is used internally 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

Documentation of the package can be found online http://madmom.readthedocs.org

License

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.

Installation

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.

Prerequisites

To install the madmom package, you must have either Python 2.7 or Python 3.3 or newer and the following packages installed:

• numpy
• scipy
• cython
• nose (to run the tests)

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 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, clone the Git repository:

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

The --recursive is needed because the pre-trained model/data files are not included in this repository but rather added as a Git submodule. If you missed to add the recursice option, you can init the submodule and fetch the data manually:

git submodule update --init --remote

You can then either include the package directory in your $PYTHONPATH, or you can simply install the package in development mode:

python setup.py develop --user

If you change any .pyx or .pxd files, you have to (re-)compile the modules with Cython. To do so, please run the above command again or:

python setup.py build_ext --inplace

Optionally you can run the included tests:

python setup.py test

Package structure

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

/bin

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

/madmom

the actual Python package

/madmom/audio

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

/madmom/evaluation

evaluation code

/madmom/features

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

/madmom/ml

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

/madmom/models

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

/madmom/utils

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

/tests

tests

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:

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.

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.

Wiki

The wiki can be found here: https://github.com/CPJKU/madmom/wiki

FAQ

Frequently asked questions can be found here: https://github.com/CPJKU/madmom/wiki/FAQ

References

Acknowledgements

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.