wavesongs 0.0.2b0

A python package for birdsongs creation and data extraction.

WaveSongs

A Python package for birdsong synthesis and bioacoustic analysis

Overview • Installation • Quick Start • Contribute • References

---

🔎 Overview

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.

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
   # Activate on Linux/macOS
   source venv/bin/activate
   # Activate on Windows
   .\venv\Scripts\activate
   

   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.

Here is an example of simple code to generate and display a sythetic audio. First, start by loading the wavesongs package:

# select matplotlib backend for notebook, enable interactive plots, just works on notebooks
%matplotlib ipympl

from wavesongs.utils.paths import ProjDirs       # Project files manager
from wavesongs.objects.syllable import Syllable  # Syllable objects
from wavesongs.utils import plots                # Display plots

Then, create a project directory manager, select a region of interest, and define the song for study. You can display it with the plots functions.

proj_dirs = ProjDirs(audios="./assets/audio", results="./assets/results")

# Region of Interest
tlim = (0.8798, 1.3009)

# Define the syllable
copeton_syllable_0 = Syllable(
   proj_dirs=proj_dirs, file_id="574179401", obj=copeton_syllable,
   tlim=tlim, type="intro-down", no_syllable="0", sr=44100
)
copeton_syllable_0.acoustical_features(
   umbral_FF=1.4, NN=256, ff_method="yin", flim=(1e2, 2e4)
)

# Display the syllable's spectrogram
plots.spectrogram_waveform(copeton_syllable_0, ff_on=True, save=True)

Figure 1: Waveform and spectrogram of the audio with id 574179401.

copeton_syllable_0.play() # just work on notebooks

https://github.com/user-attachments/assets/d15e7433-5f4c-451f-85aa-d4d53525029f

Now, let's find the optimal values to generate a comparable syllable, with errors below 5 % or even 1%.

from wavesongs.model import optimizer

optimal_z = optimizer.optimal_params(
   syllable=copeton_syllable_0, Ns=10, full_output=False
)
print(f"\nOptimal z values:\n\t{optimal_z}")

Computing a0*...
	 Optimal values: a_0=0.0010, t=0.51 min

Computing b0*, b1*, and b2*...
	 Optimal values: b_0=-0.2149, b_2=1.2980, t=13.77 min
	 Optimal values: b_1=1.0000, t=5.69 min

Time of execution: 19.97 min

Optimal z values:
	{'a0': 0.00105, 'b0': -0.21491, 'b1': 1.0, 'b2': 1.29796}

With the optimal values, define and dislpay the synthetic syllable:

# Define the synthetic syllable
synth_copeton_syllable_0 = copeton_syllable_0.solve(z=optimal_z, method="best")
plots.spectrogram_waveform(synth_copeton_syllable_0, ff_on=True, save=True)
# Display the socre variables
plots.scores(copeton_syllable_0, synth_copeton_syllable_0, save=False)

Figure 2: Scoring variables realtive errores.

plots.motor_gestures(synth_copeton_syllable_0, save=False)

Figure 3: Motor gesture, model parameters curves.

plots.syllables(copeton_syllable_0, synth_copeton_syllable_0, save=False)

Figure 4: Real and synthetic syllables.

synth_copeton_syllable_0.play() # just work on notebooks

https://github.com/user-attachments/assets/66ca1630-0ad0-43fc-bb56-cb397064ecd3

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
• Improve FF parametrization for small motor gestures

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

📚 References

Core Methodology

[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

Software

• Librosa • Audio analysis
• SciPy • Optimization routines
• scikit-maad • Soundscape metrics

Data Sources

• Xeno-Canto
• eBird