Skip to main content

A python package to analyze and visualize harmonic sounds

Project description



A python package to analyse guitar sounds. Developed as a lutherie research analysis tool with the Bruand Lutherie School. The guitarsound python package documentation is available at documentation and a Jupyter Notebook tutorial for the API is available here.


The main goal of this project is to provide a tool to efficiently analyse sound data from research projects in musical instrument design. While sound analysis packages already exist, they are more directed to feature extraction for machine learning purposes. Additionally, some features of interest, like time dependent decay, onset shape and fourier transform peaks distribution are not computable trivially or accurately with existing tools. The current release of the guitarsounds package contains usual and advanced digital signal processing tools applied to the analysis of transient harmonic sounds with easy figure generation through matplotlib. To allow the package functionalities to be used rapidly without learning the API, a graphic user interface is available based on jupyter lab widgets.


The following steps can be followed to use guitarsound interactively with Jupyter Notebook. A French version of the installation guide is available here.

  • Download the Anaconda package management system link.
Screen Shot 2022-05-22 at 9 18 26 PM
  • Install the Anaconda package management system (Tutorial).

  • Once Anaconda is installed, the guitarsound package needs to be installed. Without going into heavy details, the guitarsound package is not available from the Anaconda channels and needs to be installed using PIP, the Package Installer for Python. To install a package from PIP in Anaconda, you need to use the Anaconda Prompt :


To install guitarsound, type the following command into the Anaconda Prompt :

pip install guitarsounds

Once the installation of guitarsounds is finished, the package can be used in the Anaconda Jupyter Notebook environment. The Jupyter Notebook environment can be launched from Anaconda Navigator which is included in the Anaconda package management system.


Then, navigate to the sub-directory where you want your work to be and create a Jupyter Notebook :

Screen Shot 2022-06-02 at 9 12 01 PM

The graphic user interface can be launched by typing the following code in a cell of the notebook :

import guitarsounds
interface = guitarsounds.Interface()

Pressing shift+enter runs the code in the cell and launches the graphic user interface of guitarsounds :

Capture d’écran, le 2021-08-29 à 19 01 28

To go further, you may learn the guitarsounds API, see the API Tutorial notebook and the API documentation

Example usage

While extracting quantitative features from sounds allows for a meaningful analysis, listening to them remains an important part of the analysis. Soundfiles can be loaded by creating a Sound class instance with the soundfile path as an argument

from guitarsounds import Sound
mysound = Sound('example_sounds/Wood_Guitar/Wood_E1.wav')

The amplitude-time data of the Sound instance is stored in a Signal class and can be listened in a Jupyter Notebook:


Relevant time signal properties can then be rapidly extracted and visualized in the interactive Jupyter Notebook environment. For example, the time damping curve and the associated damping factor is a useful measure when measuring the effects of changes in the guitar design on the decay rate of different notes :


Two different sounds can also be compared using the SoundPack class, such as a tangible effect of a design change can be measured. Here we compare the fourier transform peaks of two guitars built using different materials :

import guitarsounds
file1 = 'example_sounds/Wood_Guitar/Wood_A5.wav'
file2 = 'example_sounds/Carbon_Guitar/Carbon_A5.wav'
mysounds = guitarsounds.SoundPack(file1, file2, names=['wood', 'carbon'])

The base API of the guitarsounds classes can also be leveraged to create custom signal analysis features. More info and advanced examples are available in the API Tutorial Notebook.


Feel free to fork the guitarsound repository and submit pull requests implementing useful changes. If you implement a new feature, please submit associated unit tests in your pull request. Pull requests that pass all the tests and propose changes aligned with the goal of this package should be accepted.

This project is maintained by the Bruand Lutherie School, if you have problems with the package, or you need support in using it, please write an issue in this repository.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

guitarsounds-1.2.0.tar.gz (10.8 MB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page