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 - 100% Autonome !

Installation en 3 commandes

# 1. Cloner le projet
git clone https://git.benoitsz.com/benoit/Audio-Classifier.git
cd Audio-Classifier

# 2. Configurer le chemin audio (optionnel)
echo "AUDIO_LIBRARY_PATH=/chemin/vers/votre/musique" > .env

# 3. Démarrer !
docker-compose up -d

C'est tout ! 🎉

Les images Docker sont automatiquement téléchargées depuis le registry Gitea.

• Frontend : http://localhost:3000
• API : http://localhost:8001
• API Docs : http://localhost:8001/docs

Premier scan

1. Ouvrir http://localhost:3000
2. Cliquer sur "Rescan" dans le header
3. Attendre la fin du scan
4. Profiter de votre bibliothèque musicale indexée !

✨ Particularités

• Images pré-construites : Téléchargées automatiquement depuis git.benoitsz.com
• Modèles inclus : Les modèles Essentia (28 MB) sont intégrés dans l'image
• Aucune configuration : Tout fonctionne out-of-the-box
• Transcodage automatique : MP3 128kbps créés pour streaming rapide
• Waveforms pré-calculées : Chargement instantané

📖 Documentation complète : Voir DEPLOYMENT.md

🛠 Build local (développement)

Si vous voulez builder les images localement, les modèles Essentia doivent être présents dans backend/models/ (28 MB).

# Build avec docker-compose
docker-compose -f docker-compose.build.yml build
docker-compose -f docker-compose.build.yml up -d

Note : Les modèles Essentia (.pb, 28 MB) ne sont pas versionnés dans Git. Le workflow CI/CD les télécharge automatiquement depuis essentia.upf.edu pendant le build.

📖 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:8001/api/analyze/folder \
  -H "Content-Type: application/json" \
  -d '{"path": "/audio/music", "recursive": true}'

Sous Windows 10

curl.exe -X POST http://localhost:8001/api/analyze/folder -H "Content-Type: application/json" -d '{\"path\": \"/audio/\", \"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.