[API Request] Support language tags

[certuna]

Proposal description

New discussion by request @Tolriq : language. Working on that now in Navidrome but it makes more sense if it's in OpenSubsonic too.

Two considerations:

Single or multi valued?

• song: id3 and Vorbis allow multiple languages in the TLAN/LANGUAGE tags. But if you look at MusicBrainz Picard (and the Musicbrainz DB), language is stored single valued: a song can have only one language value, if there's multiple languages in the song it gets mul (= ISO code for multiple languages). Up to us to decide - is language a single or a multivalued property?
• AlbumID3 [OS]: what should servers do: roll up an album with 10 songs in eng and 1 song in spa as a single value mul? That really limits clients ability to search for "albums in English". OS doing {eng, spa} is better IMO.
• ArtistID3 [OS]: artist with one (or more) languages associated?

Formatting

• it's not a free text field, id3v2.4 strictly specifies ISO 639-2, Vorbis (as usual) defines nothing, but auto-taggers like beets and Picard seem to follow id3 by only storing ISO codes
• defining this field in OpenSubsonic as ISO-code only makes it much easier for clients to localize the language name client-side, based on system language, e.g. Intl.DisplayNames which also takes ISO 639-2 codes.
• ISO 639-2 (1998, as in id3v2.4) or ISO 639-3 (2007)?

(edit: if we make Languages objects like Genre, then it can be up to the user, server or client to enforce ISO 639-2 validity, the API is neutral)

Backward compatibility impact

No response

Backward compatibility

• No backward compatibility impact.

API details

one new endpoint

getLanguages [OS]: http://your-server/rest/getLanguages.view?u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.1.3 (tag)",
    "openSubsonic": true
    "languages": {
      "language": [
        {
          "songCount": 4,
          "albumCount": 1,
          "value": "spa"
          "id": "1"
        },
        {
          "songCount": 1,
          "albumCount": 1,
          "value": "English"
          "id": "2"
        },
        {
          "songCount": 220,
          "albumCount": 2,
          "value": "eng"
          "id": "3"
        }
      ]
    }
  }
}

• part of the filter parameters in new endpoint getSongs -> http://your-server/rest/getSongs.view?language=eng&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
• new parameter in existing getAlbumList2?: http://your-server/rest/getAlbumList2.view?language=eng&type=random&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json
• new parameter in existing getArtists?: http://your-server/rest/getArtists.view?language=eng&u=demo&p=demo&v=1.13.0&c=AwesomeClientName&f=json

response:

language
languages -> array of language objects

{
  "language": [
    {
      "songCount": 4,
      "albumCount": 1,
      "value": "spa"
      "id": "1"
    },
    {
      "songCount": 1,
      "albumCount": 1,
      "value": "English"
      "id": "2"
    },
    {
      "songCount": 220,
      "albumCount": 2,
      "value": "eng"
      "id": "3"
    }
  ]
}

Security impacts

No response

Potential issues

No response

Alternative solutions

No response

[Tolriq]

So repeating here :)

For artists the API currently does not expose song data, if there's no genres there should not be languages either for now. If an extension is made to extend artist data with song data then it can be added but this is another discussion.

Albums should be as genre so a distinct array of the song values.

Songs tags support multiple language tags, most taggers support that, servers should not remove data because 1 website decided to. We expose the tags not MB data. If some servers wants to expose MB data they can but it must not prevent the API to return the tags.

For the format, as you said Vorbis and others do not enforce values, so enforcing something in the API brings the questions about what to do with the values that does not fit? Dropping them would be incredibly bad. Server trying to find the proper ISO code for the language, incredibly error prone.

Clients can easily still convert the ISO codes when it's 3 letters and fallback to the value if it can't.

Just the fact that ID3 says ISO 639-2 yet you propose ISO 639-3 confirm that this would not be realistic to enforce anything.

For the record I do support those fields and have already seen quite a few variations of the values that would be lost here.

[certuna]

I'm not in a hurry, doing this right is important. But if this is the direction OpenSubsonic is going ("we do Language like Genre"), then we can already write the data structures that way server-side. Deferring to @deluan as usual since he's in the lead of Navidrome development.

[Tolriq]

Not sure many servers will support it, but as a client I already support it and I think LMS was ok to add support, so with Navidrome that's enough to validate it's wanted data. Handling it more or less as Genre (with added IDS for better handling) this support most cases and still allows the server to offer tools to the users to rename / manage they languages fields. So this makes senses.

Filtering is the second more complex step, but exposing the data to the client to at least display and for offline first client to offer all is already a good start.

[certuna]

Shouldn't be very difficult for other servers to support - I think it's mostly a chicken-and-egg problem where it doesn't make much sense to support a tag serverside when the API doesn't support it, and the lack of server support is seen as a reason not to add it to the API.

Language is a relatively straightforward property of a song, everyone knows what it means. When we get to fields like Release Type, things get much more arbitrary.

[Tolriq]

It's straightforward but triggered a ton of discussions :p

Release types are already in the OS API as releaseTypes and same thing we expose the tags.

[aero31aero]

I'm just chiming in for support of some implementation of this feature. It's been a pretty long discussion but I guess common principles apply:

Be restrictive in what you transmit (subsonic servers) and be lenient in what to accept (clients). Let the API spec be lenient though. It's just some text fields.

I as a user don't care whether Korean is called ko or kor or whatever else. I might as well set my music library to have three languages, A,B,C and then expect the clients to be able to filter based on lang=A, etc.