A machine learning project that explores music similarity, clustering, and low-dimensional views of songs using a Spotify-style audio features dataset. The deliverable is a local Streamlit web app (src/app.py): you pick a song, get KNN recommendations with optional Spotify previews, then explore clustering, PCA vs. autoencoder embeddings, recommendation evaluation metrics, and dataset stats in the sidebar.
- KNN from Scratch: Uses a custom-built K-Nearest Neighbors implementation (pure NumPy) for maximum transparency.
- Dual Metrics: Toggle between Cosine Similarity (directional alignment) and Euclidean Distance (geometric proximity).
- Live Preview: Integrated Spotify Embed Players allow for instant auditioning of the original song and all recommendations.
- Hard vs. Soft Clustering: Compare K-Means (implemented from scratch) against Gaussian Mixture Models (GMM).
- Cluster Profiling: Centroids are automatically analyzed to generate descriptive labels (e.g., "High Energy, Low Acousticness") by identifying the most extreme acoustic traits.
- Quality Metrics: Real-time calculation of Silhouette Scores and Davies-Bouldin Index to evaluate cluster separation.
- Linear vs. Non-Linear: Compare PCA and Neural Autoencoders (PyTorch) for compressing 10+ audio dimensions into a visualizable space.
- Variance Analysis: Interactive bar charts showing individual and cumulative explained variance.
- 3D Projections: Toggle between 2D and Interactive 3D Scatter Plots to explore high-dimensional data clouds.
- Scientific Explanations: The UI includes professional notes on Feature Standardization and the mathematical nature of continuous musical spectrums.
- Overview tab: Row/column counts, missing values, per-column dtypes, and a small preview table so the raw data is easy to inspect without leaving the app.
- Sanity-check metrics: Evaluate recommendation behavior over multiple reference songs with interpretable metrics such as same-genre rate, same-artist rate, average popularity, popularity gap, and feature-space diversity.
To ensure complete understanding of the underlying mathematics, the following algorithms were implemented manually without higher-level library wrappers:
- K-Nearest Neighbors (KNN): Custom similarity scoring engines using L2-normalization and vector dot products.
- K-Means Clustering: Full iterative logic including K-means++ initialization, assignment steps, and centroid updates.
- Neural Autoencoder: Custom PyTorch architecture (
128 -> 64 -> latent) with a manual reconstruction loss training loop.
All numeric features (Tempo, Energy, Loudness, etc.) are processed through a StandardScaler (z-score normalization). This ensures that features with larger raw values do not disproportionately dominate distance calculations.
spotify-recommender/
├── data/ # Dataset (e.g. dataset.csv)
├── results/ # Optional precomputed lookups for fast cosine KNN
├── src/
│ ├── algorithms/ # ML implementations (KNN, K-Means, GMM, PCA, AE)
│ ├── visualization/ # Plotly-based graph generation
│ ├── evaluation/ # Metrics (Silhouette, DBI)
│ └── app.py # Main Streamlit interface
└── requirements.txt # Project dependencies
-
Clone the repository:
git clone https://github.com/dz2603/spotify-recommender.git cd spotify-recommender -
Environment Setup:
python3 -m venv venv source venv/bin/activate pip install -r requirements.txt -
Run the web app (from the repository root, with the venv activated):
python3 -m streamlit run src/app.py
The system utilizes a Spotify tracks dataset containing audio features for thousands of songs across multiple genres. Features included: Danceability, Energy, Key, Loudness, Mode, Speechiness, Acousticness, Instrumentalness, Liveness, Valence, and Tempo.