Audio-Classifier/SETUP.md

# Audio Classifier - Guide de Déploiement

## 📋 Prérequis

- **Docker** & Docker Compose
- **Node.js** 20+ (pour le frontend en mode dev)
- **Python** 3.11+ (optionnel, si vous voulez tester le backend sans Docker)
- **FFmpeg** (installé automatiquement dans le conteneur Docker)

## 🚀 Installation Rapide

### 1. Cloner le projet

```bash
cd "/Users/benoit/Documents/code/Audio Classifier"
```

### 2. Configurer les variables d'environnement

```bash
cp .env.example .env
```

Éditer `.env` et définir :

```env
# Chemin vers votre bibliothèque audio (IMPORTANT)
AUDIO_LIBRARY_PATH=/chemin/absolu/vers/vos/fichiers/audio

# Exemple macOS:
# AUDIO_LIBRARY_PATH=/Users/benoit/Music

# Le reste peut rester par défaut
DATABASE_URL=postgresql://audio_user:audio_password@localhost:5432/audio_classifier
```

### 3. Télécharger les modèles Essentia

Les modèles de classification sont nécessaires pour analyser les fichiers audio.

```bash
./scripts/download-essentia-models.sh
```

Cela télécharge (~300 MB) :
- `mtg_jamendo_genre` : Classification de 50 genres musicaux
- `mtg_jamendo_moodtheme` : Classification de 56 ambiances/moods
- `mtg_jamendo_instrument` : Détection de 40 instruments

### 4. Lancer le backend avec Docker

```bash
docker-compose up -d
```

Cela démarre :
- **PostgreSQL** avec l'extension pgvector (port 5432)
- **Backend FastAPI** (port 8000)

Vérifier que tout fonctionne :

```bash
curl http://localhost:8000/health
# Devrait retourner: {"status":"healthy",...}
```

Documentation API interactive : **http://localhost:8000/docs**

### 5. Lancer le frontend (mode développement)

```bash
cd frontend
cp .env.local.example .env.local
npm install
npm run dev
```

Frontend accessible sur : **http://localhost:3000**

## 📊 Utiliser l'Application

### Analyser votre bibliothèque audio

**Option 1 : Via l'API (recommandé pour première analyse)**

```bash
curl -X POST http://localhost:8000/api/analyze/folder \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/audio",
    "recursive": true
  }'
```

**Note** : Le chemin `/audio` correspond au montage Docker de `AUDIO_LIBRARY_PATH`.

Vous recevrez un `job_id`. Vérifier la progression :

```bash
curl http://localhost:8000/api/analyze/status/JOB_ID
```

**Option 2 : Via Python (backend local)**

```bash
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Analyser un fichier
python -c "
from src.core.analyzer import AudioAnalyzer
analyzer = AudioAnalyzer()
result = analyzer.analyze_file('/path/to/audio.mp3')
print(result)
"
```

### Rechercher des pistes

**Par texte :**

```bash
curl "http://localhost:8000/api/search?q=jazz&limit=10"
```

**Avec filtres :**

```bash
curl "http://localhost:8000/api/tracks?genre=electronic&bpm_min=120&bpm_max=140&limit=20"
```

**Pistes similaires :**

```bash
curl "http://localhost:8000/api/tracks/TRACK_ID/similar?limit=10"
```

### Télécharger / Écouter

- **Stream** : `http://localhost:8000/api/audio/stream/TRACK_ID`
- **Download** : `http://localhost:8000/api/audio/download/TRACK_ID`
- **Waveform** : `http://localhost:8000/api/audio/waveform/TRACK_ID`

## 🏗️ Architecture

```
audio-classifier/
├── backend/                  # API Python FastAPI
│   ├── src/
│   │   ├── core/            # Audio processing
│   │   │   ├── audio_processor.py      # Librosa features
│   │   │   ├── essentia_classifier.py  # Genre/Mood/Instruments
│   │   │   ├── waveform_generator.py   # Peaks pour UI
│   │   │   ├── file_scanner.py         # Scan dossiers
│   │   │   └── analyzer.py             # Orchestrateur
│   │   ├── models/          # Database
│   │   │   ├── schema.py               # SQLAlchemy models
│   │   │   └── crud.py                 # CRUD operations
│   │   ├── api/             # FastAPI routes
│   │   │   └── routes/
│   │   │       ├── tracks.py           # GET/DELETE tracks
│   │   │       ├── search.py           # Recherche
│   │   │       ├── audio.py            # Stream/Download
│   │   │       ├── analyze.py          # Jobs d'analyse
│   │   │       ├── similar.py          # Recommandations
│   │   │       └── stats.py            # Statistiques
│   │   └── utils/           # Config, logging, validators
│   ├── models/              # Essentia .pb files
│   └── requirements.txt
│
├── frontend/                # UI Next.js
│   ├── app/
│   │   ├── page.tsx        # Page principale
│   │   └── layout.tsx
│   ├── components/
│   │   └── providers/
│   ├── lib/
│   │   ├── api.ts          # Client API
│   │   ├── types.ts        # TypeScript types
│   │   └── utils.ts        # Helpers
│   └── package.json
│
├── scripts/
│   └── download-essentia-models.sh
│
└── docker-compose.yml
```

## 🔧 Configuration Avancée

### Performance CPU

Le système est optimisé pour CPU-only. Sur un CPU moderne (4 cores) :

- **Librosa features** : ~0.5-1s par fichier
- **Essentia classification** : ~1-2s par fichier
- **Total** : ~2-3s par fichier

Ajuster le parallélisme dans `.env` :

```env
ANALYSIS_NUM_WORKERS=4  # Nombre de threads parallèles
```

### Activer les embeddings CLAP (optionnel)

Pour la recherche sémantique avancée ("calm piano for working") :

```env
ANALYSIS_USE_CLAP=true
```

**Attention** : Augmente significativement le temps d'analyse (~5-10s supplémentaires par fichier).

### Base de données

Par défaut, PostgreSQL tourne dans Docker. Pour utiliser une DB externe :

```env
DATABASE_URL=postgresql://user:pass@external-host:5432/dbname
```

Appliquer les migrations :

```bash
cd backend
alembic upgrade head
```

## 📊 Données Extraites

### Features Audio (Librosa)
- **Tempo** : BPM détecté automatiquement
- **Tonalité** : Clé musicale (C major, D minor, etc.)
- **Signature rythmique** : 4/4, 3/4, etc.
- **Énergie** : Intensité sonore (0-1)
- **Danceability** : Score de dansabilité (0-1)
- **Valence** : Positivité/négativité émotionnelle (0-1)
- **Features spectrales** : Centroid, rolloff, bandwidth

### Classification (Essentia)
- **Genre** : 50 genres possibles (rock, electronic, jazz, etc.)
- **Mood** : 56 ambiances (energetic, calm, dark, happy, etc.)
- **Instruments** : 40 instruments détectables (piano, guitar, drums, etc.)

## 🐛 Troubleshooting

### Le backend ne démarre pas

```bash
docker-compose logs backend
```

Vérifier que :
- PostgreSQL est bien démarré (`docker-compose ps`)
- Les modèles Essentia sont téléchargés (`ls backend/models/*.pb`)
- Le port 8000 n'est pas déjà utilisé

### "Model file not found"

```bash
./scripts/download-essentia-models.sh
```

### Frontend ne se connecte pas au backend

Vérifier `.env.local` :

```env
NEXT_PUBLIC_API_URL=http://localhost:8000
```

### Analyse très lente

- Réduire `ANALYSIS_NUM_WORKERS` si CPU surchargé
- Désactiver `ANALYSIS_USE_CLAP` si activé
- Vérifier que les fichiers audio sont accessibles rapidement (éviter NAS lents)

### Erreur FFmpeg

FFmpeg est installé automatiquement dans le conteneur Docker. Si vous lancez le backend en local :

```bash
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install ffmpeg libsndfile1
```

## 📦 Production

### Build frontend

```bash
cd frontend
npm run build
npm start  # Port 3000
```

### Backend en production

Utiliser Gunicorn avec Uvicorn workers :

```bash
pip install gunicorn
gunicorn src.api.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
```

### Reverse proxy (Nginx)

```nginx
server {
    listen 80;
    server_name your-domain.com;

    location /api {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location / {
        proxy_pass http://localhost:3000;
    }
}
```

## 🔒 Sécurité

**IMPORTANT** : Le système actuel n'a PAS d'authentification.

Pour la production :
- Ajouter authentication JWT
- Limiter l'accès aux endpoints d'analyse
- Valider tous les chemins de fichiers (déjà fait côté backend)
- Utiliser HTTPS
- Restreindre CORS aux domaines autorisés

## 📝 Développement

### Ajouter un nouveau genre/mood

Éditer `backend/src/core/essentia_classifier.py` :

```python
self.class_labels["genre"] = [
    # ... genres existants
    "nouveau_genre",
]
```

### Modifier les features extraites

Éditer `backend/src/core/audio_processor.py` et ajouter votre fonction :

```python
def extract_new_feature(y, sr) -> float:
    # Votre logique
    return feature_value
```

Puis mettre à jour `extract_all_features()`.

### Ajouter une route API

1. Créer `backend/src/api/routes/nouvelle_route.py`
2. Ajouter le router dans `backend/src/api/main.py`

### Tests

```bash
# Backend
cd backend
pytest

# Frontend
cd frontend
npm test
```

## 📈 Améliorations Futures

- [ ] Interface de scan dans le frontend (actuellement via API seulement)
- [ ] Player audio intégré avec waveform interactive
- [ ] Filtres avancés (multi-genre, range sliders)
- [ ] Export playlists (M3U, CSV, JSON)
- [ ] Détection de doublons (audio fingerprinting)
- [ ] Édition de tags ID3
- [ ] Recherche sémantique avec CLAP
- [ ] Authentication multi-utilisateurs
- [ ] WebSocket pour progression temps réel

## 🆘 Support

Pour toute question :
1. Vérifier les logs : `docker-compose logs -f backend`
2. Consulter la doc API : http://localhost:8000/docs
3. Ouvrir une issue GitHub

Bon classement ! 🎵