Maria's Music Site

A tiny Windows app that looks at your Spotify likes and tells you which albums are worth buying as physical copies — an album is recommended when at least half of its tracks are in your library. Singles are skipped, EPs and compilations are clearly labelled.

Built with the Python standard library only. No frameworks, no pip install.

---

🚀 Quick start (for people who just want the app)

This is the easiest path — no coding, no Python.

Step 1 — Download the app

Go to the releases page and download MariaMusicSite.exe (Windows only).

Step 2 — Get your free Spotify keys

1. Open https://developer.spotify.com/dashboard and log in (or create a free account).

2. Click Create app.

3. Name it whatever you like, pick the Web API option, agree to the terms, and click Create.

4. On the app page, copy the Client ID and click Show client secret to copy the Secret.

5. Click Edit settings → under Redirect URIs click Add and enter exactly (note: no port number — the app picks a free port automatically):

   http://127.0.0.1/callback
   

   ...then click Save. (Use 127.0.0.1, not localhost — Spotify rejects localhost.)

Step 3 — Run it

1. Double-click MariaMusicSite.exe.
2. When it asks, paste in your Client ID and Client Secret.
3. Your browser opens and asks you to log in with Spotify — click Agree.
4. Done! You'll see your recommended albums. Mark any you're buying, and close the black window when you're finished.

No Spotify keys handy? Press Enter at the prompt to explore the app in demo mode with sample data.

---

👩‍💻 Run from source (for developers)

Requires Python 3.10+.

Step 1 — Get the code

git clone https://github.com/0124212/marias-music-site.git
cd marias-music-site

Step 2 — Option A: demo mode (no keys needed)

python server.py

Open http://127.0.0.1:8000 in your browser (if that port is busy the app silently uses the next free one and prints the address to use).

Step 2 — Option B: real Spotify data

Create a Spotify app as described in the Quick start above, then:

$env:SPOTIFY_CLIENT_ID = "your_client_id"
$env:SPOTIFY_CLIENT_SECRET = "your_client_secret"
python server.py

Open http://127.0.0.1:8000/login and authorize (the app auto-picks a free port if 8000 is taken — use the URL it prints).

Tip: you can also drop those two lines into a file named .env next to server.py (e.g. SPOTIFY_CLIENT_ID=...) and it will be picked up automatically. .env is gitignored, so it never gets committed.

---

📦 Build the .exe yourself

pip install pyinstaller
python -m PyInstaller --onefile --console --name MariaMusicSite --add-data "static;static" launch.py

The exe lands in dist/. Put a .env file (optional) next to it to pre-fill your credentials, or let it prompt on launch.

---

🐳 Run with Docker (same everywhere)

Runs the exact same app in a container, so it behaves identically on any machine (Windows, Mac, Linux) regardless of installed Python or other local quirks.

Step 1 — Install Docker Desktop (free): https://www.docker.com/products/docker-desktop/

Step 2 — Start it

git clone https://github.com/0124212/marias-music-site.git
cd marias-music-site

# demo mode (no keys needed)
docker compose up --build

# or real Spotify data — put your keys in a .env file first:
#   SPOTIFY_CLIENT_ID=...
#   SPOTIFY_CLIENT_SECRET=...
docker compose up --build

Step 3 — Open http://127.0.0.1:8000 (add /login to authorize with Spotify).

Your Spotify app's redirect URI stays http://127.0.0.1/callback (no port) — the port is forwarded from the container to your machine, so nothing about the Spotify setup changes. Stop it anytime with Ctrl+C (or docker compose down).

---

🧠 How it works

1. You log in with Spotify (OAuth, scope user-library-read — read-only, nothing is modified).
2. The server reads your saved tracks and groups them by album.
3. For each album: album_score = liked_tracks / total_tracks.
4. Albums with album_score >= 0.5 are recommended (singles excluded).
5. Each release is labelled Album / EP / Compilation / Single.
6. You can mark albums as "for purchase".

📁 Project layout

launch.py           Friendly launcher: prompts for keys, opens the browser
models.py           Data model: User, Album, UserLibrary
scoring.py          Pure scoring logic (album_score, recommended_albums)
spotify_client.py   OAuth login flow + Spotify API calls (demo mode included)
server.py           Local HTTP server + JSON API
static/             Lightweight frontend (vanilla HTML/CSS/JS)
tests/              Unit tests for scoring and release kinds
Dockerfile          Container image (python:3.12-slim)
docker-compose.yml  One-command container startup

✅ Tests

python -m unittest discover -s tests

🔧 Extending for a portfolio piece

• scoring.py is pure logic — easy to test and swap rules (e.g. weight by release year, require > 5 liked tracks).
• spotify_client.py — add user-top-read scope for a "new releases I'd love" section, or persist liked tracks to disk with json.
• models.py — add fields like release_date or cover_url and surface album art in the frontend.
• server.py — swap the stdlib server for Flask/FastAPI later without touching the API shape.

Note: tokens are kept in memory only; add a small SQLite store before deploying anywhere real.