Mood Identities & Scoring
Relevant source files
The following files were used as context for generating this wiki page:
MoodTune utilizes a specialized audio analysis system to categorize music into distinct "Mood Identities" based on acoustic features. The system processes audio files or catalog tracks to return a primary mood label, a confidence score, and descriptive metadata. This functionality is delivered via a FastAPI backend utilizing librosa for audio processing and presented through a Flutter-based mobile interface.
Sources: README.md:5-10, CLAUDE.md:7-10
Mood Identities Overview
The application defines four primary mood identities, each associated with a unique visual identity and color palette. These identities serve as the high-level classification for any analyzed audio track.
| Mood Identity | Description | Visual Association |
|---|---|---|
| Upbeat | High energy, positive tempo | Distinct visual identity/palette |
| Serene | Calm, melodic textures | Distinct visual identity/palette |
| Charged | High intensity, bright/sharp textures | Distinct visual identity/palette |
| Reflective | Lower energy, complex textures | Distinct visual identity/palette |
Sources: README.md:16-17
Analysis Scoring Logic
When a track is analyzed, the system generates a confidence score representing the mathematical certainty of the mood match. This score is categorized into three qualitative tiers for the end-user.
Confidence Tiers
The scoring system maps percentage-based confidence to plain-language labels:
- Strong Match: Confidence score ≥ 75%
- Good Match: Confidence score between 50% and 74%
- Possible Match: Confidence score < 50%
Sources: README.md:20-20
Audio Feature Inputs
The mood identities are derived from analyzing four primary audio characteristics:
- Tempo: The speed or pace of the music.
- Energy: The intensity and activity level.
- Brightness: The higher-frequency content and "sheen."
- Texture: The overall timbre and sonic complexity of the audio.
Sources: README.md:7-9
System Data Flow
The analysis process involves the Flutter client, a FastAPI backend, and external music services like Jamendo.
The diagram above illustrates the flow from initial audio input to the final mood identity result.
Sources: CLAUDE.md:120-125, README.md:33-40, authplan.md:15-30
Backend API for Scoring
The analysis is facilitated through specific endpoints in the AnalysisRemoteDataSource and AudioUploadRemoteDataSource.
| Endpoint | Method | Purpose |
|---|---|---|
/song/analyze/{trackId} | POST | Analyzes a specific track from the Jamendo catalog. |
/audio-upload/analyze | POST | Handles multipart uploads for local audio file analysis. |
/analysis/{id} | GET | Retrieves the results and score of a past analysis. |
Sources: CLAUDE.md:120-125
Presentation and Persistence
Mood identities and their scores are handled within the presentation layer using the AnalysisBloc. For authenticated users, these results are persisted via Supabase and can be filtered by mood identity within the history screen.
Sequence of events for mood analysis and history persistence.
Sources: README.md:18-19, CLAUDE.md:65-70, authplan.md:150-160
Visual Branding and Identity
The "Sunset" color palette used for the application's iconography correlates with the warmth and emotional range of the mood identities.
- Warm Sand:
#e9b489(0%) - Terracotta:
#d4885f(48%) - Plum:
#b16a8a(100%) - Cream:
#efece6(Glyph/Text color)
Sources: app-icon/README.md:16-22, logo/README.md:15-18
Summary
Mood Identities & Scoring represents the core value proposition of MoodTune. By combining librosa-powered feature extraction with a tiered confidence scoring system, the application provides users with immediate, data-driven insights into their music. These results are visually reinforced through a custom color system and categorized into four primary identities: Upbeat, Serene, Charged, and Reflective.