spotify-github-profile: a now-playing card for your GitHub page

An OAuth flow, a Firebase document, an SVG

The app does three things. It completes a Spotify OAuth flow, it keeps your currently playing track in a small Firebase document, and it renders an SVG card you reference from your GitHub profile README with an image tag.

What gets stored is deliberately narrow. The README states that data lives in Firebase and that it stores only access_token, refresh_token and token_expired_timestamp. No track history, no listening statistics, no profile data. That is a short list and worth reading closely if you are considering connecting an account, because the access token is what grants read access to your Spotify data and the refresh token is what keeps it alive.

The starting point is a login button that points at the hosted app's login endpoint. After granting permission, the SVG is fetched from a view endpoint with a `uid` parameter and whatever customization you have chosen. GitHub's profile READMEs render images from external URLs, which is why an SVG served by a third party works at all: GitHub proxies the image and never sees your token.

At 2,235 stars and 895 forks, this is one of the more forked repositories in the profile-README category, and the fork count is a fair proxy for why: people clone it to change the colours or the layout rather than wait for a theme to appear.

Seven themes and nine query parameters

The README's example table is the real documentation for this project. The `theme` parameter accepts default, compact, natemoo-re, novatorem, karaoke, spotify-embed and apple, with default as the fallback. The README shows a screenshot for each of them and marks spotify-embed as new.

Appearance is controlled by four parameters. `background_color` takes a hex value without the hash sign and defaults to `121212`, which is Spotify's near-black. `border_radius` is in pixels and defaults to 10. `bar_color` sets the equalizer bar colour with the same hex-without-hash convention, defaulting to `53b14f`, Spotify's green. `bar_color_cover` extracts the bar colour from the album cover instead of using a fixed value.

Three parameters control behaviour rather than looks. `cover_image` shows the album art and is on by default. `show_offline` decides what happens when nothing is playing: off by default, and turning it on shows an offline status instead of a stale or empty card. `interchange` swaps the artist and song name positions, which sounds trivial and matters if your theme puts the artist first. Finally `mode` selects light or dark for the themes that support it.

The whole customization fits in a single URL:

https://spotify-github-profile.kittinanx.com/api/view?uid=YOUR_UID&cover_image=true&theme=default&border_radius=15&bar_color=53b14f

That is the design decision worth copying. Every option is a query string argument, so a card can be tuned without a rebuild, an account or a configuration file.

Running it locally without any serverless platform

The README documents two local development paths and the no-Vercel one is shorter. You copy `.env.example` to `.env`, install the dependencies from the API directory, and run the app module:

pip install -r api/requirements.txt

python api/app.py

Then you visit the login page at `http://localhost:3000/api/login`. Two things must line up for the OAuth handshake to complete: your Spotify app's redirect URI has to be set to `http://localhost:3000/api/callback`, and `BASE_URL` in the `.env` file has to be `http://localhost:3000/api`.

The `.env.example` in the repository shows the four variables the app expects, which is more informative than a list of names would be:

SPOTIFY_CLIENT_ID='___'
SPOTIFY_SECRET_ID='____'
BASE_URL='http://localhost:3000/api'
FIREBASE='__BASE64_FIREBASE_JSON_FILE__'

That `FIREBASE` value is unusual. The setup instructions have you download the service account JSON from Firebase project settings, convert the private key content to BASE64, and paste the result into the variable, with a suggestion that an encode and decode extension in VS Code can do it. The reason is that a single environment variable survives deployment platforms that expect a conventional secret, whereas pasting multiline JSON into one does not.

The Docker Compose file takes the same idea further and splits the service into three, which maps to the three concerns in the code: a `view` service on port 5003, a `login` service on 5001 and a `callback` service on 5002, each running gunicorn against the `api` directory.

The Vercel path, its history, and why the endpoint moved

The second local path needs a fork, a Vercel project wired to it, a Firebase project with Cloud Firestore, and a Spotify developer account. The Vercel path then uses the Vercel CLI:

$ vercel dev
> Ready! Available at http://localhost:3000

That transcript is a small time capsule. The banner above it reported Vercel CLI 20.1.2 running in beta when the output was pasted, and the README has not been revised since.

The announcement block at the top of the README explains why the endpoint in the setup instructions is not the one the project started with. Dated 2024-06-21, it records that Vercel changed its packaging and the free tier was no longer enough for the project's usage, so the service moved to self-hosting on Digital Ocean. Readers are asked to replace the old `spotify-github-profile.vercel.app` endpoint with `spotify-github-profile.kittinanx.com`.

That is worth pausing on, because the README's opening line still describes the service as running on a Vercel serverless function. The announcement supersedes it, and the repository still contains a `vercel` setup section, so both descriptions remain in the file. Practically, the hosted URL in the login link is the Digital Ocean deployment now, not a Vercel function.

Tests, dependencies and one known bug

The project has a real pytest suite, and the README gives four ways to run it, which suggests it is maintained rather than aspirational:

pytest tests/ -v

pytest tests/ --cov=api --cov-report=html

pytest tests/ --maxfail=5 --disable-warnings -v

The `pyproject.toml` configures pytest with `--strict-markers --strict-config` and defines three markers, `slow`, `integration` and `unit`, so the CI-style invocation can deselect the slow tests. Coverage is configured to measure the `api` and `util` packages and to omit tests, virtual environments, migrations, static files and templates.

The dependency list is pinned exactly rather than with ranges, and two entries explain visible behaviour. `colorgram.py` alongside `Pillow` is what makes `bar_color_cover` possible, since extracting a dominant colour from album art needs both. `profanityfilter` sits there because the card renders track and artist names, and the author decided that was worth filtering before it reached a public README. That is a judgement call the README does not advertise, so it is worth knowing about if your taste differs.

The known-bugs section lists one item, a 404 or 500 error when playing local files, tracked as issue 19. There are no tagged releases in the repository, so there is no version to pin, and the last push was on 2026-07-21.

Where this sits against the alternatives

The profile-README category has a few other occupants. The README itself points at an Apple Music equivalent maintained by someone else, which is the closest comparison available, and the inspiration credit goes to a natemoo-re project that the `natemoo-re` and `novatorem` themes are named after.

What distinguishes this one is breadth of themes and the query-parameter approach to configuration. Most alternatives render one fixed card, and making it yours means editing templates and hosting your own copy. Here the seven themes cover the range from a compact single line to a full embedded Spotify player, and every visual choice is a URL argument.

The trade-off is that a working card depends on someone else's infrastructure and on Spotify's Web API continuing to behave. The self-hosting path exists and is documented in detail, which means the dependency is avoidable if you would rather hold the tokens yourself, and it means a fork can be pointed at your own deployment without waiting for an upstream change.

For a concrete starting point, the fastest path is to use the hosted service, connect an account, pick one theme, and only fork once you know which parameter you want to change. The `.env.example` file and the Docker Compose file together are everything needed to run your own instance.

Editorial conclusion

This is a small, focused app that solves one problem and documents its deployment thoroughly, which is more than most projects in the profile-README category manage. The customization surface is the strongest part, with seven themes and nine query parameters that let you match the card to your profile without forking anything. The infrastructure story is also unusually complete for a Flask service, covering local development, Vercel, Docker Compose across three ports, and a pytest suite with coverage and CI-style flags. Two rough edges are worth knowing: the repository has no tagged release at all, and an open known-bug list still records a 404 or 500 error when playing local files. Start with the hosted service and one theme, then self-host if you care about the OAuth token living outside someone else's machine.

Frequently asked questions

Official sources

1. Issues
2. kittinan/spotify-github-profile on GitHub
3. License: MIT
4. Project website
5. README