242 lines
6.1 KiB
Markdown
242 lines
6.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
|
|
|
|
### 1. Cloner et configurer
|
|
|
|
```bash
|
|
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 :
|
|
|
|
```env
|
|
AUDIO_LIBRARY_PATH=/chemin/vers/vos/fichiers/audio
|
|
```
|
|
|
|
### 3. Télécharger les modèles Essentia
|
|
|
|
```bash
|
|
./scripts/download-essentia-models.sh
|
|
```
|
|
|
|
### 4. Lancer avec Docker (Production)
|
|
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
L'API sera disponible sur `http://localhost:8001`
|
|
La documentation interactive : `http://localhost:8001/docs`
|
|
Le frontend sera accessible sur `http://localhost:3000`
|
|
|
|
### 5. Lancer avec Docker (Développement)
|
|
|
|
```bash
|
|
docker-compose -f docker-compose.dev.yml up -d
|
|
```
|
|
|
|
L'API sera disponible sur `http://localhost:8001`
|
|
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
|
|
```bash
|
|
curl -X POST http://localhost:8001/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) :
|
|
```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.
|