256 lines
7.1 KiB
Markdown
256 lines
7.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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](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).
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
curl -X POST http://localhost:8001/api/analyze/folder \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"path": "/audio/music", "recursive": true}'
|
|
```
|
|
#### Sous Windows 10
|
|
````bash
|
|
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) :
|
|
```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.
|