Add 2 media_player services and 1 custom service to Squeezebox platform

[ericpignet]

Description:

1. Add support for 2 media_player services to Squeezebox platform: shuffle_set and clear_playlist
   This part is quite straightforward.

2. Add 1 custom service to Squeezebox platform: squeezebox_call_method
   Such hass service can be used to invoke any JSON/RPC service provided by Squeezebox server.
   It makes it much simpler to integrate any Squeezebox action to an automation.
   Also it can be used to target a Squeezebox from IFTT (or DialogFlow, Alexa...).
   For example, to play an album from your collection:
   Create an IFTT Google assistant/Webhook with sentence
   "I want to listen to album $"
   and the JSON body would be:
   { "entity_id": "media_player.squeezebox_radio", "method": ["playlist", "loadtracks", "album.titlesearch={{TextField}}"] }
   Works with title search and basically any thing. The same wouldn't have worked to call directly Squeezebox server as IFTT cannot escape the text field.
   Implementation is done very similarly as custom services in sonos and kodi platforms,.

Pull request in home-assistant.github.io with documentation (if applicable): home-assistant/home-assistant.io#4142

Checklist:

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated in home-assistant.github.io

If the code communicates with devices, web services, or third-party tools:

• Local tests with tox run successfully. Your PR cannot be merged unless tests pass
• New files were added to .coveragerc.

[emlove]

One small request on the service schema, but otherwise looks great!

[emlove]

Let's avoid the more complicated quote escaping example here, and pick an easier title. Knowing how to escape quotes in yaml isn't necessary to understand this service. 😄

[ericpignet]

Fair enough, I changed the title with last commit!

[emlove]

Separate the method arguments out into their own optional field on the schema.

[ericpignet]

I agree that would be nicer (easier to use), but the API supports hundreds of commands, requiring a different number of parameters.
The parameter p2 of one query can have a completely different meaning as the paramater p2 of another one.
So we can't really name the parameters. We could create param_0, param_1 but... up to how many? Most commands have up to 4 but the count can go up quickly, especially for search commands which accept various criteria.

Extract of the documentation:

The format of the commands, queries and server replies is as follows:
[<playerid>] <p0> <p1> ... <pN> <LF>
where:
<playerid> is the unique identifier for the player, usually (but not guaranteed to be)
the MAC address of the player. Some commands are global to the Squeezebox Server
and do not require a <playerid>. For commands requiring it, a random player will be
selected by the Squeezebox Server if the <playerid> is omitted, and returned in the
server reply. <playerid> may be obtained by using the "player id" or "players" queries.

<p0> through <pN> are positional parameters. Pass a "?" to obtain a value for that
parameter in the Squeezebox Server response (i.e. send a query). Details of the
parameters vary for each command as described below.

Each parameter needs to be encoded using percent-style escaping, the same method
as is used in URLs; for example, "The Clash?" would be encoded as "The%20Clash%3F".
This also applies to <playerid>. In the examples below, the escaping is not show for
readability (except %20 for space).

Some examples:

info total artists ?
Returns the number of artists in the DB. Has to be passed as ['info', 'total', 'artists', '?']

playlist loadalbum <genre> <artist> <album>
Puts songs matching the specified genre artist and album criteria on the playlist. Songs previously in the playlist are discarded.
For example: ['playlist', 'loadalbum', 'Rock', 'Abba', '*']

genres <start> <itemsPerResponse> <taggedParameters>
This is an example of command accepting tagged parameters. An example would be
['genres', '0', '10', 'search:rock', 'artist_id:5', 'album_id:6', 'year:2003']
This would restrict the search to the genres proposed by artist with ID 5, available on the album with ID 6 and with tracks in year 2003.

As you can see in just 3 examples, parameter p1 can be static strings 'total', 'loadalbum', or a number (index of first result).
I think it is easier for somebody used to the Squeezebox API to just give the array of parameters to the service as is.
Let me know if you have another idea!

If you don't have a squeezebox server running, you can find a copy of the documentation here:
https://github.com/elParaguayo/LMS-CLI-Documentation/blob/master/LMS-CLI.md

[emlove]

Ah, sorry, that was a confusing comment. I just meant separate this out into two fields. method, which can just be a required string, and arguments, which is an optional array of any arguments.

[ericpignet]

OK I get it now.
I split the unique method field into two:

• command which is a mandatory string and will be the first parameter passed to the API. I use the word command to be consistent with the API documentation. I did not use the word 'method' because it would be conflicting with the main API method which is always 'slim.request'
• parameters which is an optional array of extra parameters added to the command.

[emlove]

Sorry for the delay here, this one fell off my radar!

Changes look good now. Thanks!

[emlove]

Thanks for the contribution! 🌟

[ericpignet]

Thanks for reviewing and merging!