[API Request] Per-user Library for a user-managed filter over the server's catalog

[hashhar]

Type of change

API extension

Proposal description

This is my first foray into Subsonic and the personal media server space. I've been a "files-only" media user for a long time. I'd be happy to implement this in one of the servers whichever is easier for a newcomer and has people who can help guide me through the contribution by answering any questions I may have. I spent more time on this than I'd like to admit, it's my first time writing a proposal/specification so pardon any mistakes I may have made - happy to learn if you can point out what to change.

Also I hope I didn't overdo it in terms of the details. This was mostly just thinking work so no code would be wasted anyway.

The problem

1. Large personal collections: A user with 100k tracks may only actively listen to 30k of them. The rest are archives, RIPs that haven't been triaged or music kept for completeness. Shuffle and "recently added" show everything with no way to curate except playlists.

2. Multi-user households: A family sharing a Navidrome instance has kid's music, one person's jazz and another's metal all in one catalog. No way for each person to say "this is mine" without the admin pre-organizing files into separate directories and assigning access. That's static, fragile, and doesn't handle overlapping taste.

Navidrome's multi-library feature solves the admin-managed, folder-based case. Users still can't dynamically curate their own view.

This proposal adds a per-user library: a user-managed set of items (artists, albums, songs) that scopes browsing, search, and playback across existing endpoints. Each user gets one implicit library. It is not named or ordered. It acts as a filter on the catalog, not a content container.

Relationship to #73 (Album Collections) and #75 (Playlist Folders)

This is not a generalization of #73. Different problem.

#73 wants curated, named, ordered lists of albums. That's structurally identical to playlists but with album entries instead of songs. The clean path for #73 is extending playlists to support album-level (and potentially artist-level) entries and it should be a separate, complementary proposal.

As @Tolriq noted in #73 "should this work for artists, not just albums? Should it support cross-media types?" The user library holds artists, albums, and songs in one set with cascading membership.

Why existing features don't work

Favorites/starred

Users could star everything and use getStarred2 as their entry point. Problems:

• conflates "favorite" with "ownership"
• getStarred2 is a standalone dump, not a filter across the API
• no way to scope getAlbumList2, getRandomSongs or search3 to starred items
• no cascading artist/album membership. You'd need to manually add every song by an artist instead of adding the artist once and keep adding any new ones from the artist you add to your library.

Jellyfin made this compromise (isFavorite is effectively "in my library") and users can't distinguish favorites from things they've just added.

Playlists

A mega-playlist of all library songs. We can do better than Spotify. 😅

• can't scope getAlbumList2 or getArtists to a playlist
• managing a 20k-song playlist is unwieldy in every client
• no cascading artist/album membership. You'd need to manually add every song by an artist instead of adding the artist once and keep adding any new ones from the artist you add to your library.
• no playlist of artists or albums so can't have a view like "artists in my library" or "albums in my library"

Prior art

Other APIs

• Jellyfin: isFavorite on /Items as a library filter + admin library access. Closest model, but conflating favorites with library membership is a known pain point.
• Ampache: Admin-assigned Catalog Filter Groups. Users can't create their own filters.
• Plex: Library Sections shared per-user, Collections are admin-managed within sections. No per-user dynamic curation.

Community discussions

• [API Request] Album Collections #73: Curated named album lists (playlists-for-albums). Different problem, composes cleanly with this proposal.
• [API Request] Playlist folders #14, [API Request] Playlist folders #75: Playlist folder discussions that evolved into collection talk.
• User-manager album lists navidrome/navidrome#5000: User-managed album lists, cross-referenced to [API Request] Album Collections #73.
• Create a personal music library for large collection of music navidrome/navidrome#4442: "Multi-library support is pretty static - you have to split the music beforehand on the file system. What I'm looking for is to do it on the fly."
• Assign every song or album to one or multiple users to make personal libraries navidrome/navidrome#1695: Assign songs/albums to specific users for personal libraries.
• Feature: Add music/Albums to personal user libary jellyfin/jellyfin#8481: "I would like the ability to add music into your own personal library."
• Navidrome user on Lemmy: "When I browse the artists I end up not recognizing about half... it significantly affects my relationship to my music library."
• Airsonic API is returning results from library folders that user does not have access to airsonic-advanced/airsonic-advanced#364: API returned results from folders the user shouldn't access. Per-user scoping was broken and hard to implement.

Backward compatibility impact

Fully additive. New endpoints plus one new optional parameter (inLibrary) on existing browsing endpoints.

• Servers without the extension: no change. getOpenSubsonicExtensions won't list userLibrary so clients won't send library parameters.
• Clients without the extension: no change. They never send inLibrary and will see the full catalog.
• musicFolderId: unchanged. inLibrary is separate and composable. musicFolderId=2&inLibrary=true means "items from music folder 2 that are also in my library".

Backward compatibility

• No backward compatibility impact.

API details

Note: Add/remove endpoints use repeatable query parameters for item IDs. Bulk operations may hit URL length limits with GET. Servers implementing this extension SHOULD support the form POST extension (#26). Clients SHOULD use POST for bulk add/remove.

New endpoints

getUserLibrary: Metadata about the authenticated user's library.

One implicit library per user. No create/delete - it exists when the account exists and is initially empty.

Parameters: none

<subsonic-response status="ok" version="...">
  <userLibrary itemCount="4521"
               artistCount="312" albumCount="487" songCount="4521"
               lastModified="2025-04-01T18:22:00Z"/>
</subsonic-response>

Field	Type	Required	Description
itemCount	int	Yes	Explicit entries (not counting cascaded items)
artistCount	int	Yes	Artists in the library (explicit + cascaded)
albumCount	int	Yes	Albums in the library (explicit + cascaded)
songCount	int	Yes	Songs in the library (explicit + cascaded)
lastModified	datetime (ISO 8601)	Yes	Last modification time

---

getUserLibraryEntries: Explicit entries in the user's library with optional type filtering and pagination.

Parameter	Required	Default	Description
type	No	all	Filter: artist, album, song
offset	No	0	Pagination offset
count	No	100	Max entries to return (server may cap this)

<subsonic-response status="ok" version="1.16.1">
  <userLibraryEntries totalCount="4521" offset="0" count="100">
    <entry id="ar-99" type="artist" added="2025-03-15T12:00:00Z"/>
    <entry id="al-442" type="album" added="2025-03-14T09:30:00Z"/>
    <entry id="sg-8821" type="song" added="2025-03-10T20:00:00Z"/>
  </userLibraryEntries>
</subsonic-response>

Field	Type	Required	Description
id	string	Yes	Item ID (same IDs used across the Subsonic API)
type	enum	Yes	artist, album, or song
added	datetime	Yes	When the item was added

---

addToUserLibrary: Add items to the library. Idempotent - re-adding is a no-op.

Parameter	Required	Description
artistId	No	Artist ID(s) to add (repeatable)
albumId	No	Album ID(s) to add (repeatable)
songId	No	Song ID(s) to add (repeatable)

At least one required. Use form POST (#26) for bulk operations.

Returns empty <subsonic-response> with status="ok".

---

removeFromUserLibrary: Remove items from the library. Idempotent - removing an absent item is a no-op.

Parameter	Required	Description
artistId	No	Artist ID(s) to remove (repeatable)
albumId	No	Album ID(s) to remove (repeatable)
songId	No	Song ID(s) to remove (repeatable)

At least one required.

Returns empty <subsonic-response> with status="ok".

Removing an artist removes the artist-level entry but does not remove individually-added albums or songs by that artist. A user adds { Album Y by Artist X, Artist X } and then removes { Artist X }. The library would still contain { Album Y by Artist X } because it was added separately.

---

New parameter on existing endpoints

Optional boolean inLibrary on these endpoints:

Endpoint	Effect when inLibrary=true
getArtists	Only artists in the library
getIndexes	Only artists in the library
getAlbumList	Only albums in the library
getAlbumList2	Only albums in the library
getRandomSongs	Only songs in the library
getSongsByGenre	Only songs in the library
getStarred	Intersect starred items with library
getStarred2	Intersect starred items with library
search2	Scope results to library
search3	Scope results to library
getSimilarSongs	Only similar songs in the library
getSimilarSongs2	Only similar songs in the library
getTopSongs	Only top songs in the library

Composable with musicFolderId - both present means intersection.

Absent or false = full catalog, same as today.

Cascading membership

Adding an artist to library means all their albums and songs are in the library (including future releases the server ingests).

Adding an album to library means all songs on that album are in the library. The album's artist appears in getArtists when inLibrary=true.

Adding individual songs means only those songs. Their album/artist appear in library-scoped browsing only if at least one song/album is in the library.

So Artist = "I want everything by this artist", Album = "I want this specific album" and Song = "I want just this track".

Response augmentation

Servers supporting userLibrary SHOULD add inLibrary (boolean) to Child and AlbumID3 responses. Lets clients show library status inline (a "+" icon or similar) without extra calls.

<song id="sg-123" title="Example" artist="Someone" album="Something"
      ... inLibrary="true" />

Extension registration

{
  "name": "userLibrary",
  "versions": [1]
}

Security impacts

• Library data is per-user. No reading or modifying another user's library.
• addToUserLibrary MUST respect existing access controls - can't add items from music folders the user doesn't have access to.
• No new auth mechanisms.

Potential issues

1. Cascading membership is opinionated: "Add artist" means follow, including future releases. Some users may want static snapshots. I chose what most users would expect. The alternative is to make the library only accept tracks which also solves the next point but requires more user effort.

2. Performance: A library with 50k cascaded songs makes filtered queries expensive. Servers should index library membership. getUserLibraryEntries returns only explicit entries (not cascaded), keeping responses manageable. Clients should use the inLibrary response field for inline status instead of fetching the full entry list.

3. Multi-library interaction: User adds an item from Library A, then loses access to Library A. Item should become invisible in library-scoped queries but not deleted. If access is restored it reappears.

4. POST support for bulk operations: Servers SHOULD support form POST ([API Request] Officialise POST support #26). Initial library population may need multiple batched calls.

Alternative solutions

This used to be my first v0 proposal idea but it didn't compose well and was bad design IMO.

Virtual musicFolderId workaround (existing clients, no changes needed)

A server or proxy can offer partial library support by:

1. Maintaining a per-user library via a separate web UI or companion app.
2. Injecting a virtual entry (e.g. {id: 9999, name: "⭐ My Library"}) into getMusicFolders responses.
3. When a client sends musicFolderId=9999 filter responses to only include items in the user's library.

Works for all 10 endpoints that accept musicFolderId (getArtists, getIndexes, getAlbumList, getAlbumList2, getRandomSongs, getSongsByGenre, getStarred, getStarred2, search2, search3). Does NOT cover getSimilarSongs, getSimilarSongs2, getTopSongs.

Works with Symfonium, Ultrasonic, Feishin and likely more as they already pass musicFolderId to browsing calls when a folder is selected.

Limitations:

• Can't add/remove from within the Subsonic client
• Can't compose with real musicFolderId filtering (same parameter)
• Overloaded semantics - a library is not a music folder
• Post-filtering may return fewer results than requested

Bridge solution only. The extension supersedes it.

[hashhar]

Oh and once I have some traction with this and a nice implementation (hopefully in Navidrome) I'd be happy to tackle the Collections spec. I have opinions there too coming from the MusicBrainz side of the world.

[paulijar]

As an alternative idea, maybe there could be a system to add user-defined labels/tags to songs, albums, and artists? It wouldn't be awfully much more complex than the original suggestion but would provide much more possibilities for the end-user.

[hashhar]

A tag could also work well with the same concept. I imagine you are also thinking that each search/browsing related endpoint will accept a tag to scope the search similar to how I propose it with a library? then a user library will be one specific tag and the ecosystem can agree on a canonical tag for "library" (or maybe it doesn't matter since users usually don't switch servers often).

it composes beautifully, also works as the foundation for collections.

the only concern i have is a much larger API surface + having to handle crud + multi-valued filtering (intersection vs union of tag values). I'll try to see if I can change something in the proposal so that it acts as the v1 for tags and can be evolved transparently to full tag support.

The inLibrary boolean on browsing endpoints establishes the pattern for user-scoped filtering. The tags work could generalize this to named user tags by replacing inLibrary=true with tagId=123. For backward compat servers could treat the implicit library as a reserved tag internally. The new endpoints (addToUserLibrary, removeFromUserLibrary) map naturally to addTag/removeTag with an implicit tag ID.

It's MUCH more work is my only worry.

[gravelld]

We've actually implemented something similar in Astiga - profile filters: https://asti.ga/docs/library/hiding-storage-with-profiles/

It's not exposed via the Subsonic API as such, but having a profile for Subsonic clients will filter the results that are returned. Currently it's only implemented for filtering by cloud storage backend. The intention is to make the selector (profile) take in more info than just the client type, and the filter being able to have more criteria - genre, bitrate, arbitrary tags etc.

So year, promoting the filter itself through the Subsonic API would also be useful for management of the filter.