AudioCommons Timbral Models
The current distribution contains python scripts for predicting eight timbral characteristics: hardness, depth, brightness, roughness, warmth, sharpness, booming, and reverberation.
More detailed explanations of how the models function can be found in Deliverable D5.8: Release of timbral characterisation tools for semantically annotating non-musical content, available: http://www.audiocommons.org/materials/
Installing the package
The timbral_models package can be installed using the pip command. This will handle installation of all dependencies. In the update to version 0.4, the dependency to essentia was removed and only pip installable packages are required.
pip install timbral_models
Please note that during testing, pip was unable to install some of the dependencies and produced an error. In these cases, either rerun the
pip install timbral_models command or install the offending dependency directly, e.g.
pip install numpy.
The package can also be installed locally and be made editable. To do this, clone the repository, navigate to the folder, and run the pip command
pip install -e .. In this method, dependencies will not be installed.
The script can also be downloaded manually from the github repository (https://github.com/AudioCommons/timbral_models). If doing this, dependencies will need to be manually installed. The timbral models rely on several other easily accessible python packages:
scipy. These are all easily installed using the
pip install command. e.g.
$ pip install numpy $ pip install soundfile $ pip install librosa $ pip install scipy $ pip install sklearn $ pip install six $ pip install pyloudnorm
Using the models
The models are formatted in a python package that can be simply imported into a Python script. The timbral extractor can be used to extract all timbral attributes with a single function call.
To calculate the timbral attributes, pass the timbral extractor function a string of the filename. The method will then read in the audio file internally and return all timbral characteristics.
import timbral_models fname = '/Documents/Music/TestAudio.wav' timbre = timbral_models.timbral_extractor(fname)
In this example,
timbre will be a python dictionary containing the predicted hardness, depth, brightness, roughness, warmth, sharpness, booming, and reverberation of the specified audio file.
Single attribute calculation
Alternative, each timbral attribute can be calculated individually by calling the specific timbral function, e.g.
These are named
xxx represents the timbral model, and also require a string of the filename to be analysed.
import timbral_models fname = '/Documents/Music/TestAudio.wav' timbre = timbral_models.timbral_hardness(fname)
The hardness, depth, brightness, roughness, warmth, sharpness, and booming are regression based models, trained on subjective ratings ranging from 0 to 100. However, the output may be beyond these ranges.
clip_output optional parameter can be used to contrain the outputs between 0 and 100.
timbre = timbral_models.timbral_extractor(fname, clip_output=True)
For additional optional parameters, please see Deliverable D5.8.
The reverb attribute is a classification model, returning 1 or 0, indicating if the file "sounds reverberant" or "does not sound reverberant" respectively.
MATLAB Reverb model
Also contained in this repository is a full version of the timbral reverb model. For instruction on installing and using this, please see Deliverable D5.8.
This section documents the version history of the timbral models. To download a specific version of the model that relate to a specific deliverable, please check this section and download the most recent version from that date.
2019/01/24 - Version 0.4 of timbral_models, relates to Audio Commons Deliverable D5.8. This version of the repository relates to the software version 0.4 on PyPI.
2018/12/14 - Version 0.3 of timbral models, relates to Audio Commons Deliverable D5.7. This version of the repository relates to the software version 0.3 on PyPI.
2018/07/26 - Version 0.2 of timbral models, relates to Audio Commons Deliverable D5.6. This version of the repository relates to the software version 0.2 on PyPI.
2017/09/05 - Version 0.1 of timbral models, relates to Audio Commons Deliverable D5.3. This version of the repository relates to the software version 0.1 on PyPI.
2017/04/27 - Version 0.0 of the timbral models, relates to Audio Commons Deliverable D5.2.
For refencing these models, please reference Deliverable D5.8, available: http://www.audiocommons.org/materials/