1. Introduction¶
The Universal Playlist Format (UPF) is a data format for music playlists. It aims to be more flexible and complete than existing formats. A Universal Playlist (UPL) will allow better description of the tracks it contains, as well as enable added functionality in music players.
Rather than just a simple filename and, perhaps, a title, the UPF contains multiple identifiers (including the filename and title), which serve different use cases. The cryptographic hashes allow library management programs to always know which entry refers to which file, even if you move them or sync your playlist across computers (and even different players), while the MusicBrainz Track ID allows programs to always know, unambiguously and exactly, which song a particular file contains. That means that you will be able to upload a playlist to iTunes or Spotify (if they support the UPL format) and instantly have all your songs on those services, without having to search for them one by one.
2. Motivation¶
Current playlist formats are greatly lacking in descriptive power. Most formats are a simple ordered list of filenames, which is brittle and inflexible. Here are some of the usecases that playlist formats should be able to address, and which the UPF aims to:
- When files are moved, players should be able to automatically update their playlists, without any additional work from the user. The playlist should contain enough information for the player to unambiguously decide which playlist entry refers to which moved file.
- When user A sends a playlist file (and just the playlist, not any of the music files) to user B, user B's music player should be able to find all the songs from the playlist that user B already owns, so they can be played.
- A user should be able to export a playlist of all their songs from an online music service (for example, their iTunes playlists) and import them on another service (for example, Spotify), and have the latter service match the songs in the playlist with those on their library, allowing the user to listen to their songs without having to search for or match songs one by one.
- If a user has the same song in varying bitrates in their library, the player should be able to automatically group all the various alternatives under the same playlist item, and choose the best quality either automatically or by asking the user.
Current playlist formats don't allow the above use cases, because they don't contain enough information for music players to be able to unambiguously find the song each entry refers to. The UPF tries to change this, and enable all the above uses.
3. Specification¶
The UPF is YAML-based. A playlist that adheres to the UPF specification is
called a Universal Playlist, or UPL, and a UPL file has the file extensionupl, for example favorites.upl.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
The term "clients" will herein refer to music players, library managers, tag editors, and any other piece of software that reads or writes UPL files.
A UPL file MUST be valid YAML, and it SHOULD be formatted in a human-readable way. As YAML is UTF8-encoded, this specification will rely on that fact and not specify an encoding. All strings herein are assumed to be Unicode strings.
Each UPL file MAY contain multiple playlists, each represented as a separate YAML document.
3.1. Format¶
The top-level object is a YAML mapping, whose keys are detailed below.
3.1.1. format¶
string, mandatory
The format and version of the playlist. Currently, this is always "UPL1", as
that is the only version that exists.
3.2. name¶
string, recommended
The name of the playlist, for display purposes. No maximum number of characters is currently specified, but clients MAY enforce a maximum when reading or writing files.
3.3. id¶
string, optional
An RFC 4122 UUID, for identifying the playlist. This SHOULD be randomly
generated on playlist creation. If the client that is reading the playlist needs
an id and one is not provided in the file, the client SHOULD then generate
one.
3.3.1. entries¶
A sequence of mappings, containing the entries in the playlist. The keys of this mapping are described below.
3.3.1.1. artist¶
string, mandatory
The artist of the entry, for display or lookup purposes. As this can be used for lookups, care should be taken to set this field to mirror the official name as closely as possible.
3.3.1.2. title¶
string, mandatory
The title of the entry, for display or lookup purposes. As with artist, this
may be used for lookups, so it should be as close to the official title as
possible.
3.3.1.3. duration¶
float, recommended
The duration of the entry, in seconds. The minimum float accuracy is one second, (i.e. the value may be an integer), and the maximum accuracy is not currently specified.
3.3.2. ids¶
mapping, recommended
The ids key contains a mapping of IDs that uniquely identify various aspects
of the track. The client should try to gather and write as many IDs as is
practical for each track, and at least the filepath type is recommended, but
this can be omitted if the client cannot come up with any IDs.
The rationale behind this is that the artist, title and duration fields
are useful on their own, even in the absence of any other identifier.
Each key in the mapping is the type of the hash, and the value is the value of the hash. Clients SHOULD support at least the hashes in the Hash types section, but a client MAY choose to support additional hashes. Clients SHOULD ignore unknown hash types, but MAY NOT strip them from the file, and MUST include them in case the file is written again.
The names of hash types will be standardized in Hash types section.
3.3.3. Hash types¶
The names of the official hash types are as follows:
sha2: The SHA-2 function. Choosing a hash length is up to the client.sha3: The SHA-3 function. Choosing a hash length is up to the client.filepath: A string of the path of the file, for looking up in the filesystem. The path MAY be absolute or relative to the directory in which the UPL file resides.mbtrackid: The file's MusicBrainz Track ID. This is the MBID corresponding to themb_releasetrackidtag.mbrecid: The file's MusicBrainz Recording ID.acoustid: The file's AcoustID.acoustidfp: The file's AcoustID/Chromaprint fingerprint.
3.4. Example¶
---format:UPL1name:Favoritesid:2b43009f-d6a6-4f00-8533-09a9a73d8b54entries:-artist:Anciientstitle:Following the Voiceduration:408.764081632ids:sha2:e577cce68a69735acccd5d8603b3e663f6aa5bc9sha3:e577cce68a69735acccd5d8603b3e663f6aa5bc9mbtrackid:b00a2b97-53f1-485a-9121-1fe76b55e651filepath:Anciients/Following the Voice.mp34. Client behavior¶
To the extent that this specification can influence the behavior of programs reading/writing UPL files, it will try to specify some best practices for working with the UPL format.
- Clients MUST NOT modify any of the data in the playlist unless the user has specifically performed an action that the latter knows will modify data. Silent changing of identifiers MUST NOT be done, unless it is part of an editing operation such as changing tags or pointing the entry to a different version of a song. Silently changing the identifiers because the client has only managed to find a different version of the song is especially heinous, and MUST be avoided always.
To report issues or give feedback for this specification, please file an issue or issue a pull request to the project's repository.