Materials accompanying the sms-tools package, including:
- lecture material
- exercises
- example notebooks
- sound files
- graphical interfaces for analysis, synthesis, and transformation models
This repository is intended as a companion to the sms-tools library and is organized for teaching, experimentation, and interactive exploration of sound and music analysis techniques.
The repository combines several kinds of learning material:
- Examples: Jupyter notebooks demonstrating analysis and transformation workflows
- Exercises: notebooks intended for hands-on practice
- Graphical interfaces: Tk-based applications for running common models without writing code
- Lecture and lab material: supporting course content
- Audio assets: example sounds used by notebooks and GUIs
The two main desktop interfaces are:
- interface-models/models_GUI.py: analysis and synthesis models
- interface-transformations/transformations_GUI.py: sound transformation models
You need a working Python 3 environment with the dependencies listed in requirements.txt:
sms-toolsnotebookmatplotlibnumpyscipyipythonessentiafreesound-python
On macOS and Linux, a typical setup is:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
On Windows, activate the environment with:
.venv\Scripts\activate
- Install dependencies from the repository root.
- Some notebooks and examples rely on audio analysis libraries that may take longer to install than standard Python packages.
- The GUIs are designed around mono WAV files, typically at 44.1 kHz.
Main top-level directories:
- examples: example notebooks covering most models and transformations
- exercises: exercise notebooks for practice
- interface-models: GUI and helper functions for analysis/synthesis models
- interface-transformations: GUI and helper functions for transformations
- lectures: lecture resources
- sounds: audio files used by the notebooks and interfaces
Important interface entry points:
Generated audio files are written to:
From the repository root, run:
python launch_gui.py
This opens a small launcher window where you can choose:
- Models GUI
- Transformations GUI
On macOS, you can also double-click launch_gui.command.
You can still launch the models interface directly:
cd interface-models
python models_GUI.py
This launcher gives access to several model interfaces, including DFT, STFT, sinusoidal, harmonic, stochastic, and combined models.
You can also launch the transformations interface directly:
cd interface-transformations
python transformations_GUI.py
This launcher provides access to transformation workflows such as sine, harmonic, stochastic, HPS, and morphing-based transformations.
The interface applications include:
- default example sound files resolved from the repository
soundsfolder - scrollable windows for smaller displays
- resizable layouts
- lazy tab loading for faster startup
- clearer audio playback buttons for input and output sounds
- interactive plot windows with Matplotlib toolbar support for pan, zoom, and navigation
If a computation generates audio output, playback buttons in the interface can be used to audition the resulting WAV files.
The examples and exercises directories contain Jupyter notebooks.
To work with them, install the dependencies and launch Jupyter from the repository root:
jupyter notebook
or:
python -m notebook
Example topics include:
- DFT and Fourier analysis
- STFT analysis and morphing
- sinusoidal and harmonic models
- sinusoidal plus residual / stochastic models
- sound and music description
- classification and clustering workflows
- Create and activate a virtual environment.
- Install the dependencies from requirements.txt.
- Launch either GUI application or Jupyter notebooks.
- Use audio files from sounds or your own mono WAV files.
- Inspect plots, listen to outputs, and compare analysis/transformation results.
- The GUI code in interface-models and interface-transformations calls corresponding
*_function.pymodules. - Those modules are useful both as GUI backends and as compact examples of how to call
sms-toolsprogrammatically. - The notebooks in examples are the best starting point for learning the underlying concepts step by step.
See LICENSE for the repository-wide licensing summary.
All software is distributed under the GNU Affero GPL v3:
Lecture slides are distributed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0:
Sounds in this repository are released under Creative Commons Attribution 4.0: