Add a mechanism to clear a saved play queue

[xxxserxxx]

Type of change

API tweak

Proposal description

Once a play queue has been saved with savePlayQueue, there is no way to clear it. id is a required attribute, so it is not sufficient to call savePlayQueue with an empty list of IDs, and there is no deletePlayQueue. This means that a user is condemned to always have a saved play queue with at least one element in it stored on the server.

• The API of savePlayQueue could be changed s.t. id is no longer mandatory, and the defined server behavior would be to clear the saved queue in this case. This would be a backwards-compatibility breaking change.
• The API of savePlayQueue could be changed to add an optional delete parameter, with defined behavior that the server ignores all other parameters and simply deletes the saved queue. This is ugly, but would be backwards compatible.
• A new call, purgePlayQueue could be added, with no parameters, that deletes the play queue. This seems like the cleanest, although it does swell the API.

I don't have a preference or any arguments other than what I've stated above. I do feel as if there needs to be a way for a client to remove or otherwise clear a previously saved play queue.

Note that gonic ignores requests that do not provide ids to savePlayQueue, and will in fact ignore invalid IDs; you can't, for example, "trick" gonic by calling savePlayQueue?id=XXX; even if it worked, it'd be a hack work-around, and not a reliable or sufficient solution.

Backward compatibility impact

Options 2 or 3 would be backwards compatible, although adding parameters to savePlayQueue could cause request validation errors on strict servers. Option 3 would merely result in 501 response codes for servers that don't implement the addition. Therefore, option 3 is probably the better solution.

Backward compatibility

• No backward compatibility impact.

API details

Going with option 3:

http://your-server/rest/purgePlayQueue

No parameters, with a 200 response code if the queue is purged, or if there is no saved queue. As with other commands, it would return an empty subsonic-response:

{
  "subsonic-response": {
    "status": "ok",
    "version": "1.20.1",
    "type": "AwesomeServerName",
    "serverVersion": "0.9.0",
    "openSubsonic": true
  }
}

Security impacts

None beyond any security concerns about operations with server-side persistent side-effects.

Potential issues

No response

Alternative solutions

I've tried:

• calling savePlayQueue with no parameters. gonic, at least, complains that the id parameter is mandatory, which it is in the spec
• calling savePlayQueue with a single, empty-value, id parameter. gonic responds with the same id is mandatory message, which I believe is a result of the id being invalid.
• calling savePlayQueue with a fictional ID. On gonic, this has the same behavior as providing an empty value.

There is no other option that changes the saved play queue; only an operation to fetch it.

[lachlan-00]

in dsub the function is used on play status change, when you start the app on another device it asks if you want to restore the queue.

outside of change in player state why would you want to clear it? I don't really see why you would need to. each user has a queue and it can be restored if they want or overwritten.

[xxxserxxx]

when you start the app on another device it asks if you want to restore the queue

Which app? Does the API mandate how apps are supposed to behave?

outside of change in player state why would you want to clear it?

Because the user wants to clear it.

In my app, I automatically save the queue when the user exits the program, and automatically reloads it when they restart the app. This is the declared and defined behavior of my app, it's what my users expect, and it's a convenience for them. Only, I can't do this properly with the current API, because if the user clears the queue before they exit it is impossible to record their preference of an empty queue.

The problem is that the API provides no mechanism for saving the state of an empty queue, and it prevents clients from implementing certain behaviors and use cases.

[lachlan-00]

oh so you want to save on exit but the empty list fails and keeps the last save?

[lachlan-00]

i think just make id optional i'll do a pull for it

[xxxserxxx]

oh so you want to save on exit but the empty list fails and keeps the last save?

Yes, exactly. Because the API spec says the ID is mandatory, servers like gonic reject the request if the ID parameter is empty or missing.

i think just make id optional i'll do a pull for it

That works! Now I just have to get PRs into gonic and Navidrome to do the right thing and clear saved list in these cases.

Thank you!

[deluan]

It's already implemented and merged in Navidrome: navidrome/navidrome#3399 :)

[epoupon]

Also implemented this for LMS (will be available in v3.61.0)

[lachlan-00]

pull here, #106