<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">
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://python.org "Go to Python homepage")
[](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)
Raw data
{
"_id": null,
"home_page": "https://wavesongs.github.io/",
"name": "wavesongs",
"maintainer": "saguileran@unal.edu.co",
"docs_url": null,
"requires_python": "<4,>=3.10",
"maintainer_email": "saguileran@unal.edu.co",
"keywords": "numerical methods, motor gestures, birdsongs, syhnthetic songs",
"author": "saguileran@unal.edu.co",
"author_email": "saguileran@unal.edu.co",
"download_url": "https://files.pythonhosted.org/packages/65/48/c1f14211bed981991925cffc056e526bc783c7ccffbc1204bdc4eb669312/wavesongs-0.0.5b1.tar.gz",
"platform": null,
"description": "<div align='center' style=\"margin: 20px 0 0px 0\">\n <img src=\"./assets/logo.png\" alt=\"WaveSongs logo\" style=\"max-width: 100%; height: 200px;\">\n\n <div class=\"text-container\" style=\"flex: 2;\">\n <h1 style=\"margin: 0; padding: 10px 0 0px 0; border-bottom: 0\">WaveSongs</h1>\n <p style=\"margin: 0; padding: 0px 0 10px 0;\">A Python package for birdsong synthesis and bioacoustic analysis</p>\n </div> \n</div>\n\n<div align='center' style=\"margin: 20px 0 50px 0\">\n\n\n[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://python.org \"Go to Python homepage\")\n\n[](https://wavesongs.github.io/wavesongs/)\n\n\n[Installation](#\ufe0f-installation) \u2022\n[Quick Start](#-gettint-started) \u2022\n[Contribute](#-contribute) \u2022\n[References](#-references)\n\n\n</div>\n\n---\n\n\nWaveSongs 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)] \n. 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).\n\nValidated against field recordings of *Zonotrichia Capensis*, *Ocellated Tapaculo*, and *Mimus Gilvus*, the model achieves **<5% relative error in FF reconstruction** compared to empirical data.\n\n## \u2692\ufe0f Installation\n\n### Prerequisites\n\n- [Python](https://www.python.org/) \u2265 3.10\n- [Git](https://git-scm.com/)\n\n### Steps\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/wavesongs/wavesongs\n cd wavesongs\n ```\n\n2. **Set up a virtual environment** (choose one method):\n\n #### Using `venv`\n ```bash\n python -m venv venv\n ```\n\n #### Using Conda\n ```bash\n conda create -n wavesongs python=3.12\n conda activate wavesongs\n ```\n\n3. **Install dependencies**:\n ```bash\n pip install -r requirements.txt\n ```\n\n4. **Install WaveSongs** in editable mode:\n ```bash\n pip install -e .\n ```\n\n## \ud83d\ude80 Gettint Started\n\nExplore the [Tutorial 1 Notebook](https://github.com/wavesongs/wavesongs/blob/main/Tutorial1_Introduction.ipynb) to generate synthetic birdsongs and explore the model plots. \n\n\nFor 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).\n\n\n## \ud83c\udfb6 Data Integration\n\nPre-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.\n\n\n## \ud83d\udd10 License\n\nWaveSongs is licensed under the [GNU General Public License v3.0](./LICENSE).\n\n## \ud83d\udcd2 Citation\n\nIf this work contributes to your research, please cite:\n\n```bibtex\n@software{aguilera_wavesongs_2025,\n author = {Aguilera Novoa, Sebasti\u00e1n},\n title = {WaveSongs: Computational Birdsong Synthesis},\n year = {2025},\n publisher = {GitHub},\n journal = {GitHub Repository},\n url = {https://github.com/wavesongs/wavesongs}\n}\n```\n\n\n## \ud83c\udf31 Contribute\n\nWe welcome contributions! See our roadmap:\n\n- [ ] **Integrate Xeno Canto API** for direct dataset downloads.\n- [ ] **Add ROIs analysis** using `scikit-maad`. This will allo automatic syllables detection and gerenration.\n- [ ] **Improve FF parametrization** for small motor gestures, chunks.\n\nTo report issues or suggest features, open a [GitHub Issue](https://github.com/wavesongs/wavesongs/issues).\n\n\n## \ud83d\udcda References\n\n\n<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)\n\n<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)\n",
"bugtrack_url": null,
"license": "GPL-3.0",
"summary": "A python package for birdsongs creation and data extraction.",
"version": "0.0.5b1",
"project_urls": {
"Documentation": "https://wavesongs.github.io/wavesongs/",
"Homepage": "https://wavesongs.github.io/",
"Repository": "https://github.com/wavesongs/wavesongs/"
},
"split_keywords": [
"numerical methods",
" motor gestures",
" birdsongs",
" syhnthetic songs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ffd4084ef34e4e8bbb6a749a99f91f408afe76fb1fb7bcff20cf03e803e6d7c3",
"md5": "9a9f589dda24ffbfb073976b75586f35",
"sha256": "9ea551ab2e929106f57ffcede3477b660687db1cf6bbe9cecf1f57514314b90f"
},
"downloads": -1,
"filename": "wavesongs-0.0.5b1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9a9f589dda24ffbfb073976b75586f35",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 47161,
"upload_time": "2025-02-19T06:55:06",
"upload_time_iso_8601": "2025-02-19T06:55:06.018918Z",
"url": "https://files.pythonhosted.org/packages/ff/d4/084ef34e4e8bbb6a749a99f91f408afe76fb1fb7bcff20cf03e803e6d7c3/wavesongs-0.0.5b1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6548c1f14211bed981991925cffc056e526bc783c7ccffbc1204bdc4eb669312",
"md5": "b8f4c85f04bde435b47645ac57095c79",
"sha256": "381d38e6df431aced516066a4442eaec5579dc2494a42e803d6bc6425db06bca"
},
"downloads": -1,
"filename": "wavesongs-0.0.5b1.tar.gz",
"has_sig": false,
"md5_digest": "b8f4c85f04bde435b47645ac57095c79",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 43799,
"upload_time": "2025-02-19T06:55:07",
"upload_time_iso_8601": "2025-02-19T06:55:07.862088Z",
"url": "https://files.pythonhosted.org/packages/65/48/c1f14211bed981991925cffc056e526bc783c7ccffbc1204bdc4eb669312/wavesongs-0.0.5b1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-19 06:55:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wavesongs",
"github_project": "wavesongs",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "llvmlite",
"specs": [
[
">=",
"0.44.0"
],
[
"<",
"0.45.0"
]
]
},
{
"name": "librosa",
"specs": [
[
"<",
"0.11.0"
],
[
">=",
"0.10.2.post1"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"2.1.3"
]
]
},
{
"name": "matplotlib",
"specs": [
[
"<",
"4.0.0"
],
[
">=",
"3.10.0"
]
]
},
{
"name": "ffmpeg",
"specs": [
[
"<",
"2.0"
],
[
">=",
"1.4"
]
]
},
{
"name": "ipykernel",
"specs": [
[
"<",
"7.0.0"
],
[
">=",
"6.29.5"
]
]
},
{
"name": "mpl_pan_zoom",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "mpl_point_clicker",
"specs": [
[
">=",
"0.4.1"
]
]
},
{
"name": "pandas",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"2.2.3"
]
]
},
{
"name": "peakutils",
"specs": [
[
"<",
"2.0.0"
],
[
">=",
"1.3.5"
]
]
},
{
"name": "sympy",
"specs": [
[
"<",
"2.0.0"
],
[
">=",
"1.13.3"
]
]
},
{
"name": "scikit_maad",
"specs": [
[
"<",
"2.0.0"
],
[
">=",
"1.4.3"
]
]
},
{
"name": "scikit_learn",
"specs": [
[
"<",
"2.0.0"
],
[
">=",
"1.6.1"
]
]
},
{
"name": "plotly",
"specs": [
[
">=",
"6.0.0"
],
[
"<",
"7.0.0"
]
]
},
{
"name": "ipympl",
"specs": [
[
">=",
"0.9.6"
],
[
"<",
"0.10.0"
]
]
}
],
"lcname": "wavesongs"
}
JSON
