Spotify x GitHub - Readme Cards

Cool looking cards for your GitHub README that show your currently playing song on Spotify.

How to use?

Unfortunately, due to Spotify not allowing quota extensions for the API, running this is a bit more involved than the usual click-and-deploy route...

Refer to DEPLOYING.md for more details.

For local build instructions, you want BUILDING.md.

Use your personal URL like so: ![](https://now-playing-cards.vercel.app/now-playing/q?uid=YOUR_USER_ID) and paste your user ID from the last step instead of YOUR USER ID.

OPTIONAL: For more custom styling, refer to the parameters below.

URL Parameters

Parameters	Description	Options
size	Size of the cards to be displayed.	small, med (default), large
theme	Color theme of the card displayed.	light, dark (default), colorblock (extract colors from the song cover art)
bg-color	custom background color for the card (is ignored if a theme is also specified)	CSS compatible hex string in the format #RRGGBB or #RRGGBBAA
text-color	custom text color for the card (also ignored if a theme is specified too)	CSS compatible hex string in the format #RRGGBB or #RRGGBBAA

Demos

The cards come in various sizes and styles, which can also be customized by passing the above parameters to the URL. You can mix and match many options to your liking and there's more of them coming soon. Here's some examples.

size: large theme: colorblock bar: waves	size: med theme: light bar: waves	size: small theme: dark bar: waves

size: large theme: light bar: progress-bar	size: med theme: dark bar: progress-bar	size: small theme: colorblock bar: progress-bar

Roadmap

TODO:

• add landscape cards
• make more themes
• add endpoints for top artists/tracks
• make self-hosting easier, maybe move to Vercel KV store?
• bring back progress bars & waves
• actually add docs
• cache readme pics, they take too long to load
• turn on strict typechecking no

Landscape cards

The portrait oriented cards tend to occupy a lot of vertical space, so having one of them at the end or in the middle of your profile readme would look kinda wierd. so besides not having to left/right align the cards against some other content for space, horizontal cards make much more sense in terms of using the space better. This is an example SVG implementation of such layout, will implement the daynamic data fetching soon and then this can be used.

Top tracks / artists card

an separate endpoint (/top) for cards showing a list of a user's top artist (at /top/artsits) or top tracks (/top/tracks).

will create a design on figma and an svg implementation of it before setting up dynamic data and the corresponding endpoints.

more themes

more themes for card backgrounds besides the ones available now (dark, light and colorblock)

• gradient

  extracts the dominant colors from the album cover art, but instead of a flat color fill, the background will have a gradient fill, between the extracted color and black (as the gradient-dark theme) or between the extracted color and white (as gradient-light)

• blurred covert art background

  having the blurred version of the cover art as the card background. Again, could have a black or white tints on top of the blur (for text legibility) and call them blur-dark or blur-light themes.

Contribution

Any and every contribution is welcomed and appreciated.