[API Request] Filter getAlbumList2 by starting character

[jeffvli]

Type of change

API tweak

Proposal description

Would also be used for other list endpoints such as #18.
Also related to #7

Adds an optional parameter startsWith to getAlbumList2 which accepts a string value. The value included in the parameter would allow users to quickly view only albums that start with the specified character.

Clients can implement this in different ways such as:

• Allowing the user to input the starting characters
• Displaying an alphabetical list of buttons to click

Example from MusicBee:

Backward compatibility impact

No response

Backward compatibility

• No backward compatibility impact.

API details

The startsWith parameter really only makes sense when using type=alphabeticalByName, but technically it can be used for other filters as well except random.

Parameters
- startsWith (optional) -- accepts a string value (case-insensitive)

Example:

In this example, the music library has 4 albums with the following names:
- "Alpha"
- "Apple"
- "Beta"
- "Gamma"


Using startsWith=a will filter the response to only include albums that have a name that starts with "A"
GET /getAlbumList2?type=alphabeticalByName&startsWith=a&size=500&offset=0

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.16.1",
    "albumList2": {
      "album": [
        {
          "title": "Alpha",
          "name": "Alpha",
          ...rest of album response
        },
        {
          "title": "Apple",
          "name": "Apple",
          ...rest of album response
        }
      ]
    }
  }
}

Security impacts

No response

Potential issues

The implementation can be complex depending on how far server owners want to implement it. It would likely be trivial for the english/latin alphabetic. Different languages such as Japanese would be significantly more difficult if you wanted to have it full-featured.

For example:
In japanese, the word 飛行 can also be written as ひこう in Hiragana.
If we have an album titled 飛行 and use startsWith=ひ, it would not find the album unless a separate column in the database is added with the album title parsed to Hiragana / Katakana.

The above is just some food for thought. Definitely not needed, and a simple implementation would likely suffice for most users.

Servers owners may also want to sanitize album / song titles in the database to omit common starting words to enhance this filter:

• A
• An
• The

Alternative solutions

No response

[Tolriq]

Can't this be done by expanding the search3 API?

Like adding a new parameter isRegexp and accept a regular expression as the query. This allows to support start character, but also end with or more complex queries that would allow to search 2 words or ignore punctuation?

That would solve this and greatly improve the searches? WDTY?

[deluan]

Regular expressions can be unpractical for really big libraries, if the server does not use a proper search engine. Regex against SQLite can be really slow for 1MI+ songs. Even though I'm personally planning to move to a search engine that supports it, it may not make sense for all servers to have to support regexes and risk alienating users with really big libraries.

[Tolriq]

Well in the example above there's a # that represent numbers, there could also be the need for all the non ascii first character or punctuation, for such kind of navigation that's always the need there's not an entry for 0 for 1 for 2 then one for . or for ( .

IMO startWith with a single char on just albums is not a proper long term solution. Specially if we limit to a single character due to the remarks on other language like Japanese. There's already quite a few Subsonic forks just to improve Japanese support, would be nice if they could join the org and not have to deal with arbitrary ascii limitations.

So IMO the need is real and useful, but only start character and only for getAlbums2 feels ultra limited and temporary, the goal is to try to improve the API for the future, let's take time to think about the global need and address it properly.