Audio Upload & Analysis
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Audio Upload & Analysis is a core feature of the MoodTune application that enables users to determine the emotional characteristics of music. The system supports two primary workflows: uploading local audio files (MP3, M4A, FLAC, WAV, OGG) and selecting tracks from external catalogs like Jamendo or Spotify. The analysis engine processes technical audio features—tempo, energy, brightness, and texture—to generate a primary mood label, confidence scores, and descriptive explanations.
The system is built using a Flutter mobile frontend, a FastAPI backend for heavy-lifting audio processing via the librosa library, and Supabase for authentication and data persistence. Authenticated users benefit from auto-saved history and mood filtering, though the analysis capability is available to guests as well.
Sources: README.md:5-18, CLAUDE.md:7-9
System Architecture
The analysis system follows Clean Architecture principles, separating concerns into Presentation, Domain, and Data layers. The mobile app communicates with the FastAPI backend using specialized DataSources for remote analysis and multipart file uploads.
High-Level Component Flow
The following diagram illustrates the interaction between the Flutter client, the FastAPI backend, and the analysis engine.
Sources: CLAUDE.md:38-40, README.md:46-52
Analysis Data Sources
The system utilizes two distinct remote data sources for handling music analysis requests:
- AnalysisRemoteDataSource: Handles catalog-based analysis (Spotify track IDs, Jamendo IDs) and retrieves analysis history.
- AudioUploadRemoteDataSource: Specifically configured for multipart file uploads with extended timeouts (30s connect, 90s receive/send) to accommodate large audio files.
Sources: CLAUDE.md:95-97, CLAUDE.md:105-107
Audio Upload Workflow
Users can upload local audio files up to 15 MB. The frontend utilizes the file_picker package to access the device's storage and the dio package to stream the file to the backend via a multipart request.
Feature Specifications
| Feature | Detail |
|---|---|
| Supported Formats | MP3, M4A, FLAC, WAV, OGG |
| Max File Size | 15 MB |
| Processing Time | ~30 seconds |
| HTTP Method | POST (Multipart) |
| Timeout | 90 seconds (Send/Receive) |
Sources: README.md:15-18, pubspec.yaml:16, CLAUDE.md:97
Upload Sequence
The sequence below details the communication during a local file analysis request.
Sources: CLAUDE.md:65-68, CLAUDE.md:105-107
Analysis Output & Mood Mapping
The backend returns a comprehensive analysis object. The application maps these results into four distinct "Mood Identities," each associated with a specific color palette and visual identity.
Mood Categories & Confidence
| Identity | Visual Profile | Confidence Logic |
|---|---|---|
| Upbeat | High energy/tempo | Strong: ≥75% |
| Serene | Low energy, smooth texture | Good: 50–74% |
| Charged | High energy, bright texture | Possible: <50% |
| Reflective | Lower tempo, complex texture | — |
Sources: README.md:15-21
Data Flow Pattern (BLoC)
The AnalysisBloc manages the state for playlist analysis, song analysis, audio upload, and history. It uses the dartz library's Either type to handle functional error management.
// lib/features/analysis/presentation/bloc/analysis_bloc.dart pattern
final result = await _repository.uploadAudio(event.file);
result.fold(
(failure) => emit(state.copyWith(
status: AnalysisStatus.error,
error: failure.message
)),
(analysis) => emit(state.copyWith(
status: AnalysisStatus.success,
currentAnalysis: analysis
)),
);
Sources: CLAUDE.md:65-71
API Surface for Analysis
The Flutter app interacts with the following backend endpoints to perform analysis and retrieve data:
| Endpoint | Method | Description |
|---|---|---|
/analysis/analyze/{playlistId} | POST | Analyzes a Spotify/Jamendo playlist |
/song/analyze/{trackId} | POST | Analyzes a specific track from a catalog |
/audio-upload/analyze | POST | Processes a multipart audio file upload |
/analysis/history | GET | Retrieves past analyses (Authenticated users) |
/analysis/{id} | GET | Retrieves details for a specific analysis |
Sources: CLAUDE.md:105-107
Conclusion
The Audio Upload & Analysis module provides the primary functional value of MoodTune by combining complex Python-based audio signal processing with a responsive Flutter interface. By leveraging distinct DataSources for file uploads and catalog analysis, the system ensures robust handling of varying payloads, while the BLoC-based state management provides clear feedback (loading states, confidence scores) to the user throughout the ~30-second processing window.