Scripting

myMPD integrates Lua for scripting purposes. Scripts are executed asynchronously and can not block the main thread of myMPD. There are two types of scripts.

The first type of scripts are executed by triggers, timers or manual through the web ui. The script output is printed to STDOUT and the return value is broadcasted to all connected clients in the current partition.

• Triggers

The second type of script are called by http requests (/script/<partition>/<script>) and special triggers. This scripts should return a valid http response including status code, headers and body.

Global variables

myMPD populates automatically some global variables.

myMPD uses function and variable names prefixed with mympd. You should avoid this in your naming convention.

myMPD environment

myMPD environment variables are populated in the lua table mympd_env.

Additionally all user defined variables are populates in this table. They are prefixed with var_.

Arguments

Script arguments are populated in the lua table mympd_arguments. All arguments are of type string.

-- return the argument named playlist
return mympd_arguments["playlist"]

Arguments can be defined as simple names (text input field) or with typical html form element types.

myMPD state

The mympd_state global lua table is NOT populates automatically. You must call mympd.init() to populate it.

• mympd.init

Custom myMPD lua functions

myMPD provides custom lua functions through the mympd and json lua library.

• List of all functions

Lua manual

• Lua manual

Examples

Here can you find some simple examples.

Complete scripts that can be imported are in the mympd-scripts repository.

Simple

-- load a playlist
mympd.api("MYMPD_API_QUEUE_REPLACE_PLAYLIST", {plist = "NonPop"})
-- start playing
mympd.api("MYMPD_API_PLAYER_PLAY")

With arguments

Script should be called with an argument named playlist.

-- load a playlist
mympd.api("MYMPD_API_QUEUE_REPLACE_PLAYLIST", {plist = mympd_arguments.playlist})
-- start playing
mympd.api("MYMPD_API_PLAYER_PLAY")
-- broadcast message to all connected myMPD clients
return("Loaded playlist: " .. mympd_arguments.playlist)

Error handling

-- get current playing song
rc, result = mympd.api("MYMPD_API_PLAYER_CURRENT_SONG", {})
if rc == 0
  return "Current song title: " .. result.Title
else
  return "Error message: " .. result.message
end

Script file format

Scripts are saved in the directory /var/lib/mympd/scripts with the extension .lua. The metadata is saved in the first line in a lua comment as json object.

-- {"name": "scriptname", "file": "category/scriptname.lua", "version": 1, "desc": "short description", "order":1,"arguments":["testarg1", "testarg2"]}
return("Arguments are: " .. mympd_arguments.testarg1 .. mympd_arguments.testarg2)

Metadata