External API

This page describes the dispatches that Dynamic Playlists 4 (DPL) offers to external apps and plugins: list the available dynamic playlists, get values for their parameters, start, add, stop and save them, get their tracks without playing them (for example for offline use), and move an active dynamic playlist to another player. To start or stop dynamic playlists from other LMS plugins or scripts, see CLI commands for plugins and scripts.

Requires DPL 4.7.2 or newer.

1. Basics

Transport: LMS JSON-RPC

All dispatches are called through the LMS JSON-RPC interface (slim.request):

POST http://<lms-host>:9000/jsonrpc.js
Content-Type: application/json

{
    "id": 1,
    "method": "slim.request",
    "params": [
        "aa:bb:cc:dd:ee:ff",
        ["dynamicplaylist", "isactive"]
    ]
}

The first element of params is the player ID (the player's MAC address as known by LMS). Every DPL request needs a player, including queries like playlists.
The second element is the request as an array: first "dynamicplaylist", then the dispatch words, then parameters. Named parameters are strings of the form "key:value". Values need no URL encoding.
If password protection is enabled in LMS, send HTTP Basic authentication as for any other LMS JSON-RPC call.

LMS answers with the request data plus a result object. The examples below show only the params[1] array of the request and the result object of the response:

{
    "id": 1,
    "method": "slim.request",
    "params": [
        "aa:bb:cc:dd:ee:ff",
        ["dynamicplaylist", "isactive"]
    ],
    "result": {
        "_isactive": "dpldefault_albums_001_random"
    }
}

The same call with curl:

curl -s -X POST http://lms.local:9000/jsonrpc.js -H "Content-Type: application/json" -d '{"id":1,"method":"slim.request","params":["aa:bb:cc:dd:ee:ff",["dynamicplaylist","isactive"]]}'

Errors

If a request fails (unknown player, unknown dynamic playlist ID, missing required parameters, a disabled feature), LMS closes the HTTP connection without a JSON response body and writes the reason to the server log. Treat a failed HTTP request or a closed connection as an error and check the LMS server log for details.

2. Concepts

Dynamic playlist IDs

Every dynamic playlist has a string ID, for example dpldefault_albums_001_random (built-in), dplusercustom_<name> (user-provided SQL files), dplccustom_<name> (created with the Dynamic Playlist Creator plugin) or dplstaticpl_<hash> (saved static playlists). Use the IDs exactly as returned by playlists.

Parameters

Some dynamic playlists need user input before they can start, for example a genre or a decade. playlists lists these parameters for every dynamic playlist, numbered 1, 2, 3 and so on. To start such a dynamic playlist you must send a value for every parameter as dynamicplaylist_parameter_<number>:<value>. There are no default values, and a request with missing parameter values fails.

The server does not check whether a value is valid. A value that matches nothing usually makes the dynamic playlist find no tracks and stop itself (see Good to know).

Parameter types and value formats

Each parameter has a type that tells you which value to send and where to get it.

Type	Value to send	Where to get the values
`list`	`id` of one entry in the parameter's `values`	inline in `playlists`
`album`	LMS album ID	`parametervalues`
`artist`	LMS artist ID	`parametervalues`
`genre`	LMS genre ID	`parametervalues`
`year`	year (`0` = unknown year)	`parametervalues`
`playlist`	LMS static playlist ID	`parametervalues`
`virtuallibrary`	the `id` exactly as returned, including the surrounding single quotes	`parametervalues` only
`multiplegenres`	comma-separated genre IDs, e.g. `1414,1415`	`parametervalues`
`multipleyears`	comma-separated years, e.g. `1999,2001`	`parametervalues`
`multipledecades`	comma-separated decade start years, e.g. `1980,1990` (`0` = unknown year); the server expands them to years	`parametervalues`
`multiplestaticplaylists`	comma-separated LMS static playlist IDs	`parametervalues`
`albumtitlecontains`, `tracktitlecontains`	free text (send it as typed)	none, `parametervalues` returns an empty array
`customalbum`, `customartist`, `customdecade`, `customgenre`, `customplaylist`, `customyear`	the `id` exactly as returned	`parametervalues` only

For the core types (album, artist, genre, year, playlist and the multiple-selection types) the values are ordinary LMS database IDs. An app that already has them, for example from its own library browser or from the LMS queries albums, artists, genres, years and playlists, may send them directly without calling parametervalues. For virtuallibrary and all custom* types, use parametervalues because only DPL knows the correct values.

Volatile parameter types

The types artist, album, genre, multiplegenres, playlist and multiplestaticplaylists are marked as volatile: their values are database IDs that can change after a delete/wipe and rescan of the LMS library. A dynamic playlist with such parameters has hasvolatileparams set to 1 in playlists. Do not store these IDs permanently; ask again when you need them.

3. Reference

All dispatches need a player ID (see Transport).

isactive

Returns the ID of the dynamic playlist that is currently active on the player.

Request:

["dynamicplaylist", "isactive"]

Result:

{
    "_isactive": "dpldefault_albums_001_random"
}

_isactive is empty (an empty string or null) if no dynamic playlist is active. The field name starts with an underscore (an LMS convention).

A dynamic playlist becomes active with playlist play if the first track search finds tracks.
_isactive is empty again after playlist stop, or when the dynamic playlist stops itself because it finds no more matching tracks.
playlist add never starts a dynamic playlist and never changes what isactive reports.

playlists

Returns the dynamic playlists that an app can use, with their parameters.

Request:

["dynamicplaylist", "playlists"]

Optional paging with the positional values <start> and <items per page>:

["dynamicplaylist", "playlists", 0, 50]

Result (example):

{
    "count": 2,
    "offset": 0,
    "volatileparamsdplsaveenabled": 1,
    "playlists": {
        "dplccustom_example_by_genre": {
            "name": "Random songs by genre",
            "dynamicplaylistfavourite": 0,
            "playlistcategory": "songs",
            "groups": [["Songs"]],
            "hasvolatileparams": 1,
            "parameters": {
                "1": {
                    "id": "1",
                    "type": "genre",
                    "name": "Select genre"
                },
                "2": {
                    "id": "2",
                    "type": "list",
                    "name": "Minimum rating",
                    "values": [
                        {
                            "id": "0",
                            "name": "Any rating"
                        },
                        {
                            "id": "3",
                            "name": "3 stars or more"
                        }
                    ]
                }
            }
        },
        "dplccustom_example_random_songs": {
            "name": "Random songs",
            "dynamicplaylistfavourite": 1,
            "playlistcategory": "songs",
            "groups": [["Songs"]]
        }
    }
}

Field	Meaning
`count`	total number of dynamic playlists (not the size of the current page)
`offset`	the `<start>` value of this response
`volatileparamsdplsaveenabled`	`1` if dynamic playlists with volatile parameters may be saved as favorites, see playlist savefavorite
`playlists`	object with the dynamic playlist ID as key
`name`	display name of the dynamic playlist (in the server language)
`dynamicplaylistfavourite`	`1` if the dynamic playlist is marked as a favorite in the DPL settings (not an LMS favorite)
`playlistcategory`	category string of the dynamic playlist
`groups`	list of group paths, each path is an array of group names
`parameters`	only present if the dynamic playlist needs user input; object with the parameter number as key
`hasvolatileparams`	only present together with `parameters`, see Volatile parameter types
`parameters.<n>.type`	parameter type, see Parameter types
`parameters.<n>.name`	display name of the parameter
`parameters.<n>.values`	only for type `list`: array of `id` and `name` in the intended order

Notes:

playlists is an object. Sort the entries by name in your app. Paging follows the alphabetical order of the IDs.
Dynamic playlists that are disabled in the DPL settings, that only make sense in a context menu, or that depend on the DPL preselection lists are not part of this API and are not listed.

parametervalues

Returns the possible values of one parameter of a dynamic playlist. This is the way to get the values for every parameter type except list (whose values are already part of playlists).

Request:

["dynamicplaylist", "parametervalues", "playlistid:dplccustom_example_by_genre", "parameterid:1"]

Parameter	Required	Meaning
`playlistid`	yes	dynamic playlist ID
`parameterid`	yes	parameter number from `playlists`
`dynamicplaylist_parameter_<n>`	for dependent parameters	values already chosen for earlier parameters

Result:

{
    "values": [
        {
            "id": "1414",
            "name": "Rock"
        },
        {
            "id": "1415",
            "name": "Jazz"
        }
    ]
}

values is an ordered array, in the order defined by the dynamic playlist (for example alphabetical for genres, newest first for decades). Show the entries in this order. For free-text types the array is empty.

Dependent parameters: if a dynamic playlist has a virtuallibrary parameter, send the chosen library value while asking for the values of the following parameters. The values (for example genres, decades or years) are then limited to that library. The same mechanism lets custom* parameters depend on earlier ones. If the player itself has an active virtual library, it takes precedence over the library chosen in the dynamic playlist.

Example: values for parameter 2 after the user chose library '91b427f1' for parameter 1:

["dynamicplaylist", "parametervalues", "playlistid:dplccustom_example_library_by_genre", "parameterid:2", "dynamicplaylist_parameter_1:'91b427f1'"]

playlist play

Starts a dynamic playlist on the player. The current player playlist is replaced, the player is powered on if necessary, and the dynamic playlist keeps adding tracks while it is active.

Request (dynamic playlist without parameters):

["dynamicplaylist", "playlist", "play", "playlistid:dplccustom_example_random_songs"]

Request (dynamic playlist with parameters):

["dynamicplaylist", "playlist", "play", "playlistid:dplccustom_example_by_genre", "dynamicplaylist_parameter_1:1414", "dynamicplaylist_parameter_2:0"]

Parameter	Required	Meaning
`playlistid`	yes	dynamic playlist ID
`dynamicplaylist_parameter_<n>`	for dynamic playlists with parameters, one for every parameter	value, see Parameter types

Result: an empty result object.

The response is sent after DPL has finished its first search for tracks. Call isactive right afterwards: it returns the dynamic playlist ID if tracks were found and the dynamic playlist is running, and it is empty if no tracks were found (the dynamic playlist then stops itself immediately). A successful response alone does not mean that tracks were found.

playlist add

Adds tracks of a dynamic playlist to the end of the current player playlist without replacing it. Parameters and result are the same as for playlist play.

["dynamicplaylist", "playlist", "add", "playlistid:dplccustom_example_by_genre", "dynamicplaylist_parameter_1:1414", "dynamicplaylist_parameter_2:0"]

add is a one-time action. It does not start a dynamic playlist and does not change what isactive reports: a dynamic playlist that is running keeps running.

playlist tracks

Returns the tracks of a dynamic playlist without playing or adding them. The player's playlist is not touched, no dynamic playlist is started, isactive is not affected and the DPL history of the player is not changed. This is meant for apps that handle the tracks themselves, for example to download them for offline use.

Request (dynamic playlist without parameters):

["dynamicplaylist", "playlist", "tracks", "playlistid:dplccustom_example_random_songs", "limit:50"]

Request (dynamic playlist with parameters and optional values):

["dynamicplaylist", "playlist", "tracks", "playlistid:dplccustom_example_by_genre", "dynamicplaylist_parameter_1:1414", "dynamicplaylist_parameter_2:0", "limit:50", "primaryartist:1", "excludetrackids:1203,1877,2045"]

Parameter	Required	Meaning
`playlistid`	yes	dynamic playlist ID
`limit`	yes	maximum number of tracks, a whole number from `1` to `5000`
`dynamicplaylist_parameter_<n>`	for dynamic playlists with parameters, one for every parameter	value, see Parameter types
`primaryartist`	no	`1` adds the `primary_artist` to every track, see below
`excludetrackids`	no	comma-separated LMS track IDs that must not be returned, for example tracks the app already has

Result:

{
    "count": 2,
    "tracks": [
        {
            "id": "4512"
        },
        {
            "id": "877"
        }
    ]
}

Result with primaryartist:1:

{
    "count": 2,
    "tracks": [
        {
            "id": "4512",
            "primary_artist": 387
        },
        {
            "id": "877",
            "primary_artist": 12
        }
    ]
}

Field	Meaning
`count`	number of returned tracks, can be lower than `limit`
`tracks`	ordered array, see below for the order
`tracks[].id`	LMS track ID
`tracks[].primary_artist`	only with `primaryartist:1`: LMS ID of the track's primary artist, `null` if there is none

primary_artist is optional because DPL can only take it from the search result of the dynamic playlist if that search provides it. Otherwise DPL has to look it up in the LMS database for every track, which costs time. Ask for it if your app needs it: LMS uses the primary artist for balanced shuffling, which distributes the tracks of each artist evenly along the list instead of shuffling purely at random. With the artist IDs your app can group the tracks the same way when it plays them in shuffled order.

Which tracks you get:

DPL runs the same search as for playlist play, removes duplicates, shuffles the tracks according to the DPL shuffle setting (not for ordered dynamic playlists) and cuts the result to limit. The tracks are returned in this order. If your app plays them in random order, shuffle them again in the app.
You still need a player ID. The search uses the player's virtual library, and the built-in dynamic playlists skip tracks that DPL has already used for that player while a dynamic playlist is active on it. Use a player that is not running a dynamic playlist.
DPL does not remember what it returned. Two calls can return the same tracks. Send the IDs your app already has in excludetrackids to get new ones.
Start and stop actions of a dynamic playlist are not executed. DPL itself does not apply Custom Skip rules, so tracks that Custom Skip would skip during normal playback can be part of the result.
Track and artist IDs are LMS database IDs. Like the volatile parameter types they can change after a wipe and rescan of the library.
The response is sent after the search has finished. Large values for limit can take a while.

The request fails (see Errors) if the dynamic playlist ID is unknown, a parameter value is missing, limit is missing, not a whole number or outside 1 to 5000, or the dynamic playlist definition contains an error.

playlist stop

Stops the active dynamic playlist of the player. It adds no further tracks.

["dynamicplaylist", "playlist", "stop"]

No parameters. Result: an empty result object.

playlist savefavorite

Saves a dynamic playlist (with the given parameter values) as an LMS favorite.

["dynamicplaylist", "playlist", "savefavorite", "playlistid:dplccustom_example_by_genre", "dynamicplaylist_parameter_1:1414", "dynamicplaylist_parameter_2:0", "name:Rock songs"]

Parameter	Required	Meaning
`playlistid`	yes	dynamic playlist ID
`dynamicplaylist_parameter_<n>`	for dynamic playlists with parameters, one for every parameter	values to store in the favorite
`addOnly`	no	`1` creates a favorite that adds the tracks to the current playlist instead of replacing it (note the capital `O`)
`name`	no	title of the favorite, default is the dynamic playlist name

Result: an empty result object.

If the same favorite already exists, no duplicate is created and the request still succeeds.
If the dynamic playlist has volatile parameters (hasvolatileparams is 1) and volatileparamsdplsaveenabled is 0, the request fails.

transfer

Moves the active dynamic playlist, including the current player playlist, from one player to another. This takes two calls.

Step 1: get the possible target players. Send this request to the player that currently plays the dynamic playlist. playlistid is the ID that isactive reports for this player.

["dynamicplaylist", "transfer", "playlistid:dplccustom_example_random_songs", "showtargetplayerlist:1"]

Result (the fields item_loop, window, offset and count are menu data for other clients, ignore them):

{
    "players": {
        "11:22:33:44:55:66": {
            "id": "11:22:33:44:55:66",
            "name": "Kitchen"
        }
    }
}

The list contains all other players. Players that are synced are only listed if this is allowed in the DPL settings.

Step 2: transfer.

["dynamicplaylist", "transfer", "playlistid:dplccustom_example_random_songs", "targetplayerid:11:22:33:44:55:66"]

Parameter	Required	Meaning
`playlistid`	yes	ID of the active dynamic playlist
`showtargetplayerlist`	for step 1	`1` returns the list of target players
`targetplayerid`	for step 2	player ID of the target player

Result of step 2: an empty result object. The target player is powered on if necessary and takes over the dynamic playlist and the player playlist. If the source player was not playing, the target is paused. The dynamic playlist is stopped on the source player and its playlist is cleared.

A request with neither showtargetplayerlist nor targetplayerid fails.

refreshplaylists

Re-reads the dynamic playlist definitions, for example after dynamic playlist files were added or changed while the server was running.

["dynamicplaylist", "refreshplaylists"]

No parameters. Result: an empty result object.

4. Typical workflow

Call playlists and show the dynamic playlists (sorted by name, grouped by groups if you like).
The user picks a dynamic playlist. If it has no parameters, go to step 4.
For each parameter in order (1, 2, 3 and so on): show the values from playlists for type list, otherwise call parametervalues and pass the values chosen so far as dynamicplaylist_parameter_<n>. For free-text types ask the user for the text.
Call playlist play (or playlist add) with playlistid and all dynamicplaylist_parameter_<n> values.
After play, call isactive to see whether the dynamic playlist is running. Use playlist stop to end it.
Offline caching: instead of playlist play call playlist tracks with the same playlistid, parameter values and a limit, and download the returned tracks. To get more tracks of the same dynamic playlist later, call it again and send the IDs you already have in excludetrackids.

5. Good to know

A successful response does not prove that tracks were found. play returns after the first track search. A dynamic playlist whose filters match nothing (for example because of strict minimum track duration or minimum album track settings in small or unusual libraries) stops itself. Check with isactive right after play. Later on, a dynamic playlist also stops when it runs out of matching tracks, so isactive can become empty again.
Values are not validated. The server passes your values to the dynamic playlist as they are. A value that does not exist simply matches no tracks.
IDs can change. Database IDs of volatile parameter types can change after a wipe and rescan of the library. Do not store them long-term; request fresh values instead.
Order. parametervalues and the values of list parameters are ordered arrays and must be shown in that order. playlists and players are objects, sort them yourself.
Errors. A failed request closes the HTTP connection without a JSON body. The reason is in the LMS server log.
playlist tracks can return fewer tracks than limit. DPL repeats the search up to 20 times. Dynamic playlists that find only a few tracks per search (for example one album at a time) or have only few matching tracks in the library return fewer tracks. count tells you how many you got.

Navigation Menu

Repository navigation

External API

Contents

1. Basics

Transport: LMS JSON-RPC

Errors

2. Concepts

Dynamic playlist IDs

Parameters

Parameter types and value formats

Volatile parameter types

3. Reference

isactive

playlists

parametervalues

playlist play

playlist add

playlist tracks

playlist stop

playlist savefavorite

transfer

refreshplaylists

4. Typical workflow

5. Good to know

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally