AI Music Recommendation via Signal Embeddings

This project implements an end-to-end music recommendation system that relies purely on audio signal analysis, without using any metadata (tags, genres, artists).

🧠 Core Concept

Conventional recommenders use collaborative filtering (user behavior) or metadata tags. This system uses Content-Based Filtering on the raw audio:

1. DSP Features: Extracts "classical" music theory features like Tempo, Key (Chroma), Timbre (MFCCs), and Energy using librosa.
2. Deep Embeddings: Uses a Convolutional Neural Network (CNN) on Mel Spectrograms to learn abstract features.
3. Unified Embedding: Combines both vectors into a robust "Song Fingerprint".
4. Explainability: Recommends songs and explains why (e.g., "Similar Tempo", "Harmonic Similarity") by analyzing the feature distances.

📂 Project Structure

ai-music-recommendation/
│
├── data/               # (Gitignored) Audio storage
│   ├── raw/            # Place .wav/.mp3 files here
│   └── embeddings/     # Persistent FAISS index
│
├── src/
│   ├── features/       # Feature extraction logic (DSP + Deep)
│   ├── models/         # Embedding orchestration & Recommender Engine
│   ├── preprocessing/  # Loading, Resampling, Normalization
│   └── explainability/ # "Why this song?" logic
│
├── app/
│   ├── api.py          # FastAPI Backend
│   └── recommender_ui.py # Streamlit Dashboard
│
└── notebooks/          # Analysis & Visualization

🚀 Setup & Usage

1. Installation

pip install -r requirements.txt

2. Run the UI (Dashboard)

The easiest way to use the system is the Streamlit UI.

streamlit run app/recommender_ui.py

• Sidebar: Click "Re-Index Data Folder" to process any audio files in data/raw.
• Main: Upload a song to find similar songs in the database.

3. Run the API (Backend)

For production use or integration:

uvicorn app.api:app --reload

Docs available at: http://localhost:8000/docs

4. Notebooks

Explore the logic step-by-step:

• notebooks/01_audio_explore.ipynb: Visualizing waveforms/spectrograms.
• notebooks/02_feature_extraction.ipynb: Seeing the extraction of MFCCs/Embeddings.

⚙️ Configuration

See src/utils/config.py to adjust:

• SAMPLE_RATE: Default 22050 Hz
• DURATION: Default 30s analysis window
• VECTOR_DIMENSION: Size of the combined embedding

🛠 Features

• Tag-Free: Works on unknown/new music.
• Explainable: "Matches based on: Similar Tempo (120 BPM), Similar Energy".
• Hybrid Vector: Combines interpretable DSP physics with Deep Learning intuition.
• Scalable: Uses FAISS for sub-millisecond similarity search.