Playlist Analysis
Relevant source files
The following files were used as context for generating this wiki page:
Playlist Analysis is a core feature of the MoodTune backend that evaluates the emotional and technical characteristics of a Spotify playlist. It leverages Spotify's audio features (such as valence, energy, and danceability) to categorize a playlist into specific mood categories, calculate mood distributions, and identify top representative tracks. The system provides users with insights into their listening habits and persists these analyses for historical tracking.
The process involves authenticating with Spotify, fetching track metadata and audio features in batches, and applying a classification logic based on predefined thresholds. The final results include a primary mood label, a confidence score based on the variance of audio features, and a detailed breakdown of the playlist's musical profile.
Sources: app/api/v1/analysis.py:46-118, app/services/analysis_service.py:165-240
System Architecture and Data Flow
The analysis process follows a structured path from the API layer through service logic to database persistence. The following diagram illustrates the sequence of operations triggered when a user requests a playlist analysis.
The workflow ensures that only valid Spotify tracks are processed and that the resulting data is both returned to the user and stored in the playlist_analyses table for future reference.
Sources: app/api/v1/analysis.py:46-118, app/crud/analysis.py:11-35
Logic and Classification
Mood Thresholds
The analysis service uses a set of constant thresholds to classify individual tracks and calculate the overall playlist distribution.
| Feature | Category | Threshold |
|---|---|---|
| Valence | Happy | >= 0.6 |
| Valence | Sad | < 0.4 |
| Energy | Energetic | >= 0.6 |
| Energy | Calm | < 0.4 |
| Danceability | Danceable | >= 0.6 |
Sources: app/services/analysis_service.py:13-24
Primary Mood Categorization
The system determines a "Primary Mood" for the entire playlist by averaging the valence and energy of all valid tracks.
if avg_valence > 0.6 and avg_energy > 0.6:
primary_mood = "Happy & Energetic"
mood_category = "upbeat"
elif avg_valence > 0.6 and avg_energy <= 0.6:
primary_mood = "Happy & Calm"
mood_category = "peaceful"
elif avg_valence <= 0.6 and avg_energy > 0.6:
primary_mood = "Intense & Dark"
mood_category = "intense"
else:
primary_mood = "Calm & Melancholic"
mood_category = "calm"
Sources: app/services/analysis_service.py:202-211
Confidence Scoring
Confidence is calculated as a normalized distance from the "neutral" center (0.5, 0.5) on a valence-energy coordinate plane. A minimum confidence of 30% is maintained for playlists near the center.
Sources: app/services/analysis_service.py:90-108
API Endpoints
The playlist analysis functionality is exposed through the following endpoints in the analysis router.
| Method | Endpoint | Description |
|---|---|---|
POST | /analyze/{playlist_id} | Triggers a new analysis for a Spotify playlist (min 5, max 100 tracks). |
GET | /history | Returns a paginated list of the user's past analyses. |
GET | /{analysis_id} | Retrieves a specific analysis result by its UUID. |
Sources: app/api/v1/analysis.py:46, 122, 140
Data Models
Database Schema
Analyses are stored in the playlist_analyses table with Row Level Security (RLS) enabled to ensure users only access their own data.
Sources: db/playlist_analyses.sql:1-24
Result Schema (MoodResult)
The core analysis output contains a summary of the playlist's characteristics.
| Field | Type | Description |
|---|---|---|
primary_mood | string | The dominant mood label. |
mood_category | string | Internal category (e.g., "upbeat", "calm"). |
confidence | float | Score from 0 to 100. |
averages | AudioFeaturesSummary | Mean values for valence, energy, tempo, etc. |
mood_distribution | MoodDistribution | Percentage of tracks meeting specific thresholds. |
top_tracks | list[TrackAnalysis] | Most representative tracks based on distance from neutral. |
Sources: app/schemas/analysis.py:38-51, app/services/analysis_service.py:228-240
Summary
Playlist Analysis acts as a bridge between raw Spotify signal data and human-readable emotional insights. By processing tracks in batches and applying a valence-energy model, the system provides a comprehensive profile of a playlist's musical identity, helping users understand the "vibe" of their curated content.