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

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

2. Configurer les variables d'environnement

cp .env.example .env

Éditer .env et définir :

# 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.

./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

docker-compose up -d

Cela démarre :

• PostgreSQL avec l'extension pgvector (port 5432)
• Backend FastAPI (port 8000)

Vérifier que tout fonctionne :

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

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

5. Lancer le frontend (mode développement)

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)

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 :

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

Option 2 : Via Python (backend local)

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 :

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

Avec filtres :

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

Pistes similaires :

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 :

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") :

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 :

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

Appliquer les migrations :

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

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"

./scripts/download-essentia-models.sh

Frontend ne se connecte pas au backend

Vérifier .env.local :

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 :

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install ffmpeg libsndfile1

📦 Production

Build frontend

cd frontend
npm run build
npm start  # Port 3000

Backend en production

Utiliser Gunicorn avec Uvicorn workers :

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

Reverse proxy (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 :

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

Modifier les features extraites

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

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

# 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 ! 🎵