Catalog Search

Relevant source files

The following files were used as context for generating this wiki page:

• app/api/v1/catalog.py
• app/services/audio_analysis_service.py
• app/schemas/catalog_analysis.py
• app/schemas/audio_analysis.py
• app/crud/song_analysis.py (Inferred from imports in catalog.py)
• db/song_analyses.sql

Introduction

The Catalog Search feature, specifically implemented through the catalog module, facilitates the analysis of tracks from external music catalogs like Jamendo. Unlike standard Spotify-based analysis, this module allows for the direct processing of audio stream URLs. It serves as an unauthenticated or authenticated entry point where the backend acts as a proxy to download audio data, validate its constraints, and perform a rich audio analysis using a specialized pipeline.

The system integrates directly with the Audio Analysis Service to extract mood and technical audio features. For authenticated users, these results are persisted in the Song Analysis History.
Sources: app/api/v1/catalog.py:17-26, CLAUDE.md:8-12

Architecture and Data Flow

The process initiates when a client sends a track's audio URL and metadata. The backend downloads the file, processes it in memory, and utilizes the librosa library to generate a mood profile.

Request Flow

1. Audio Acquisition: The system uses httpx to fetch audio from the provided audio_url (e.g., Jamendo stream).
2. Validation: The file size is checked against MAX_UPLOAD_SIZE_MB.
3. Analysis: The audio bytes are passed to the audio_analysis_service for feature extraction.
4. Persistence: If a current_user is detected, the analysis is saved to the Supabase song_analyses table.
   Sources: app/api/v1/catalog.py:31-72, app/services/audio_analysis_service.py:97-124

Data Flow Diagram

The following diagram illustrates the lifecycle of a catalog track analysis request:

API Implementation

The primary interaction point is the /analyze endpoint. This endpoint is designed to be flexible, supporting both guest users and logged-in users who wish to save their findings.

Endpoint: POST /analyze

Parameter	Type	Description
audio_url	String	The Jamendo stream URL to be analyzed.
track_id	String	External ID used for temporary file naming.
track_name	String	The title of the track.
artist_name	String	The artist performing the track.
jamendo_page_url	String	(Optional) Attribution link for the track.
Sources: app/schemas/catalog_analysis.py:4-9

Analysis Metadata Response

The response includes calculated fields and raw features:

• primary_mood: The high-level mood (e.g., happy, sad).
• confidence: A value between 0.0 and 1.0 indicating result reliability.
• audio_features: Technical metrics including tempo, rms_energy, and spectral_centroid.
• processing_time_seconds: Time taken to run the librosa pipeline.
  Sources: app/schemas/audio_analysis.py:48-77, app/api/v1/catalog.py:100-112

Audio Analysis Pipeline

The Catalog Search feature relies on the AudioAnalysisService to interpret audio signals. It employs a valence-energy model to map technical features to human-readable moods.

Mood Mapping Logic

The system uses the following quadrants for classification:

• Happy: High Valence (>0.6) + High Energy (>0.6)
• Sad: Low Valence (<0.4) + Low Energy (<0.4)
• Angry: Low Valence (<0.4) + High Energy (>0.6)
• Calm: Low Energy (<0.4)
• Energetic: Default for high-energy tracks not meeting other criteria.
  Sources: app/services/audio_analysis_service.py:228-245

Feature Extraction Sequence

Persistence and History

When an authenticated user analyzes a catalog track, the data is stored in the song_analyses table. This allows the user to retrieve their analysis history later via the /history endpoint.

Database Schema: song_analyses

Column	Type	Constraints
id	UUID	PRIMARY KEY, Default gen_random_uuid()
user_id	UUID	REFERENCES auth.users(id), ON DELETE CASCADE
track_id	TEXT	Nullable (Jamendo track ID)
track_name	TEXT	NOT NULL
artist_name	TEXT	NOT NULL
mood_results	JSONB	NOT NULL (Stores features and mood scores)
created_at	TIMESTAMPTZ	Default NOW()
Sources: db/song_analyses.sql:1-9

Conclusion

Catalog Search extends the MoodTune ecosystem beyond Spotify, providing a robust mechanism for analyzing open-source or external audio streams. By combining httpx for retrieval, librosa for signal processing, and Supabase for persistent storage, it delivers a high-performance analysis tool for both anonymous and registered users. Significance lies in its ability to process 300-second audio segments to derive accurate emotional profiles based on energy, valence, and spectral characteristics.
Sources: app/api/v1/catalog.py, app/services/audio_analysis_service.py:112