Audio-Classifier/README.md

# Audio Classifier

Outil de classification audio automatique capable d'indexer et analyser des bibliothèques musicales entières.

## 🎯 Fonctionnalités

- **Analyse audio automatique** : Genre, instruments, tempo (BPM), tonalité, ambiance
- **Classification intelligente** : Utilise Essentia + Librosa pour extraction de features
- **Recherche avancée** : Filtres combinés (genre, mood, BPM, énergie) + recherche textuelle
- **Lecteur audio intégré** : Prévisualisation avec waveform + téléchargement
- **Base de données vectorielle** : PostgreSQL avec pgvector (prêt pour embeddings CLAP)
- **100% local et CPU-only** : Aucune dépendance cloud, fonctionne sur CPU

## 🛠 Stack Technique

### Backend
- **Python 3.11** + FastAPI (API REST async)
- **Librosa** : Extraction features audio (tempo, spectral, chroma)
- **Essentia-TensorFlow** : Classification genre/mood/instruments (modèles pré-entraînés)
- **PostgreSQL + pgvector** : Base de données avec support vectoriel
- **SQLAlchemy** : ORM

### Frontend
- **Next.js 14** + TypeScript
- **TailwindCSS** + shadcn/ui
- **React Query** : Gestion cache API
- **Recharts** : Visualisations

## 📋 Prérequis

- **Docker** + Docker Compose (recommandé)
- Ou manuellement :
  - Python 3.11+
  - Node.js 20+
  - PostgreSQL 16 avec extension pgvector
  - FFmpeg (pour librosa)

## 🚀 Démarrage Rapide

### 1. Cloner et configurer

```bash
git clone <repo>
cd audio-classifier
cp .env.example .env
```

### 2. Configurer l'environnement

Éditer `.env` et définir le chemin vers votre bibliothèque audio :

```env
AUDIO_LIBRARY_PATH=/chemin/vers/vos/fichiers/audio
```

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

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

### 4. Lancer avec Docker

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

L'API sera disponible sur `http://localhost:8000`
La documentation interactive : `http://localhost:8000/docs`

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

```bash
cd frontend
npm install
npm run dev
```

Le frontend sera accessible sur `http://localhost:3000`

## 📖 Utilisation

### Scanner un dossier

#### Via l'interface web
1. Ouvrir `http://localhost:3000`
2. Cliquer sur "Scan Folder"
3. Entrer le chemin : `/audio/votre_dossier`
4. Cocher "Recursive" si nécessaire
5. Lancer l'analyse

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

### Rechercher des pistes

- **Recherche textuelle** : Tapez dans la barre de recherche
- **Filtres** : Genre, mood, BPM, énergie, instruments
- **Similarité** : Cliquez sur "🔍 Similar" sur une piste

### Écouter et télécharger

- **Play** : Lecture directe dans le navigateur avec waveform
- **Download** : Téléchargement du fichier original

## 🏗 Architecture

```
audio-classifier/
├── backend/              # API FastAPI
│   ├── src/
│   │   ├── core/        # Audio processing, classification
│   │   ├── models/      # SQLAlchemy models, CRUD
│   │   ├── api/         # Routes FastAPI
│   │   └── utils/       # Config, logging
│   └── models/          # Essentia models (.pb)
│
├── frontend/            # Next.js UI
│   ├── app/            # Pages
│   ├── components/     # React components
│   ├── lib/            # API client, types
│   └── hooks/          # React hooks
│
└── docker-compose.yml
```

## 🎼 Métadonnées Extraites

### Features Audio
- **Tempo** : BPM détecté
- **Tonalité** : Clé musicale (C major, D minor, etc.)
- **Signature rythmique** : 4/4, 3/4, etc.
- **Énergie** : Intensité sonore (0-1)
- **Valence** : Positivité/négativité (0-1)
- **Danceability** : Dansabilité (0-1)
- **Features spectrales** : Centroid, zero-crossing rate, rolloff

### Classification
- **Genre** : Primary + secondary (50 genres via Essentia)
- **Mood** : Primary + secondary + arousal/valence (56 moods)
- **Instruments** : Liste avec scores de confiance (40 instruments)
- **Voix** : Présence, genre (futur)

## 📊 API Endpoints

### Tracks
- `GET /api/tracks` - Liste des pistes avec filtres
- `GET /api/tracks/{id}` - Détails d'une piste
- `DELETE /api/tracks/{id}` - Supprimer une piste

### Search
- `GET /api/search?q=...&genre=...&mood=...` - Recherche

### Audio
- `GET /api/audio/stream/{id}` - Stream audio
- `GET /api/audio/download/{id}` - Télécharger
- `GET /api/audio/waveform/{id}` - Waveform data

### Analysis
- `POST /api/analyze/folder` - Scanner un dossier
- `GET /api/analyze/status/{job_id}` - Statut d'analyse

### Similar
- `GET /api/tracks/{id}/similar` - Pistes similaires

### Stats
- `GET /api/stats` - Statistiques globales

## ⚙️ Configuration Avancée

### CPU-only vs GPU

Par défaut, le système fonctionne en **CPU-only** pour compatibilité maximale.

Pour activer CLAP embeddings (nécessite plus de RAM/temps) :
```env
ANALYSIS_USE_CLAP=true
```

### Parallélisation

Ajuster le nombre de workers pour l'analyse :
```env
ANALYSIS_NUM_WORKERS=4  # Adapter selon votre CPU
```

### Formats supportés

- WAV, MP3, FLAC, M4A, OGG

## 🔧 Développement

### Backend

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

# Run migrations
alembic upgrade head

# Start dev server
uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000
```

### Frontend

```bash
cd frontend
npm install
npm run dev
```

## 📝 TODO / Améliorations Futures

- [ ] CLAP embeddings pour recherche sémantique ("calm piano for working")
- [ ] Détection voix (homme/femme/choeur)
- [ ] Export batch vers CSV/JSON
- [ ] Création de playlists
- [ ] Détection de doublons (audio fingerprinting)
- [ ] Édition de tags (écriture dans les fichiers)
- [ ] Authentication multi-utilisateurs
- [ ] WebSocket pour progression temps réel

## 📄 Licence

MIT

## 🤝 Contribution

Les contributions sont les bienvenues ! Ouvrir une issue ou PR.

## 📞 Support

Pour toute question ou problème, ouvrir une issue GitHub.