[API Request] Playlist folders

[jeffvli]

Type of change

API extension

Proposal description

Add the ability to create/update/delete playlist folders, and assign playlists to folders.

Subsonic currently does not organize playlists, and returns them in a single static list. Having playlist folders would allow users to create server-side groupings for related playlists.

I would say for simplicity, it should be 1-1 playlist to folder pairing per-user. Folders are private to the user and will need to be created by each user.

Backward compatibility impact

No response

Backward compatibility

• No backward compatibility impact.

API details

New endpoints

createPlaylistFolder

Description: Creates a playlist folder

Parameters:
- name (required) -- The name of the playlist folder
- parentId -- The id of the playlist folder to nest under
- comment - A comment for the folder
- playlistIdToAdd - A playlist id or array of playlist ids to add to the folder

deletePlaylistFolder

Description: Deletes a playlist folder

Parameters:
- playlistFolderId (required) -- The id of the playlist folder

updatePlaylistFolder

Description: Updates a playlist folder

Parameters:
- playlistFolderId (required) -- The id of the playlist folder
- name -- The name of the playlist folder
- comment --  A comment for the folder
- playlistIdToAdd - A playlist id or array of playlist ids to add to the folder
- playlistIdToRemove - A playlist id or array of playlist ids to remove from the folder

getPlaylists2

• Use "isDir: true" to specify that the item is a playlist folder (could possibly also split out folders to a separate object array)
• Use "parentId" (or "playlistFolderId") to specify the playlist or folder's parent

Possible response 1: Require additional requests to navigate through playlist folders similar to getMusicDirectory

Parameters:
- username -- If specified, return playlists for this user only
- playlistFolderId -- If specified, return only playlists / folders that are related to the folder
- recursive [boolean] -- If specified, return all playlists related to the folder, including playlists within nested folders

Example:
GET /getPlaylists2
"playlist": [
  {
    "id": "800000003",
    "name": "Non-associated Playlist",
    "owner": "admin",
    "public": false,
    "created": "2021-02-23T04:35:38+00:00",
    "changed": "2021-02-23T04:35:38+00:00",
    "songCount": 43,
    "duration": 17875
  },
  {
    "id": "800000003",
    "name": "Folder 1",
    "isDir": true,
    "owner": "admin",
    "created": "2021-02-23T04:34:56+00:00",
    "changed": "2021-02-23T04:34:56+00:00",
  }
]

GET /getPlaylists2?playlistFolderId=800000003
"playlist": [
  {
    "id": "800000005",
    "name": "Playlist in folder",
    "owner": "admin",
    "public": false,
    "created": "2021-02-23T04:35:38+00:00",
    "changed": "2021-02-23T04:35:38+00:00",
    "songCount": 43,
    "duration": 17875
  },
]

Possible response 2: Return all folders and their nested playlists in the same request.

Parameters:
- username -- If specified, return playlists for this user only

Example:
"playlist": [
  {
    "id": "800000003",
    "name": "Non-associated Playlist",
    "owner": "admin",
    "public": false,
    "created": "2021-02-23T04:35:38+00:00",
    "changed": "2021-02-23T04:35:38+00:00",
    "songCount": 43,
    "duration": 17875
  },
  {
    "id": "800000004",
    "isDir": true,
    "name": "Folder 1",
    "owner": "admin",
    "created": "2021-02-23T04:34:56+00:00",
    "changed": "2021-02-23T04:34:56+00:00",
    "children": [
      {
        "id": "800000002",
        "parentId": "800000004",
        "name": "Nested Playlist",
        "owner": "admin",
        "public": true,
        "created": "2021-02-23T04:34:56+00:00",
        "changed": "2021-02-23T04:34:56+00:00",
        "songCount": 43,
        "duration": 17786
      },
      {
        "id": "800000002",
        "parentId: "800000004",
        "name": "Nested Folder",
        "isDir": true,
        "owner": "admin",
        "public": true,
        "created": "2021-02-23T04:34:56+00:00",
        "changed": "2021-02-23T04:34:56+00:00",
        "children": []
      },
    ]
  }
]

Updates for existing endpoints

createPlaylist / updatePlaylist

Optionally add additional parameters to the existing playlist endpoints to assign playlists to and from folders

Parameters (to add):
- playlistFolderId (optional) -- The id of the playlist folder (use empty string to remove from folder?)

getPlaylists (if we don't want getPlaylists2)

Parameters (to add):
- playlistFolderId -- If specified, return only playlists that are related to this playlist folder

Response:
- parentId -- The id of the playlist folder the playlist is related to

Similar to above, add isDir and parentId to applicable playlists so we can list the playlists and folders in a flat array.

getPlaylist

Response:
- parentId -- The id of the playlist folder the playlist is related to

Additional QoL (optional)

• An endpoint to return all songs from all playlists in a folder (recursively)

Security impacts

No response

Potential issues

No response

Alternative solutions

No response

[dweymouth]

Interesting idea. If we decide to add something like this, IMO it should be not just for playlists, but albums and artists as well. Also I am not a fan of the name "folders" for this concept, since it implies filesystem folders, but what about "collections"? So users could create playlist collections, album collections, or artist collections. Or should the collections be multi-typed i.e. you can add albums, artists, and playlists to a single collection? This might be a harder concept to design into a good client UI but is certainly more flexible.

[Tolriq]

Is there a need for parent / child ? Else this could be considered like the tag system many others system use.

[deluan]

When I receive requests to implement this, users are basically asking for the functionality/UX already supported by the big players, like Apple Music:

Spotify:

This is great for Playlists, but for Album/Artist/Song, I think tags (or grouping) works best.

[dweymouth]

@deluan what are you referring to by grouping for album/artist/song? The thing I like about this concept for album/artist/songs is that the grouping, folders, collections, whatever we call it would be per-user and could be created/updated via the API, unlike tags which most servers including Navidrome don't expose write-access to and in any case are global, not user-specific.

However I don't think it's that high-priority.

[deluan]

unlike tags which most servers including Navidrome don't expose write-access

I mean tags like in "blog post tags", very different from ID3 tags. AFAIU, tagging (like in "blog post tags") is a more generic, loose and flexible way to group things, but I don't see it replacing Playlists folders.

I think folders is not the same as tags. Folders imply a hierarchical structure, a parent/children relationship.

By grouping I mean use the grouping ID3 tag/Vorbis comment.

would be per-user and could be created/updated via the API

IMHO, any organizational solution like this should be per-user, except when they come from the id3tag, like grouping or mood.

[Tolriq]

Tag have a double meaning here, I think he meant tag as grouping value (as I did in my first comment). You add a tag to an object. Not a TAG like a music file TAG.
So many cases where wording for music is a double sense :p

[sumnerevans]

We should think about how to handle deeply nested folders. I don't think we should limit the number of nestings at a spec level, but I think that clients might want to impose limits for UX purposes. I think that Sublime Music would probably flatten anything past 2 or 3 levels deep.

For this reason, I'm in favor of response option 2.

[deluan]

I don't think there should be a limit in the nesting levels. Too much nesting is a bad UX experience, for sure, but the user gets what they want. Ex from Apple Music:

[sumnerevans]

Alternative response option: flat list where each playlist has an optional parentId pointer. It has the advantage of being more backwards-compatible (besides the directories).

Example

Parameters:
- username -- If specified, return playlists for this user only

Example:
"playlist": [
  {
    "id": "800000003",
    "name": "Non-associated Playlist",
    "owner": "admin",
    "public": false,
    "created": "2021-02-23T04:35:38+00:00",
    "changed": "2021-02-23T04:35:38+00:00",
    "songCount": 43,
    "duration": 17875
  },
  {
    "id": "800000004",
    "isDir": true,
    "name": "Folder 1",
    "owner": "admin",
    "created": "2021-02-23T04:34:56+00:00",
    "changed": "2021-02-23T04:34:56+00:00"
  },
  {
    "id": "800000002",
    "parentId": "800000004",
    "name": "Nested Playlist",
    "owner": "admin",
    "public": true,
    "created": "2021-02-23T04:34:56+00:00",
    "changed": "2021-02-23T04:34:56+00:00",
    "songCount": 43,
    "duration": 17786
  },
  {
    "id": "800000002",
    "parentId: "800000004",
    "name": "Nested Folder",
    "isDir": true,
    "owner": "admin",
    "public": true,
    "created": "2021-02-23T04:34:56+00:00",
    "changed": "2021-02-23T04:34:56+00:00",
    "children": []
  }
]

[dweymouth]

We can do this but to be truly backward compatible, I think we need to put it behind a new getPlaylists2 API, and have 'getPlaylists` return the flat list of only playlists, excluding folders. Otherwise a client not aware of OpenSubsonic would show all the playlist folders as if they were regular playlists with zero tracks. In the case where we create a new API, we could choose to go with an actual nested response schema if we want, which could make it easier for clients to display the proper tree structure. I have no idea how many playlists and playlist folders are typical (I don't really use playlists personally) but we can even make the API paginated if needed.

[deluan]

I agree that it should be a new endpoint (getPlaylists2?) but I think the answer should be flat, like @sumnerevans suggestion. IMO, it would be easier to extend the currently structures used to support it, both for servers and clients.

[Tolriq]

We should discuss pagination before adding new endpoints that return flat list that can be large.
Something that will be the base for all new endpoints.
New pagination should be better than current and return total counts for example.

[spl0k]

Why not just add some kind of path parameter / field that would hold where the playlists are located in folders. You wouldn't need new entities in responses to represent folders and would allow to keep current endpoints with the flat representation. We still might need new endpoints for the folders themselves if we want to set some additional attributes on them such as a description, and to allow their creation before moving any playlist there.

[jsspen]

Has anyone taken a look at this recently?

[vg16855]

Yeah it's the biggest feature missing from subsonic clients that apps like Spotify and Apple Music have.

[DahliaWitt]

My proposal: #255