⚒️ Installation

WaveSongs

Version Package Python Version Open Source Love svg2 GPLv3 license made-with-sphinx-doc Documentation Status

WaveSongs is a Python package designed to generate synthetic songs (currently focused on birdsongs) from audio recordings.

The package utilizes the motor gestures model for birdsong developed by Gabo Mindlin to generate synthetic birdsongs through numerical optimization [A1, B1]. By leveraging fundamental frequency (FF) and spectral content index (SCI) as key parameters. The package solves a minimization problem using SciPy [S1] and performs audio analysis with librosa [S2] and scikit-maad [S3]. This combination of tools enables the precise and realistic synthesis of birdsongs, achieving relative errors in fundamental frequency (FF) of less than 1%. [1]

⚒️ Installation#

There are two ways to install wavesongs: a single line code installation via pypi, or a manual installation to get the latest developer version. Check the ⚒️ Installation guide for more details.

Now, let’s dive into the package! Check out the 🚀 Getting Started guide to learn how to analyze recordings and create synthetic syllables. You can download recording samples from the 📥 Download Samples guide.

🗂️ Documentation#

wavesongs

A Python package for generating synthetic bird songs through physical modeling and numerical optimization techniques.

🌱 Contribute#

We welcome contributions! See our roadmap:

  • Add ROIs analysis using scikit-maad. This will allow automatic syllables detection and generation.

  • Improve FF parametrization for small motor gestures, chunks.

  • Create a Machine Learning module for data augmentation for synthetic songs.

  • Add more physical models for songs generation. Explore the sounds production in other animals as fish, frogs, frogs, etc. Animals who uses waves to geenrate song.

  • Explore music concepts (notes, acords, etc) and how to generate them with wavesongs.

  • Smooth songs at the extremes of the syllables to make the sound more natural.

To report issues or suggest features, open a GitHub Issue.

Do you need some other functionality? Let us know!

🔐 License#

WaveSongs is licensed under the GNU General Public License v3.0.

📒 Citation#

If this work contributes to your research, please cite:

@software{san_wavesongs_2025,
   author = {Aguilera Novoa, Sebastian},
   title = {WaveSongs: Computational Birdsong Synthesis},
   year = {2025},
   publisher = {GitHub},
   journal = {GitHub Repository},
   url = {https://github.com/wavesongs/wavesongs}
}

📚 References#

Articles

[A1]

Gabriel B. Mindlin & Daniel Margoliash Ana Amador, Yonatan Sanz Perl. Elemental gesture dynamics are encoded by song premotor cortical neurons. Nature, 495(7439):59–64, Mar 2013. URL: https://doi.org/10.1038/nature11967, doi:10.1038/nature11967.

Books

[B1]

Gabriel Mindlin and Rodrigo Laje. The physics of birdsong. The Physics of Birdsong: , Biological and Medical Physics, Biomedical Engineering. ISBN 978-3-540-25399-0. Springer-Verlag Berlin Heidelberg, 2005, pages, 01 2005. doi:10.1007/3-540-28249-1.

Software

[S1]

Pauli Virtanen, Ralf Gommers, Travis E. Oliphant, Matt Haberland, Tyler Reddy, David Cournapeau, Evgeni Burovski, Pearu Peterson, Warren Weckesser, Jonathan Bright, Stéfan J. van der Walt, Matthew Brett, Joshua Wilson, K. Jarrod Millman, Nikolay Mayorov, Andrew R. J. Nelson, Eric Jones, Robert Kern, Eric Larson, C J Carey, İlhan Polat, Yu Feng, Eric W. Moore, Jake VanderPlas, Denis Laxalde, Josef Perktold, Robert Cimrman, Ian Henriksen, E. A. Quintero, Charles R. Harris, Anne M. Archibald, Antônio H. Ribeiro, Fabian Pedregosa, Paul van Mulbregt, and SciPy 1.0 Contributors. SciPy 1.0: Fundamental Algorithms for Scientific Computing in Python. Nature Methods, 17:261–272, 2020. doi:10.1038/s41592-019-0686-2.

[S2]

Brian McFee, Colin Raffel, Dawen Liang, Daniel PW Ellis, Matt McVicar, Eric Battenberg, and Oriol Nieto. Librosa: audio and music signal analysis in python. In Proceedings of the 14th Python in Science Conference, 18–25. 2015.

[S3]

Juan Sebastián Ulloa, Sylvain Haupert, Juan Felipe Latorre, Thierry Aubin, and Jérôme Sueur. Scikit‐maad: An open‐source and modular toolbox for quantitative soundscape analysis in Python. Methods in Ecology and Evolution, pages 2041–210X.13711, September 2021. URL: https://onlinelibrary.wiley.com/doi/10.1111/2041-210X.13711, doi:10.1111/2041-210X.13711.

Footnotes

Contents