Home
Relevant source files
The following files were used as context for generating this wiki page:
MoodTune Backend is a FastAPI-based Python application designed to provide sophisticated musical mood analysis. The system leverages librosa for direct audio signal processing and integrates with the Spotify API to analyze playlists and individual tracks based on audio features like valence, energy, and tempo.
The backend is architected to handle Spotify OAuth authentication, audio file uploads, and catalog searches. It utilizes Supabase Postgres for data persistence and is optimized for deployment on the Railway platform.
Sources: CLAUDE.md:8-13, README.md:3-5
System Architecture
The project follows a modular structure that separates concerns between API routing, business logic (services), and data persistence.
The architecture diagram illustrates the flow from user requests through FastAPI routers to specialized services that interact with external APIs and the database.
Sources: CLAUDE.md:27-42, app/services/audio_analysis_service.py:15-18
Core Components
| Component | Responsibility | Relevant Files |
|---|---|---|
| API Routers | Handle HTTP requests, validation, and response formatting. | app/api/v1/ |
| Analysis Services | Orchestrate mood detection and audio feature extraction. | app/services/analysis_service.py, app/services/audio_analysis_service.py |
| Configuration | Manages environment-specific settings and credentials. | app/core/config.py |
| Persistence | Stores analysis history and user connections via Supabase. | db/song_analyses.sql, db/playlist_analyses.sql |
Sources: CLAUDE.md:27-42, app/core/config.py:30-90
Audio Analysis Logic
The system utilizes two primary methods for mood detection: direct audio processing via librosa and Spotify feature aggregation.
Direct Audio Signal Processing
For uploaded files or catalog streams, the AudioAnalysisService extracts raw features from the audio signal.
The flow shows how raw audio data is transformed into human-readable mood classifications using mathematical estimations of valence and danceability.
Sources: app/services/audio_analysis_service.py:44-93, app/services/audio_analysis_service.py:126-150
Mood Classification Matrix
Individual tracks and playlists are classified into quadrants based on Valence (Positivity) and Energy.
| Valence | Energy | Primary Mood | Category |
|---|---|---|---|
| High (>0.6) | High (>0.6) | Happy & Energetic | upbeat |
| High (>0.6) | Low (<0.6) | Happy & Calm | peaceful |
| Low (<0.4) | High (>0.6) | Intense & Dark | intense |
| Low (<0.4) | Low (<0.4) | Calm & Melancholic | calm |
Sources: app/services/analysis_service.py:43-58, app/services/analysis_service.py:202-212
API Endpoints
The backend exposes several v1 endpoints for song and playlist analysis.
Song Analysis
POST /api/v1/song/analyze: Analyzes an uploaded audio file.POST /api/v1/song/analyze/{track_id}: Analyzes a song by Spotify ID using a provided audio file.GET /api/v1/song/history: Retrieves the authenticated user's song analysis history.
Sources: app/api/v1/song_analysis.py:53-157
Playlist Analysis
POST /api/v1/analysis/analyze/{playlist_id}: Fetches Spotify audio features for all tracks in a playlist and generates a collective mood report.GET /api/v1/analysis/history: Retrieves playlist analysis history.
Sources: app/api/v1/analysis.py:48-125
Database Schema
The system uses Supabase (Postgres) with Row Level Security (RLS) to ensure data isolation.
The ER diagram displays the relationship between users and their stored analysis results for both individual songs and full playlists.
Sources: db/song_analyses.sql:1-7, db/playlist_analyses.sql:1-7
Development and Deployment
Environment Configuration
The application supports multiple environments (development, staging, production) via specific .env files.
Sources: app/core/config.py:9-25
Local Execution
# Run with automatic reload
uvicorn app.main:app --reload
Sources: CLAUDE.md:15-18
MoodTune Backend provides a robust foundation for music-based emotional intelligence by combining traditional signal processing with modern API integrations and cloud-native persistence.