Package: tempocnn
Tempo-CNNTempo-CNN is a simple CNN-based framework for estimating temporal properties
of music tracks featuring trained models from several publications[1][2][3][4].First and foremost, Tempo-CNN is a tempo estimator. To determine theglobaltempo of
an audio file, simply run the scripttempo -i my_audio.wavTo create alocaltempo“tempogram”, runtempogram my_audio.wavFor a complete list of options, run either script with the parameter--help.For programmatic use via the Python API, please seehere.InstallationIn a clean Python 3.6 or 3.7 environment, simply run:pip install tempocnnIf you rather want to install from source, clone this repo and runsetup.py installusing Python 3.6 or 3.7:git clone https://github.com/hendriks73/tempo-cnn.git
cd tempo-cnn
python setup.py installModels and FormatsYou may specify other models and output formats (MIREX,JAMS) via command line parameters.E.g. to create JAMS as output format and the model originally used in the ISMIR 2018
paper[1], please runtempo -m ismir2018 --jams -i my_audio.wavFor MIREX-style output, add the--mirexparameter.DeepTemp ModelsTo use one of theDeepTempmodels from[3](see also repodirectional_cnns), runtempo -m deeptemp --jams -i my_audio.wavor,tempo -m deeptemp_k24 --jams -i my_audio.wavif you want to use a higher capacity model (somek-values are supported).deepsquareandshallowtempmodels may also be used.Note that some models may be downloaded (and cached) at execution time.Mazurka ModelsTo use DT-Maz models from[4], runtempo -m mazurka -i my_audio.wavThis defaults to the model nameddt_maz_v_fold0.
You may choose another fold[0-4]or another split[v|m].
So to use fold 3 from theM-split, usetempo -m dt_maz_m_fold3 -i my_audio.wavNote that Mazurka models may be used to estimate a global tempo, but were
actually trained to createtempogramsfor Chopin
Mazurkas[4].While it’s cumbersome to list the split definitions for the Version folds,
the Mazurka folds are easily defined:fold0was tested onChopin_Op068No3and validated onChopin_Op017No4fold1was tested onChopin_Op017No4and validated onChopin_Op024No2fold2was tested onChopin_Op024No2and validated onChopin_Op030No2fold3was tested onChopin_Op030No2and validated onChopin_Op063No3fold4was tested onChopin_Op063No3and validated onChopin_Op068No3The networks were trained on recordings of the three remaining Mazurkas.
In essence this means,do notestimate the local tempo forChopin_Op024No2usingdt_maz_m_fold0, becauseChopin_Op024No2was used in training.Batch ProcessingFor batch processing, you may want to runtempolike this:find /your_audio_dir/ -name '*.wav' -print0 | xargs -0 tempo -d /output_dir/ -iThis will recursively search for all.wavfiles in/your_audio_dir/, analyze then
and write the results to individual files in/output_dir/. Because the model is only
loaded once, this method of processing is much faster than individual program starts.InterpolationTo increase accuracy for greater than integer-precision, you may want to enable quadratic interpolation.
You can do so by setting the--interpolateflag. Obviously, this only makes sense for tracks
with a very stable tempo:tempo -m ismir2018 --interpolate -i my_audio.wavTempogramInstead of estimating a global tempo, Tempo-CNN can also estimate local tempi in the
form of a tempogram. This can be useful for identifying tempo drift.To create such a tempogram, runtempogram -p my_audio.wavAs output,tempogramwill create a.pngfile. Additional options to select different models
and output formats are available.You may use the--csvoption to export local tempo estimates in a parseable format and the--hop-lengthoption to change temporal resolution.
The parameters--sharpenand--norm-framelet you post-process the image.Greek FolkTempo-CNN provides experimental support for temporal property estimation of Greek
folk music[2]. The corresponding models are namedfma2018(for tempo) andfma2018-meter(for meter). To estimate the meter’s numerator, runmeter -m fma2018-meter -i my_audio.wavProgrammatic UsageAfterinstallation, you may use
the package programmatically.Example forglobaltempo estimation:fromtempocnn.classifierimportTempoClassifierfromtempocnn.featureimportread_featuresmodel_name='cnn'input_file='some_audio_file.mp3'# initialize the model (may be re-used for multiple files)classifier=TempoClassifier(model_name)# read the file's featuresfeatures=read_features(input_file)# estimate the global tempotempo=classifier.estimate_tempo(features,interpolate=False)print(f"Estimated global tempo:{tempo}")Example forlocaltempo estimation:fromtempocnn.classifierimportTempoClassifierfromtempocnn.featureimportread_featuresmodel_name='cnn'input_file='some_audio_file.mp3'# initialize the model (may be re-used for multiple files)classifier=TempoClassifier(model_name)# read the file's features, specify hop_length for temporal resolutionfeatures=read_features(input_file,frames=256,hop_length=32)# estimate local tempi, this returns tempo classes, i.e., a distributionlocal_tempo_classes=classifier.estimate(features)# find argmax per frame and convert class index to BPM valuemax_predictions=np.argmax(local_tempo_classes,axis=1)local_tempi=classifier.to_bpm(max_predictions)print(f"Estimated local tempo classes:{local_tempi}")LicenseSource code and models can be licensed under the GNU AFFERO GENERAL PUBLIC LICENSE v3.
For details, please see theLICENSEfile.CitationIf you use Tempo-CNN in your work, please consider citing it.Original publication:@inproceedings{SchreiberM18_TempoCNN_ISMIR,
   Title ={A Single-Step Approach to Musical Tempo Estimation Using a Convolutional Neural Network},
   Author ={Schreiber, Hendrik and M{\"u}ller Meinard},
   Booktitle ={Proceedings of the 19th International Society for Music Information Retrieval Conference ({ISMIR})},
   Pages ={98--105},
   Month ={9},
   Year ={2018},
   Address ={Paris, France},
   doi ={10.5281/zenodo.1492353},
   url ={https://doi.org/10.5281/zenodo.1492353}}ShallowTemp, DeepTemp, and DeepSquare models:@inproceedings{SchreiberM19_CNNKeyTempo_SMC,
   Title ={Musical Tempo and Key Estimation using Convolutional Neural Networks with Directional Filters},
   Author ={Hendrik Schreiber and Meinard M{\"u}ller},
   Booktitle ={Proceedings of the Sound and Music Computing Conference ({SMC})},
   Pages ={47--54},
   Year ={2019},
   Address ={M{\'a}laga, Spain}}Mazurka models:@inproceedings{SchreiberZM20_LocalTempo_ISMIR,
   Title ={Modeling and Estimating Local Tempo: A Case Study on Chopin’s Mazurkas},
   Author ={Hendrik Schreiber and Frank Zalkow and Meinard M{\"u}ller},
   Booktitle ={Proceedings of the 21th International Society for Music Information Retrieval Conference ({ISMIR})},
   Pages ={773--779},
   Year ={2020},
   Address ={Montreal, QC, Canada}}References[1](1,2)Hendrik Schreiber, Meinard Müller,A Single-Step Approach to Musical Tempo Estimation
Using a Convolutional Neural Network,
Proceedings of the 19th International Society for Music Information
Retrieval Conference (ISMIR), Paris, France, Sept. 2018.[2](1,2)Hendrik Schreiber,Technical Report: Tempo and Meter Estimation for
Greek Folk Music Using Convolutional Neural Networks and Transfer Learning,
8th International Workshop on Folk Music Analysis (FMA),
Thessaloniki, Greece, June 2018.[3](1,2)Hendrik Schreiber, Meinard Müller,Musical Tempo and Key Estimation using Convolutional
Neural Networks with Directional Filters,
Proceedings of the Sound and Music Computing Conference (SMC),
Málaga, Spain, 2019.[4](1,2,3)Hendrik Schreiber, Frank Zalkow, Meinard Müller,Modeling and Estimating Local Tempo: A Case Study on Chopin’s
Mazurkas,
Proceedings of the 21st International Society for Music Information
Retrieval Conference (ISMIR), Montréal, QC, Canada, Oct. 2020.Changes0.0.6:Require h5py<3.0.0, to avoid model loading issues.0.0.5:Moved to TensorFlow 1.15.4.Consolidated version info.Consolidated requirements.Switched to pytest.Officially support Python 3.7.Enabled GitHub actions for packaging and testing.Added Pypi workflow.Cache models locally.Load models from GitHub.Turned off TensorFlow debug logging.Migrated scripts to entry points.Removed charset encoding comments.0.0.4:Added support for DeepTemp, DeepSquare, and ShallowTemp models.Added support for Mazurka models.Added support for exporting data from tempograms.Added support for framewise normalization in tempograms.Moved to TensorFlow 1.15.2.Print number of model parameters.0.0.3:Added flag--interpolatefortempoto increase accuracy.Migrated models to TensorFlow 1.10.1.0.0.2:Added-doption for improved batch processing (tempo)Improved jams outputMoved to librosa 0.6.2Continue processing batch, even when encountering an error0.0.1:Initial version