[API Discussion] Existing single-valued fields that should be multi-valued

[dweymouth]

Type of change

API extension

Proposal description

I think it makes sense to cover all of these as a single discussion, since the way we'd handle it should be the same for all the fields, and different from handling new metadata fields like artist roles, etc.

The following are existing Subsonic API metadata fields that should be multi-valued:

• Artist (both albums and tracks should be able to have multiple artists)
• Genre (both albums and tracks should be able to have multiple genres)
• any others anyone can think of please add in the comments

Backward compatibility impact

We need to discuss if there's a way to do this without backward compatibility impact. A potential way could be to just add Artists and Genres as new fields to the album and song payloads, but this is a little awkward as the Artist and Genre fields would still exist and only have one of the potentially multiple entries from the Artists and Genres.

Backward compatibility

• No backward compatibility impact.

API details

Context above. We need to discuss what this would actually look like, API-wise.

Security impacts

No response

Potential issues

No response

Alternative solutions

No response

[Tolriq]

I had not yet the time to port the rest of the proposals but there's a lot to see about extending the metadata with new fields and everything.

Since we should differentiate album artists from song artists it should be all talked at the same time as it's connected to the multi values. Same for artist roles like composer and everything.
Need to ensure all can be covered without impacts on the namings / structure.

[gravelld]

We need to discuss if there's a way to do this without backward compatibility impact. A potential way could be to just add Artists and Genres as new fields to the album and song payloads, but this is a little awkward as the Artist and Genre fields would still exist and only have one of the potentially multiple entries from the Artists and Genres.

How about only supporting this in an extension? It would be a little confusing for client authors, but this is only something that needs to be understood once, by the programmer of the client.

[Tolriq]

That would require new API endpoints for nearly everything that returns data, in that case it's better to build a new API from the start, something that was already ruled out.

[lachlan-00]

The way I'll be doing this in Ampache is to add the plural element for each field. Keeping the original single values as the main/primary.

e.g. a song/album has a primary artist and then additional artists attached to the object

so the response returns

• artist:
• artists: []
• albumartist:
• albumartists: []

This will let me keep things back compatible and can be ignored by clients.

[sentriz]

since beets.io has nearly added support for this stuff it has peeked my interest

@dweymouth @lachlan-00 you both mentioned how to tackle backwards compatibility and i like the idea, just thought i would make sure we're on the same page:

problem

consider this musicbrainz release group, the tags of a track on this album may look like

albumartist="Marc Hurtado & Alan Vega"
albumartists=["Marc Hurtado", "Alan Vega"]

with the current state of subsonic clients and servers we just have a single album artist named "Marc Hurtado & Alan Vega", completely independent from any other artists named "Marc Hurtado" or "Alan Vega" that the user might have

getArtists

id	name
ar-1	Marc Hurtado & Alan Vega
ar-2	Marc Hurtado
ar-3	Alan Vega

getAlbums2

id	name	artist
al-1	Sniper	ar-1

here have no connection to ar-2 or ar-3, which is not so nice for the user 👎

proposal

considering the same release, we only store those individual artists

getArtists

id	name
ar-1	Marc Hurtado
ar-2	Alan Vega

getAlbums2

id	name	albumartist	albumartists
al-1	Sniper	ar-1	[ar-1, ar-2]

so just an xml/json array like thing as already suggested

now the user sees a much cleaner view of their album artists, and from a single album page, can click on either of the 2 albums artists to check them out 👍

---

does this line up with what was suggested already?

and how about for clients that don't support the extension? from their perspective the album artist is just "Marc Hurtado" and there's no mention of Alan Vega anywhere. maybe that's fine if was the Marc Hurtado was the primary artist, and he was the first in the list in the audio metadata. but maybe that's not always the case. is there a better way to do backwards compatibility?

[Tolriq]

Since OpenSubsonic is adding new fields that will be consistent in all cases as supporting both single and multiple artists, I do not think there's any benefits on implying that OpenSubsonic servers should update how they handle the older data.
Either they keep doing what they do and do not support the new fields and we should not have anything to say.
Or they support the new fields and then what is present is the older fields is not really related to Open Subsonic.

Anything we enforce can make things harder for the servers to manage their transition in handling both fields if they need internal rewrite.
So let's keep things simple and limited to the purpose of this project.

[lachlan-00]

We've gotten a bit long winded, should probably update the original proposal/comments now?

I suggest that this is limited to adding (for this change and all optional additions)

• song objects
  • add artists
  • add artistIds
  • add genres
• album objects
  • add artists
  • add artistIds
  • add genres
• artist objects
  • add genres

[Tolriq]

I would have merged all the new "data" fields addition in a single update (So also mood, bpm, ...).
Since all the fields are optional I'm not sure there's a need to handle each cases differently no?

We make the list of new supported fields and their definition. All the fields are optional. This is one of the simple non breaking change.

[lachlan-00]

we can do that too. i was just thinking that some servers may not be able to support all new fields in one go so doing them in groups would let servers say "supports multi-artist", supports x

[Tolriq]

No server will add them in one go, but it does not matter, they add the field as they have them. Some servers already have some in db and it's just exposing them. Some will need to scan the data, ...
Everything is optional data.

The only difference with current API is that when a field is supported by a server it must be returned with empty data when no data, so that clients can know that the data is missing and it's not the server not supporting the field.

[sentriz]

taking the subsonic "album" as an example it has the fields "artist", and "artistId". extending this, the natual thing seems to add 2 extra. giving us a total of "artist", "artistId", "artists", "artistIds"

for example

"album": {
  "id": "al-6",

  "artistId": "ar-1",
  "artist": "Alan Vega",

  "artistIds": [ "ar-1", "ar-2", "ar-3" ],
  "artists": [ "Alan Vega", "Alex Chilton", "Ben Vaughn" ],
}

though it feels a bit clunky, we assume that artistIds and artists are the same length, and sorted the same way. but it leaves room for mistakes

---

there's also the option of a single array with a more complex object like

"album": {
  "id": "al-6",

  "artistId": "ar-1",
  "artist": "Alan Vega",

  "artists": [ 
    {"id": "ar-1", "name": "Alan Vega"},
    {"id": "ar-2", "name": "Alex Chilton"},
    {"id": "ar-3", "name": "Ben Vaughn"}
  ],
}

though i don't know how that would translate to XML, or if we have anything like that elsewhere in the spec

thoughts on these options?

[sentriz]

search3 also works this way IIRC

[Tolriq]

I personally have 0 opinion about the best XML way.

[dweymouth]

I think that works, I was just thinking about avoiding the possibility of:

<album>
  <artist/>
  <song/>
  <genre/>
  <song/>
  <artist/>
  <song/>
</album>

but any half-decent XML parser should be able to handle this fine anyway

[sentriz]

OK should we roll with that then? I think not having the nesting will make things a little cleaner for clients too

[Tolriq]

For the record currently the doc does not cover XML, I hope to get some help to write that part, as it was already a tons of work to build the current doc, and it will take time to prepare the JSON proposals.

[epoupon]

Naïve question: in some of your examples in this whole discussion, we sometimes can read "albumartists", and sometimes "artists".
But do we agree we want to just use "artists" and the parent element is used to know the context? (in "album" => "album artist", in "track" => "track artist", like it is in the original Subsonic API).
And in getArtists, we list them all.

[Tolriq]

Well IMO no they are different and should be exposed differently properly.

1. To ensure that the returned value correspond to what we expect. Artists on album can be the album artists or the list of all artists of the albums or both.
2. getArtists should be able to return both only albumartist and all artists with a flags, as many people do not want to see hundreds of track collaborators. (Even worse if we expose composers, lyricist, ... as artists to get their metadata).
3. Being able to easily display the different data on the right place without needing to do additional queries.
4. Being able to easily filter albums where artists are album artists and albums where they are collaborators. So should be different filters.

Those are frequent needs from users, and all other media providers properly expose both data. (I personally have a full copy of the database and recreate the data from the tracks and albums, but this would help faster syncs and would help all the online first apps to propose the same features).

[epoupon]

Ok, but then for artists in general this is more than just duplicate existing "artist" fields to handle multiple values. Maybe this would deserve a separate discussion?

[Tolriq]

Not sure to follow what part you are referring to?

[epoupon]

I just mean that handling multi values for artists is more complicated than for genres if we want to refactor things like you proposed.

[Tolriq]

Not that much, but everything is split in multiple thread already, with the support of composers and everything. I'll try to build a full proposal for the field extensions soon.

[tamland]

Not sure if this has been mentioned, but many releases use specific order and words for multiple artists.

Examples:
https://www.discogs.com/master/143760-Alpha-Omega-Meets-Dub-Judah-Almighty-Jah
https://www.discogs.com/release/1663520-Alpha-And-Omega-Featuring-Jonah-Dan-Paul-Fox-12-And-Dan-I-Songs-From-The-Holy-Mountain
https://www.discogs.com/master/1967440-Jonah-Dan-Alpha-Omega-Spirit-Of-The-Ancients

Any ideas how this can be visually preserved by clients? I think the spec should say something about order at least (such as the server should return them as they appears)

[Tolriq]

1. Order
   This is a pain point for most providers :( They most of the time return the data sort alphabetically.
   While this is a nice to have and clients should try to keep the order that provider provide, I'm not sure that we should enforce this as it can be hard for servers. Maybe just a note about should try to keep tag order ?

2. Join / display value
   About the joints this is a point some providers support by returning a displayArtist and displayAlbumArtist fields so that clients can use that precise value and do not try to recreate the display value themselves. I'm not sure I already talked about those field somewhere here. But if servers can / want to support those I'd gladly expose them to the API.

[sentriz]

Maybe just a note about should try to keep tag order ?

i agree on the note 👍

some providers support by returning a displayArtist and displayAlbumArtist fields so that clients can use that precise value and do not try to recreate the display value themselves

i'm not sure that's entirely useful here, the client could display it, but it still needs to generate clickable links for individual components of it. eg [A](/artist/A), [B](/artist/B), and [C](/artist/C)

[Tolriq]

Well on Symfonium I open a bottomsheet with the actual list of artists if there's more than one. Having items directly clickable on a phone screen is hard to click + need to scroll if a few long names + ...

So it's both world, the proper display value as intended and link to all the artists. Most clients can also easily match the names in the display value and create the clickable entries if they want.

I for sure use the value when available and users like it (Specially because it workaround the issue with order of the tags, that value is always the proper one).

[tamland]

The musicbrainz solution seems nice and would work as a possible extension to the proposal at least. (how to actually obtain this data is a different story though). Same with "Artist as credited".

[Tolriq]

As a reminder there's also the sort artist, sort album artist composer sort to handle. IMO the MB way is only useful to generate the displayXXX values. I don't see any provider storing that low level data to regenerate a display value each time. That's a lot more complex to handle at a database level. Specially for all those who do not even handle the order of the artists.

[sentriz]

following the decision made on getAlbum's artists field, are we okay with following the same pattern for genres? (but just an array, we don't need an object this time)

for example:

JSON:

XML:

[sentriz]

for gonic, since track artists are not supported (for now) the track's artistId is the album's album artist. so consistent with getArtists.

but still, my understanding is we're updating field X to be [X]. we shouldn't change the meaning of X. if it was albumartist, it should now be albumartists. if it was artist it should now be artists.

picard and beets can set these multi value tags

i suppose its up to different servers but what makes sense to me, in general is

album.artists is album artists
song.artists is track artists

in gonic these happen to be the same, but still I'm not proposing to change the meaning of the fields we have already. that could be a separate proposal to define that better

[epoupon]

are there any subsonic servers right now that would return track artists there? seems crazy to me. even in the example response we mention "albumCount" which implies album artists only surely.

LMS returns them all by default (both track and album artists), and there is a per-user option to return only "album artists" in the search endpoint...
"albumCount" is never set to 0 for track artists, it is the count of albums where the artist appears on (very handy for compilations).

In LMS, an artist is just an artist whatever the tag that has been used to extract it (like artist, albumartist, composer, remixer, conductor, performer, etc.). A track or an album is not linked to an artist, but to an artist/role entry.

Ideally we should be able to filter an artist for a given role:

• I want to see all the albums composed by Mozart.
• I want to see all albums or even just tracks sung by Bruce Dickinson
• etc.

[sentriz]

👍 i agree it would be nice to have better filters like that. but in terms of album.artist becoming album.artists (or track.artist becoming track.artists), what would that mean for LMS? given that the user can configure how they like their artists to be set up

[Tolriq]

What LMS does is how all most providers do and how it should be handled.

By having song track artists being in fact album artists, you hide very valuable information. That's a blocking point for me for example.

And we must be able to return all artists by a way or another.

So the simple fact that already 2 servers have different understanding of the values, confirm that there's the need to clarify things and your sentence:

i suppose its up to different servers but what makes sense to me, in general is

album.artists is album artists
song.artists is track artists

An API value can't be up to the server, that's what currently make Subsonic API a complete mess and one of the reason of this project. Having all servers returning the same data with the same meaning from the same endpoints.

So while I agree your definition can make sense, it's currently not defined and is part of the proposal. We can totally agree on your definition without preventing a filter on getAlbums with contributors that will not be part of the returned data.

But we need to be clear on what is what to ensure that we can support roles and track artists.

On a personal note I want to ditch Jellyfin for a Subsonic for my large collection but need multi artists (track and album) and multi genre and hope for Composer to have the same navigation abilities.

[Tolriq]

Ok so @opensubsonic/servers @opensubsonic/clients I've planned to do the draft on multiples values and most common missing data from all the current issue next week. If you have some ideas you did not wrote, you can just add some details in this thread so I compile them in the global draft.

[Tolriq]

See proposal #52