Framework for experiments with differentiable audio and music processing (DDSP) in PyTorch.
This project uses uv to manage the environment and dependencies. After checking out this repository, install uv and run:
uv sync
This creates a .venv and installs libdamp in editable mode together with its core dependencies, using the versions pinned in uv.lock.
To also pull in the optional dependency groups (development tooling, docs, notebooks, etc.), use:
uv sync --extra develop,tests,doc,notebooks
If you'd rather install into an existing/active environment with pip, that works too:
pip install -e .
On Linux with a CUDA device, incremental_mod uses a Triton kernel that is at least 10-100x faster than the fallback implementation. If Triton fails to import (for example because setuptools is missing from the environment), the code silently falls back to the slow path without any warning, which will slow down the Pulsetable synthesis in particular. You can run the following script after setting up your environment on a CUDA machine to confirm Triton is actually working:
uv run scripts/check_triton.py
import libdamp
experiment = libdamp.Experiment(...)A full documentation is available here.
See the configs and experiments directories for example experiment configurations, and scripts for entry points used to run them.
libdamp/ # library source code (datasets, models, losses, helpers, ...)
configs/ # gin config files for experiments
docs/ # Sphinx documentation sources
experiments/ # Experiment definitions
scripts/ # CLI entry points for running experiments
test/ # unit tests
notebooks/ # Jupyter notebooks with examples and explanations of the algorithms
The files in experiments/ICASSP2026, configs/ICASSP2026, and notebooks/ICASSP2026 are accompanying the following publication:
@inproceedings{SchwaerDBM26_DiffPulse_ICASSP,
author = {Simon Schw{\"a}r and Christian Dittmar and Stefan Balke and Meinard M{\"u}ller},
title = {Differentiable Pulsetable Synthesis for Wind Instrument Modeling},
booktitle = {Proceedings of the {IEEE} International Conference on Acoustics, Speech, and Signal Processing ({ICASSP})},
year = {2026},
pages = {14792--14796},
address = {Barcelona, Spain},
doi = {10.1109/ICASSP55912.2026.11462505}
}
To reproduce results:
- Download the ChoraleBricks dataset (we used version 1.0.1, but newer versions work too).
- Preprocess the data following the instructions in the notebook
notebooks/ICASPP2026/preprocess_choralebricks.ipynb. This creates a folder with separate files for audio, F0 trajectory, gain envelope, etc. in the format that is readable bylibdamp.PulseItDataset. - Update the config variable
PulseItDataset.pathinconfigs/ICASSP2026/pulsewave_base.gin. The default path is../datasets/ChoraleBricks/libdamp_all, relative to the main folder of this framework. - Run the experiment, for example with
uv run scripts/run.py --config configs/ICASSP2026/pulsewave_base.gin configs/ICASSP2026/instr/01_tp.gin configs/ICASSP2026/mode/pulse_4.ginfor training with trumpet voice 1 and using the pulsetable method with 4 pulses (see the configs folder for other options). - Trained models are stored in the
resultsfolder. You can load them and play around with them using the notebooknotebooks/ICASSP2026/explore_model.ipynb.
The files in experiments/VocalRevolutions, configs/VocalRevolutions, and notebooks/VocalRevolutions are accompanying an art project in collaboration with Tim Otto Roth and his Heaven's Carousel.
Coming soon.
uv run pytest
This project uses ruff for linting and formatting. Check the repository with (after syncing the develop extra):
uv run ruff check .
uv run ruff format --check .
If you want to run these checks automatically on commit, install the pre-commit hook:
uv run pre-commit install
This also strips output cells from Jupyter notebooks before they are committed, via nbstripout.
The API documentation is built with Sphinx from the docstrings in libdamp and the sources in docs. After syncing the doc extra (see Installation), build the HTML docs with (after syncing the docs extra):
uv run make -C docs html
The output is written to docs/_build/html/index.html, which you can open directly in a browser. To remove the build output, run uv run make -C docs clean.
Contributions are welcome! Please open an issue to discuss any significant changes before submitting a pull request, and make sure tests and the linter pass beforehand. User-facing changes should be noted in CHANGELOG.md.
If you use libdamp in your research, please cite this research paper the code is accompanying:
@inproceedings{SchwaerDBM26_DiffPulse_ICASSP,
author = {Simon Schw{\"a}r and Christian Dittmar and Stefan Balke and Meinard M{\"u}ller},
title = {Differentiable Pulsetable Synthesis for Wind Instrument Modeling},
booktitle = {Proceedings of the {IEEE} International Conference on Acoustics, Speech, and Signal Processing ({ICASSP})},
year = {2026},
pages = {14792--14796},
address = {Barcelona, Spain},
doi = {10.1109/ICASSP55912.2026.11462505}
}
This project is licensed under the MIT License.