CLI commands for plugins and scripts

For LMS plugins and scripts. This page shows how other plugins (for example KidsPlay macros) and scripts start, add and stop dynamic playlists with the LMS CLI notation. Apps that need more (list dynamic playlists, look up parameter values, save favorites, transfer to another player) should use the External API instead.

DPL offers a couple of CLI commands:

• PLAY will (re)start the dynamic playlist with the provided ID on your player (client).

  CLIENT_ID dynamicplaylist playlist play DYNAMICPLAYLIST_ID
  

• ADD will only add tracks from the dynamic playlist with the provided ID to your player (client).

  CLIENT_ID dynamicplaylist playlist add DYNAMICPLAYLIST_ID
  

• STOP will stop adding tracks from the dynamic playlist with the provided ID to your player (client). Though it's probably faster/easier to stop DPL by simply clearing the playlist on that player.

  CLIENT_ID dynamicplaylist playlist stop
  

The CLIENT_ID is your player's MAC address. It's listed on the LMS Settings > Player > Basic Settings page.

Dynamic playlist ID

The DYNAMICPLAYLIST_ID is the unique ID of the dynamic playlist. You can look it up in the plugin settings:

1. Open the settings of the Dynamic Playlists plugin in the LMS web interface and go to the Playlists page.
2. Open the group that contains your dynamic playlist (for example Songs, Albums or Static playlists).
3. Click the name of the dynamic playlist. Below it you will find the line Dynamic playlist ID.

If your script can talk JSON-RPC, the playlists query of the External API returns the IDs of all available dynamic playlists.

Example 1:
If you have a player with the MAC address 00:af:53:be:82:11 and a custom dynamic playlist with the ID dplusercustom_my_genre_mix_1 (see above), the CLI command to start this playlist would look like this:

00:af:53:be:82:11 dynamicplaylist playlist play dplusercustom_my_genre_mix_1

Example 2:
If you're using the KidsPlay plugin you can start dynamic playlists of your choice by creating macros for preset buttons of devices like Boom or SB Radio.

If you wanted to start the dynamic playlist from Example 1 by pressing preset button 1 on a Boom it'd look something like this:

power 1; stop; show "line1:Random" "line2:Genre Mix 1" duration:3 centered:1; dynamicplaylist playlist play dplusercustom_my_genre_mix_1;

Dynamic playlists that require (user) input

If you want to start a dynamic playlist that requires user input (e.g. genre, min. track rating), you will have to include values for all user input parameters in your CLI command.

CLIENT_ID dynamicplaylist playlist play DYNAMICPLAYLIST_ID dynamicplaylist_parameter_1:{values} dynamicplaylist_parameter_2:{values}

Example: Your dynamic playlist called mycustomplaylistname has 2 playlist parameters:

-- PlaylistParameter1:multiplegenres:Select genres:
-- PlaylistParameter2:list:Select min. rating Songs:0:unrated,10:0.5 stars,20:1 star,30:1.5 stars,40:2 stars,50:2.5 stars,60:3 stars,70:3.5 stars,80:4 stars,90:4.5 stars,100:5 stars

Let's say you want to play tracks from three genres with a minimum track rating of 1.5 stars on a player with the client ID 00:af:53:be:82:11.
Your CLI command would look like this:

00:af:53:be:82:11 dynamicplaylist playlist play dplusercustom_mycustomplaylistname dynamicplaylist_parameter_1:158,163,171 dynamicplaylist_parameter_2:30

Your command includes three LMS database genre IDs (158,163,171) for the first required parameter dynamicplaylist_parameter_1 and the min. track rating value (30) for the second required parameter dynamicplaylist_parameter_2.

⚠️ Please note: user input requests for volatile parameters like artist, album, genre, multiplegenres, playlist and multiplestaticplaylists always use the LMS database IDs - which may change after a rescan. If you always use the same parameter values (e.g. the same genres), it's better to include the values (e.g. genre names) directly in the SQLite statement.

❗️ If you don't include parameter values in your CLI command for dynamic playlists that require them, they won't start: since DPL 4.7.0 the command fails and a warning is written to the server log (set the plugin's debug level to Warn or a more verbose level). To look up valid parameter values, see parametervalues on the External API page.