Question about getIndexes and getMusicDirectory

[epoupon]

Hello!

For now, LMS emulates the functionality of getIndexes by listing the artists. In getMusicDirectory, if an artist is requested, we list the albums, and if an album is requested, we list the tracks of the album.

Now, I would like to understand how it is supposed to work in the original API, because for me, everything is not very clear when looking at the legacy Subsonic's examples, which only consider the artist/album/tracks structure.

For example, if I place my music in subfolders like this:
Techno/Compilations/HardBassVol17, what type of node should be indicated for "Techno" in the getIndexes response? And the same question for "Compilations" and "HardBassVol17" in the getMusicDirectory requests?

The same questions apply for an organization like this: Metal/Metallica/Reload. I see in the responses that the node type is "artist," but I don't quite see how the original API distinguishes between an intermediate folder and a folder that contains only the artist's albums?

Bonus question: what about MyArtist/MyAlbum/CDX?

[epoupon]

I finally installed an instance of Airsonic-advanced to try to get closer to the original behavior.

Here's what I observe:

• MyAlbum/songs
  getIndexes: "MyAlbum" is reported with an artist tag with the property name="MyAlbum"
getMusicDirectory on MyAlbum: reported with a directory tag with the property name="MyAlbum". Inside, for each song, there is a child element with the standard song properties. There is an isDir="false" property for each song.

• MyArtist/MyAlbum/songs
  getIndexes: "MyArtist" is reported with an artist tag with the property name="MyArtist"
getMusicDirectory on MyArtist: reported with a directory tag with the property name="MyArtist". Inside, for each album, there is a child element with the standard album properties (title, album, artist, genre, etc.), and an isDir="true" property. Note: the directory name is put in the title property.
  getMusicDirectory on MyAlbum: same as the previous case.

• MyCompilations/MyFavGenre/MyAlbum/songs
  getIndexes: "MyCompilations" is reported with an artist tag with the property name="MyCompilations"
getMusicDirectory on MyCompilations: reported with a directory tag with the property name="MyCompilations". Inside, MyFavGenre is reported with a child tag, with the properties isDir=true, title=MyFavGenre, artist=MyFavGenre, as if it were an album.
  getMusicDirectory on MyFavGenre: reported with a directory tag with the property name=MyFavGenre. Inside, there are albums as in the previous cases.

• MyArtist/MyAlbum/CD_N/songs
  getMusicDirectory on MyAlbum: we see one child element per CD, which carries all the properties of the album. The properties are the same for each CD, except the title property that carries the name of the folder.

• MyCompilations/MyFavGenre /UnrelatedSongs
  getMusicDirectory on MyCompilations: reported with a directory tag with the property name="MyCompilations". Inside, MyFavGenre is reported with a child tag, with the properties isDir=true, title=MyFavGenre, and all the other album related properties are set using the first scanned song inside the directory.

There you go, I hope this can help others.

[xxxserxxx]

I think this is a general issue with the API definition, inherited no doubt from Subsonic, which made assumptions about filesystem layouts and how they relate to artists, albums, and so on.

The issue for users of the API is that the expected behaviors are ill-defined enough that servers implement these differently -- and inconsistently. For example:

• Navidrome: getIndexes children IDs -- "artists", per the documentation -- are also valid getMusicDirectory IDs. It follows the assumption that, at the top level in the music directory, are only artists. In particular, songs do not appear, and albums are assumed to be artists.
• gonic: getIndexes returns artist IDs which are only valid for calls to getArtists (and things that deal specifically with artists). In particular, Artist IDs are not valid IDs for getMusicDirectories
• Oddly, in neither gonic nor Navidrome is the ID in getMusicDirectory valid IDs for any other API call. You might expect it to show up as, say, a parent ID in one of the getMusicDirectories call, but it does not.

Fundamentally, the API does not clearly distinguish between file structure and metadata structure, although there's a clear implicit assumption that the music directory follows a strict layout of ARTIST/ALBUM/SONG.

I think here gonic's approach is more sane, because (a) it doesn't make assumptions about filesystem layouts, and (b) it handles edge cases which are not always irrational. However, gonic's approach is also non-conformant to the API because the behavior deviates: getIndexes explicitly states that it returns artists, but getMusicDirectory explicitly states that the IDs can be gotten from getIndexes, which -- by extrapolation -- means that getMusicDirectory is a synonym for getArtist.

An example filesystem layout which I've used elsewhere is: assume a music directory layout:

  musicDirectory/
    Amy Grant/
      Black Sabbath/
        Sabbath Bloody Sabbath.opus
    Billie Eilish/
      Ocean Eyes.opus
    Live and let die.mp3
    Le Onde/
      Ludivico Einaudi/
        Ombre.flac

Assume the songs are correctly tagged. Who's the artist for "Sabbath Bloody Sabbath"? If you look at the metadata, it's Black Sabbath; if you look at the filesystem, it's Amy Grant. A contrived example, but let's assume some kid that is obfuscating their directory structure assuming their parents aren't going to drill down too far, and they've named all of their files weird -- but "acceptable" things.

The second example is absolutely valid. Increasingly, artists are releasing songs that are not on albums, so the assumption of ARTIST/ALBUM/SONG is wrong.

The third is also contrtived, but I'll bet it's also super common: people download individual songs; are they going to create nested directory structures to put single songs into? Not usually. I'm fairly organized, but my music directory is (literally) decades old and I have over 300 songs still hanging out at the top level, because they're one-hit-wonders and I didn't bother to buy the whole album.

The fourth entry is totally contrived, and backwards. Only the truly insane would lay out their filesystem like this, but the point I'm driving at is that I fundamentally disagree with making assumptions about metadata ("who's the artist") being derived from filesystem layout.

I'd like to see some consensus and agreement to clarify some of these behaviors in the API, to more strongly separate "filesystem view" from "metadata view", and to add additional API calls to cover the gaps. Put another way, I'd like to be able to write a client that can either browse the filesystem -- not making assumptions about what the directory structure implies about metadata -- or browse the music library using only metadata from the audio files. This is currently not possible with the current API definition for reasons stated above.

One final point: I'd love if we could rely on metadata, but the fact is that audio files are often poorly or incompletely tagged, and clients have to deal with that. If, for example, we agree that getArtists returns all of the artists purely from tag data, users will never see songs that don't have an ARTIST tag -- even if the song is in musicDirectory/Artist/Album/untaggedsong.mp3. Unfortunately, I think it's beyond the scope of an API documentation project to try to enforce algorithms solving these issues -- e.g. "IFF a song is untagged, then assign an artist based on filesystem structure." That's not only beyond scope, it'd be impossible to do correctly for, for example, compilations. Various Artists/... would just make it confusing.

[epoupon]

Forgot about this post, by the time it is now implemented in https://github.com/epoupon/lms

This is quite pragmatic:

• Purely filesystem based, IDs are dedicated directory IDs, unrelated with other metadata-based endpoints
• If a directory happens to directly contains entries that all belong to the same album, then album info is set on this directory
• Could do the same for album artist, at the deepest possible level (I have not done this since tempo does not care about artist info in)

[xxxserxxx]

I don't know that the API covers this, but it occurs to me (as a client author) that I'll need to have server-specific API handlers. I love what lms is doing, but my client can't rely on every server being lms. In any case, I'm going to update ostui to have said handlers, because right now it's sort of assuming gonic's behavior and behaves oddly in edge cases with Navidrome, and because I'd like to take advantage of lms's behavior.

Sorry it's taken me a year to respond to your comment, @epoupon. I don't know what happened to the notification, but I didn't see this until @adjenks' comment.

[adjenks]

[epoupon]

Hello,

Browsing by folder is already supported in the Subsonic API.
In order for this to work, you have to pick a client and a server that both support browsing commands. AFAIK gonic, LMS, supysonic for servers and DSub, Symfonium, Tempus, etc. for clients

[adjenks]

I stand corrected. I hadn't found one that implimented it.