mirror of
https://github.com/bnair123/MusicAnalyser.git
synced 2026-02-25 11:46:07 +00:00
92 lines
2.9 KiB
Markdown
92 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.
|
|
|
|
## Features
|
|
|
|
- **Continuous Ingestion**: Polls Spotify every 60 seconds to record your listening history.
|
|
- **Data Enrichment**:
|
|
- **Genres & Images** (via Spotify)
|
|
- **Audio Features** (Energy, BPM, Mood via ReccoBeats)
|
|
- **Lyrics & Metadata** (via Genius)
|
|
- **Dashboard**: A responsive UI (Ant Design) to view your history, stats, and "Vibes".
|
|
- **AI Ready**: Database schema and environment prepared for Gemini AI integration.
|
|
|
|
## Hosting Guide
|
|
|
|
You can run this application using Docker Compose. You have two options: using the pre-built image from GitHub Container Registry or building from source.
|
|
|
|
### 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**.
|
|
- **Genius API Token** (Optional, for lyrics).
|
|
|
|
### 2. Configuration (`.env`)
|
|
|
|
Create a `.env` file in the root directory (same level as `docker-compose.yml`). This file is used by Docker Compose to populate environment variables.
|
|
|
|
```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"
|
|
GENIUS_ACCESS_TOKEN="your_genius_token"
|
|
```
|
|
|
|
### 3. Run with Docker Compose
|
|
|
|
#### Option A: Build from Source (Recommended for Dev/Modifications)
|
|
|
|
Use this if you want to modify the code or ensure you are running the exact local version.
|
|
|
|
1. Clone the repository.
|
|
2. Ensure your `.env` file is set up.
|
|
3. Run:
|
|
```bash
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
#### Option B: Use Pre-built Image
|
|
|
|
Use this if you just want to run the app without building locally.
|
|
|
|
1. Open `docker-compose.yml`.
|
|
2. Ensure the `backend` service uses the image: `ghcr.io/bnair123/musicanalyser:latest`.
|
|
* *Note: If you want to force usage of the image and ignore local build context, you can comment out `build: context: ./backend` in the yaml, though Compose usually prefers build context if present.*
|
|
3. Ensure your `.env` file is set up.
|
|
4. Run:
|
|
```bash
|
|
docker pull ghcr.io/bnair123/musicanalyser:latest
|
|
docker-compose up -d
|
|
```
|
|
|
|
### 4. Access the Dashboard
|
|
|
|
Open your browser to:
|
|
`http://localhost:8991`
|
|
|
|
### 5. Data Persistence
|
|
|
|
- **Database**: Stored in a named volume or host path mapped to `/app/music.db`.
|
|
- **Migrations**: The backend uses Alembic. Schema changes are applied automatically on startup.
|
|
|
|
## Local Development (Non-Docker)
|
|
|
|
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
|
|
```
|
|
Access at `http://localhost:5173`.
|