CLI Documentation Questions

[Daksol]

Command line interface - CLI commands documentation

Some (not high priority) issues which came up when doing some further testing of the CLI - done mostly with the intention of generating some more examples, particularly JSONRPC ones, which are (IMHO) heaps easier to read.

PURPOSE OF ID PARAMETER WITH JSONRPC ?

See JSONRPC section of Using the CLI
Question about the "id" parameter for JSONRPC. In the JSONRPC notes for use by CURL etc, one of the parameters passed is "id" (along with "params" and "method"). I realise that when running the commmands via JSON I have not included "id" and it still seems to work.

What is its function? - maybe to allow the response to multiple JSONRPC calls to be easily distinnguished?

---

PLAYER COMMAND INCONSISTENCIES

I was doing some followup checking on behaviour of certain CLI commands for Players.

The command players provides full info about all connected players; this works fine, documentation is inline with behaviour.

There is also group of eight commands like "player name" which return a specific piece of info about a particular player.
The subcommands are: name, uuid, displaytype, id, ip, model, isplayer, canpoweroff

These commands have more than one format to achieve the same result - based on the documentation and examples given. The variants are wrt the parameter used (playerid or playerindex) and where the parameter is placed (as a pre-pended player identifier or after the 'player ' bit).

Syntax Options with Player identifier after the player <subcommand> string

• SYNTAX-1 player name <playerindex> ?
• SYNTAX-2 player name <playerid> ?

where <playerid> is (usually) the player's MAC address, and <playerindex> is a sequence number assigned to players currently recognised by the server, with values like 0, 1, 2 etc

Syntax options where Player identifier precedesthe player <subcommand> string

Some places in the documentation it is shown that these two forms are also permissable.

• SYNTAX-3 <playerindex> player name ?
• SYNTAX-4 <playerid> player name ?

See for instance syntax and examples for player name

Testing results

All of these formats (SYNTAX-1 thru -4) "work" in that they return a result; but I noticed some discrepancies.

So we need to test all four formats for eight subcommands for four players (as one does).

• used all four SYNTAX options as above
• used all eight subcommands (name, uuid, displaytype, id, ip, model, isplayer, canpoweroff)
• while having four players connected (one squeezelite, two Sb Radios one SB Classic v3)

And compared the results with what comes back from the players command

Result of this testing is that SYNTAX-3, and SYNTAX-4 while they work (in that a result is returned) do not provide an accurate response. They seem to always return information about the player currently with Index 0.

Suggested actions:

• Remove any use of Syntax-3 or Syntax-4 from the documentation, including the Examples
• Include a cautionary note

@mherger - Your call as whether this should be raised as a bug?

Number of players: 4
Info on all players from the players command
0 {'playerindex': '0', 'playerid': '98:2c:bc:18:e1:06', 'uuid': None, 'ip': '192.168.5.22:60888', 'name': 'Squeezelite-X', 'seq_no': 0, 'model': 'squeezelite', 'modelname': 'Squeezelite-X', 'power': 1, 'isplaying': 0, 'displaytype': 'none', 'isplayer': 1, 'canpoweroff': 1, 'connected': 1, 'firmware': 'v1.9.9-1419'}
1 {'playerindex': 1, 'playerid': '00:04:20:28:c7:f1', 'uuid': 'ca1c8fbf2d48cbb1c859b5ea7ce4ecf9', 'ip': '192.168.5.102:56551', 'name': 'Stalking Horse', 'seq_no': '12', 'model': 'baby', 'modelname': 'Squeezebox Radio', 'power': 1, 'isplaying': 0, 'displaytype': 'none', 'isplayer': 1, 'canpoweroff': 1, 'connected': 1, 'firmware': '8.0.1-r16924'}
2 {'playerindex': 2, 'playerid': '00:04:20:12:ae:f5', 'uuid': None, 'ip': '192.168.5.103:47742', 'name': 'Dittography', 'seq_no': 0, 'model': 'squeezebox3', 'modelname': 'Squeezebox Classic', 'power': 1, 'isplaying': 0, 'displaytype': 'graphic-320x32', 'isplayer': 1, 'canpoweroff': 1, 'connected': 1, 'firmware': 137}
3 {'playerindex': 3, 'playerid': '00:04:20:2a:e0:74', 'uuid': '7147ee259b66f5c9c39c0eb14cfefb5c', 'ip': '192.168.5.101:53614', 'name': 'Runcible Red', 'seq_no': '220', 'model': 'baby', 'modelname': 'Squeezebox Radio', 'power': 1, 'isplaying': 0, 'displaytype': 'none', 'isplayer': 1, 'canpoweroff': 1, 'connected': 1, 'firmware': '8.0.1-r16924'}
****************************************

Now testing the 'player <subcommand>' set of commands giving info on individual players
Subcommands to test are: ['canpoweroff', 'displaytype', 'id', 'ip', 'isplayer', 'model', 'name', 'uuid']

Subcommand      Syntax 1              Syntax 2              Syntax 3              Syntax 4             
--------------- --------------------- --------------------- --------------------- ---------------------
PLAYER Index:0 ID:98:2c:bc:18:e1:06  Name:Squeezelite-X

canpoweroff     1                     1                     1                     1                    
displaytype     none                  none                  none                  none                 
id              98:2c:bc:18:e1:06     98:2c:bc:18:e1:06     98:2c:bc:18:e1:06     98:2c:bc:18:e1:06    
ip              192.168.5.22:60888    192.168.5.22:60888    192.168.5.22:60888    192.168.5.22:60888   
isplayer        1                     1                     1                     1                    
model           squeezelite           squeezelite           squeezelite           squeezelite          
name            Squeezelite-X         Squeezelite-X         Squeezelite-X         Squeezelite-X        
uuid            None                  None                  None                  None                 
*******************************************************************************************************
PLAYER Index:1 ID:00:04:20:28:c7:f1  Name:Stalking Horse

canpoweroff     1                     1                     1                     1                    
displaytype     none                  none                  none                  none                 
id              00:04:20:28:c7:f1     00:04:20:28:c7:f1     98:2c:bc:18:e1:06     98:2c:bc:18:e1:06    
ip              192.168.5.102:56551   192.168.5.102:56551   192.168.5.22:60888    192.168.5.22:60888   
isplayer        1                     1                     1                     1                    
model           baby                  baby                  squeezelite           squeezelite          
name            Stalking Horse        Stalking Horse        Squeezelite-X         Squeezelite-X        
uuid            ca1c8fbf2d48cbb1c...  ca1c8fbf2d48cbb1c...  None                  None                 
*******************************************************************************************************
PLAYER Index:2 ID:00:04:20:12:ae:f5  Name:Dittography

canpoweroff     1                     1                     1                     1                    
displaytype     graphic-320x32        graphic-320x32        none                  none                 
id              00:04:20:12:ae:f5     00:04:20:12:ae:f5     98:2c:bc:18:e1:06     98:2c:bc:18:e1:06    
ip              192.168.5.103:47742   192.168.5.103:47742   192.168.5.22:60888    192.168.5.22:60888   
isplayer        1                     1                     1                     1                    
model           squeezebox2           squeezebox2           squeezelite           squeezelite          
name            Dittography           Dittography           Squeezelite-X         Squeezelite-X        
uuid            None                  None                  None                  None                 
*******************************************************************************************************
PLAYER Index:3 ID:00:04:20:2a:e0:74  Name:Runcible Red

canpoweroff     1                     1                     1                     1                    
displaytype     none                  none                  none                  none                 
id              00:04:20:2a:e0:74     00:04:20:2a:e0:74     98:2c:bc:18:e1:06     98:2c:bc:18:e1:06    
ip              192.168.5.101:53614   192.168.5.101:53614   192.168.5.22:60888    192.168.5.22:60888   
isplayer        1                     1                     1                     1                    
model           baby                  baby                  squeezelite           squeezelite          
name            Runcible Red          Runcible Red          Squeezelite-X         Squeezelite-X        
uuid            7147ee259b66f5c9c...  7147ee259b66f5c9c...  None                  None                 
*******************************************************************************************************

UUID values truncated to 17 chars to keep the table pretty.
UUID values of None (the Python key word indicating a nullvalue) shown as the string 'None'

[michaelherger]

Thanks for looking into all this, @Daksol! Alas, it can be overwhelming... It would be easier to follow up if you had one question per issue, or if you posted one question per thread in the forums. Here you have at least two totally independent questions, with a lot of information...

So in short: the id I don't know, really. Might be something from CometD. But in my JSON/RPC requests I always put 1 and don't care. I believe in theory it would allow to link the response to a request, as they can be out of sync in CometD. But with JSON/RPC that's not the case, therefore probably irrelevant for that use case.

As for the playerindex: I never used that. I mean... how would you know which player you're dealing with? I'm pretty sure that's a legacy thing nobody bothers to use that way. We should probably remove it from the documentation and consistently use the playerid instead (MAC address).

player <id> something also sounds like legacy. We should always suggest the <id> player something syntax.

[Daksol]

OK thanks, will ensure one question per comment.

Let me restate the issue with the player <subcommand> ? only using playerid as identifier.

• Using Syntax-2: player <subcommand> <playerid> ?

  • Responses are accurate

• Using Syntax-4: <playerid> player <subcommand> ?

  • You get a response but it is not accurate. Info returned when querying any of the players is same - equal to that for the particular player with playerindex = 0. In the output query above the query response for Syntax-3 and Syntax-4 is always the same as that for the Squeezelite-X player which has playerindex = 0

[Daksol]

I have a Python script which runs the whole thing, can share that if useful.

Meantime here is the CURL version, should work once you have correct IP and port
STEP 1 - Ensure you have at least two players connected. Three or more makes it more obvious.

STEP 2 - Run this command to get the current players and their mac addresses

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["-",["players", "0"]]}' http://192.168.5.75:9005/jsonrpc.js

STEP 3 - Take the mac addresses of first three players and put them into the code below. There are two commands (as per my syntax-2, syntax-4 from above) for each player,

If for the second and subsequent players you see different responses from the two syntax commands - then problem demonstrated.

STEP 3-0: playerindex=0, 98:2c:bc:18:e1:06

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["-",["player", "name", "98:2c:bc:18:e1:06", "?"]]}' http://192.168.5.75:9005/jsonrpc.js

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["98:2c:bc:18:e1:06",["player", "name", "?"]]}' http://192.168.5.75:9005/jsonrpc.js

STEP 3-1: Playerindex=1, 00:04:20:28:c7:f1

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["-",["player", "name", "00:04:20:28:c7:f1", "?"]]}' http://192.168.5.75:9005/jsonrpc.js

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["00:04:20:28:c7:f1",["player", "name", "?"]]}' http://192.168.5.75:9005/jsonrpc.js

STEP 3-2: Playerindex=2, 00:04:20:12:ae:f5

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["-",["player", "name", "00:04:20:12:ae:f5", "?"]]}' http://192.168.5.75:9005/jsonrpc.js

curl -g -X POST -d '{"id":1, "method":"slim.request","params":["00:04:20:12:ae:f5",["player", "name", "?"]]}' http://192.168.5.75:9005/jsonrpc.js

[Daksol]

Markup of the curl queries indicating where the two different syntaxes of the player name get a different response except for player with playerindex=0

[michaelherger]

You should look at the code where those functions are registered. The decision to have player with and without the requirement for a client certainly is a legacy. But it's clearly defined in the registration call whether the client is required as the first parameter or not. See eg. https://github.com/LMS-Community/slimserver/blob/public/9.0/Slim/Control/Request.pm#L466-L472 - there's the "requires Client" column (parameter).

[michaelherger]

@Daksol I just learned that the favorites commands/queries were not documented here. Should they be part of one of the existing sections?

[edgar-vincent]

I'd be happy to help add the favorites commands after I have familiarised myself with the way the website is structured and built.

[Daksol]

@michaelherger
Thanks for your note, sorry not responding more quickly,

I have looked again at the original HTML source, and can see the error I made.
The original steer was that the "Plugins" section should not be migrated.

I clearly not careful enough when looking at the section starting with "Plugins" - because there are other sections (Favorites, RandomPlay, MusicIP ??) which may not really have been part of "Plugins".

The unmigrated sections are as follows, in the order in which they appear...

• Plugins commands and queries - presume NOT migrating
• Podcasts, RadioTime, RSS - Not sure
• Favorites - Still to be Migrated
• RandomPlay - Still to be Migrated
• MusicIP - Still to be Migrated
• Deprecated commands and queries - presume NOT migrating

Could I ask @michaelherger to review this list and confirm which sections still need to be migrated?

With that clear, happy to work with @edgar-vincent to see work to completion.

Thanks.

[michaelherger]

• Plugins commands and queries - presume NOT migrating
• Podcasts, RadioTime, RSS - Not sure
• Favorites - Still to be Migrated
• RandomPlay - Still to be Migrated
• MusicIP - Still to be Migrated
• Deprecated commands and queries - presume NOT migrating

I'd say only migrate those labeled Still to be Migrated. All of the rest can be considered obsolete. Thanks!

[Daksol]

@michaelherger
Hi, followup questions - will need some help for "musicip", see below

I have done some quick tests to confirm that I can make these other commands work properly - via a Python script which submits the commands into the JSONRPC processor.

Observations/Questions arising from that testing (may need some help with musicip, see below)

Favorites

• observations
  • works fine via the JSON CLI interface
  • however returns a zero FALSE value if I submit a "can" command ("can favorites ?"). Though that is a curiousity rather than a problem.
• please confirm
  • this should work out of box - so no requirement for any particular plugin to be enabled ?
  • defined in source at Slim/Plugin/Favorites/Plugin.pm https://github.com/LMS-Community/slimserver/blob/public/9.0/Slim/Plugin/Favorites/Plugin.pm

Randomplay

• observations
  • seems to be dependent on the "Random Mix" plugin first being installed
  • once "Random Mix" plugin enabled
    • installed the JSON CLI commands work
    • the can command "can randomplay ?" returns a 1 TRUE
    • the option appears in the "My Music" dropdown
• please confirm
  • Defined in Source in Plugin/RandomPlay/Plugin.pm https://github.com/LMS-Community/slimserver/blob/public/9.0/Slim/Plugin/RandomPlay/Plugin.pm

MusicIP

• observations
  • Not getting a response via JSON commands to any of the musicip options
  • getting value of 0 FALSE from the can commmand "can musicip ?"
  • and that remained true even after enabling the "MusicIP" plugin
• please confirm
  • this is dependent on MusicIP plugin being enabled
  • plugin is called "MusicMagic" in the Source
  • Source is in the Plugin/MusicMagic/Plugin.pm https://github.com/LMS-Community/slimserver/blob/public/9.0/Slim/Plugin/MusicMagic/Plugin.pm
• please assist
  • what else do I need to do to make this appear on menus or respond to CLI ?

[michaelherger]

The Favorites plugin is "enforced": you can't disable it, as it's too deeply integrated in to the core of LMS. "can" seems to be buggy, but I wouldn't care too much either. Just don't tell anyone 😂.

Random Mix requires the plugin.

MusicIP not only requires the plugin itself, but also a working MusicIP application setup. If the plugin can't find the application, it wouldn't initialise.