Lua plugin API

Rmpcd provides a set of functions available on the global scope to help with plugin development. Each of the plugins runs on a fully separate Lua VM and as such they are completely isolated from each other which means that they do not share state and cannot block each other.

You also should not use any of the Lua built in blocking APIs such as io library as that could starve rmpcd’s async executor.

Available modules

These modules are available on the global scope

• mpd - Functions to interact with MPD directly. These are relatively low level primitives mirroring the MPD protocol
• fs - A set of functions used to interact with the filesystem
• http - A simple HTTP client
• log - Logging facilities
• process - To spawn external programs
• sync - Utilities to for asynchronous execution
• util - Set of random utility functions that do not fit anywhere else

MPD

These functions correspond to the MPD protocol, see its documentation for more details.

They are available on global scope by accessing the mpd table.

	Function	Description
+ Expand row	get_song	Get song by its URI
Parameters uri string Song URI Returns Song | nil The song object if found string | nil Error message if any
+ Expand row	get_song_by_id	Get song by its ID in the current queue
Parameters id number Song ID Returns Song | nil The song object if found string | nil Error message if any
+ Expand row	get_current_song	Get the currently playing song
Parameters Returns Song | nil The song object if found string | nil Error message if any
+ Expand row	set_song_sticker	Set a song sticker
Parameters uri string Song URI name string Sticker name value string Sticker value Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	get_song_sticker	Get a song sticker value
Parameters uri string Song URI name string Sticker name Returns string | nil The sticker value if success, nil otherwise string | nil Error message if any
+ Expand row	set_consume	Set the consume state
Parameters value "on", "off" or "oneshot" The consume state Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	set_crossfade	Set crossfade duration
Parameters seconds number Crossfade duration in seconds Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	set_random	Set the random state
Parameters value boolean Whether to enable or disable random Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	set_repeat	Set the repeat state
Parameters value boolean Whether to enable or disable repeat Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	set_single	Set the single state
Parameters value "on", "off" or "oneshot" The single state Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	set_volume	Set MPD's volume
Parameters volume number Volume between 0 and 100 Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	get_volume	Get MPD's current volume
Returns number | nil The volume value if successful string | nil Error message if any
+ Expand row	volume	Set MPD's volume, supports relative change
Parameters value string +5 to increase volume by 5, -5 to decrease by 5 and 5 to set to 5 Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	prev	Switch to the previous song
Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	next	Switch to the next song
Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	play	Start playback
Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	pause	Pause playback
Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	stop	Stop playback
Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	toggle_pause	Toggle pause state on/off
Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	seek_current	Seek the current song
Parameters value string +5 to seek forward by 5 seconds, -5 to seek backwards by 5 seconds and 5 to seek to the 5th second directly Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	get_status	Returns MPD's current status info
Returns MpdStatus MPD's current status string | nil Error message if any
+ Expand row	album_art	Get song's album art by searching for cover.jpg, cover.png or cover.webp in the song's directory
Parameters uri string The song URI Returns number[] | nil Raw bytes of the image if successful string | nil Error message if any
+ Expand row	read_picture	Get song's embedded image
Parameters uri string The song URI Returns number[] | nil Raw bytes of the image if successful string | nil Error message if any
+ Expand row	subscribe	Subscribe to a channel
Parameters channel string Channel name Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	unsubscribe	Unsubscribe from a channel
Parameters channel string Channel name Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	channels	List of currently active channels
Returns string[] | nil List of active channels if successful string | nil Error message if any
+ Expand row	send_message	Send message to a channel
Parameters channel string Channel name message string Message to send Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	read_messages	Read messages from all channels that rmpcd is currently subscribed to, this probably should not be used directly unless you know what you are doing
Returns table Messages if successful string | nil Error message if any

FS

Filesystem API. These are available on global scope by accessing the fs table.

	Function	Description
+ Expand row	exists	Check whether a file exists
Parameters path string File path Returns boolean true if the file exists string | nil Error message if any
+ Expand row	create_dir_all	Create all directories in the path if they do not exist already
Parameters path string Directory path Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	create_dir	Create a directory
Parameters path string Directory path Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	write	Write raw bytes to a file
Parameters path string File path contents number[] Raw bytes Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	write_str	Write a string to a file
Parameters path string File path contents string Content to write Returns boolean Whether the call was successful string | nil Error message if any
+ Expand row	read	Read raw bytes from a file
Parameters path string File path Returns number[] | nil Raw bytes if successful string | nil Error message if any
+ Expand row	read_str	Read file as string
Parameters path string File path Returns string | nil String content if successful string | nil Error message if any
+ Expand row	delete	Delete a file
Parameters path string File path Returns boolean Whether the file was deleted string | nil Error message if any
+ Expand row	remove_dir	Remove a directory
Parameters path string Directory path Returns boolean Whether the directory was deleted string | nil Error message if any
+ Expand row	remove_dir	Remove a directory recursively
Parameters path string Directory path Returns boolean Whether the directory was deleted string | nil Error message if any

Http

A simple HTTP client. Available on the global scope by accessing the http table.

	Function	Description
+ Expand row	call	Do an HTTP call
Parameters url string URL to call to opts HttpRequestOpts Options for the HTTP request Returns HttpResponse The response, see below for more details
+ Expand row	get	Do a GET request
Parameters url string URL to call to opts HttpGetOpts Options for the GET HTTP request Returns HttpResponse The response, see below for more details
+ Expand row	post	Do a POST request
Parameters url string URL to call to opts HttpGetOpts Options for the POST HTTP request Returns HttpResponse The response, see below for more details

Opts

Each of the http functions takes an opts table.

	Property	Description
	method	HTTP method string
	headers	table of HTTP headers
	body	String body
	params	table to send as query parameters

The get function only takes headers and params in opts. The post function only takes headers, params and body in opts.

Response

The response is a table with following properties and functions:

	Property or function	Description
	code	Http Response code
	error	String error if any
	body	Raw string body of the response
+ Expand row	text	Gets the body text
Returns string The body
+ Expand row	json	Gets the body json as a table
Returns table The json value

Log

Logging facilities. Available on the global scope by accessing the log table.

	Function	Description
+ Expand row	info	Log at the info level
Parameters content string String content to log
+ Expand row	warn	Log at the warn level
Parameters content string String content to log
+ Expand row	error	Log at the error level
Parameters content string String content to log
+ Expand row	debug	Log at the debug level
Parameters content string String content to log
+ Expand row	trace	Log at the trace level
Parameters content string String content to log

Process

Spawn external processes. Available on the global scope by accessing the process table.

	Function	Description
+ Expand row	spawn	Spawn an external process
Parameters cmd string[] First element is the program to spawn, rest are passed in as arguments Returns number | nil The child process PID string | nil Error message if any

Sync

Execute things asynchronously. Available on the global scope by accessing the sync table.

	Function	Description
+ Expand row	set_timeout	Schedule a function to run at some later time
Parameters timeout_ms number Timeout in milliseconds callback function A function to run when the timeout expires Returns TimeoutHandle A handle to the timeout, call handle.cancel() to cancel the timeout
+ Expand row	set_interval	Schedule a function to run repeatedly with an interval
Parameters interval_ms number Interval in milliseconds callback function A function to run every interval tick Returns TimeoutHandle A handle to the interval, call handle.cancel() to cancel the interval
+ Expand row	debounce	Create a debounced version of a function
Parameters interval_ms number Interval in milliseconds callback function A function to run when the debounce timeout expires Returns function The debounced function

Util

Set of random utilities that do not fit anywhere else. Available on the global scope by accessing the util table.

	Function	Description
+ Expand row	dump_table	Dump table to the logger
Parameters tbl table Dump the table to the logger
+ Expand row	md5	Compute an md5 hash of a value
Parameters data string Data to hash Returns string The md5 hash
+ Expand row	which	Check whether a program exists in path
Parameters prog string The program Returns boolean Whether the program exists
+ Expand row	nil_or_null	Check whether a value is nil or null, useful to for example validate HTTP responses
Parameters value any The value Returns boolean Whether the value is nil or nul
+ Expand row	deserialize_ron	Deserialize a ron value
Parameters data number[] Input bytes Returns any | nil Deserialized value if success string | nil Error message if any