Audio-Classifier/TRANSCODING_SETUP.md

Configuration Transcodage & Optimisation

📋 Vue d'ensemble

Ce système implémente un transcodage automatique MP3 128kbps pour optimiser le streaming, tout en conservant les fichiers originaux pour le téléchargement.

🎯 Fonctionnalités

1. Transcodage automatique

• Tous les fichiers audio sont transcodés en MP3 128kbps lors du scan
• Fichiers optimisés stockés dans un dossier transcoded/ à côté des originaux
• Compression ~70-90% selon le format source

2. Pré-calcul des waveforms

• Waveforms générées lors du scan (800 points)
• Stockées en JSON dans un dossier waveforms/
• Chargement instantané dans le player

3. Double chemin en BDD

• filepath : Fichier original (pour téléchargement)
• stream_filepath : MP3 128kbps (pour streaming)
• waveform_filepath : JSON pré-calculé

4. Bouton Rescan dans l'UI

• Header : bouton "Rescan" avec icône
• Statut en temps réel du scan
• Reload automatique après scan

🔧 Architecture

Backend

backend/
├── src/
│   ├── core/
│   │   ├── transcoder.py          # Module FFmpeg
│   │   └── waveform_generator.py  # Génération waveform
│   ├── api/routes/
│   │   ├── audio.py                # Stream avec fallback
│   │   └── library.py              # Endpoint /scan
│   ├── cli/
│   │   └── scanner.py              # Scanner CLI amélioré
│   └── models/
│       └── schema.py               # Nouveaux champs BDD

Frontend

frontend/app/page.tsx
- Bouton rescan dans header
- Polling du statut toutes les 2s
- Affichage progression

🚀 Utilisation

Rescan via UI

1. Cliquer sur le bouton "Rescan" dans le header
2. Le scan démarre en arrière-plan
3. Statut affiché en temps réel
4. Refresh automatique à la fin

Rescan via CLI (dans le container)

docker-compose exec backend python -m src.cli.scanner /music

Rescan via API

curl -X POST http://localhost:8000/api/library/scan

Vérifier le statut

curl http://localhost:8000/api/library/scan/status

📊 Bénéfices

Streaming

• Temps de chargement réduit de 70-90%
• Bande passante économisée
• Démarrage instantané de la lecture

Waveform

• Chargement instantané (pas de génération à la volée)
• Pas de latence perceptible

Espace disque

• MP3 128kbps : ~1 MB/min
• FLAC original : ~5-8 MB/min
• Ratio: ~15-20% de l'original

🛠️ Configuration

Dépendances

• FFmpeg : Obligatoire pour le transcodage
• Déjà installé dans le Dockerfile

Variables

Pas de configuration nécessaire. Les dossiers sont créés automatiquement :

• transcoded/ : MP3 128kbps
• waveforms/ : JSON

📝 Migration BDD

Migration appliquée : 003_add_stream_waveform_paths

Nouveaux champs :

ALTER TABLE audio_tracks ADD COLUMN stream_filepath VARCHAR;
ALTER TABLE audio_tracks ADD COLUMN waveform_filepath VARCHAR;
CREATE INDEX idx_stream_filepath ON audio_tracks (stream_filepath);

🔍 Fallback

Si le fichier transcodé n'existe pas :

1. L'API stream utilise le fichier original
2. Aucune erreur pour l'utilisateur
3. Log warning côté serveur

🎵 Formats supportés

Entrée

• MP3, WAV, FLAC, M4A, AAC, OGG, WMA

Sortie streaming

• MP3 128kbps (toujours)
• Stéréo, 44.1kHz
• Codec: libmp3lame

📈 Performance

Temps de traitement (par fichier)

• Analyse audio : ~5-10s
• Transcodage : ~2-5s (selon durée)
• Waveform : ~1-2s
• Total : ~8-17s par fichier

Parallélisation future

Le code est prêt pour une parallélisation :

• --workers paramètre déjà prévu
• Nécessite refactoring du classifier (1 instance par worker)

✅ Checklist déploiement

• Migration BDD appliquée
• FFmpeg installé dans le container
• Endpoint /api/library/scan fonctionnel
• Bouton rescan dans l'UI
• Streaming utilise MP3 transcodé
• Waveform pré-calculée
• Tester avec de vrais fichiers
• Configurer cron/scheduler pour scan nocturne (optionnel)

🐛 Troubleshooting

FFmpeg not found

# Dans le container
docker-compose exec backend ffmpeg -version

Permissions

Les dossiers transcoded/ et waveforms/ doivent avoir les mêmes permissions que le dossier parent.

Scan bloqué

# Vérifier le statut
curl http://localhost:8000/api/library/scan/status

# Redémarrer le backend si nécessaire
docker-compose restart backend