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

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 :

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

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

./scripts/download-essentia-models.sh

4. Lancer avec Docker

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)

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

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

ANALYSIS_USE_CLAP=true

Parallélisation

Ajuster le nombre de workers pour l'analyse :

ANALYSIS_NUM_WORKERS=4  # Adapter selon votre CPU

Formats supportés

• WAV, MP3, FLAC, M4A, OGG

🔧 Développement

Backend

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

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.