tomato

Turkish-Ottoman Makam (M)usic Analysis TOolbox

Introduction
tomato in a nutshell
Installation
Documentation
License
FAQ
Authors
Acknowledgments
References

1. Introduction

tomato is a comprehensive and easy-to-use toolbox in Python for the analysis of audio recordings and music scores of Turkish-Ottoman makam music. The toolbox includes the state of art methodologies applied to this music tradition. The analysis tasks include:

Symbolic Analysis: score metadata extraction, score section extraction, score phrase segmentation, semiotic section, and phrase analysis
Audio Analysis: audio metadata crawling, predominant melody extraction, tonic and transposition identification, makam recognition, pitch distribution computation, tuning analysis, melodic progression analysis
Joint Analysis: score-informed tonic identification and tempo estimation, section linking, note-level audio-score alignment, predominant melody octave correction, note modeling

The toolbox aims to facilitate the analysis of large-scale audio recording and music score collections of Turkish-Ottoman makam music, using the state of the art methodologies designed for the culture-specific characteristics of this tradition. The analysis results can then be further used for several tasks such as automatic content description, music discovery/recommendation, and musicological analysis.

If you are using tomato in your work, please cite the dissertation:

Şentürk, S. (2016). Computational Analysis of Audio Recordings and Music Scores for the Description and Discovery of Ottoman-Turkish Makam Music. Ph.D. thesis, Universitat Pompeu Fabra, Barcelona, Spain.

For the sake of reproducibility, please also state the version you used as indexed at Zenodo.

For the descriptions of the methodologies in the toolbox, please refer to the papers listed in the References.

2. tomato in a nutshell

# import ...
from tomato.joint.completeanalyzer import CompleteAnalyzer
from matplotlib import pyplot as plt

# score input
symbtr_name = 'makam--form--usul--name--composer'
txt_score_filename = 'path/to/txt_score'
mu2_score_filename = 'path/to/mu2_score'

# audio input
audio_filename = 'path/to/audio'
audio_mbid = '11111111-1111-1111-1111-11111111111'  # MusicBrainz Recording Identifier

# instantiate analyzer object
completeAnalyzer = CompleteAnalyzer()

# Apply the complete analysis. The resulting tuple will have
# (summarized_features, score_features, audio_features,
# score_informed_audio_features, joint_features) in order
results = completeAnalyzer.analyze(
    symbtr_name=symbtr_name, symbtr_txt_filename=txt_score_filepath,
    symbtr_mu2_filename=mu2_score_filepath, audio_filename=audio_filepath,
    audio_metadata=audio_mbid)

# plot the summarized features
fig, ax = completeAnalyzer.plot(results[0])
ax[0].set_ylim([50, 500])
plt.show()

You can refer to the Jupyter notebooks in demos folder for detailed, interactive examples.

3. Installation

3.1. Prequisites

tomato may require several packages before installation, depending on your operating system. For example, in Ubuntu 16.04 using Python 3.5, you have to install the python 3, libxml2, libxslt1, freetype, and png development packages. You can install them by:

sudo apt-get install python3 python3.5-dev python3-pip libxml2-dev libxslt1-dev libfreetype6-dev libpng12-dev

3.2. Install tomato using GNU make

You can install tomato and all its dependencies by running in the terminal:

cd path/to/tomato
make

The above command installs tomato to a virtual environment called ./venv, as well as LilyPond and MATLAB Compiler Runtime.

If you want to install tomato in editable mode with the extra Python requirements (i.e., demo and development), you can run:

make all-editable

For more options, please refer to the help by running:

make help

3.3. Running tomato using docker

For the reproducibility and maintability's sake, tomato comes with docker support.

To build the docker image simply go to the base folder of the repository and run:

docker build . -t sertansenturk/tomato:latest

You may interact with the docker image in many different ways. Below, we run a container by mounting the demos folder in tomato and start an interactive bash session:

docker run -v "$PWD/demos/":/home/tomato_user/demos/ -it sertansenturk/tomato bash

Then, you can work on the command line, like you are on your local machine. Any changes you make to the demos folder will be reflected back to your local folder.

For more information on working with docker, please refer to the official documentation.

3.4. Step-by-step installation

If the above options do not work for you, you need to complete the steps below:

3.4.1. Installing tomato

It is recommended to install tomato and its dependencies into a virtualenv. In the terminal, do the following:

virtualenv -p python3 venv

Activate the virtual environment:

source venv/bin/activate

Then, change the current directory to the repository folder and install by:

cd path/to/tomato
python -m pip install .

If you want to edit files in the package and have the changes reflected, instead, you can call:

python -m pip install -e .

If you want to run the demo Jupyter notebooks and/or make development, you may include the extras to the installation by:

python -m pip install -e .[demo,development]

The requirements are installed during the setup. If that step does not work for some reason, you can install the requirements by calling:

pip install -r requirements.txt

3.4.2. Installing MATLAB runtime

The score phrase segmentation, score-informed joint tonic identification and tempo estimation, section linking, and note-level audio-score alignment algorithms are implemented in MATLAB and compiled as binaries. They need MATLAB Runtime for R2015a (8.5) to run. You must download and install this specific version (Linux installer).

We recommend you to install MATLAB Runtime in the default installation path, as tomato searches them automatically. Otherwise, you have to specify your own path in the MATLAB Runtime configuration file, tomato/config/mcr_path.cfg.

3.4.3. Installing LilyPond

tomato uses LilyPond under the hood to convert the music scores to SVG format.

In most Linux distributions, you can install LilyPond from the software repository of your distribution (e.g., sudo apt install lilypond in Debian-based distributions).

tomato requires LilyPond version 2.18.2 or above. If your distribution comes with an older version, we recommend you to download the latest stable version from the LilyPond website. If you had to install LilyPond this way, you might need to enter the LilyPond binary path to the "custom" field in tomato/config/lilypond.cfg (the default location is $HOME/bin/lilypond).

4. Documentation

Coming soon...

5. License

The source code hosted in this repository is licensed under Affero GPL version 3.

Any data (the music scores, extracted features, training models, figures, outputs, etc.) are licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

6. FAQ

The notes aligned by JointAnalyzer.align_audio_score(...) seems shifted. What is the problem?

Your audio input is probably a compressed format, such as mp3. There are typically shifts between different decoders (and even different versions of the same decoder) when they decode the same compressed audio file. In the predominant melody extraction step (AudioAnalyzer.extract_pitch(...)), Essentia has to decode the recording for processing. You observe a shift when the application you use another decoder.

These shifts are typically small (e.g., 50 samples ~1ms), so they are not very problematic. Nevertheless, there is no guarantee that the shift will be prominent. If you need "perfect" synchronization, you should use an uncompressed format such as wav as the audio input.

Note: In demos, we use mp3, because it would be too bulky to host a wav file.
Which operating systems are supported?
- tomato is fully supported only in Linux. It is tested against Ubuntu 16.04 and 18.04.
- We suggest people use the tomato docker image for other operating systems.
- tomato was tested on Mac OSX Sierra until version v0.10.1. You can still install tomato on Mac OSX by referring to the Linux installation instructions, but you need to install and configure Essentia & MATLAB Compiler Runtime by yourself.
What are the supported Python versions?

tomato supports Python versions 3.5, 3.6, and 3.7. If you want to run tomato on Python 2.7, please install v0.13.0 or below.
Where are the MATLAB binaries?

The binaries are not stored in tomato because it would take too much space to store these large files and their old versions here. Instead, the binaries are provided within the releases of the relevant packages. The binaries are downloaded to tomato/bin during the installation.

Please refer to tomato/config/bin.cfg for the relevant releases.
ScoreConverter fails to convert music scores with an error saying "The LilyPond path is not found." How can I fix this problem?

There can be several reasons regarding this problem:
- The user-provided file path (the music score input) does not exist.
  
  Check your input MusicXML-score path.
- LilyPond is not installed.
  
  Install the appropriate version of LilyPondby following the instructions.
- The binary path exists, but it is not used.
  
  Add the path of the LilyPond binary to the "custom" section in the configuration file: ./tomato/config/lilypond.cfg.
Is tomato a fruit or a vegetable?

It has a culture-specific answer.

7. Authors

Sertan Şentürk contact@sertansenturk.com

8. Acknowledgments

We would like to thank Harold Hagopian, the founder of Traditional Crossroads, for allowing us to use Tanburi Cemil Bey's performance of Uşşak Sazsemaisi in our demos.

9. References

The toolbox has been realized as part of the thesis:

[1] Şentürk, S. (2016). Computational analysis of audio recordings and music scores for the description and discovery of Ottoman-Turkish makam music. Ph.D. thesis, Universitat Pompeu Fabra, Barcelona, Spain.

The methods used in the toolbox are described in the papers:

Score Phrase Segmentation
[2] Bozkurt, B., Karaosmanoğlu, M. K., Karaçalı, B., and Ünal, E. (2014). Usul and makam driven automatic melodic segmentation for Turkish music. Journal of New Music Research. 43(4):375–389.

Score Section Extraction; Semiotic Section and Phrase Analysis
[3] Şentürk S., and Serra X. (2016). A method for structural analysis of Ottoman-Turkish makam music scores. In Proceedings of 6th International Workshop on Folk Music Analysis (FMA 2016), pages 39–46, Dublin, Ireland.

Audio Predominant Melody Extraction
[4] Atlı, H. S., Uyar, B., Şentürk, S., Bozkurt, B., and Serra, X. (2014). Audio feature extraction for exploring Turkish makam music. In Proceedings of 3rd International Conference on Audio Technologies for Music and Media (ATMM 2014), pages 142–153, Ankara, Turkey.

Audio Pitch Filter
[5] Bozkurt, B. (2008). An automatic pitch analysis method for Turkish maqam music. Journal of New Music Research. 37(1):1–13.

Audio Tonic and Transposition Identification, Makam Recognition, Pitch Distribution Computation, Tuning Analysis
[6] Bozkurt, B. (2008). An automatic pitch analysis method for Turkish maqam music. Journal of New Music Research. 37(1):1–13.
[7] Gedik, A. C., and Bozkurt, B. (2010). Pitch-frequency histogram-based music information retrieval for Turkish music. Signal Processing. 90(4):1049–1063.
[8] Chordia, P., and Şentürk, S. (2013). Joint recognition of raag and tonic in North Indian music. Computer Music Journal. 37(3):82–98.

Audio Tonic Identification from the Last Note
[9] Atlı, H. S., Bozkurt, B., and Şentürk, S. (2015). A method for tonic frequency identification of Turkish makam music recordings. In Proceedings of 5th International Workshop on Folk Music Analysis (FMA 2015), pages 119–122, Paris, France.

Audio Melodic Progression (Seyir) Analysis
[10] Bozkurt B. (2015). Computational analysis of overall melodic progression for Turkish Makam Music. In Penser l’improvisation, pages 289–298, Delatour France, Sampzon.

Score-Informed Audio Tonic Identification
[11] Şentürk, S., Gulati, S., and Serra, X. (2013). Score informed tonic identification for makam music of Turkey. In Proceedings of 14th International Society for Music Information Retrieval Conference (ISMIR 2013), pages 175–180, Curitiba, Brazil.

Score-Informed Audio Tempo Estimation
[12] Holzapfel, A., Şimşekli U., Şentürk S., and Cemgil A. T. (2015). Section-level modeling of musical audio for linking performances to scores in Turkish makam music. In Proceedings of 40th IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP 2015), pages 141–145, Brisbane, Australia.

Audio-Score Section Linking
[13] Şentürk, S., Holzapfel, A., and Serra, X. (2014). Linking scores and audio recordings in makam music of Turkey. Journal of New Music Research, 43(1):34–52.

Note-Level Audio-Score Aligment
[14] Şentürk, S., Gulati, S., and Serra, X. (2014). Towards alignment of score and audio recordings of Ottoman-Turkish makam music. In Proceedings of 4th International Workshop on Folk Music Analysis (FMA 2014), pages 57–60, Istanbul, Turkey.

Score-Informed Audio Predominant Melody Correction; Note Modeling
[15] Şentürk, S., Koduri G. K., and Serra X. (2016). A score-informed computational description of svaras using a statistical model. In Proceedings of 13th Sound and Music Computing Conference (SMC 2016), pages 427–433, Hamburg, Germany.

sertansenturk / tomato

readme