Single Song Analysis
Relevant source files
The following files were used as context for generating this wiki page:
Single Song Analysis is a core feature of the MoodTune backend that enables the extraction of emotional and technical characteristics from individual audio tracks. The system supports multiple input methods, including direct file uploads, Spotify track IDs, and Jamendo stream URLs. It leverages the librosa library to perform digital signal processing (DSP) and calculate features such as tempo, energy, valence, and danceability.
The analysis result provides a primary mood classification (e.g., Happy, Sad, Energetic) and detailed audio metrics. These results are persisted in a Supabase PostgreSQL database for authenticated users, allowing for history retrieval and personalized mood tracking.
Technical Architecture
The architecture follows a layered approach: the API layer handles requests and file validation, the Service layer performs the heavy computation using librosa, and the CRUD layer manages data persistence via the Supabase client.
Analysis Data Flow
When a song is analyzed, the system writes the audio bytes to a temporary file before loading a 30-second segment (or up to 300 seconds for catalog tracks) into memory for processing.
Audio Feature Extraction
The AudioAnalysisService extracts several key metrics to determine the track's mood.
Extracted Metrics
| Feature | Description | Methodology |
|---|---|---|
| Tempo | Beats Per Minute (BPM) | Derived via librosa.beat.beat_track |
| Energy | Physical intensity and loudness | Calculated from Root Mean Square (RMS) of the signal |
| Valence | Musical positiveness (Happiness) | Estimated from spectral brightness and tempo |
| Danceability | Suitability for dancing | Derived from tempo proximity to 110 BPM and energy |
| Brightness | Perceived "brightness" of sound | Calculated from the Spectral Centroid |
| Texture | Smoothness vs Roughness | Calculated from the Harmonic-to-Percussive ratio |
Sources: app/services/audio_analysis_service.py:53-75, app/services/audio_analysis_service.py:129-158
Mood Classification Logic
The system maps tracks into specific mood categories based on the Valence-Energy quadrant model.
API Endpoints
1. Song Analysis via Upload
POST /api/v1/song-analysis/analyze
Allows users to upload an audio file (MP3, WAV, etc.) for immediate mood analysis.
- Parameters:
audio_file(File),track_name(Form),artist_name(Form). - Constraints: Maximum file size is defined by
settings.MAX_UPLOAD_SIZE_MB.
Sources: app/api/v1/song_analysis.py:97-105
2. Analysis via Track ID
POST /api/v1/song-analysis/analyze/{track_id}
Combines Spotify metadata with a local file upload. The system fetches the track name and artist from Spotify while analyzing the provided audio file.
Sources: app/api/v1/song_analysis.py:176-184
3. Catalog Stream Analysis
POST /api/v1/catalog/analyze
An unauthenticated endpoint that downloads audio from a Jamendo stream URL and runs the full analysis pipeline.
Sources: app/api/v1/catalog.py:23-35
Database Schema
Song analyses are stored in the song_analyses table. Row Level Security (RLS) ensures users can only access their own analysis history.
Sources: db/song_analyses.sql:1-9
Data Model Details
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier (Primary Key) |
user_id | UUID | Reference to auth.users in Supabase |
track_id | TEXT | Optional Spotify track ID |
mood_results | JSONB | Stores MoodResult and AudioFeatures |
created_at | TIMESTAMPTZ | Record creation timestamp |
Sources: db/song_analyses.sql:1-9, app/schemas/audio_analysis.py:64-79
Core Logic Implementation
Valence and Danceability Estimation
Since librosa does not provide a native "happiness" metric, valence is estimated by combining spectral brightness (timbre) and tempo.
def _estimate_valence(self, brightness: float, chroma: np.ndarray, tempo: float) -> float:
# Brighter + faster = happier
brightness_norm = self._normalize(brightness, 1000, 4000)
tempo_norm = self._normalize(tempo, 60, 180)
valence = (brightness_norm * 0.6) + (tempo_norm * 0.4)
return max(0, min(1, valence))
Sources: app/services/audio_analysis_service.py:129-136
Summary
The Single Song Analysis module provides a robust pipeline for converting raw audio data into meaningful emotional metadata. By combining librosa for feature extraction with a custom valence-energy mapping, MoodTune enables detailed tracking of musical moods across various platforms and file types. Results are securely stored in Supabase, providing a historical record of analyzed content for authenticated users.