A sophisticated music discovery platform that leverages machine learning to provide personalized song recommendations. The system analyzes audio characteristics, clustering patterns, and lyrical content to deliver diverse and accurate music suggestions through an intuitive web interface.
This system analyzes music characteristics using multiple approaches - audio features, clustering algorithms, and lyrical content - to provide diverse and accurate song recommendations. Built with scalability and user experience in mind, it features a React frontend, FastAPI backend, and PostgreSQL database.
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
β React Frontend β β FastAPI Backend β β PostgreSQL DB β
β β β β β β
β β’ Song Search βββββΊβ β’ ML Models βββββΊβ β’ Track Data β
β β’ Recommendationsβ β β’ Clustering β β β’ User Prefs β
β β’ User Interfaceβ β β’ Similarity β β β’ Clusters β
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
β β β
β βββββββββββββββββββ β
ββββββββββββββ€ ML Pipeline βββββββββββββββββ
β β
β β’ HDBSCAN β
β β’ Lyrics Models β
β β’ Feature Eng β
βββββββββββββββββββ
- Audio Feature Analysis: Analyzes tempo, energy, valence, and other musical characteristics
- Clustering-Based Discovery: Groups similar songs using advanced clustering algorithms
- Lyrical Similarity: Finds songs with similar themes and lyrical content
- Hybrid Approach: Combines multiple recommendation strategies for better results
- Real-time song search with autocomplete
- Filter by genre, mood, energy level, and more
- Explore music through interactive cluster visualizations
- Discover new artists and songs based on your preferences
- Like/unlike songs to improve recommendations
- View your music taste profile
- Track your listening history
- Get recommendations tailored to your preferences
- Frontend: React 18 with TypeScript, Vite, and modern UI components
- Backend: FastAPI with async support and automatic API documentation
- Database: PostgreSQL with optimized queries and indexing
- ML Pipeline: Scikit-learn, HDBSCAN, and custom feature engineering
- Deployment: Docker containers with nginx load balancing
The system uses five different clustering approaches to group similar songs:
- Naive Features: Basic audio characteristics (12 features)
- PCA Features: Dimensionally reduced audio features (6 components)
- Combined Features: Audio features + derived characteristics
- Low-Level Audio Features: Detailed audio analysis
- Low-Level PCA: Reduced low-level features (60 components)
Four different approaches for finding songs with similar lyrical content:
- KNN Cosine: Cosine similarity with k-nearest neighbors
- KNN Euclidean: Euclidean distance-based similarity
- SVD + KNN: Dimensionality reduction with similarity search
- KNN Cosine (k=20): Optimized cosine similarity with smaller k
- Prerequisites: Docker, Docker Compose, Git, 4GB RAM
- Clone:
git clone <repository-url> && cd spotify_recommendation_system_v2 - Setup:
./docker-setup.bat full(Windows) or./docker-setup.sh full(Linux/Mac) - Access: Open http://localhost:3000
For detailed instructions, see the Quick Start Guide.
For development with hot reloading:
# Start development environment
docker-compose -f docker-compose.yml up -d
# View logs
docker-compose logs -f- Open the application in your browser
- Search for a song you like
- Click "Get Recommendations" to see similar songs
- Use the like/unlike buttons to improve future recommendations
- Navigate to the "Clusters" section
- Browse different music clusters
- Click on clusters to see all songs in that group
- Discover new music based on cluster characteristics
- Go to "Model Comparison" in the interface
- Select different recommendation models
- Compare results from different approaches
- See which models work best for your taste
The system expects the following data files in the data/raw/ directory:
spotify_tracks.csv: Main track database with audio featureslow_level_audio_features.csv: Detailed audio analysis (optional)- Additional data files as specified in the documentation
Key configuration options in .env:
# Database
POSTGRES_HOST=database
POSTGRES_PORT=5432
POSTGRES_DB=spotify_recommendations
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
# API
API_HOST=0.0.0.0
API_PORT=8000
# Frontend
VITE_API_URL=http://localhost:8000Models can be configured in the model-prep/ directory:
- Adjust clustering parameters
- Modify feature engineering
- Configure similarity thresholds
Get Recommendations
POST /api/recommendations
Content-Type: application/json
{
"song_id": "track_id",
"model_type": "hdbscan",
"limit": 10
}Search Songs
GET /api/songs/search?q=song_name&limit=20Get Clusters
GET /api/clusters?model_type=naive_featuresLike/Unlike Song
POST /api/songs/{song_id}/like
DELETE /api/songs/{song_id}/likeGet Available Models
GET /api/modelsModel Health Check
GET /api/health- Database indexing on frequently queried columns
- Caching of model predictions
- Async request handling
- Connection pooling
- Efficient batch processing
- Use multiple worker processes for the API
- Implement Redis for caching recommendations
- Consider model serving with dedicated ML servers
- Database read replicas for heavy read workloads
Models not loading
# Check model generation status
docker-compose exec model-prep python model_pipeline.py --check-only
# Regenerate models if needed
docker-compose exec model-prep python model_pipeline.py --forceDatabase connection errors
# Check database status
docker-compose ps database
# View database logs
docker-compose logs databaseFrontend not loading
# Rebuild frontend
docker-compose build frontend
# Check frontend logs
docker-compose logs frontend- Increase container memory limits
- Check disk space for model files
- Monitor database query performance
- Review API response times
We welcome contributions! Please see our Contributing Guide for details on:
- Code style and standards
- Testing requirements
- Pull request process
- Development workflow
This project is licensed under the MIT License - see the LICENSE file for details.
- Quick Start Guide - Get running in 5 minutes
- User Guide - Complete feature walkthrough
- Technical Guide - Developer documentation
- Project Overview - System architecture and design
- Setup Instructions - Detailed installation guide
- Database Setup - Database configuration
- Docker Guide - Container deployment
- Environment Template - Configuration options
- Docker Compose - Service definitions
- Setup Scripts - Automated deployment tools
- Quick Start Guide - Common setup issues
- Technical Guide - Troubleshooting section
- User Guide - Feature questions
- GitHub Issues - Report bugs and request features
- API Documentation: http://localhost:8000/docs (when running)
- System Health: http://localhost:8000/health
- Frontend: http://localhost:3000
Built with β€οΈ for music discovery and powered by advanced machine learning.