Audio File Upload
Relevant source files
The following files were used as context for generating this wiki page:
The Audio File Upload module provides functionality for users to upload local audio files or stream catalog tracks for direct mood analysis using digital signal processing (DSP). Unlike standard playlist analysis that relies on Spotify's pre-calculated features, this module utilizes librosa to extract raw acoustic characteristics directly from the audio data.
The system supports two primary upload flows: a guest-accessible endpoint for immediate analysis and an authenticated endpoint that saves results to the user's history. The analysis pipeline involves temporary file storage, feature extraction (tempo, energy, brightness, texture), and a valence-energy quadrant mapping to determine the track's primary mood.
Sources: app/api/v1/audio_upload.py:12-25, app/services/audio_analysis_service.py:16-20, app/api/v1/catalog.py:21-25
API Endpoints and Interaction
The system exposes RESTful endpoints to handle different upload scenarios. The /analyze endpoint in the audio_upload router is designed for guest access, processing files in-memory without persistent storage of the audio itself.
Endpoint Summary
| Endpoint | Method | Auth Required | Description |
|---|---|---|---|
/api/v1/audio-upload/analyze | POST | No | Direct file upload for guest users. |
/api/v1/song/analyze | POST | Yes | Authenticated upload that saves analysis to DB. |
/api/v1/song/analyze/{track_id} | POST | Yes | Upload for a specific Spotify track ID to fetch metadata. |
/api/v1/catalog/analyze | POST | No/Opt | Downloads track from URL and analyzes it. |
Sources: app/api/v1/audio_upload.py:12-18, app/api/v1/song_analysis.py:108-115, app/api/v1/catalog.py:21-28
Upload Request Structure
For direct file uploads, the system utilizes Multipart/Form-Data. Key fields include:
audio_file: The binary audio data (required).title: Optional track title.artist: Optional artist name.album: Optional album name.
Sources: app/api/v1/audio_upload.py:14-19, app/schemas/audio_analysis.py:8-14
Audio Analysis Pipeline
The analysis is performed by the AudioAnalysisService. The service writes the uploaded bytes to a temporary local directory before loading them into librosa.
The pipeline caps analysis at 300 seconds (5 minutes) to maintain predictable memory and processing time for long tracks.
Sources: app/services/audio_analysis_service.py:79-110, app/api/v1/audio_upload.py:34-45
Feature Extraction Details
The service extracts several technical audio features to construct a mood profile:
- Temporal Features: Tempo (BPM) and Beat Strength.
- Spectral Features: Spectral Centroid (Brightness), Spectral Rolloff, and Spectral Bandwidth.
- Timbral Features: MFCC (Mel-frequency cepstral coefficients) means and Zero Crossing Rate.
- Dynamic Features: RMS Energy and Dynamic Range (95th vs 5th percentile).
- Harmonic Features: Harmonic vs. Percussive ratio using HPSS (Harmonic-Percussive Source Separation).
Sources: app/services/audio_analysis_service.py:136-175
Mood Determination Logic
Mood is inferred using a valence-energy quadrant model. For uploaded audio, valence and energy are estimated from extracted features rather than provided by an external API.
Valence and Energy Estimation
- Valence (Happiness): Estimated using a weighted combination of normalized Brightness (60%) and Tempo (40%).
- Energy: Derived directly from the normalized RMS energy of the signal.
Sources: app/services/audio_analysis_service.py:112-118, app/services/audio_analysis_service.py:228-232
Mood Quadrants
Data Models
AudioAnalysisResponse
This schema represents the final output delivered to the client after a successful upload and analysis.
| Field | Type | Description |
|---|---|---|
id | UUID | Unique identifier for the analysis session. |
filename | str | Original name of the uploaded file. |
duration_seconds | float | Calculated duration of the audio. |
mood | MoodFromAudio | Nested object containing primary mood, scores, and descriptors. |
processing_time_seconds | float | Time taken to complete librosa analysis. |
analysis_method | str | Method used (e.g., "direct_audio", "catalog_stream"). |
Sources: app/schemas/audio_analysis.py:53-70
Configuration and Constraints
The upload system is governed by settings defined in the application core to prevent resource exhaustion and ensure compatibility.
- Maximum Upload Size: Defined by
settings.MAX_UPLOAD_SIZE_MB(checked againstlen(file_data)). - Allowed Formats: Checked against
settings.ALLOWED_AUDIO_FORMATS(e.g., mp3, wav, ogg). - Temp Storage: Temporary files are stored in
settings.TEMP_AUDIO_DIRand are cleaned up in afinallyblock to ensure deletion even if analysis fails.
Sources: app/api/v1/audio_upload.py:27-40, app/services/audio_analysis_service.py:189-200, app/services/audio_analysis_service.py:265-272
Summary
The Audio File Upload feature enables direct mood classification by processing raw audio data. By combining librosa for feature extraction with a custom valence-energy mapping service, the system provides a robust alternative to metadata-based analysis, supporting both guest and authenticated user flows with high-precision acoustic metrics.