Music, live on your profile.
SpotiBadge generates dynamic Spotify README badges for GitHub profiles, portfolios, and project pages. Show your real-time now playing track, recently played songs, top tracks, or top artists as a customizable SVG widget. No database, no trackers, just your music.
Use the hosted app at spotibadge.vercel.app to generate your badge without writing a single line of code.
SpotiBadge is a no-code Spotify now playing badge generator for GitHub README profiles. It uses Spotify OAuth, Flask, Jinja2 SVG templates, and Vercel-friendly stateless URLs to render live music widgets without storing user data.
Keywords: Spotify README widget, Spotify now playing badge, GitHub profile music badge, no-code Spotify badge, dynamic SVG badge, recently played Spotify widget, top tracks badge, top artists badge, Vercel Spotify widget.
- Real-Time Now Playing: Instantly displays the song you are currently vibing to on Spotify.
- Recently Played Fallback: If you pause your music, the widget automatically falls back to showing your most recently played track.
- BPM-Synced Equalizer: The animated EQ bars pulse and change color based on the actual Tempo (BPM) and Energy of the track.
- Dynamic Blur Themes: The widget extracts a color palette from the album art to generate a beautiful, dynamic blurred background.
- Click to Play: The entire widget is a link that redirects visitors straight to the track on Spotify.
- Stateless & Secure: No database is required! Your Spotify credentials are encrypted and signed directly into the widget URL.
- Self-Service Mode: Friends can use your hosted instance without you having to manually whitelist them in the Spotify Developer Dashboard. They just provide their own Client ID and Secret!
Getting your own SpotiBadge takes a few clicks and requires no coding.
- Visit spotibadge.vercel.app.
- Connect your Spotify account.
- Customize the widget style in the browser.
- Copy the generated Markdown.
- Paste it into your GitHub profile README.
That is it. You do not need to clone this repo, deploy an app, edit code, or manually build an SVG.
👉 Read the Full Setup Guide (SETUP.md) if you want to self-host or use your own Spotify Developer credentials.
The setup guide covers:
- How to generate your free Spotify Developer credentials.
- How to bypass Spotify's "403 Forbidden" errors.
- How to deploy your own instance of SpotiBadge for free on Vercel.
You can customize your badge directly via URL parameters.
| Parameter | Type | Default | Description |
|---|---|---|---|
background_type |
string | color |
Options: blur_dark, blur_light, color |
border_color |
hex | ffffff |
Hex color code without the # |
background_color |
hex | 181414 |
Hex color code without the # (Only works if type is color) |
show_status |
boolean | false |
Set to true to show "Vibing to:" or "Recently played:" |
content_size |
string | medium |
Adjust inner album art, text, and bars. Options: small, medium, large |
compact |
boolean | false |
Legacy smaller widget layout |
Example Markdown:
[](https://spotibadge.vercel.app/redirect/your_id)SpotiBadge is entirely stateless. Once you generate your public_id via the login flow, you can interact with these core endpoints:
- SVG Image:
GET /api/now-playing/{public_id}.svg - Redirect:
GET /redirect/{public_id}
- SVG Image:
GET /api/recently-played/{public_id}.svg - Redirect:
GET /redirect-recently-played/{public_id}
- SVG Image:
GET /api/top-track/{public_id}.svg?time_range=short_term - Redirect:
GET /redirect-top-track/{public_id}?time_range=short_term - Options for
time_range:short_term(4 weeks),medium_term(6 months),long_term(1 year)
- SVG Image:
GET /api/top-artist/{public_id}.svg?time_range=short_term - Redirect:
GET /redirect-top-artist/{public_id}?time_range=short_term
(Note: Adding custom CSS or changing widget parameters via query parameters like ?compact=true works on all SVG endpoints.)
- Python 3 & Flask (Routing and OAuth Orchestration)
- Requests (Spotify API interaction)
- ColorThief (Extracting color palettes from Album Art)
- Jinja2 (SVG and HTML Templating)
- ItsDangerous (Stateless URL encryption)
Contributions are welcome! If you want to add new widgets (like Top Tracks or Top Artists), feel free to open a Pull Request.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request