Audio-Classifier/QUICKSTART.md

# 🚀 Démarrage Rapide - Audio Classifier

## En 5 minutes

### 1. Configuration initiale

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

# Copier les variables d'environnement
cp .env.example .env

# IMPORTANT : Éditer .env et définir votre chemin audio
# AUDIO_LIBRARY_PATH=/Users/benoit/Music
nano .env
```

### 2. Télécharger les modèles d'IA

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

Cela télécharge ~300 MB de modèles Essentia pour la classification.

### 3. Lancer le backend

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

Vérifier : http://localhost:8000/health

### 4. Analyser votre bibliothèque

```bash
# Analyser un dossier (remplacer par votre chemin)
curl -X POST http://localhost:8000/api/analyze/folder \
  -H "Content-Type: application/json" \
  -d '{"path": "/audio", "recursive": true}'

# Note: "/audio" correspond à AUDIO_LIBRARY_PATH dans le conteneur
```

Vous recevrez un `job_id`. Suivre la progression :

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

### 5. Lancer le frontend

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

Ouvrir : http://localhost:3000

## 📊 Exemples d'utilisation

### Rechercher des pistes

```bash
# Par texte
curl "http://localhost:8000/api/search?q=jazz"

# Par genre
curl "http://localhost:8000/api/tracks?genre=electronic&limit=10"

# Par BPM
curl "http://localhost:8000/api/tracks?bpm_min=120&bpm_max=140"

# Par ambiance
curl "http://localhost:8000/api/tracks?mood=energetic"
```

### Trouver des pistes similaires

```bash
# 1. Récupérer un track_id
curl "http://localhost:8000/api/tracks?limit=1"

# 2. Trouver des similaires
curl "http://localhost:8000/api/tracks/TRACK_ID/similar?limit=10"
```

### Statistiques

```bash
curl "http://localhost:8000/api/stats"
```

### Écouter / Télécharger

- Stream : http://localhost:8000/api/audio/stream/TRACK_ID
- Download : http://localhost:8000/api/audio/download/TRACK_ID

## 🎯 Ce qui est analysé

Pour chaque fichier audio :

✅ **Tempo** (BPM)
✅ **Tonalité** (C major, D minor, etc.)
✅ **Genre** (50 genres : electronic, jazz, rock, etc.)
✅ **Ambiance** (56 moods : energetic, calm, dark, etc.)
✅ **Instruments** (40 instruments : piano, guitar, drums, etc.)
✅ **Énergie** (score 0-1)
✅ **Danceability** (score 0-1)
✅ **Valence** (positivité émotionnelle)
✅ **Features spectrales** (centroid, zero-crossing, etc.)

## ⚡ Performance

**Sur CPU moderne (4 cores)** :

- ~2-3 secondes par fichier
- Analyse parallèle (4 workers par défaut)
- 1000 fichiers ≈ 40-50 minutes

**Pour accélérer** : Ajuster `ANALYSIS_NUM_WORKERS` dans `.env`

## 📁 Structure

```
Audio Classifier/
├── backend/          # API Python + analyse audio
├── frontend/         # Interface Next.js
├── scripts/          # Scripts utilitaires
├── .env              # Configuration
└── docker-compose.yml
```

## 🔍 Endpoints Principaux

| Endpoint | Méthode | Description |
|----------|---------|-------------|
| `/api/tracks` | GET | Liste des pistes |
| `/api/tracks/{id}` | GET | Détails piste |
| `/api/search` | GET | Recherche textuelle |
| `/api/tracks/{id}/similar` | GET | Pistes similaires |
| `/api/analyze/folder` | POST | Lancer analyse |
| `/api/audio/stream/{id}` | GET | Streaming audio |
| `/api/audio/download/{id}` | GET | Télécharger |
| `/api/stats` | GET | Statistiques |

Documentation complète : http://localhost:8000/docs

## 🐛 Problèmes Courants

**"Connection refused"**
```bash
docker-compose ps  # Vérifier que les services sont up
docker-compose logs backend  # Voir les erreurs
```

**"Model file not found"**
```bash
./scripts/download-essentia-models.sh
ls backend/models/*.pb  # Vérifier présence
```

**Frontend ne charge pas**
```bash
cd frontend
cat .env.local  # Vérifier NEXT_PUBLIC_API_URL
npm install  # Réinstaller dépendances
```

## 📚 Documentation Complète

- **[README.md](README.md)** - Vue d'ensemble du projet
- **[SETUP.md](SETUP.md)** - Guide détaillé d'installation et configuration
- **[.claude-todo.md](.claude-todo.md)** - Détails techniques d'implémentation

## 🎵 Formats Supportés

✅ MP3
✅ WAV
✅ FLAC
✅ M4A
✅ OGG

## 💡 Prochaines Étapes

1. **Analyser votre bibliothèque** : Lancer l'analyse sur vos fichiers
2. **Explorer l'interface** : Naviguer dans les pistes analysées
3. **Tester la recherche** : Filtrer par genre, BPM, mood
4. **Découvrir les similaires** : Trouver des recommandations

Enjoy! 🎶