Playlist

🟢 Stable

This API is stable since festivald v1.0.0.

Playlist's are objects where

The key is the playlist name (string)
The value is an array of Entry-like objects, Playlist Entries

Field	Type	Description
`${PLAYLIST_NAME}`	array of `Playlist Entry`'s	The name of the playlist as the key, and the `Song` entries in an array

Playlist Entry

The Entry object in the context of playlists is similar to Entry, except it does not have the path field.

The Playlist Entry takes 2 forms: valid & invalid:

`Playlist Entry` form	Meaning
`valid`	This is a valid `Song`; it exists within the current `Collection`
`invalid`	This `Song` does NOT exist in the current `Collection`, although it did in a previous one (it may have been lost in-between `Collection` resets)

These objects will appear in playlist-related methods, like playlist_full & playlist_single.

Example:

{
  "hello": [ // <--- the playlist name is "hello"
    // This is an "valid" entry.
    // The underlying Song exists in the current Collection.
    {
      "valid": {
        "key_artist": 46,
        "key_album": 168,
        "key_song": 1756,
        "artist": "Artist Name",
        "album": "Album Title",
        "song": "Song Title"
      }
    },
    // This is an "invalid" entry.
    // The underlying Song doesn't exist in Collection anymore.
    {
      "invalid": {
        "artist": "Artist Name",
        "album": "Album Title",
        "song": "Song Title"
      }
    }
  ]
}

`valid`

The data definition for valid playlist entry types.

Exact same as Entry but does not have path.

Field	Type	Description
key_artist	Artist key (unsigned integer)	This entry's `Artist key`
key_album	Album key (unsigned integer)	This entry's `Album key`
key_song	Song key (unsigned integer)	This entry's `Song key`
artist	string	The `Artist` name
album	string	The `Album` title
song	string	The `Song` title

Example:

{
  "key_artist": 46,
  "key_album": 168,
  "key_song": 1762,
  "artist": "Artist Name",
  "album": "Album Title",
  "song": "Song Title"
}

`invalid`

The data definition for invalid playlist entry types is the same as valid, but with no keys.

Field	Type	Description
artist	string	The `Artist` name
album	string	The `Album` title
song	string	The `Song` title

Example:

{
  "artist": "Artist Name",
  "album": "Album Title",
  "song": "Song Title"
}

Validation

Upon a Collection reset, it is not guaranteed that the same Song's will even exist at all.

This is a problem since existing Playlist's may now be referencing Song's that don't exist anymore.

The way festivald handles this is not to delete them, but "mark" those entries as invalid.

These invalid entries will continue to exist indefinitely.

Upon every future Collection reset, if an invalid entry is able to recover (a matching Song file is found with the correct metadata), it will turn back into a valid entry automatically.