Skip to content

Data Export

Other than using a playlist in other platforms, you can also download the playlist data in portable XSPF (spiff) format by clicking on the Export button and selecting Download as XSPF from the dropdown. Since spiff doesn't allow rich annotations as present in mbzlists playlists, the exported XML file has an extension to support this. The specification for the extension is documented next.

Warning

Currently images are exported with urls which cause a dependency on the tool to be live. This will change in a future version.

XSPF Extension Documentation

1.0

This document describes the mbzlists XML namespace, which is designed to extend the standard XSPF (XML Shareable Playlist Format) with rich, annotated block content. This allows a playlist to be more than just a list of tracks; it can be a narrative, a curated mix with commentary, or a photo album.

Note

The current specification duplicates the track details in extension content and the tracklist of the playlist.

Namespace Declaration

To use the mbzlists vocabulary, you must declare the namespace on the root <playlist> element of your XSPF document. We will use the prefix mbzlists for this.

<playlist version="1" xmlns="http://xspf.org/ns/0/" xmlns:mbzlists="http://docs.lepisma.xyz/mbzlists/ns/1.0/">
  <!-- XSPF general content goes here -->
  <extension application="https://docs.lepisma.xyz/mbzlists/ns/1.0/">
    <!-- mbzlists playlist content goes here >
  </extension>
  <!-- continued XSPF content -->
</playlist>

Based on the XSPF guidelines, all extra mbzlists content goes inside an <extension> tag as shown above. Next we specify content that can go inside the <extension>.

1. Metadata: <mbzlists:metadata>

1.1. <mbzlists:lastModifiedOn>

Date time information about the last modification done for the playlist. The format is similar to that of <date> tag in XSPF file.

2. Block Container: <mbzlists:blocks>

Each mbzlists playlist is represented as a list of blocks that can contain text elements, images, or songs. The <mbzlists:blocks> element is the container for all the individual content blocks within the list. The blocks currently supported are specified next:

2.1. <mbzlists:header>

Text for the heading. It can contain inline HTML for formatting like <i> or <a>. It contains the following attributes.

  1. level. A value from 1 to 6 that specifies the heading level.
2.2. <mbzlists:paragraph>

A simple text block for commentary or descriptions. The text content of the paragraph. It can contain inline HTML for formatting like <i> or <a>.

2.3. <mbzlists:image>

An image block with various display options as following attributes:

  1. caption (optional) A caption to be displayed with the image.
  2. withBorder boolean (true or false) to indicate if the image should have a border.
  3. withBackground boolean to indicate if the image should have a background color.
  4. stretched boolean to indicate if the image should stretch to fill the width.

The main content is displayed using child elements that could be either of the following: 1. <mbzlists:file> with url as the attribute specifying the full download URL of the image. 2. <mbzlists:blob> with name attribute specifying the filename and base64 encoded image data as content.

2.4. <mbzlists:mbrecording>

A block for a specific MusicBrainz recording. This is the core element identifying each track in the playlist.

Attributes:

  1. mbid The MusicBrainz recording ID.
  2. length The length of the recording in milliseconds.

Child elements:

  1. <mbzlists:title> The title of the recording
  2. <mbzlists:artist> Name of the music artist. This has mbid as the attribute keeping the MusicBrainz artist ID.
  3. <mbzlists:release> Title of the release associated with this track. This has mbid attribute identifying the MusicBrainz release ID, along with date that has string representation of the release date. Note that the date is optional, as well as, has no strict format as it can by just the year or a string like 1985-11-23 or something else.
2.5. <mbzlists:quote>

Element representing quoted text as its content. It has caption and alignment (left, right, or center) as attributes.

2.6. <mbzlists:list>

Element containing text lists. Each list, including sublists, can only be of one type (ordered, unordered, etc.)

Attributes:

  1. style, ordered, checklist, or unordered
  2. counterType (optional) numeric is the only value supported right now.

Child elements:

<mbzlists:listItem> represents a single item in the list with checked as optional attribute present in checklist type lists. The text content is kept inside <mbzlists:listContent> element. In case of nesting, another <mbzlists:list> can go after <mbzlists:listContent>.

Complete Example

Here is a complete example exported from the example list here:

<?xml version="1.0" encoding="UTF-8"?>
<playlist version="1" xmlns="http://xspf.org/ns/0" xmlns:mbzlists="http://docs.lepisma.xyz/mbzlists/ns/1.0/">
  <title>Test playlist with annotation</title>
  <creator>mbzlists</creator>
  <info>https://mbzlists.com/list/8a07ff86-7406-45f6-9afc-cbdd97df7b02</info>
  <date>2025-08-18T14:52:47.027Z</date>
  <extension application="http://docs.lepisma.xyz/mbzlists/ns/1.0/">
    <mbzlists:metadata>
      <mbzlists:lastModifiedOn>2025-08-19T06:28:29.626Z</mbzlists:lastModifiedOn>
    </mbzlists:metadata>
    <mbzlists:blocks>
      <mbzlists:paragraph>This is a test playlist to showcase all features of an mbzlists playlist.</mbzlists:paragraph>
      <mbzlists:header level="2">This is a heading of level 2</mbzlists:header>
      <mbzlists:paragraph>This is a paragraph. A paragraph could &lt;b&gt;have&lt;/b&gt; &lt;i&gt;inline&lt;/i&gt; styles. Also you can add links like &lt;a href="https://xspf.org/"&gt;this&lt;/a&gt;.</mbzlists:paragraph>
      <mbzlists:header level="3">This is a level 3 heading</mbzlists:header>
      <mbzlists:header level="4">This is a level 4 heading</mbzlists:header>
      <mbzlists:paragraph>Let's add a few songs:</mbzlists:paragraph>
      <mbzlists:mbrecording mbid="7b54cad3-7542-4edf-8d0e-fd423c9b8166" length="566466">
        <mbzlists:title>In Your Room</mbzlists:title>
        <mbzlists:artist mbid="a6bf1276-9150-40fc-a94e-6b14f377fe3d">Airiel</mbzlists:artist>
        <mbzlists:release mbid="3c05be8d-1783-42f5-8207-645fc741bc0d" date="2023-11-03">Winks &amp; Kisses: 20th Anniversary Deluxe Edition</mbzlists:release>
      </mbzlists:mbrecording>
      <mbzlists:paragraph>You can also add text lists.</mbzlists:paragraph>
      <mbzlists:list style="ordered" counterType="numeric">
        <mbzlists:listItem>
          <mbzlists:listContent>One</mbzlists:listContent>
        </mbzlists:listItem>
        <mbzlists:listItem>
          <mbzlists:listContent>Two</mbzlists:listContent>
        </mbzlists:listItem>
        <mbzlists:listItem>
          <mbzlists:listContent>Three, only numeric bullets are supported in ordered lists</mbzlists:listContent>
        </mbzlists:listItem>
      </mbzlists:list>
      <mbzlists:paragraph>The lists can be of unordered type too, and also checkboxes.</mbzlists:paragraph>
      <mbzlists:list style="unordered">
        <mbzlists:listItem>
          <mbzlists:listContent>A list without order</mbzlists:listContent>
        </mbzlists:listItem>
        <mbzlists:listItem>
          <mbzlists:listContent>Another element</mbzlists:listContent>
          <mbzlists:list style="unordered">
            <mbzlists:listItem>
              <mbzlists:listContent>Nesting is allowed, but only with the same list type.</mbzlists:listContent>
            </mbzlists:listItem>
          </mbzlists:list>
        </mbzlists:listItem>
      </mbzlists:list>
      <mbzlists:list style="checklist">
        <mbzlists:listItem>
          <mbzlists:listContent>Check lists are also supported</mbzlists:listContent>
        </mbzlists:listItem>
        <mbzlists:listItem checked="true">
          <mbzlists:listContent>This is a done item</mbzlists:listContent>
        </mbzlists:listItem>
      </mbzlists:list>
      <mbzlists:paragraph>Let's add a few more songs.</mbzlists:paragraph>
      <mbzlists:mbrecording mbid="ea346317-7114-42a8-b16d-dd41d5f70bd4" length="237000">
        <mbzlists:title>kisses</mbzlists:title>
        <mbzlists:artist mbid="a16371b9-7d36-497a-a9d4-42b0a0440c5e">Slowdive</mbzlists:artist>
        <mbzlists:release mbid="318f59fe-dabf-4023-9817-25cb30769777">Kisses (Remixes)</mbzlists:release>
      </mbzlists:mbrecording>
      <mbzlists:mbrecording mbid="3be1e03e-376f-49fd-a0e3-2b372c6bfecd" length="231600">
        <mbzlists:title>Time Baby III</mbzlists:title>
        <mbzlists:artist mbid="0f24bcb0-8d37-409d-aed1-92bd4e5337ed">Medicine</mbzlists:artist>
        <mbzlists:release mbid="28fbf6ac-7056-4009-aad4-6620970b8ee1" date="1994">Sounds of Medicine: Stripped and Reformed Sounds</mbzlists:release>
      </mbzlists:mbrecording>
      <mbzlists:paragraph>Of course images are supported,</mbzlists:paragraph>
      <mbzlists:image caption="" withBorder="false" withBackground="false" stretched="true">
        <mbzlists:file url="https://mbzlists.com/api/image/e5b6845b-a9b6-4870-99aa-cf3d3ed1ba07/"/>
      </mbzlists:image>
      <mbzlists:quote caption="Here is the caption for the quote" alignment="left">Quoted texts show up like this. Lorem ipsum (/ˌlɔː.rəm ˈɪp.səm/ LOR-əm IP-səm) is a dummy or placeholder text
 commonly used in graphic design, publishing, and web development. Its 
purpose is to permit a page layout to be designed, independently of the copy that will subsequently populate it, or to demonstrate various fonts of a typeface without meaningful text that could be distracting.</mbzlists:quote>
    </mbzlists:blocks>
  </extension>
  <tracklist>
    <track>
      <title>In Your Room</title>
      <creator>Airiel</creator>
      <album>Winks &amp; Kisses: 20th Anniversary Deluxe Edition</album>
      <info>https://musicbrainz.org/recording/7b54cad3-7542-4edf-8d0e-fd423c9b8166</info>
      <location>https://musicbrainz.org/recording/7b54cad3-7542-4edf-8d0e-fd423c9b8166</location>
    </track>
    <track>
      <title>kisses</title>
      <creator>Slowdive</creator>
      <album>Kisses (Remixes)</album>
      <info>https://musicbrainz.org/recording/ea346317-7114-42a8-b16d-dd41d5f70bd4</info>
      <location>https://musicbrainz.org/recording/ea346317-7114-42a8-b16d-dd41d5f70bd4</location>
    </track>
    <track>
      <title>Time Baby III</title>
      <creator>Medicine</creator>
      <album>Sounds of Medicine: Stripped and Reformed Sounds</album>
      <info>https://musicbrainz.org/recording/3be1e03e-376f-49fd-a0e3-2b372c6bfecd</info>
      <location>https://musicbrainz.org/recording/3be1e03e-376f-49fd-a0e3-2b372c6bfecd</location>
    </track>
  </tracklist>
</playlist>