Metadata-Version: 2.3
Name: wavesongs
Version: 0.0.6b1
Summary: A python package for birdsongs creation and data extraction.
License: GPL-3.0
Keywords: numerical methods,motor gestures,birdsongs,syhnthetic songs
Author: saguileran@unal.edu.co
Author-email: saguileran@unal.edu.co
Maintainer: saguileran@unal.edu.co
Maintainer-email: saguileran@unal.edu.co
Requires-Python: >=3.10,<4
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
Classifier: Topic :: Scientific/Engineering :: Physics
Provides-Extra: dev
Provides-Extra: test
Requires-Dist: black ; extra == "dev"
Requires-Dist: ffmpeg (>=1.4,<2.0)
Requires-Dist: ipykernel (>=6.29.5,<7.0.0)
Requires-Dist: ipykernel ; extra == "dev"
Requires-Dist: ipympl (>=0.9.6,<0.10.0)
Requires-Dist: librosa (>=0.10.2.post1,<0.11.0)
Requires-Dist: llvmlite (>=0.44.0,<0.45.0)
Requires-Dist: matplotlib (==3.9.0)
Requires-Dist: mpl-pan-zoom (>=1.0.0,<2.0.0)
Requires-Dist: mpl-point-clicker (>=0.4.1,<0.5.0)
Requires-Dist: notebook (>=7.3.2,<8.0.0)
Requires-Dist: numpy (==2.1.3)
Requires-Dist: pandas (>=2.2.3,<3.0.0)
Requires-Dist: peakutils (>=1.3.5,<2.0.0)
Requires-Dist: plotly (>=6.0.0,<7.0.0)
Requires-Dist: poetry ; extra == "dev"
Requires-Dist: pytest (>=7) ; extra == "test"
Requires-Dist: scikit-learn (>=1.6.1,<2.0.0)
Requires-Dist: scikit-maad (>=1.4.3,<2.0.0)
Requires-Dist: sympy (>=1.13.3,<2.0.0)
Project-URL: Documentation, https://wavesongs.github.io/wavesongs/
Project-URL: Homepage, https://wavesongs.github.io/
Project-URL: Repository, https://github.com/wavesongs/wavesongs/
Description-Content-Type: text/markdown

<div align='center' style="margin: 20px 0 0px 0">
   <img src="./assets/logo.png" alt="WaveSongs logo" style="max-width: 100%; height: 200px;">

   <div class="text-container" style="flex: 2;">
      <h1 style="margin: 0; padding: 10px 0 0px 0; border-bottom: 0">WaveSongs</h1>
      <p style="margin: 0; padding: 0px 0 10px 0;">A Python package for birdsong synthesis and bioacoustic analysis</p>
   </div> 
</div>

<div align='center' style="margin: 20px 0 50px 0">

![version](https://img.shields.io/badge/Version-0.0.4b1-darkgreen.svg)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Made with Python](https://img.shields.io/badge/Python->=3.10-blue?logo=python&logoColor=white)](https://python.org "Go to Python homepage")
![Open Source](https://badges.frapsoft.com/os/v2/open-source.svg?v=103)
[![Documentation](https://readthedocs.org/projects/ansicolortags/badge/?version=latest)](https://wavesongs.github.io/wavesongs/)


[Installation](#️-installation) •
[Quick Start](#-gettint-started) •
[Contribute](#-contribute) •
[References](#-references)


</div>

---


WaveSongs implements the [motor gestures model for birdsong](http://www.lsd.df.uba.ar/papers/simplemotorgestures.pdf) developed by [Gabo Mindlin](https://scholar.google.com.ar/citations?user=gMzZPngAAAAJ&hl=en) to generate synthetic birdsongs through numerical optimization [[1](#1), [2](#2)] 
. By leveraging **fundamental frequency (FF)** and **spectral content index (SCI)** as key parameters, the package solves a minimization problem using [SciPy](https://docs.scipy.org/doc/scipy/tutorial/optimize.html) and performs audio analysis with [librosa](https://librosa.org/) and [scikit-maad](https://github.com/scikit-maad/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](https://www.python.org/) ≥ 3.10
- [Git](https://git-scm.com/)

### Steps

1. **Clone the repository**:
   ```bash
   git clone https://github.com/wavesongs/wavesongs
   cd wavesongs
   ```

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

   #### Using `venv`
   ```bash
   python -m venv venv
   ```

   #### Using Conda
   ```bash
   conda create -n wavesongs python=3.12
   conda activate wavesongs
   ```

3. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

4. **Install WaveSongs** in editable mode:
   ```bash
   pip install -e .
   ```

## 🚀 Gettint Started

Explore the [Tutorial 1 Notebook](https://github.com/wavesongs/wavesongs/blob/main/Tutorial1_Introduction.ipynb) 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](https://github.com/wavesongs/wavesongs/blob/main/Tutorial2_SpectrumMeasures.ipynb) or [Synthetic Songs](https://github.com/wavesongs/wavesongs/blob/main/Tutorial3_SyntheticSongs.ipynb). More details can be found in the [Documentation](https://wavesongs.github.io/doc).


## 🎶 Data Integration

Pre-processed field recordings from [Xeno Canto](https://xeno-canto.org/) and [eBird](https://ebird.org/home) 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](./LICENSE).

## 📒 Citation

If this work contributes to your research, please cite:

```bibtex
@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](https://github.com/wavesongs/wavesongs/issues).


## 📚 References


<a id="1" style="color:#318bf8;">[1]</a>  Mindlin, G. B., & Laje, R. (2005). *The Physics of Birdsong*. Springer. [DOI](https://doi.org/10.1007/3-540-28249-1)

<a id="1" style="color:#318bf8;">[2]</a>  Amador, A., et al. (2013). Elemental gesture dynamics in song premotor neurons. *Nature*. [DOI](https://doi.org/10.1038/nature11967)

