Jamendo Catalog Browsing
Relevant source files
The following files were used as context for generating this wiki page:
Jamendo Catalog Browsing is a core feature within the MoodTune application that allows users to explore and analyze music from the Jamendo music library. This module enables users to discover new tracks without the need to upload personal audio files. It serves as a secondary method for audio acquisition alongside direct file uploads, providing a seamless experience for both guest and authenticated users to interact with the app's mood analysis engine.
The catalog browsing system leverages the Jamendo API v3 to fetch track metadata and audio streams. Once a track is selected from the catalog, the application utilizes the MoodTune backend (FastAPI) and audio analysis libraries (librosa) to return primary mood labels, confidence scores, and descriptors. This integration is designed to be non-intrusive, allowing full analysis capabilities even in Guest Mode.
Sources: README.md:9-11, README.md:46-47, CLAUDE.md:6-7
Architecture and Integration
The Jamendo catalog browsing feature is integrated into the Clean Architecture of the Flutter mobile app. It operates within the features/analysis directory, specifically interacting with the presentation and data layers to handle search queries and track confirmations.
Component Overview
| Component | Responsibility |
|---|---|
| Catalog Search Screen | Provides the UI for users to query the Jamendo library. |
| Catalog Track Confirm | A modal or screen where users confirm the track selection before analysis. |
| Jamendo API v3 | The external data source providing music catalog metadata. |
| AnalysisRemoteDataSource | The internal service that sends selected Jamendo track IDs to the backend for processing. |
| JAMENDO_CLIENT_ID | A required environment variable for authenticating API requests to Jamendo. |
Sources: README.md:27-28, README.md:47, CLAUDE.md:144-146, codemagic.yaml:26
Data Flow Diagram
The following diagram illustrates the flow from a user searching the Jamendo catalog to receiving a mood analysis result.
This flow shows how the Jamendo API serves as the discovery layer while the MoodTune backend handles the heavy computational task of audio analysis.
Sources: README.md:9-13, CLAUDE.md:6-8
Implementation Details
API Integration and Endpoints
The catalog browsing feature depends on the FastAPI backend to interface with the Jamendo ecosystem. While search queries are typically directed to Jamendo, the subsequent analysis of a selected track is handled via specific backend endpoints.
- Endpoint:
POST /song/analyze/{trackId} - Description: Sends a Jamendo track ID to the backend. The backend fetches the audio from Jamendo, processes it using librosa, and returns a mood analysis object.
Sources: CLAUDE.md:145-146
Environment Configuration
For the catalog browsing to function in production and development environments, the JAMENDO_CLIENT_ID must be correctly configured. This key is injected during the build process via --dart-define.
# Example from CI configuration
- name: Flutter build ipa
script: |
flutter build ipa --release \
--flavor production \
--target lib/main_production.dart \
--dart-define=JAMENDO_CLIENT_ID=$JAMENDO_CLIENT_ID
Sources: codemagic.yaml:49-59
User Experience (UX) States
The catalog browsing feature supports multiple UI states as defined in the application's navigation and UX specification:
- Search Input: Active for both Guest and Authenticated users.
- Results Display: Lists tracks retrieved from Jamendo.
- Analysis Loading State: A transitional state (~30 seconds) while the backend analyzes the selected Jamendo track.
- Results Screen: Displays "Upbeat", "Serene", "Charged", or "Reflective" mood identities based on the analysis.
Sources: README.md:16-29
Navigation and Routing
Navigation to the catalog features is managed by AppRouter using go_router. The catalog search and confirmation are distinct steps in the user journey.
Sources: README.md:27-28, routing_plan.md:173-180
Conclusion
Jamendo Catalog Browsing provides a frictionless way for MoodTune users to interact with audio analysis technology. By offloading audio hosting to Jamendo and processing to a dedicated FastAPI backend, the app maintains a lightweight footprint while offering a rich library of content for analysis. The feature is central to the "Discover" pillar of the MoodTune platform.
Sources: README.md:7-11