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, in one of three styles — minimal, fancy, or full — described here. Supports both the 1.0 and 1.1 mbzlists spec (auto-detected from the XSPF file).

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

See it live at unpkg.com/mbzlists-embed/example/index.html (or browse example/ in this repo) for a demo of every style plus custom CSS variants.

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>

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. See example/index.html for worked examples (a stripped-down track list, a dark card, and a compact inline list).

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 |

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 plus custom CSS variants is in example/. To run it:

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

The example loads example/shoegaze-v1.1.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