mbzlists-embed

This library was generated by an AI tool based on the mbzlists XSPF format spec and example XSL transforms. The source is reviewed and maintained by humans.

Embed mbzlists XSPF playlists in any HTML page. Supports three styles described here:

• minimal — title + plain track list
• fancy — numbered tracks with cover art, duration, and artist/album/date metadata
• full — complete annotated playlist (headers, paragraphs, images, quotes, and tracks as authored in mbzlists)

Zero dependencies. Works via <script> tag or as an ES module.

Quick start (CDN / unpkg)

<!-- Add once in your page -->
<script src="https://unpkg.com/[email protected]/dist/mbzlists-embed.min.js"></script>

<!-- Option A: data-attribute auto-embed -->
<div data-mbzlists-src="/playlists/shoegaze.xspf"
     data-mbzlists-style="fancy"></div>

<script>
  MbzlistsEmbed.autoEmbed();
</script>

<!-- Option B: explicit render call -->
<div id="playlist"></div>

<script>
  MbzlistsEmbed.render('#playlist', {
    src: '/playlists/shoegaze.xspf',
    style: 'full',
  });
</script>

Styles

minimal

Title + unstyled track list. Inherits your page's fonts and colours — good for blending into blog posts.

Starting with Shoegaze

• To Here Knows When — My Bloody Valentine · Loveless
• Sleep — Slowdive · 1991-11 through 1993-01: Souvlaki Demos
...

fancy

All spec blocks rendered in a card with numbered recording rows. Each row shows cover art (from Cover Art Archive, falling back to a placeholder), track duration, and release date alongside the title, artist, and album. A stats bar below the playlist title shows track count, total duration, and creation/modification dates. Fully customizable via CSS — see Custom CSS.

┌────────────────────────────────────────────────────┐
│ Starting with Shoegaze                             │
│ 13 tracks · 58:44+ · created Mar 21, 2025 · ...   │
│                                                    │
│  1  [art]  To Here Knows When  5:31               │
│            My Bloody Valentine · Loveless (1999)  │
│  2  [art]  Sleep                                  │
│            Slowdive · Souvlaki Demos              │
└────────────────────────────────────────────────────┘

full

Renders every block in the mbzlists XSPF extension — headers, paragraphs, quotes, images, lists, and recording entries — exactly as you wrote them in mbzlists. Document-like, inherits page styles. Recording entries show cover art (72 × 72 px), duration, and release date. Falls back to a plain recording list for XSPF files without the mbzlists extension.

Custom CSS

Every element rendered by this library carries a mbzlists__* CSS class. You can override any style by targeting these classes in your own stylesheet after loading the library.

Class reference

| Class | Element | Description | |---|---|---| | .mbzlists | div | Root container for all styles | | .mbzlists--minimal | div | Minimal style modifier | | .mbzlists--fancy | div | Fancy style modifier | | .mbzlists--full | div | Full style modifier | | .mbzlists__title | h1/h2 | Playlist title | | .mbzlists__tracklist | ul | Track list (minimal only) | | .mbzlists__track | li | Single track row (minimal only) | | .mbzlists__track-title | span | Track title (minimal only) | | .mbzlists__sep | span | Separator between track fields — ' — ' before artist, ' · ' before album (minimal only); hide with display: none | | .mbzlists__track-artist | span | Artist name (minimal only) | | .mbzlists__track-album | span | Album name (minimal only) | | .mbzlists__recording | div | A recording entry (full/fancy) | | .mbzlists__recording-cover | img | Cover art thumbnail; links to the recording when a MusicBrainz ID is present | | .mbzlists__recording-cover-link | a | Wrapper link around the cover art (display: block) | | .mbzlists__recording-info | div | Wrapper for title + meta | | .mbzlists__recording-title | span | Recording title, contains <a> if linked | | .mbzlists__recording-duration | span | Track duration (e.g. 5:31), inside the title span | | .mbzlists__recording-meta | span | Artist · album (release date) line | | .mbzlists__recording-artist | span | Artist name within meta | | .mbzlists__recording-album | span | Album name (with release date if present) within meta | | .mbzlists__stats | div | Playlist stats bar: track count, total duration, creation/modification dates | | .mbzlists__header | h1–h6 | Section header block | | .mbzlists__header--1 … --6 | h1–h6 | Level-specific header modifier | | .mbzlists__paragraph | p | Paragraph block | | .mbzlists__quote | blockquote | Quote block | | .mbzlists__image | figure | Image block | | .mbzlists__image-caption | figcaption | Image caption | | .mbzlists__list | ol/ul | List block | | .mbzlists__list--ordered | ol | Ordered list modifier | | .mbzlists__list--unordered | ul | Unordered list modifier | | .mbzlists__list--checklist | ul | Checklist modifier | | .mbzlists__list-item | li | List item |

Example: dark theme for fancy

<style>
.mbzlists--fancy {
  background: #1a1a2e;
  border-color: #16213e;
  color: #eee;
  box-shadow: none;
}
.mbzlists--fancy .mbzlists__title { color: #e94560; }
.mbzlists--fancy .mbzlists__recording { border-bottom-color: #16213e; }
.mbzlists--fancy .mbzlists__recording::before { color: #555; }
.mbzlists--fancy .mbzlists__recording-title { color: #eee; }
.mbzlists--fancy .mbzlists__recording-duration { color: #666; }
.mbzlists--fancy .mbzlists__recording-meta { color: #888; }
.mbzlists--fancy .mbzlists__stats { color: #666; }
</style>

minimal inherits page fonts and colours naturally — target .mbzlists--minimal for any container-level overrides.

API

MbzlistsEmbed.render(target, options) → Promise<void>

| Parameter | Type | Description | |-----------|------|-------------| | target | string \| Element | CSS selector or DOM element to render into | | options.src | string | URL of the XSPF file to fetch | | options.xml | string | Raw XSPF XML string (alternative to src) | | options.style | 'minimal' \| 'fancy' \| 'full' | Embed style (default: 'minimal') |

// From a URL
await MbzlistsEmbed.render('#playlist', {
  src: '/playlists/shoegaze.xspf',
  style: 'fancy',
});

// From a raw XML string
await MbzlistsEmbed.render(document.getElementById('playlist'), {
  xml: myXmlString,
  style: 'full',
});

MbzlistsEmbed.autoEmbed()

Scans the page for [data-mbzlists-src] elements and renders each one.

<div data-mbzlists-src="/playlists/shoegaze.xspf" data-mbzlists-style="minimal"></div>

ES module / npm

npm install mbzlists-embed

import { render, autoEmbed } from 'mbzlists-embed';

await render('#playlist', { src: '/playlists/shoegaze.xspf', style: 'fancy' });

Development

An example page showing all three styles is in example/. To run it:

npm run build
npx serve .
# open http://localhost:3000/example/

The example loads example/shoegaze.xspf via the local ESM build at dist/mbzlists-embed.esm.js, so it reflects your latest build automatically.

Getting your XSPF file

In mbzlists, open your playlist → Export → Download as XSPF. Host the file anywhere your page can reach it (same origin, or a CORS-enabled host).

License

MIT