Commit
feat: implement Python Essentia service for audio analysis
Commit details
Commit notes
Replace essentia.js WebAssembly bindings with a dedicated Python microservice using the official Essentia C++ library for production-grade audio analysis.
## Python Essentia Service (services/essentia-service/)
New FastAPI microservice providing comprehensive audio analysis:
### Features Extracted: - **Rhythm**: BPM (RhythmExtractor2013), beat positions, danceability, onset rate - **Tonal**: Key detection with 3 profiles (EDMA, Krumhansl, Temperley), tuning - **Loudness**: LUFS (integrated/short-term/momentary), true peak, dynamic range - **Spectral**: Centroid, bandwidth, rolloff, flatness, flux, ZCR, energy - **Loop**: Loop detection with LoopBpmEstimator, bar alignment, beat grid - **Transients**: Onset detection, transient positions - **Envelope**: Attack time, effective duration, temporal centroid - **Embedding**: 39-dim MFCC-based embedding (mean + std + delta)
### Architecture: - FastAPI with async endpoints - Pydantic models for request/response validation - Multi-stage Docker build with all Essentia C++ dependencies - Health checks and graceful shutdown - Shared /tmp volume for file-based analysis (avoids network transfer)
## Backend Integration
- New essentia-client.ts: HTTP client for Python service - Updated hybrid-analyzer.ts: Uses Python service with TS fallback - Config: ESSENTIA_SERVICE_URL, ESSENTIA_SERVICE_ENABLED env vars - docker-compose.yml: Essentia service with health checks, worker dependency
## Removed
- essentia.js npm package (WebAssembly version) - essentia.ts (JS bindings wrapper) - essentia.js.d.ts type declarations
## Why Python over JS?
1. Full algorithm coverage (200+ vs ~70%) 2. Streaming mode for memory efficiency 3. Active development (vs stale 2021 release) 4. Native TensorFlow integration for ML models 5. Production-proven (used by AcousticBrainz) 6. Multi-processing support for parallel analysis
Co-authored-by: armin.naimi <[email redacted]>
- Files changed
- 17
- Lines added
- +1,863
- Lines removed
- −1,192