Metadata-Version: 2.4
Name: piafzam
Version: 0.0.2
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: 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`) — plus de valeurs d’équipe en dur dans
`params.py`.

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               # → models/model.keras
make evaluate
make api                 # http://127.0.0.1:8000/docs
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 /species` et `GET /predict?path=/chemin/vers/chant.mp3`.

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
└── 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 pipeline data prep (profil par défaut)
make prepare-smoke       # test A→Z rapide (2 espèces × 2 enregistrements)
make prepare-smoke-plus  # smoke plus large (4×3), timeout 5 min, self-delete
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 job-logs            # suivi
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/). Détail : [docs/JOBS.md](docs/JOBS.md#relancer-un-job--skip-ou-overwrite).

Équivalent : `piafzam job prepare`. Mode d’emploi : [docs/JOBS.md](docs/JOBS.md).
