Issues found in documentation

[Gr3q]

Taken as-is from #137 description

• ItemDate description and spec doesn't match (in required fields)
• Disc number must be a number but obviously it can be other things
• getAlbumInfo2 return type incorrect (based on AlbumList)?
• downloadPodcastEpisode return type incorrect?
• deleteBookmark summary and description is wrong
• download error payload schema missing completely
• getArtists page first artists link is broken
• getAvatar username parameter is "required" and has a "default" as well. it should be one or the other
• getCaptions return payload not clear
• getCoverArt size param type not specified, I assume int as pixels
• Indexes ignoredArticles pattern is unclear, it was comma-separated list as string before
• internetRadioStation homePageUrl has wrong details
• getLyrics artist and title query parameters are really optional?
• is getLyrics returns only one element?
• Extension not supported error is unclear, assumed servers will 404 on the request.
• PodcastEpisode description "PodcastEntry extends Child". Wrong name used?
• NowPlayingEntry minutesAgo format is unclear
• PlayQueue description incorrect
• PodcastChannel errorMessage existence could depend on status in documentation?
• GetSimilarSongs and GetSimilarSongs2 response type is the same in the spec (not the names)?
• User example uses booleans and integers as strings, but they are typed as booleans and integers.
• VideoInfo is not documented
• Videos is not documented
• hls endpoint summary matches download
• Typo in search album parameters's comment
• search any parameter type unclear
• SearchResult is not documented
• SearchResult2 all field details are incorrect
• stream timeOffset param's description typo, "Transcode Offet"
• tokenInfo data is too deeply nested in docs?
• tokenInfo says "A subsonic-response element with a nested tokenInfo on success, or error 44 on invalid token.". Does that mean it cannot return any other error code on error?
• unstar summary is incorrect
• updateuser is missing playlistRole parameter?
• createuser is missing maxBitRate parameter?

[lachlan-00]

Disc number must be a number but obviously it can be other things

What does this mean?

[Gr3q]

It's actually my misunderstanding about what Disc numbers are, even for vinyl records (A1, B1 etc). Removed from list

[lachlan-00]

Things I've noticed after starting my rewrite.

• getAlbumList and getAlbumList2 types are unclear. (highest, frequent, recent and starred)

Are these returning results for the server or the user?

I return server results here but the official subsonic demo returns user results for highest and starred then server results for recent and frequent which is inconsistent.

• Playlist and playlistwithsongs why are they separated? there seems to be only one use of each (not finished looking)

• References to responses have some odd links. E.g. Album links to albumid3

• Token documentation is way too vague

I'm going to to a cleanup pull on some of this as they slowed me down when starting so it should make things easier for others

[dweymouth]

getAlbumList2 types are unclear - Are these returning results for the server or the user?

I think returning user results, possibly including recent and frequent (a change in behavior from O.G. Subsonic) is better. First of all, returning server results can "leak" one user's play history to another. Secondly, for favorite albums specifically, the getAlbumList2 API allows pagination, while getFavorites does not. As such, some clients may prefer to fetch user favorite albums via getAlbumList2 for better performance with users who have very large numbers of favorited albums.

[lachlan-00]

do you mean getStarred? it does suck a bit.

I think getAlbumList/2 has to be clear about whether they are user or public results and provide a filter for the opposite behaviour. (eg user=1 to filter by your user only or public=1 to provide public information)

I have privacy settings and filtering in the server to block things from reaching public lists but as long as there is a choice on that it is it would clear up a lot of confusion, especially the types returning different sources.

either way that's picked doesn't really matter but they need to be unified

[Tolriq]

Adding to the list it's missing the isrc recently added to not forget. I'll do it to start touching this and prepare the transcoding API docs.

[lachlan-00]

Another one on https://opensubsonic.netlify.app/docs/responses/artistid3/

roles Array of string No Yes The list of all roles this artist has in the library.

as in album artist / song artist / manual uploaded artist / owned by specific user?

[Tolriq]

No the roles are from the tags as in the example, it's albumartist,artist, composer, lyricist, writer, ....

[lachlan-00]

Another one (Nearly done on the initial implementation)

https://opensubsonic.netlify.app/docs/responses/podcaststatus/

This status is what i use for episodes and not for podcasts.

I'm assuming there is a status order for returning on a single channel based on whether these status' ovvue in the list of all episodes

e.g. if you have pending episodes you are new, if there isn't anything pending you are completed and then anything that failed to download is an error

[lachlan-00]

found one more, https://opensubsonic.netlify.app/docs/endpoints/getplaylist/

should getplaylist be returning the entries? it might be a typo from the create playlist update but it points to playlistwithsongs

[Woonters]

In IndexID3 (

open-subsonic-api/content/en/docs/Responses/indexid3.md

Line 53 in 45cf25b

| `artist` | Array of [`Artist`](../artistid3) | No | | Artist list |

) the type is written as an Array of Artist when it should be ArtistID3

Also the responses Starred and Starrred2 are both documented as the same, but the OpenAPI scheme has Starred2 using ArtistID3 and AlbumID3