Rate your music. Own your taste.
RateIt is a MacOS desktop app for rating and cataloguing every album you listen to.
Search any album from Spotify API, rate it track-by-track and across five quality criteria (or your own!), and build a personal library that reflects your actual taste — no cloud, no subscription. Everything lives locally on your Mac.
- Features
- Requirements
- Installation
- Setup: Spotify API credentials
- Usage
- Project structure
- Tech stack
- Contributing
- License
- Search & Rate — Find any album via the Spotify API and rate each track (1–5 ★) plus five quality criteria: Flow, Production, Lyricism, Originality, Replay. The overall score (out of 10) calculates automatically.
- Rated Albums — Your full library with sort (score, date) and group (artist, genre) controls, a mini stats bar, and one-click export.
- Gallery — A visual card grid of everything you've rated. Each card extracts the album's dominant colour and applies it as a theme. Click a card to expand it; click again to flip it and see the full score breakdown.
- Custom Criteria — Rename or reweight the five scoring dimensions so the formula fits how you actually listen (jazz, classical, electronic — all different).
- Stats in Profile - Your own taste statistics and Hall of fame (top 3 highest rated).
- Year in Review — Annual Wrapped-style stats: albums per month, avg score, top genre, most active month, highest and lowest rated album.
-
Surprise Me — One-click random album picker in the main screen, weighted toward your top genres.
-
Export — Download your library as JSON, CSV, or a self-contained styled HTML page.
-
Open in Spotify — Deep-link any album straight into the Spotify app.
-
MacOS
-
A Spotify Developer account to search albums (no Spotify subscription required, free tier works)
-
Node.js 18+ and npm (only if building from source)
Download the latest RateIt DMG from the Releases page (pick arm64 for Apple Silicon Macs or x86-64 for Intel Macs), open it, and drag RateIt to your Applications folder.
git clone https://github.com/sjcsoftware/rateit.git
cd rateit
npm install
npm run rebuild # recompiles SQLite for Electron's Node runtime
npm start # launch in dev mode
npm run build # produces dist/RateIt-<version>-arm64.dmg and dist/RateIt-<version>-x86-64.dmgAs a serverless local only app, RateIt does not ship updates to you.
In order to update, you have to delete your current outdated version of the app, go to the Releases page and re-download the newest version. Your account and rated albums DB will not be lost, and the application will automatically login. I apologize for the inconvenience.
The reason why RateIt has a sign up page is, each person need to add their own Spotify API credentials.
RateIt does not connect your information to any type of server nor cloud in any way. Everything is managed locally (feel free to check the source code!)
RateIt uses the Spotify API only to search albums and fetch track lists. Also, your ratings and library data never touch Spotify's servers.
- Go to developer.spotify.com/dashboard and sign in with any Spotify account.
- Click Create App. Name and description can be anything.
- Set the Redirect URI to
https://localhost(doesn't matter, put anything), check Web API, accept the Terms, and save. - From your app's settings page, copy the Client ID and click View client secret to reveal the Client Secret.
On first launch, RateIt will prompt you to create a local account and paste both values. They are stored in your local database — again, never transmitted.
- Type any album name or artist in the Search & Rate bar. Results appear from Spotify.
- Click an album — RateIt loads the full track list.
- Rate each track from 1–5 stars.
- Rate the five album qualities (Flow, Production, Lyricism, Originality, Replay) from 1–5 stars.
- Optionally write a one-line review.
- Hit Save Rating. Done.
The Gallery shows all your rated albums as cards with their album colour applied. Click any card to see it full-size. Click again to flip it — the back shows your complete score breakdown by dimension and top tracks.
Hit the 🎲 Surprise Me button on the Search page for a random album recommendation drawn from your top genres. Great for when you can't decide what to listen to next.
Open Custom Criteria from the left nav to adjust dimension weights via sliders. All weights must total 100%. You can also rename dimensions or add your own (e.g. swap "Lyricism" for "Technique" for instrumental albums).
Already rated albums will retain their old criteria (and weights). If you want to re-rate them with the new criteria, simply click the "Refresh Criteria" button in the album page, inside your Rated Albums library. You'll be able to re-rate with the current criteria.
In Rated Albums, click Export (top right) to save your library as:
- JSON — full fidelity, machine-readable
- CSV — opens in Numbers / Excel
- HTML — a styled personal music page ready to share or archive (below)
rateit/
├── electron/ # Electron main process
│ └── main.js
├── frontend/ # UI (vanilla JS, no frameworks)
│ ├── index.html
│ ├── app.js
│ └── style.css
├── backend/ # Express server + SQLite
│ ├── server.js
│ └── .env.example
├── assets/ # App icon
├── screenshots/ # Screenshots for README.md
├── scripts/ # Renaming script for x86-64
└── package.json
Data is stored in ~/Library/Application Support/rateit/ratings.db and persists across updates.
| Shell | Electron 28 |
| Server | Express 5, better-sqlite3 |
| Frontend | Vanilla JS / CSS |
| Database | SQLite — fully local |
| Music data | Spotify Web API (search & metadata only) |
PRs are welcome. For significant changes, open an issue first to discuss the direction.
git checkout -b feature/your-feature
# make changes
git commit -m "feat: describe your change"
git push origin feature/your-feature
# open a pull requestMIT © 2026 Cha Seungjoon