Metadata-Version: 2.4
Name: piafzam
Version: 0.0.3
Summary: Reconnaissance de chants d'oiseaux
Author: ElGrandeSosoo
License-Expression: MIT
Project-URL: Homepage, https://github.com/ElGrandeSosoo/piafzam_project
Project-URL: Repository, https://github.com/ElGrandeSosoo/piafzam_project
Project-URL: Issues, https://github.com/ElGrandeSosoo/piafzam_project/issues
Keywords: birds,audio,xeno-canto,spectrograms
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-dotenv
Requires-Dist: requests
Requires-Dist: numpy
Requires-Dist: librosa
Requires-Dist: pillow
Requires-Dist: mutagen
Requires-Dist: scikit-learn
Requires-Dist: matplotlib
Requires-Dist: google-cloud-storage
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: python-multipart
Requires-Dist: pyyaml
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Provides-Extra: train
Requires-Dist: tensorflow>=2.16; extra == "train"
Dynamic: license-file

# PIAFZAM

Reconnaissance de chants d'oiseaux (35 espèces européennes) à partir
d'enregistrements [Xeno-canto](https://xeno-canto.org/).

Paquet Python `piafzam`, Python 3.10–3.12.

Comment le code est organisé : **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
Index de la doc : [docs/README.md](docs/README.md).

## Installation

```bash
pip install piafzam
```

Pour le développement local :

```bash
cp .env.sample .env
pip install -e ".[dev]"
make test
```

Pour entraîner le modèle : `pip install tensorflow`.

Depuis GitHub : `pip install "git+https://github.com/ElGrandeSosoo/piafzam_project.git"`.

Dans `.env` : `XENO_CANTO_API_KEY` et `GOOGLE_APPLICATION_CREDENTIALS`.
Le bucket, les filtres Xeno-canto et les chemins dataset se configurent
dans `.env` (voir `.env.sample`).

Le chemin `data/` / `models/` se déduit du clone. Après un `pip install`
classique, le fixer avec `PIAFZAM_ROOT`.

## Usage

```bash
piafzam species
make preprocess          # data/raw → spectrogrammes locaux
make train               # VM : CNN → dataset/models/ (puis self-delete)
piafzam train            # train local (même dataset GCS)
make evaluate
make api                 # http://0.0.0.0:8000/docs
make listen              # HTTPS Shazam (smartphone WiFi)
make test
```

```python
from piafzam.data.xeno_canto import download_species
from piafzam.ml_logic.preprocessor import load_audio, to_melspectrogram
from piafzam.interface.main import pred

download_species("Turdus merula", "data/raw/merle_noir")
y, sr = load_audio("data/raw/merle_noir/xc123.mp3")
spec = to_melspectrogram(y, sr)
pred("chemin/vers/chant.mp3")
```

API : `GET /` (écoute BirdNET), `POST /listen/predict`, `GET /species`,
`GET /predict?path=/chemin/vers/chant.mp3` (CNN PIAFZAM).

Préparation du dataset sur GCS : `make prepare` (pas `piafzam trim` —
voir [architecture, CLI](docs/ARCHITECTURE.md#cli-piafzam)).

## Structure

```
piafzam_project/
├── docs/
│   ├── ARCHITECTURE.md         # packages, fonctions, flux
│   ├── JOBS.md                 # lancer / suivre les jobs VM
│   ├── NOMENCLATURE.md         # suffixes fichiers / chemins bucket
│   └── DATASET_INVENTORY.md    # schéma de l'inventaire global
├── piafzam/
│   ├── params.py               # espèces, chemins GCS, variantes spectro
│   ├── audio/                  # DSP : trim, fragments, flaques
│   ├── data/                   # GCS, Xeno-canto, spectrogrammes
│   ├── jobs/<nom>/             # un dossier par traitement batch
│   ├── ml_logic/               # preprocessor, CNN, chargement
│   ├── interface/main.py       # preprocess / train / evaluate / pred
│   └── api/fast.py             # FastAPI
├── scripts/                    # boot VM (startup.sh), GIF démo
├── data/raw                    # audios locaux
├── data/processed              # spectrogrammes locaux
├── models/                     # artefacts entraînés (local)
└── tests/
```

Détail des appels entre modules : [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## VM éphémère (GCP)

Une VM traite le bucket, puis **se détruit toute seule** (plus de facturation).

Une fois : `gcloud auth login`. Dans `.env`, `COMPUTE_PROJECT` et
`GCLOUD_ACCOUNT` si ce n’est pas déjà le compte / projet gcloud actifs.

```bash
make job                 # liste
make prepare             # mega : trim → … → spectro → train → inventory
make prepare-smoke       # smoke A→Z : prep + train (models/smoke_test/)
make prepare-smoke-plus  # smoke prep only (4×3), timeout 5 min
make split               # découpe audio (job isolé)
make silence             # JSON sidecar _s / _ns
make trim                # coupe silences de bord
make flaques             # flaques PNG HD (fixe) ; FLAQUES_MODE=gif pour l'animé
make spectro             # PNG + NPY (SPLIT_SEC=3|5|8)
make train               # CNN NPY → dataset/models/ (self-delete)
make job-progress        # snapshot % global + étapes
make job-logs            # suivi live
make job-status          # résultat (écrit à la fin, avant destruction)
```

Relancer : par défaut les fichiers déjà produits sont **sautés** ;
`PREPARE_OVERWRITE=1 make prepare` pour **tout régénérer**.
Le mega process produit aussi `dataset/dataset_inventory.json` (index global
audio/ + img/) et les CNN sous `dataset/models/`.

Détail : [docs/JOBS.md](docs/JOBS.md).
