Music Analyser

A personal analytics dashboard for your music listening habits, powered by Python, FastAPI, and Google Gemini AI.

Project Structure

• backend/: FastAPI backend for data ingestion and API.
  • app/ingest.py: Background worker that polls Spotify.
  • app/services/: Logic for Spotify and Gemini APIs.
  • app/models.py: Database schema (Tracks, PlayHistory).
• frontend/: (Coming Soon) React/Vite frontend.

Getting Started

Prerequisites

• Docker & Docker Compose (optional, for containerization)
• Python 3.11+ (for local dev)
• A Spotify Developer App (Client ID & Secret)
• A Google Gemini API Key

1. Setup Environment Variables

Create a .env file in the backend/ directory:

SPOTIFY_CLIENT_ID="your_client_id"
SPOTIFY_CLIENT_SECRET="your_client_secret"
SPOTIFY_REFRESH_TOKEN="your_refresh_token"
GEMINI_API_KEY="your_gemini_key"

To get the SPOTIFY_REFRESH_TOKEN, run the helper script:

python backend/scripts/get_refresh_token.py

2. Run Locally

Install dependencies:

cd backend
pip install -r requirements.txt

Run the server:

uvicorn app.main:app --reload

The API will be available at http://localhost:8000.

3. Run Ingestion (Manually)

You can trigger the ingestion process via the API:

curl -X POST http://localhost:8000/trigger-ingest

Or run the ingestion logic directly via python shell (see app/ingest.py).

4. Docker Build

To build the image locally:

docker build -t music-analyser-backend ./backend