wavesongs 0.0.1b0

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. 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 Notebook to generate synthetic birdsongs and analyze acoustic features. Here is an example of simple code to import and display an audio.

# select matplotlib backend for notebook, enable interactive plots
%matplotlib ipympl

from wavesongs.utils.paths import ProjDirs       # project files manager
from wavesongs.objects.song import Song          # song objects
from wavesongs.objects.syllable import Syllable  # syllable objects
from wavesongs.utils import plots                # plotter

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

# define the song and compute its acoustical features
copeton_song = Song(proj_dirs, file_id="574179401")
copeton_song.acoustical_features(umbral_FF=1.4, NN=256)

# display the song
plots.spectrogram_waveform(copeton_song, save=False)

For advanced usage (e.g., custom gestures, parameter tuning), refer to 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 non-linear 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: Sharing wildlife sounds from around the world
• eBird: Macaulay Library. The Cornell Lab of Ornithology (2005)