Scripting

myMPD integrates Lua for scripting purposes. Script execution can be triggered in the main menu, with home icons, timers or triggers. Scripts are executed asynchronously, therefore scripts can not block the main threads of myMPD. The script output is printed to STDOUT and the return value is broadcasted to all connected clients in the current partition.

Arguments

Script arguments are populated in the lua table arguments. myMPD populates automatically the global partition variable.

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

Custom myMPD lua functions

myMPD provides custom lua functions through the mympd lua library.

Accessing the myMPD API

Calls the myMPD API, look at API for detailed API description.

rc, result = mympd.api("method", params)

Parameters:

Returns:

HTTP client

A simple http client.

rc, code, header, body = mympd.http_client(method, uri, headers, payload)

Parameters:

Returns:

Accessing myMPD and MPD status information

Populates the lua table mympd_state with configuration values and current status of myMPD and MPD.

mympd.init()

Parameters:

No parameters needed.

Returns:

• Lua table mympd_state

Execute a system command

Executes a system command and captures its output.

output = mympd.os_capture(command)

Parameters:

Returns:

If you want to run commands that changes the effective userid (e.g. with sudo) and you run myMPD with the default systemd service unit, you must create the mympd user manually and add an override.

groupadd -r mympd
useradd -r -g mympd -s /bin/false -d /var/lib/mympd mympd

curl -s https://raw.githubusercontent.com/jcorporation/myMPD/v10.0.0/contrib/initscripts/mympd.service.in | sed 's|@CMAKE_INSTALL_FULL_BINDIR@|/usr/bin|' /etc/systemd/system/mympd.service

systemctl daemon-reload
systemctl restart mympd

Lua manual

• Lua manual

Examples

Complete scripts can be found in the 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 = arguments["playlist"]})
-- start playing
mympd.api("MYMPD_API_PLAYER_PLAY")
-- broadcast message to all connected myMPD clients
return("Loaded playlist: " .. 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

Lua standard libraries

myMPD loads in the default config all lua standard libraries and the myMPD custom libraries. The configuration file lualibs controls which libraries myMPD opens before script execution.

Valid values are:

• Use all to load all standard lua libraries and the myMPD custom libraries
• Available standard lua libraries: base, coroutine, debug, io, math, os, package, string, table, utf8
• Available myMPD custom libraries:
  • mympd
  • json

Script file format

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

-- {"order":1,"arguments":["testarg1", "testarg2"]}
return("Arguments are: " .. arguments["testarg1"] .. arguments["testarg2"])