Skip to content
LienThuan04 edited this page Nov 14, 2026 · 8 revisions

Spotify-SPARK icon

Spotify-SPARK Wiki

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:

  1. 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.
  2. 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.

Contents

  1. Card Studio
  2. Themes
  3. Equalizer styles
  4. Options
  5. Development
  6. Feedback and ideas

Card Studio

Card Studio is the page you land on after connecting your Spotify account. It builds your card URL for you, with a live preview.

  1. Connect — open https://spotify-spark.vercel.app/api/login and allow access to your currently playing and recently played tracks.
  2. Choose a layout — pick one of the 15 themes. Controls that do not apply to the chosen theme are hidden.
  3. Pick an equalizer — Spotify themes support 19 equalizer styles.
  4. Tune colors and shape — background color, equalizer color (or take it from the album cover), corner radius, and appearance (light/dark) for apple and spotify-embed.
  5. 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.
  6. Copy — choose Markdown, HTML or the plain image URL and paste it into your profile README.md. Use Reset to start over.
  7. 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.

↑ Back to contents

Themes

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-card
theme=spotify-bar
theme=spotify-bar
theme=spotify-album
theme=spotify-album
theme=spotify-mini
theme=spotify-mini
theme=spotify-vinyl
theme=spotify-vinyl
theme=spotify-banner
theme=spotify-banner
theme=spotify-glass
theme=spotify-glass
theme=spotify-mobile
theme=spotify-mobile
theme=default
theme=default
theme=compact
theme=compact
theme=natemoo-re
theme=natemoo-re
theme=novatorem
theme=novatorem
theme=karaoke
theme=karaoke
theme=apple
theme=apple
theme=spotify-embed
theme=spotify-embed

↑ Back to contents

Equalizer styles

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
theme=spotify-card&eq_style=bars
eq_style=spectrum
theme=spotify-card&eq_style=spectrum
eq_style=mirror
theme=spotify-card&eq_style=mirror
eq_style=wave
theme=spotify-card&eq_style=wave
eq_style=pulse
theme=spotify-card&eq_style=pulse
eq_style=iso
theme=spotify-card&eq_style=iso
eq_style=ribbon
theme=spotify-card&eq_style=ribbon
eq_style=floor
theme=spotify-card&eq_style=floor
eq_style=dots
theme=spotify-card&eq_style=dots
eq_style=vu
theme=spotify-card&eq_style=vu
eq_style=ring
theme=spotify-card&eq_style=ring
eq_style=ripple
theme=spotify-card&eq_style=ripple
eq_style=heartbeat
theme=spotify-card&eq_style=heartbeat
eq_style=pixel
theme=spotify-card&eq_style=pixel
eq_style=glow
theme=spotify-card&eq_style=glow
eq_style=bubbles
theme=spotify-card&eq_style=bubbles
eq_style=skyline
theme=spotify-card&eq_style=skyline
eq_style=tunnel
theme=spotify-card&eq_style=tunnel
eq_style=none
theme=spotify-card&eq_style=none

↑ Back to contents

Options

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 theme=spotify-card
eq_style Equalizer for Spotify themes — see Equalizer styles. Unknown values fall back to bars. bars theme=spotify-card&eq_style=iso
background_color Background color (hex without #). 121212 theme=spotify-card&background_color=0d1117
border_radius Border radius in pixels. 10 theme=spotify-card&border_radius=24
bar_color Equalizer color (hex without #). 1ed760 for Spotify themes; 53b14f otherwise theme=spotify-card&eq_style=spectrum&bar_color=ff4fd8
bar_color_cover Take the equalizer color from the album cover (true/false). false theme=spotify-card&eq_style=spectrum&bar_color_cover=true
cover_image Show the album cover (true/false). true theme=spotify-card&cover_image=false
show_offline Show "Not playing" instead of a recently played track when nothing is playing (true/false). false theme=spotify-card&show_offline=true
interchange Swap artist and song name positions (true/false). false theme=spotify-card&interchange=true
mode Color mode for apple and spotify-embed (light/dark). light theme=apple&mode=dark
hide_remaster Strip "Remastered" suffixes from song titles (true/false). false theme=spotify-card&hide_remaster=true
profanity Censor profanity in titles (true/false). false theme=spotify-card&profanity=true
redirect Open the current or recently played track on Spotify instead of returning an image — use it as the link target (true/false). false —

Example

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&amp;redirect=true">
  <img src="https://spotify-spark.vercel.app/api/view?uid=YOUR_UID&amp;theme=spotify-card&amp;eq_style=iso" alt="Spotify Now Playing" />
</a>

↑ Back to contents

Development

Self-deploy your own instance

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:

  1. Fork LienThuan04/Spotify-SPARK.
  2. 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.
  3. Firebase — create a Firebase project, enable Cloud Firestore, generate a service-account JSON key, and base64-encode it (see Setting up Firebase).
  4. Vercel — import your fork, set environment variables SPOTIFY_CLIENT_ID, SPOTIFY_SECRET_ID, BASE_URL (https://<your-vercel-url>/api), FIREBASE, and optionally FEEDBACK_URL, then deploy.
  5. Register users — in your Spotify app's User Management, add each Spotify account (name + email) that may connect via <your-vercel-url>/api/login.

Running for development locally without Vercel

To run the application locally without Vercel:

  1. Copy .env.example to .env in the root directory and replace the placeholder values with your actual configuration.

  2. Install the required dependencies:

    pip install -r api/requirements.txt
  3. Run the application:

    python api/app.py
  4. 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.

Running for development locally with Vercel

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

Setting up Vercel

Setting up Firebase

  • 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

Setting up Spotify dev

  • Login to developer.spotify.com
  • Create a new project
  • Edit settings to add Redirect URIs
    • add http://localhost:3000/api/callback

Running locally

  • Install Vercel command line with npm i -g vercel
  • Create .env file 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 in FIREBASE
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

Run unittest

  • 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

How to Contribute

  • 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]

Known Bugs

404/500 Error when playing local files

Other Platforms

↑ Back to contents

Feedback and ideas

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.

↑ Back to contents