Metadata-Version: 2.4
Name: yaaat
Version: 0.2.1
Summary: YAAAT! Yet Another Audio Annotation Tool. Interactive bioacoustic annotation tool for measuring vocalizations
Author: laelume
License-Expression: MIT
Project-URL: Homepage, https://github.com/laelume/yaaat
Project-URL: Repository, https://github.com/laelume/yaaat
Keywords: bioacoustic,acoustic,ecoacoustic,soundscape,annotation,audio annotation,annotation tool,signal processing,audio analysis,time frequency representation,tfr,spectrogram,spectral analysis,speech analysis,vocalization,animal communications,communication,interactive,visualization,toolkit,changepoint,nonlinear,nonlinear phenomena,nlp
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: natsort
Requires-Dist: pandas
Requires-Dist: pysoniq>=0.1.8
Provides-Extra: ai
Requires-Dist: birdnet; extra == "ai"
Dynamic: license-file

# YAAAT! Yet Another Audio Annotation Tool

Interactive bioacoustic annotation tool for measuring animal vocalizations. 

Features: 
1. Changepoint Annotator, for marking temporal onset, offset, and changepoints in vocalizations. Useful for describing rapid fluctuations and identifying nonlinear phenomena. 
2. Peak Annotator, for marking dominant frequency peaks on the power spectrum. Useful for describing spectrally complex vocalizations. 
3. Harmonic Annotator, for identifying harmonics. 
4. Batch Annotator, for multi-file review and defining binary and multi-label annotation schema
<table>
  <tr>
    <td><img src="https://raw.githubusercontent.com/laelume/yaaat/main/yaaat/images/changepoint_annotator_screenshot.jpg" alt="Changepoint Annotator" width="400"/></td>
    <td><img src="https://raw.githubusercontent.com/laelume/yaaat/main/yaaat/images/peak_annotator_screenshot.jpg" alt="Peak Annotator" width="400"/></td>
    <td><img src="https://raw.githubusercontent.com/laelume/yaaat/main/yaaat/images/harmonic_annotator_screenshot.jpg" alt="Harmonic Annotator" width="400"/></td>
  </tr>
  <tr>
    <td align="center">Changepoint Annotator</td>
    <td align="center">Peak Annotator</td>
    <td align="center">Harmonic Annotator</td>
    <td align="center">Batch Annotator</td>
  </tr>
</table>

## Installation

```bash
pip install yaaat
```

## WIP: 
Optional detection/classification backend:

```bash
pip install yaaat[ai]
```

---

## Requirements

- Python 3.9+
- numpy, scipy, matplotlib, natsort, pandas
- pysoniq (custom minimal audio I/O)
- ffmpeg (adds MP3 support via pysoniq, optional)

---

## Usage

Launches the full 4-tab interface:
```bash
yaaat
```


From the local directory: 
```bash
python -m yaaat
```

From Python command line:

```python
from yaaat import main
main()
```

---

## Tabs

#### Base Annotator
Spectrogram and waveform viewer. No annotation logic. Shared point
annotation API available for programmatic use.

#### Changepoint Annotator
Click-to-add contour points for syllable segmentation. Supports lasso
selection, Ctrl+Click dual-endpoint marking, harmonic bounding boxes,
skip file dialog, and find-next-skipped navigation.

#### Peak Annotator
Dual-resolution display — vertical spectrogram (temporal resolution)
with PSD overlay (frequency resolution). Click-to-mark spectral peaks.
Auto-detection with prominence threshold.

#### Harmonic Annotator
Auto-detects F0 from mean spectrum. Builds harmonic series with
draggable correction lines. Computes inter-harmonic valley boundaries
(min energy search) for spectral band visualization. Multiple ridge
detection methods: max, peaks, centroid, parabolic, peak ratio.

#### Batch Annotator
Paginated grid view of mel spectrograms across a dataset. Define named
batch annotation columns (e.g. has_noise, has_bifurcation). Batch
annotate selected files True/False. Export to CSV.




## Copyright and License
Copyright 2025-2026 laelume aka Ashlae Blum'e. Licensed under MIT License.

Please ⭐ or follow us if you enjoy this work !! 

To cite the repository:

@software{blume2025yaaat,
  author       = {Ashlae Blum'e},
  title        = {{YAAAT: Yet Another Audio Annotation Tool}},
  year         = {2025},
  url          = {https://github.com/laelume/yaaat},
  version      = {0.2.0},
  note         = {GitHub repository}
}

To cite the paper:

@article{blume2026yaaat,
  author  = {Ashlae Blum'e},
  title   = {{YAAAT! Yet Another Audio Annotation Tool}},
  year    = {2026},
  url     = {https://hal.science/hal-05638791v2},
  note    = {HAL preprint, version 2}
}
