mirror of
https://github.com/bnair123/MusicAnalyser.git
synced 2026-02-25 11:46:07 +00:00
0ca9893c68
- Initialize React+Vite Frontend with Ant Design Dashboard. - Implement Data Enrichment: ReccoBeats (Audio Features) and Spotify (Genres). - Update Database Schema via Alembic Migrations. - Add Docker support (Dockerfile, docker-compose.yml). - Update README with hosting instructions.
88 lines
2.9 KiB
Markdown
88 lines
2.9 KiB
Markdown
# Music Analyser
|
|
|
|
A personal analytics dashboard for your music listening habits, powered by Python, FastAPI, React, and Google Gemini AI.
|
|
|
|
## Project Structure
|
|
|
|
- `backend/`: FastAPI backend for data ingestion and API.
|
|
- `app/ingest.py`: Background worker that polls Spotify and enriches data via ReccoBeats.
|
|
- `app/services/`: Logic for Spotify, ReccoBeats, and Gemini APIs.
|
|
- `app/models.py`: Database schema (Tracks, PlayHistory).
|
|
- `frontend/`: React + Vite frontend for visualizing the dashboard.
|
|
- `docker-compose.yml`: For easy deployment.
|
|
|
|
## Features
|
|
|
|
- **Continuous Ingestion**: Polls Spotify every 60 seconds to record your listening history.
|
|
- **Data Enrichment**: Automatically fetches **Genres** (via Spotify) and **Audio Features** (Energy, BPM, Mood via ReccoBeats).
|
|
- **Dashboard**: A responsive UI to view your history and stats.
|
|
- **AI Ready**: Database schema and environment prepared for Gemini AI integration.
|
|
|
|
## Hosting Guide (Docker)
|
|
|
|
This application is designed to run via Docker Compose.
|
|
|
|
### 1. Prerequisites
|
|
- Docker & Docker Compose installed.
|
|
- **Spotify Developer Credentials** (Client ID & Secret).
|
|
- **Spotify Refresh Token** (Run `backend/scripts/get_refresh_token.py` locally to generate this).
|
|
- **Google Gemini API Key**.
|
|
|
|
### 2. Deployment
|
|
|
|
1. **Clone the repository**.
|
|
2. **Create a `.env` file** in the root directory (or use environment variables directly):
|
|
|
|
```bash
|
|
SPOTIFY_CLIENT_ID="your_client_id"
|
|
SPOTIFY_CLIENT_SECRET="your_client_secret"
|
|
SPOTIFY_REFRESH_TOKEN="your_refresh_token"
|
|
GEMINI_API_KEY="your_gemini_key"
|
|
```
|
|
|
|
3. **Run with Docker Compose**:
|
|
|
|
```bash
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
This will:
|
|
- Build and start the **Backend** (port 8000).
|
|
- Build and start the **Frontend** (port 8991).
|
|
- Create a **Persistent Volume** at `/opt/mySpotify` (mapped to the container's database) to ensure **no data loss** during updates.
|
|
|
|
4. **Access the Dashboard**:
|
|
Open your browser to `http://localhost:8991` (or your server IP).
|
|
|
|
### 3. Data Persistence & Updates
|
|
|
|
- **Data**: All data is stored in `music.db` inside the container, which is mounted to `/opt/mySpotify/music.db` on your host machine.
|
|
- **Migrations**: The project uses **Alembic** for database migrations. When you update the container image in the future, the backend will automatically apply any schema changes without deleting your data.
|
|
|
|
### 4. Pulling from Registry (Alternative)
|
|
|
|
If you prefer to pull the pre-built image instead of building locally:
|
|
|
|
```bash
|
|
docker pull ghcr.io/bnair123/musicanalyser:latest
|
|
```
|
|
|
|
(Note: You still need to mount the volume and pass environment variables as shown in `docker-compose.yml`).
|
|
|
|
## Local Development
|
|
|
|
1. **Backend**:
|
|
```bash
|
|
cd backend
|
|
pip install -r requirements.txt
|
|
python run_worker.py # Starts ingestion
|
|
uvicorn app.main:app --reload # Starts API
|
|
```
|
|
|
|
2. **Frontend**:
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|