ListenBrainz Widgets

Check out the landing page for the widgets here to see them in action.

About

Two widgets hosted on GitHub Pages for your ListenBrainz listening history: a live Now Playing card you can embed on your site, and a shareable Weekly Top 5 Albums image for social media. Both are single HTML files with no build step — set your username, deploy to GitHub Pages, and you're done. A landing page (index.html) links to both.

Also check out my ListenBrainz Autoposter that automatically posts to Mastodon and / or BlueSky your weekly top listens.

---

Now Playing Widget

listenbrainz-now-playing.html — an auto-refreshing card that shows your current or most recent track, with album art and an animated equalizer. Designed to be embedded as an iframe on any website.

Setting your username

Option A — hardcode it (recommended for a personal widget)

Open listenbrainz-now-playing.html and find this line near the top of the <script> block:

const DEFAULT_USERNAME = "";

Replace the empty string with your ListenBrainz username:

const DEFAULT_USERNAME = "yourname";

Option B — pass it in the URL

Leave DEFAULT_USERNAME empty and append ?user=yourname to the iframe src. Useful if you want to reuse one hosted file for multiple profiles:

<iframe src="https://yourusername.github.io/listenbrainz-widget/listenbrainz-now-playing.html?user=yourname" ...></iframe>

If both are set, the ?user= URL parameter wins.

Matching the background color to your site

The widget background is controlled by two CSS variables near the top of the <style> block:

/* Background colors — set these to match your site's background.
   --bg-0 should match your page's main background color.
   --bg-1 is used for the subtle gradient and should be slightly lighter. */
--bg-0: #1e2129;
--bg-1: #252b38;

Change --bg-0 to your site's background color and --bg-1 to a slightly lighter shade of the same color. If your site has a light background, use light values (e.g. --bg-0: #f5f5f5).

Deploying to GitHub Pages

1. Push the files to a GitHub repository
2. Go to Settings → Pages in your repo
3. Under Build and deployment, set Source to Deploy from a branch
4. Set Branch to main and folder to / (root), then click Save
5. After ~1 minute your widgets will be live at https://yourusername.github.io/your-repo-name/

Embedding the iframe

<iframe
  src="https://yourusername.github.io/your-repo-name/listenbrainz-now-playing.html"
  width="460"
  height="180"
  style="border:none; border-radius:20px; overflow:hidden;"
  title="Now Playing on ListenBrainz"
  loading="lazy">
</iframe>

Sizing notes:

• The card is capped at 440px wide — 460px gives a little breathing room
• 180px height fits the card with no scrollbar
• border-radius on the iframe clips the widget corners to match the card's rounded edges

Cover art

The widget resolves album art from two sources, in order:

1. Cover Art Archive — ListenBrainz asynchronously maps each listen to a MusicBrainz release and stores the result in a mbid_mapping field. When that mapping is present the widget fetches the artwork directly from the Cover Art Archive. This is the primary source and works for any music service.

2. MusicBrainz search fallback — When mbid_mapping is absent (the track is actively playing and hasn't been processed yet, or ListenBrainz couldn't match it), the widget searches the MusicBrainz API by artist, track name, and album, then uses the first matching release MBID to fetch art from Cover Art Archive. The card renders immediately with a music note placeholder; the art swaps in once the search completes.

If neither source returns art, the widget shows a music note placeholder.

How it works

• Polls the ListenBrainz API every 20 seconds
• Shows Now Playing with an animated equalizer if a track is active
• Falls back to Last Played with a timestamp if nothing is currently playing
• Clicking the card opens your ListenBrainz profile in a new tab
• Polling pauses automatically when the tab or iframe is not visible

---

Top 5 Albums

top5.html — generates a shareable 1200×1200 PNG of your top 5 most-played albums, complete with album cover art. Pick a time range from the dropdown, then click Download PNG.

Generating an image

Once deployed (see Deploying to GitHub Pages above), open:

https://yourusername.github.io/your-repo-name/top5.html

Choose a time range from the dropdown (see Choosing a time range below), wait for your top 5 albums to load with their cover art, then click Download PNG. The image is rendered at 2× resolution and ready to post to Instagram, Mastodon, Bluesky, and more.

Choosing a time range

Use the dropdown to switch between This week (default), Last week, This month, This year, and All time. The card heading and date range update to match, and the date label is taken directly from the window ListenBrainz computed (its from/to timestamps).

These are ListenBrainz's own calendar ranges, not rolling windows — "This week" is the current Monday-to-now week, "Last week" is the previous full Monday–Sunday week, and so on.

A note on the ListenBrainz date ranges

The ListenBrainz statistics API has two limitations worth understanding, because they affect which dates the card shows:

1. The ranges are fixed calendar periods, not rolling windows. There is no "last 7 days" or "last 30 days" option. week means the previous completed Monday–Sunday week, month means the previous calendar month, etc. So selecting "Last week" will not give you the most recent seven days.

2. The stats are batch-computed, roughly once a day, and lag behind real time. A range only reflects data up to the last time ListenBrainz recalculated it, so today's listens (and sometimes yesterday's) won't appear yet.

As a concrete example, here is what the API actually returned on June 9, 2026:

Dropdown option	API range	Window returned	Last updated
This week	this_week	Jun 1 – Jun 8	Jun 3
Last week	week	May 25 – Jun 1	Jun 2
This month	this_month	Jun 1 – now	—
This year	this_year	Jan 1 – now	—
All time	all_time	everything	—

The card always shows the real window via the API's from/to timestamps, so you can see exactly which days each image covers. If you need a genuine up-to-the-minute, rolling 7-day total, that isn't available from the statistics API — it would require computing the totals yourself from the raw /user/{name}/listens endpoint.

Username

The generator uses the same DEFAULT_USERNAME hardcode and ?user=yourname URL override as the Now Playing widget. It fetches data from the ListenBrainz statistics API and pre-loads all album art before rendering so the exported PNG is crisp and complete.