Metadata-Version: 2.4
Name: bioamla
Version: 0.2.2
Summary: Bioacoustics & Machine Learning Applications
Project-URL: Homepage, https://github.com/jmcmeen/bioamla
Project-URL: Documentation, https://jmcmeen.github.io/bioamla
Project-URL: Source, https://github.com/jmcmeen/bioamla
Project-URL: Changelog, https://github.com/jmcmeen/bioamla/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/jmcmeen/bioamla/issues
Author-email: John McMeen <johnmcmeen@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: audiomentations
Requires-Dist: datasets[audio]
Requires-Dist: evaluate
Requires-Dist: hdbscan>=0.8.0
Requires-Dist: huggingface-hub
Requires-Dist: librosa
Requires-Dist: matplotlib
Requires-Dist: mlflow>=2.0
Requires-Dist: numba
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pyarrow
Requires-Dist: pydub
Requires-Dist: pyinaturalist
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.28.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: scipy
Requires-Dist: sounddevice>=0.4.0
Requires-Dist: soundfile
Requires-Dist: tensorboard
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: torch
Requires-Dist: torchaudio
Requires-Dist: torchvision
Requires-Dist: transformers[torch]>=5.10.2
Requires-Dist: umap-learn>=0.5.0
Provides-Extra: cli
Requires-Dist: click; extra == 'cli'
Requires-Dist: rich; extra == 'cli'
Provides-Extra: dev
Requires-Dist: click; extra == 'dev'
Requires-Dist: mkdocs-click>=0.8; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocs>=1.6; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-mock; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: rich; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# bioamla

[![PyPI version](https://img.shields.io/pypi/v/bioamla.svg)](https://pypi.org/project/bioamla/)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jmcmeen/bioamla/blob/main/LICENSE)
[![CI](https://github.com/jmcmeen/bioamla/actions/workflows/ci.yml/badge.svg)](https://github.com/jmcmeen/bioamla/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-mkdocs--material-blue.svg)](https://jmcmeen.github.io/bioamla)
[![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

A Python library and CLI for **bioacoustics and machine-learning applications** — audio
I/O and signal processing, acoustic indices, event detection, spectrogram visualization,
embedding clustering, species catalogs, datasets, and AST-based ML inference.

> **Prerelease:** 0.2.x is a ground-up rebuild. APIs may still change.

## Design

`bioamla` is organized by **domain**, not by layer. Each domain is a focused subpackage you
import directly:

| Import | What it does |
| --- | --- |
| `bioamla.audio` | audio I/O, analysis, signal processing (filter/denoise/normalize/resample/segment), playback |
| `bioamla.viz` | spectrograms, mel/MFCC, waveform plots |
| `bioamla.indices` | acoustic indices — ACI, ADI, AEI, BIO, NDSI, spectral/temporal entropy |
| `bioamla.detect` | event detection — energy, RIBBIT, peaks, accelerating-pattern |
| `bioamla.cluster` | embedding dimensionality reduction, clustering, novelty detection |
| `bioamla.catalogs` | external catalogs — Xeno-canto, iNaturalist, eBird, Macaulay, HuggingFace |
| `bioamla.datasets` | dataset merge / augment / licensing, annotation conversion, labeled-clip extraction |
| `bioamla.ml` | Audio Spectrogram Transformer (AST) inference, training, embeddings |
| `bioamla.batch` | generic batch engine (directory + CSV-metadata modes) |
| `bioamla.system` | system dependency checks, version & environment info |

Two conventions matter for consumers:

- **Errors are exceptions.** Functions return plain data and raise from a single hierarchy
  rooted at `bioamla.exceptions.BioamlaError` (e.g. `AudioLoadError`, `InvalidInputError`,
  `DependencyError`). Catch the base class to handle everything.
- **Batteries included.** A single `pip install bioamla` installs the full analysis/ML runtime
  stack — audio/signal/indices/detect/viz, the PyTorch + AST ML stack, clustering, and playback.
  Heavy imports are still **lazy**, so `import bioamla` and `bioamla --help` stay fast and don't
  load torch until you actually call a feature that needs it. The command-line interface lives in
  a thin `[cli]` extra (`pip install bioamla[cli]`) — the library never imports it.

## Install

Requires Python ≥ 3.10. Install into a **virtual environment** so bioamla's dependency stack
(PyTorch, librosa, transformers, …) stays isolated from other projects and your system Python:

```bash
python -m venv .venv && source .venv/bin/activate    # or: uv venv / conda create -n bioamla
pip install bioamla                 # the full analysis/ML library

pip install "bioamla[cli]"          # + the `bioamla` command-line interface
pip install "bioamla[dev]"          # + contributor tooling (pytest, ruff, mkdocs; includes [cli])
```

The `bioamla` console command needs the `[cli]` extra; on a library-only install it prints an
install hint pointing you to `pip install bioamla[cli]`.

### System dependencies

Beyond the Python packages, bioamla needs a working **FFmpeg** install on the host:

- **FFmpeg shared libraries (`libav*`), major version 4–8** — used by `torchcodec` (the backend
  behind `torchaudio.load`) to *decode* audio for waveform loading, AST inference/training, and
  HuggingFace dataset materialization.
- **The `ffmpeg`/`ffprobe` CLI** — used by `pydub` to *encode* non-WAV formats (FLAC/MP3/OGG/M4A)
  and to read metadata. (Plain WAV I/O works without FFmpeg.)

Both come from a single FFmpeg install:

```bash
sudo apt-get install -y ffmpeg            # Debian/Ubuntu
sudo dnf install -y ffmpeg-free           # Fedora/RHEL
brew install ffmpeg                        # macOS
conda install -c conda-forge 'ffmpeg<9'    # conda env (no root); pin to a supported major version
```

Run `bioamla system deps` to check what's available. Without FFmpeg, audio decode/encode features
raise a clear error (and the affected tests skip rather than fail).

## Configuration (API keys)

The `bioamla.catalogs` providers need API keys to reach their services:

| Variable | Used by | Get a key |
| --- | --- | --- |
| `EBIRD_API_KEY` | eBird catalog | <https://ebird.org/api/keygen> |
| `XC_API_KEY` | Xeno-canto catalog | <https://xeno-canto.org/account> |
| `HF_TOKEN` | HuggingFace push/pull (datasets, models) | <https://huggingface.co/settings/tokens> |

You can either export these as environment variables, or drop them in a `.env` file in your
working directory — `bioamla` loads it automatically on import (for both the CLI and library
use). A real exported variable always takes precedence over the file.

```bash
# .env
EBIRD_API_KEY=your_key_here
XC_API_KEY=your_key_here
HF_TOKEN=your_token_here
```

Keys are only required for the catalog/HuggingFace features that use them; the rest of the
library works without any configuration.

## Library quickstart

```python
from bioamla.audio import load_audio_data
from bioamla.indices import compute_all_indices
from bioamla.viz import generate_spectrogram
from bioamla.exceptions import BioamlaError

try:
    audio = load_audio_data("recording.wav")          # -> AudioData (mono float32 + sample_rate)

    idx = compute_all_indices(audio.samples, audio.sample_rate, include_entropy=True)
    print(idx.aci, idx.ndsi, idx.h_spectral)

    generate_spectrogram("recording.wav", output_path="spec.png")
except BioamlaError as e:
    print(f"failed: {e}")
```

AST inference:

```python
from bioamla.ml import predict_file
pred = predict_file("frog.wav", model_path="bioamla/scp-frogs")
print(pred.predicted_label, pred.confidence)
```

## CLI quickstart

```bash
bioamla --help                                  # all command groups
bioamla audio info recording.wav                # metadata
bioamla audio filter in.wav out.wav --bandpass-low 500 --bandpass-high 8000
bioamla indices compute recording.wav           # ACI/ADI/AEI/BIO/NDSI + entropy
bioamla detect energy recording.wav             # energy-based detections
bioamla audio visualize recording.wav -o spec.png

# Audio editing transforms (deterministic, single-file):
bioamla audio pitch-shift in.wav out.wav --steps 2
bioamla audio time-stretch in.wav out.wav --rate 1.2
bioamla audio add-noise in.wav out.wav --snr-db 15

# Batch — over a directory or a CSV metadata file (with a `file_name` column):
bioamla batch index --input-dir ./recordings --output-dir ./out
bioamla batch index --input-file meta.csv --output-dir ./out   # merges results into the CSV
bioamla batch audio convert --input-dir ./wavs --output-dir ./flac --format flac

# Catalogs, models, datasets, system:
bioamla catalogs xc search --species "Hyla cinerea"
bioamla catalogs hf pull-dataset ashraq/esc50 ./esc50      # Hub dataset -> labeled-folder layout
bioamla catalogs hf cache --datasets                       # inspect/purge the HF cache (--purge)
bioamla models ast predict frog.wav --model-path bioamla/scp-frogs
bioamla models ast predict soundscape.wav --segment-seconds 3 -o preds.csv   # classify each 3s segment
bioamla models ast train --train-dataset ashraq/esc50      # grab-and-go: train off a Hub id directly
bioamla models ast train --train-dataset ./esc50 --config train.toml   # or from local data + a config
bioamla system deps                                                    # check system deps
```

Every command is self-documenting (`bioamla <group> <command> --help`), and the full
command tree is in the [CLI reference](https://jmcmeen.github.io/bioamla/cli/). The
[API reference](https://jmcmeen.github.io/bioamla/) documents the library.

### Two kinds of augmentation

bioamla keeps a deliberate boundary between **audio editing** and the
**pre-training augmentation layer**:

- **Editing ops** (`bioamla.audio` — `pitch_shift`, `time_stretch`, `add_noise`,
  `apply_gain`, plus filter/denoise/normalize/resample/trim) are deterministic
  single-file transforms you apply with explicit parameters.
- **The augmentation layer** (`bioamla.datasets.create_augmentation_pipeline`) is
  the randomized, range+probability pipeline used both for synthetic dataset
  generation (`dataset augment`) and on-the-fly during `models ast train`.

## Example workflows

Runnable end-to-end studies wired from the CLI live in
[`examples/`](https://github.com/jmcmeen/bioamla/tree/main/examples) — each is a
self-contained shell script (see the [examples README](https://github.com/jmcmeen/bioamla/tree/main/examples#readme)):
catalog → annotate → dataset → train → publish, fine-tuning from a Hub dataset,
soundscape analysis, embedding clustering, and iNaturalist clip inference.

## Development

```bash
make install        # uv sync --extra dev (full stack + tooling)
make test           # pytest
make check          # lint + format-check + test
```

`make install` brings in the full runtime stack plus contributor tooling, so the whole test
suite runs.

## Contributing

Contributions are welcome — see
[CONTRIBUTING.md](https://github.com/jmcmeen/bioamla/blob/main/CONTRIBUTING.md) for setup and
conventions, and the
[Code of Conduct](https://github.com/jmcmeen/bioamla/blob/main/CODE_OF_CONDUCT.md). Security
issues should be reported privately per our
[Security Policy](https://github.com/jmcmeen/bioamla/blob/main/SECURITY.md).

## Citation

If you use `bioamla` in your research, please cite it. Machine-readable metadata lives in
[`CITATION.cff`](https://github.com/jmcmeen/bioamla/blob/main/CITATION.cff) — GitHub's **"Cite this repository"** button generates APA and
BibTeX from it.

Each release is archived on [Zenodo](https://zenodo.org/) with a DOI. Prefer citing the DOI
for the specific version you used; otherwise cite the repository:

```bibtex
@software{mcmeen_bioamla,
  author  = {McMeen, John},
  title   = {bioamla: Bioacoustics \& Machine Learning Applications},
  year    = {2026},
  license = {MIT},
  url     = {https://github.com/jmcmeen/bioamla}
}
```

## License

MIT License — see [LICENSE](https://github.com/jmcmeen/bioamla/blob/main/LICENSE).
