Playlist format

Overview

The Calliope playlist format is very similar to XSPF. For a list of available properties and their meanings, see the XSPF specification.

The XSPF format is not suited to line-based processing, so the Calliope playlist format has some differences from XSPF:

  1. A playlist is a JSON Lines stream, and playlist item is a separate JSON document.

  2. In addition to the properties defined by XSPF, a playlist may contain any number of custom properties. These must be namespaced using a . character. For example creator is an XSPF property, while musicbrainz.artist_id is a custom property in the ‘musicbrainz’ namespace.

Working with the Calliope playlist format

The cpe validate command can validate that a playlist stream conforms to the schema.

The cpe import and cpe export commands convert between the Calliope playlist format and other formats. It’s recommended that you store your playlists on disk in XSPF format, so other applications can read them, and use the cpe import and cpe export commands when you want to bring them in and out of Calliope operations.

Example playlist

Here is a short example of a Calliope format playlist. Remember that the format is optimised for processing with line-based tools such as jq.

{
  "playlist.title": "Winter Mix 3 - Too many words for their own good"
  "creator": "Jeffrey Lewis & Los Bolts",
  "title": "Avenue A, Shanghai, Hollywood",
  "musicbrainz.artist_id": "e1889f99-02fa-40aa-828c-4a74c255c568"
}
{
  "creator": "SKAndalous All-Stars",
  "title": "Age of Insects"
  "musicbrainz.artist_id": "bd9a7562-ee6f-41c0-a01b-da7119ef8f17",
  "musicbrainz.artist_country": "US"
}
{
  "creator": "Courtney Barnett",
  "title": "Lance Jr."
  "musicbrainz.artist_id": "55111838-f001-494a-a1b5-9d818db85810",
  "musicbrainz.artist_country": "AU"
}

Schema

The Calliope playlist is formally defined by the following schema:

Playlist item

https://gitlab.com/samthursfield/calliope/-/tree/main/calliope/playlist-item.jsonschema

An item in a Calliope playlist.

Core properties are taken from the XSPF standard.

type

object

properties

  • location

URI of resource to be rendered. Probably an audio resource, but MAY be any type of resource with a well-known duration, such as video.

type

string

  • identifier

Canonical ID for this resource. Likely to be a hash or other location-independent name, such as a MusicBrainz identifier.

type

string

  • title

type

string

  • creator

type

string

  • annotation

A human-readable comment on the track. This is character data, not HTML, and it may not contain markup.

type

string

  • info

URI of a place where this resource can be bought or more info can be found.

type

string

  • image

URI of an image to display for the duration of the track.

type

string

  • album

type

string

  • trackNum

type

integer

  • duration

The time to render a resource, in milliseconds.

type

number

minimum

0

patternProperties

  • ^[\w_]+(\.[\w_]+)+$

additionalProperties

False