PyTimbre 0.5.20

Python conversion of Timbre Toolbox

PyTimbre

PyTimbre is a Python conversion of the Matlab package Timbre Toolbox, found here (https://github.com/VincentPerreault0/timbretoolbox).

This package was created in association with work conducted at the United States Air Force Research Laboratory on human perception of sound. Generally, models of perception have focused on sound pressure level spectra, and time histories of sound pressure. But auditory detection, identification/classification, and localization may be described better by attributes of the sound that are more based on perceptual studies of signals.

The concept of Timbre has been used in music perception research for many years. In 2011, Geoffroy Peeters compiled a collection of spectro-temporal attributes (features calculated on a frequency spectrum, that varies with time), and temporal attributes (features calculated on the waveform, or waveform's envelop). This paper forms the basis for the Matlab toolbox referenced above.

Though the Matlab coding functioned, it was cumbersome as Matlab is not a true object-oriented language. This conversion has sought to integrate the calculation of the various timbre auditory features with the structure of classes and provides a more robust method for extension of these ideas and concepts than was available within the Matlab version.

In addition, a generic time waveform object (Waveform) was provided to represent the time signal. From this class, a child class is derived to read wave files. This derived class permits the reading of multiple types of wav files ( canonical, and non-canonical) with bit rates from 8-, 16-, 24-, and 32-bit. Also included are interface methods for reading and adding meta-data that is similar to the MP3 tagging and assists in organizing the audio files by more than name or date.

Over the course of research at the United States Air Force Research Laboratory a number of other features were determined to be of interest for the use of the PyTimbre toolbox. In effort to unify these different extraction methods with the data that PyTimbre represents, the tool kits were added to the requirements list and added as properties of the various classes. These represent the sound quality metrics extracted from the Mosqito project (https://github.com/Eomys/MoSQITo) and the speech feature extraction ()

Usage Example

1. Defining a waveform from an array of values

from pytimbre2.audio_files.waveform import Waveform

fs = 48000 w = 2 * np.pi * f t = np.arange(0, 10, 1/fs)

wfm = Waveform(0.75 * np.sin(w*t), fs, 0.0)

2. Define a waveform from a wav file

from pytimbre2.audio_files.wavefile import WaveFile

wfm = wave_file(filename)

3. Obtain global temporal attributes

from pytimbre2.audio_files.wavefile import WaveFile

wfm = wave_file(filename)

print(wfm.amplitude_modulation)

4. Create single spectrogram and get a feature

from pytimbre2.audio_files.wavefile import WaveFile from pytimbre2.spectrogram import Spectrogram

wfm = wave_file(filename) spectrum = PowerSpectralDensity_Spectrum(wfm)

print(spectrum.spectral_roll_off)

Clearance review and publication permission

This software was developed in conjunction with research into the human perception of sound at the 711th Human Performance Wing, Airman Systems Directorate.

It is approved for Distribution A, 88ABW-2020-2147.

A series of audio files employed in classification research within the wing are provided for testing and examples of how .to use the interface.

PyTimbre

Development History

2020

April

• Added logic to avoid adding the STFT when it is not within the input configuration
• Added logic to generate and evaluate functions to skip over elements that are not included, or included as None
• Added try catch to trap error on linear algebra analysis
• Added a new function to create a column-wise output file for the results.
• Edited the calculation of the Attack so that if it returns a single value rather than the expected array, it will continue to process the data.
• Added logic to put -9999 in place of the NaN while exporting data that was not calculated

May

• Added logic to ensure that the index is always less than the length of the vector (lines 967 of StaticMethods)

July

• Added the History.md file back into the repository, and changed the column widths in every file to the limit within PyCharm.

October

• Added comments and details regarding classes.

2021

May

• Added the average statistic to the output dictionary

• Added logic to the determination of the Attack start and stop in cases when there is no array matching the constraints.

June

• Added functions to SoundFile to facilitate easier use of the class. Created an 'all' and new 'default' configuration. Added the ability to return only a specific metric from the new 'process' function.
• Updated calculation within Harmonic representation to address potential for index violations.

July

• Updated the default_configuration function

• Updated document string and other formatting issues within the source code.

• Initial design of new interface complete. This design removes the MATLAB style 'eval' command and creates the parent-child classes for the various spectro-temporal representations. The entirety of the feature extraction is contained within the parent class and provides the interface for interaction with the pytimbre classes.

August

• Added a function to the AudioSignal that permits the definition of the names of the features prior to running the analysis. This assists with the definition of the DataFrame that might hold the data.

2022

May

• Added a refactored version of the generic_time_waveform object from external sources. This provides the basis for calculating the features on the waveform
• Added a refactored version of the wav_file class that permits the reading/writing of most wav files that have canonical format. This class also includes the ability to read/write additional chunks for the addition of meta-data to the wave file.

June

• Updated the interface with the deprecation module. This permits the inclusion of the former methods, but marks them with deprectation decoration.
• Added tests for the various new methods for representation of the temporal and spectral characteristics.
• Updated the Data_Chunk to return a single dimension vector when reading a mono wav file.
• Added functions to create the dictionary of featres from a Spectrum object
• Numerous minor fixes to ensure the functioning of the system for the calculation of the various features

August

• Added files from another library to provide test cases for the various shared classes
• Updated the spectrum file with a spectrogram class that creates a short time Fourier transform in a manner similar to the spectrogram function from scipy but in accordance with the Matlab Timbre toolbox code.
• Removed the time history calculation ability
• Moved the chunk classes that support the WaveFile class to the same file.
• Create test cases for the single frequency sine wave. This test case was pushed through the MATLAB version of the toolbox. All spectral features, but the spectral variance, were checked against these results.

2023

January

• Fixed use of automatic headers on history and readme files.
• Added a property to the spectrogram class that returns a dictionary of the various temporal and spectral features, averaged in time.
• Began adding the hooks for inclusion of the mosqito sound quality metrics for extension of the auditory features into this realm.
• Added acoustic weighting and fractional octave band classes to begin facilitation of the inclusion of sound pressure level determination based on FFT and digital filters.
• Added elements of other AFRL spectral calculations in preparation for an increase of the minor revision number.
• Renamed the spectrum.py and time_history.py files to their plural since they contain multiple classes.

February

• There was an issue reading StandardBinaryFile formatted files from another organization. A significant amount of restructuring was conducted on the constructor of this class to permit multiple variations on the required data within the header.
• The get_features function in the Spectrum class did not return all the values of the spectral features in the dictionary. This was updated and a new version pushed.
• Added a function to wrap up the creation of the generic time history with fractional octave resolution calculated from the Narrowband spectra
• Edited the TimeHistory and NarrowbandTimeHistory classes to insert the header, correctly set the integration time on loading the file, and run new tests.
• Changed how WaveFile.audio_info returns the data

MIT License

Copyright (c) 2021 Frank Mobley, Gregory Bowers

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.