🎧 DJ Song Match

www.djsongmatch.com

A web-based tool for DJs to curate seamless sets faster.
It recommends harmonically compatible song transitions using:

• Camelot wheel key matching
• BPM-based tempo compatibility
• Approximate Nearest Neighbors (ANN) using FAISS ML model

Tech Stack
🧠 Python + Flask + SQLAlchemy (Backend)
🎵 Next.js + TypeScript + Tailwind (Frontend)
🔍 FAISS (Vector search for song similarity)
🐳 Dockerized for easy setup

---

🧠 Features in the App

From your frontend, users can:

• Search for a base song
• View harmonic & tempo-compatible recommendations
• Use interactive sliders and filters to fine-tune results
• Toggle dark mode, manage playlists, and get recommendations instantly

The app is designed to be fast, modular, and DJ-friendly.

---

🚀 Getting Started

Prerequisites

• Install Docker
• Make sure Docker is running

---

🐳 Option 1: Run Full App with Docker Compose

This starts both the backend and frontend.

docker-compose up --build

• Frontend: http://localhost:3000
• Backend: http://localhost:5001

Stop services:

docker-compose stop

Restart services:

docker-compose restart

Stop/restart individual containers:

docker-compose stop frontend
docker-compose restart backend

Clean up unused Docker resources:

docker system prune

---

⚛️ Option 2: Run Only the Frontend (Next.js)

docker build -t djsongmatch .
docker run -p 3000:3000 djsongmatch

---

🐍 Option 3: Run Only the Backend (Flask)

cd src/app/backend
docker build -t flask-backend .
docker run -p 5001:5001 flask-backend

---

🛠 Backend Script Usage (Optional Dev Workflows)

Set Up Virtual Environment (For Script Dev)

python3 -m venv venv
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows

Install dependencies:

pip install -r backend/requirements.txt

Run Backend Scripts

Example (from root level):

python3 -m backend.scripts.pre_process_data

Deactivate Environment

deactivate