Metadata Specification

Album metadata is provided as a nested dict that contains information for the album, its tracks, and the player.

A simple example follows:

album = {
    "artist": "Sluggy Puppernutters",
    "title": "Self-Titled Album",

    "artist_url": "https://sluggy.example",
    "album_url": "https://sluggy.example/album/self-titled",

    "artwork": {
        "1x": "album-art-thumb.jpg",
        "2x": "album-art-hidpi.jpg",
        "fullsize": "album-art-fullsize.jpg"
    },

    "tracks": [
        {
            "title": "Hit Single",
            "filename": "hit single.mp3",
            "artwork": {
                "1x": "hit-single-thumb.jpg"
            },
            "explicit": True,
            "duration": 273
        },
        {
            "title": "We Hate Our Hit Single",
            "filename": "something else.mp3",
            "explicit": True,
            "duration": 273,
            "lyrics": [
                "Here is a stanza",
                "And another stanza",
                "",
                "And this is the second verse",
                "It's the first but worse"
            ],
            "about": "Here's a cat.\n\n![](https://placekitten.com/640/480)"
        },
        {
            "title": "You'll have to buy the album to hear this one",
            "duration": 3600
        }
    ],
    "theme": {
        "foreground": "white",
        "background": "black",
        "highlight": "yellow",
        "hide_footer": False,
        "user_css": "fancypants.css",
        "footer_text": "Custom footer text"
    }
}

Album

The top-level dict contains the following data:

• artist: The recording artist’s name

• title: The title of the album

• artist_url: The recording artist’s homepage/website

• album_url: The canonical web address for this album

• artwork: The album-level artwork data

• tracks: The individual tracks of this album

• theme: Visual theme settings

Tracks

Track data is a list of dict of the following data for each track:

• title: The title of the track

• filename: The preview audio file (optional)

• artwork: Track-level artwork data

• explicit: Whether this track contains explicit lyrics

• duration: The length of the track (in seconds)

• lyrics: The lyrics of the song, either as a big newline-separated string or as a list of strings (one per line).

• about: The extended information of the track, either as a newline-separated string or as a list of strings (one per line). This text may be formatted with markdown.

Theme

The visual theme settings are as follows:

• foreground: Foreground text color

• background: Background color

• highlight: Highlight text color

• hide_footer: Whether to hide the “Made with” footer

• user_css: User CSS file to include, for deeper visual customization

• footer_text: Custom HTML to override the “Made with” footer

Artwork

Artwork data can be attached to an album and/or its tracks. It is a dict with the following keys (all optional):

• width: The nominal width of the thumbnail

• height: The nominal height of the thumbnail

• 1x: The normal-DPI rendition of the thumbnail

• 2x: The high-DPI rendition of the thumbnail

• fullsize: The fullsize rendition of the artwork