Repository navigation
Home
SPARK is the Spotify Presence Activity Render Kit: SVG cards of what is playing on Spotify, for GitHub profiles, by LianHarman(LienThuan04). Everything is on this one page — use the contents to jump around.
Quick start: connect with Spotify → build your card in Card Studio → paste the code into your profile README.
Got
403 - The user is not registered for this application? This deployment runs in Spotify Development Mode: only users registered in the Spotify app's User Management can connect. Pick one:
- Self-deploy (recommended, free). Fork the repo, create your own app in the Spotify Developer Dashboard, and deploy with your own
SPOTIFY_CLIENT_ID/SPOTIFY_SECRET_ID. Then anyone you register can connect. See Development.- Request access. Email lienthuan2004@gmail.com with the subject
Spotify-SPARK access request, including your name and the email address of your Spotify account. Your address is only used to register you so you can log in; allow some time for manual approval.
Card Studio is the page you land on after connecting your Spotify account. It builds your card URL for you, with a live preview.
- Connect — open https://spotify-spark.vercel.app/api/login and allow access to your currently playing and recently played tracks.
- Choose a layout — pick one of the 15 themes. Controls that do not apply to the chosen theme are hidden.
- Pick an equalizer — Spotify themes support 19 equalizer styles.
-
Tune colors and shape — background color, equalizer color (or take it from the album cover), corner radius, and appearance (light/dark) for
appleandspotify-embed. - Playback options — show the album cover, show "Not playing" when idle, swap artist/title, hide "Remastered" suffixes, censor profanity, and make the card open the song on click.
-
Copy — choose Markdown, HTML or the plain image URL and paste it into your profile
README.md. Use Reset to start over. -
Share ideas — the Coming soon tile after the themes and Suggest a theme or feature in the footer open the feedback page (
FEEDBACK_URL, or the owner's GitHub profile).
Every parameter Card Studio sets is documented in Options, so you can also edit the URL by hand.
| Theme | Size | Best for |
|---|---|---|
spotify-card |
400×200 | Default choice; sits next to other 400×200 cards |
spotify-bar |
400×112 | Compact strip under your bio |
spotify-album |
240 wide | Artwork-first column |
spotify-mini |
320×96 (offline: 320×72) | Tiny pill with playback timeline |
spotify-vinyl |
400×200 | Spinning picture disc made from the album cover |
spotify-banner |
800×180 | Full-width hero banner |
spotify-glass |
400×200 | Frosted glass over the blurred cover |
spotify-mobile |
280×500 | Phone "Now Playing" screen |
default, compact, natemoo-re, novatorem, karaoke, apple, spotify-embed
|
varies | Classic themes kept for existing links |
Every preview below uses this project's deployment. Cards show the current track, a randomly selected recently played track when playback stops, or an offline status if no track is available. Connect your Spotify account above to generate a URL with your own uid.
All 15 themes include a progress bar with elapsed time and total duration. During playback, CSS advances the bar and elapsed clock together, stopping at the end of the track. Recently played tracks stay at 0:00; offline cards hide the timeline. If Spotify does not provide timing, the timeline stays static. Pause, seeking and track changes require a fresh image response. Classic layouts grow by 33px to fit the timeline; Apple and Spotify Embed keep their existing size.
theme=spotify-card |
theme=spotify-bar |
theme=spotify-album |
theme=spotify-mini |
theme=spotify-vinyl |
theme=spotify-banner |
theme=spotify-glass |
theme=spotify-mobile |
theme=default |
theme=compact |
theme=natemoo-re |
theme=novatorem |
theme=karaoke |
theme=apple |
theme=spotify-embed |
Styles at a glance:
-
Classic —
bars,spectrum,mirror,wave,pulse -
3D depth —
iso,ribbon,floor,skyline,tunnel -
Retro & fun —
dots,vu,ring,ripple,heartbeat,pixel,glow,bubbles -
Off —
none
Equalizers animate only while a track is playing; recently played cards show them still, and offline cards hide them.
eq_style changes the equalizer on spotify-card, spotify-bar, spotify-album, spotify-mini, spotify-vinyl, spotify-banner, spotify-glass, and spotify-mobile. Animated styles use pure CSS without JavaScript. They animate during playback, pause for recently played tracks, and are hidden offline; none always hides the equalizer. iso, ribbon, floor, skyline, and tunnel add a 3D depth effect.
eq_style=bars |
eq_style=spectrum |
eq_style=mirror |
eq_style=wave |
eq_style=pulse |
eq_style=iso |
eq_style=ribbon |
eq_style=floor |
eq_style=dots |
eq_style=vu |
eq_style=ring |
eq_style=ripple |
eq_style=heartbeat |
eq_style=pixel |
eq_style=glow |
eq_style=bubbles |
eq_style=skyline |
eq_style=tunnel |
eq_style=none |
Add these as query parameters to your card URL alongside your uid. The previews use theme=spotify-card, with spectrum to show equalizer color changes; the mode example uses theme=apple.
| Parameter | Description | Default | Live preview |
|---|---|---|---|
theme |
Card layout — see Themes. | default |
|
eq_style |
Equalizer for Spotify themes — see Equalizer styles. Unknown values fall back to bars. |
bars |
|
background_color |
Background color (hex without #). |
121212 |
|
border_radius |
Border radius in pixels. | 10 |
|
bar_color |
Equalizer color (hex without #). |
1ed760 for Spotify themes; 53b14f otherwise |
|
bar_color_cover |
Take the equalizer color from the album cover (true/false). |
false |
|
cover_image |
Show the album cover (true/false). |
true |
|
show_offline |
Show "Not playing" instead of a recently played track when nothing is playing (true/false). |
false |
|
interchange |
Swap artist and song name positions (true/false). |
false |
|
mode |
Color mode for apple and spotify-embed (light/dark). |
light |
|
hide_remaster |
Strip "Remastered" suffixes from song titles (true/false). |
false |
|
profanity |
Censor profanity in titles (true/false). |
false |
|
redirect |
Open the current or recently played track on Spotify instead of returning an image — use it as the link target (true/false). |
false |
— |
https://spotify-spark.vercel.app/api/view?uid=YOUR_UID&theme=spotify-card&eq_style=iso&cover_image=true&show_offline=true
Wrap it in a link with redirect=true so clicking the card opens the song:
<a href="https://spotify-spark.vercel.app/api/view?uid=YOUR_UID&redirect=true">
<img src="https://spotify-spark.vercel.app/api/view?uid=YOUR_UID&theme=spotify-card&eq_style=iso" alt="Spotify Now Playing" />
</a>Because this project's public deployment runs in Spotify Development Mode, it can only serve registered users. To run a card for yourself (and anyone you register), deploy your own copy — it is free on Vercel's hobby tier:
- Fork LienThuan04/Spotify-SPARK.
-
Spotify app — in the Spotify Developer Dashboard,
create an app, add the Redirect URI
<your-vercel-url>/api/callback, and note the Client ID and Client Secret. Tick only Web API. - Firebase — create a Firebase project, enable Cloud Firestore, generate a service-account JSON key, and base64-encode it (see Setting up Firebase).
-
Vercel — import your fork, set environment variables
SPOTIFY_CLIENT_ID,SPOTIFY_SECRET_ID,BASE_URL(https://<your-vercel-url>/api),FIREBASE, and optionallyFEEDBACK_URL, then deploy. -
Register users — in your Spotify app's User Management, add each Spotify account
(name + email) that may connect via
<your-vercel-url>/api/login.
To run the application locally without Vercel:
-
Copy
.env.exampleto.envin the root directory and replace the placeholder values with your actual configuration. -
Install the required dependencies:
pip install -r api/requirements.txt
-
Run the application:
python api/app.py
-
Access the login page at http://localhost:3000/api/login
Note: Ensure your Spotify app's redirect URI is set to http://localhost:3000/api/callback and BASE_URL in .env is set to http://localhost:3000/api.
To develop locally, you need:
- A copy of this project in your GitHub repository
- A Vercel project connected with your repository
- A Firebase project with Cloud Firestore setup
- A Spotify developer account
- Create a new Vercel project by importing your project on GitHub
- Create a new Firebase project
- Create a new Cloud Firestore in the project
- Download configuration JSON file from Project settings > Service accounts > Generate new private key
- Convert private key content as BASE64
- You can use Encode/Decode extension in VSCode to do so
- This key will be used in step explained below
- Login to developer.spotify.com
- Create a new project
- Edit settings to add Redirect URIs
- add
http://localhost:3000/api/callback
- add
- Install Vercel command line with
npm i -g vercel - Create
.envfile at the root of the project - Paste your keys in
SPOTIFY_CLIENT_ID,SPOTIFY_SECRET_ID, and insert the name of your downloaded JSON file inFIREBASE
BASE_URL='http://localhost:3000/api'
SPOTIFY_CLIENT_ID='____'
SPOTIFY_SECRET_ID='____'
FIREBASE='__BASE64_FIREBASE_JSON_FILE__'- Run
vercel dev
$ vercel dev
Vercel CLI 20.1.2 dev (beta) — https://vercel.com/feedback
> Ready! Available at http://localhost:3000- Now try to access http://localhost:3000/api/login
- Test the card builder's URL generation and controls (Node.js 22+):
node --test tests/test_builder.js- Run all tests
pytest tests/ -v- Run tests with coverage
pytest tests/ --cov=api --cov-report=html- Run specific test file
pytest tests/test_api_view.py -v- Run with maxfail (like CI)
pytest tests/ --maxfail=5 --disable-warnings -v- Develop locally and submit a pull request!
- Submit newly encountered bugs to the Issues page
- Submit feature suggestions to the Issues page, with the label [Feature Suggestion]
404/500 Error when playing local files
More themes and features are still in development. Have an idea for a theme or a feature? Send it to me on my website or through my GitHub profile. Card Studio links there too: the Coming soon tile under the themes and Suggest a theme or feature in the footer.
This wiki mirrors wiki/Home.md in the repository — edit it there.