[API Request] Playlist folders

[certuna]

Type of change

API Clarification

Proposal description

Playlist folders for better playlist organisation - a popular feature in iTunes/Apple Music and often requested by users.

As usual we're in a bit of a chicken/egg situation where it isn't worthwhile for Navidrome to implement it, since Subsonic clients wouldn't be able to make use of them, so support in the OS API would get things going.

Should be relatively straightforward - a list of PlaylistFolder objects, each containing Playlist objects.

Backward compatibility impact

No response

Backward compatibility

• No backward compatibility impact.

API details

• new endpoints createPlaylistFolder, deletePlaylistFolder (presumable, only if empty), updatePlaylistFolder, getPlaylistFolder, getPlaylistFolders
• new responses playlistFolders, playlistFolderWithPlaylists

Security impacts

No response

Potential issues

No response

Alternative solutions

No response

[dweymouth]

Would it make sense to support "Album folders" (ie collections) as well? Of course that could be a separate OpenSubsonic extension - just starting the discussion. (And personally wondering why this feature is so often requested for playlists and not other content types)

[certuna]

Yes I already started that discussion here, and indeed in terms of data structure they're very similar - just objects (folders/collections) of objects (playlists/albums) of objects (songs).

[Tolriq]

There was already some discussions around that at some point.

IMO the big question is do we support subfolder and infinite levels of deepness or not?

From user feedback another way to manage this is to handle tags and being able to affect multiple tags to collections (so playlists, albums, artists).

That fit probably 99% of the needs if not all with some adjustments and is relatively easy to handle at all levels.

Personally that's something I'd prefer to see.

[deluan]

@certuna, iTunes/Apple Music actually allows multiple (infinite?) levels:

But I agree that this can be a nightmare for clients (that's why I din't implement in Navidrome yet, the current menu code is very messy :P)

[deluan]

@Tolriq Some users tell me that they have hundreds of playlists, and being able to organize them in folders and subfolders are essential for them. Not sure how tags would solve their use case. But in general tags would be a good solution. It was also discussed here: navidrome/navidrome#1858

[Tolriq]

@deluan tags are the same as folders but flat.

The usual way to handle those are via chips for example (https://m3.material.io/components/chips/overview)

Since you can add multiple tags to playlists, you can easily filter and browse, while still seeing all if wanted and easily navigating.

You can have tags "Level 1", "Level 2", "Level 3" and apply them to playlists to generate the same "deepness" the user select the 3 tags.

But the magic is that he can only select level 1 and level 2 and see everything that could have been in level 3 and level 3b and level 3c for example. Or level 1 and Level 3, this allows a lot more flexibility in organizing and navigating the playlists, something that folders can not offer except if you allow a playlist to be in multiple folder (WTF to manage this) or duplicate your playlist (also WTF to manage)

This covers all the needs and add more features than folders.

[certuna]

Hmm yes not a fan of infinitely deep trees. Would this also help with implementing Mood and Style tags?

[Tolriq]

I don't see a relation between tags and those. In the end tags are really like genres. Just applied to current collections : Artists/Albums/Playlists/Podcasts (I would also support them for radios, but I suppose if we support them for radios some will want to expand to songs too, up for debate).

[sentriz]

what about a generic collection type? just a bag of ids. could be playlists, tracks, podcast episodes, whatever. and a parent collection ID for nesting

I think it could work since subsonic already require that ids are unique across different types (star.view takes a single ID param which works for tracks, albums, and podcast episodes already)

it also would address #73 I believe

[Tolriq]

Ids are not forced to be different when using id3 there's specific parameters for that, and it's not enforced anywhere.

But proposed tag system is mostly that, we have a tag list and we apply tags to what we want. So you can reuse a tag for multiple different media type.

We can eventually also add a global getTagItems that returns things that have the tag in any type, just need to properly define the paging first.

[deluan]

I like the idea of using tags instead of folders for all media types, but @sentriz is right: There are endpoints that, because how they are implemented, they force servers to have distinct ids across different media types, even for id3 endpoints. Examples from the Subsonic API doc:

star, unstar,

The ID of the file (song) or folder (album/artist) to star.

setRating

A string which uniquely identifies the file (song) or folder (album/artist) to rate.

getCoverArt

The ID of a song, album or artist.

Because of this, most (if not all) server implementations already make ids distinct across media types, by making them unique or prefixing with the media type.

I think any new endpoint we define that receives an id should also receive a mediaType. And maybe even propose an extension to add mediaType to the current endpoints that do disambiguation by distinct ids (as the ones above).

[Tolriq]

As said star/unstar have The ID of an album to star. Use this rather than id if the client accesses the media collection according to ID3 tags rather than file structure. Multiple parameters allowed.
For coverArt we already discussed this and explicited that the ID is the ID of the cover art not the id of the media.

Anyway since IDs have no reasons to be forced to be unique across the different type we have no reason to enforce that in the future.
Forcing the IDs to be unique for servers that don't already do that would just make their life impossible. Most servers cheats and have autoincrements and prefix the ids, but it's just an hack around the API, not a proper base for an API. Real unique IDs accross all media type and handling joins and triggers would not be fun.

For new endpoints unless the endpoint name is explicit like getLyricsBySongId parameters needs to be explicit so will be songId, albumId, ... a parameter should not represent different incompatible things.

If there's any doubts already, I propose we change getLyricsBySongId to have a songId parameter instead of id to clear things up and show how it should be in the future.

mediaType should only be used for disambiguation of the values returned by the API. Passing an ID and the type of ID makes no sense in a proper API. Either the parameter name or the function name should be enough to define things. (But I'm OK to enforce parameters names even if the function name is clear enough.)

[vg16855]

This is a very important feature for users who make a lot of playlists.

[DahliaWitt]

This is already a common idiom compared to existing apps (Spotify, iTunes) and should be adopted and supported here.

[DahliaWitt]

I drafted a V1 spec at this PR: #255

Koel now has nested playlist folders built in (koel/koel#2612) and it implements OpenSubsonic, so there's a server with the feature and no way to expose it to clients.

I wrote up a v1 spec based on what was proposed here: flat list + parentId for nesting (Apple and Spotify both do multi-level), client-assigned sortOrder so manual ordering is preserved, per-user placement so you can file shared playlists without touching them, and getPlaylists unchanged for backward compatibility.

On tags: I don't think folders and tags are competing, I think both can exist. Playlist folders (and nested ones) are explicitly needed to match common idioms found in other music software (iTunes, Spotify, Rekordbox…). The thing I need is to bring an existing iTunes/Rekordbox/Koel hierarchy over intact, and a flat tag set can't carry a tree.

PR: #255. Feedback welcome, especially from client authors.