WaveSongs

A Python package for birdsong synthesis and bioacoustic analysis

WaveSongs implements the motor gestures model for birdsong developed by Gabo Mindlin to generate synthetic birdsongs through numerical optimization [1, 2] . By leveraging fundamental frequency (FF) and spectral content index (SCI) as key parameters, the package solves a minimization problem using SciPy and performs audio analysis with librosa and scikit-maad.

Validated against field recordings of Zonotrichia Capensis, Ocellated Tapaculo, and Mimus Gilvus, the model achieves <5% relative error in FF reconstruction compared to empirical data.

⚒️ Installation

Prerequisites

• Python ≥ 3.10
• Git

Steps

1. Clone the repository:

   git clone https://github.com/wavesongs/wavesongs
   cd wavesongs
   

2. Set up a virtual environment (choose one method):

   Using venv

   python -m venv venv
   

   Using Conda

   conda create -n wavesongs python=3.12
   conda activate wavesongs
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Install WaveSongs in editable mode:

   pip install -e .
   

🚀 Gettint Started

Explore the Tutorial 1 Notebook to generate synthetic birdsongs and explore the model plots.

For advanced usage (e.g., custom gestures, parameter tuning, data measures, etc), check the other tutorials: Spectrum Measures or Synthetic Songs. More details can be found in the Documentation.

🎶 Data Integration

Pre-processed field recordings from Xeno Canto and eBird are included in ./assets/audio. To use custom recordings place .wav or .mp3 files in ./assets/audio/ or define the audios path with the ProjDirs class.

🔐 License

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

📒 Citation

If this work contributes to your research, please cite:

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

🌱 Contribute

We welcome contributions! See our roadmap:

• Integrate Xeno Canto API for direct dataset downloads.
• Add ROIs analysis using scikit-maad. This will allo automatic syllables detection and gerenration.
• Improve FF parametrization for small motor gestures, chunks.

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

📚 References

[1] Mindlin, G. B., & Laje, R. (2005). The Physics of Birdsong. Springer. DOI

[2] Amador, A., et al. (2013). Elemental gesture dynamics in song premotor neurons. Nature. DOI