File mpd.lua
A Lua client libary for mpd.
Functions
MPD:add (uri) | Adds the file URI to the playlist and increments playlist version. |
MPD:addid (uri, position) | Adds a song to the playlist (non-recursive) and returns the song id. |
MPD:clear () | Clears the current playlist. |
MPD:clearerror () | Clear last error. |
MPD:close () | Closes the connection to MPD. |
MPD:commands () | Shows which commands the current user has access to. |
MPD:connect () | Connect (or reconnect) to the server. |
MPD:count (tag, value) | Counts the number of songs and their total playtime in the db matching TAG exactly. |
MPD:currentsong () | Get current song (if any). |
MPD:delete (spec, arg) | Deletes a song from the playlist. |
MPD:deleteid (songid) | Deletes the song SONGID from the playlist |
MPD:disableoutput (arg) | Turns an output off. |
MPD:enableoutput (arg) | Turns an output on. |
MPD:find (type, what) | Finds songs in the db that are exactly WHAT. |
MPD:findadd (type, what) | Finds songs in the db that are exactly WHAT and adds them to current playlist. |
MPD:idle (subsystems) | Wait for changes in one or more subsystem(s). |
MPD:kill () | Kills MPD. |
MPD:list (type, artist) | Lists all tags of the specified type. |
MPD:listall (uri) | Lists all songs and directories in URI. |
MPD:listallinfo (uri) | Same as listall, except it also returns metadata info in the same format as lsinfo. |
MPD:listplaylist (name) | Lists the files in the playlist NAME.m3u. |
MPD:listplaylistinfo (name) | Lists songs in the playlist NAME.m3u. |
MPD:listplaylists () | Prints a list of the playlist directory. |
MPD:load (name) | Loads the playlist NAME.m3u from the playlist directory. |
MPD:lsinfo (uri) | Lists the contents of the directory URI. |
MPD:move (pos, to) | Moves the song at FROM or song range at START:END to TO in the playlist. |
MPD:moveid (id, to) | Moves the song with FROM (songid) to TO (playlist index) in the playlist. |
MPD:next () | Plays next song in the playlist. |
MPD:noidle () | Cancel blocking idle command. |
MPD:notcommands () | Shows which commands the current user does not have access to. |
MPD:outputs () | Shows information about all outputs. |
MPD:password (password) | This is used for authentication with the server. |
MPD:pause (flag) | Set pause to true/false. |
MPD:ping () | Does nothing but return "OK". |
MPD:play (songpos) | Begins playing the playlist at song number SONGPOS. |
MPD:playid (songid) | Begins playing the playlist at song SONGID. |
MPD:playlistadd (name, uri) | Adds URI to the playlist NAME.m3u. |
MPD:playlistclear (name) | Clears the playlist NAME.m3u. |
MPD:playlistdelete (name, songpos) | Deletes SONGPOS from the playlist NAME.m3u. |
MPD:playlistfind (tag, value) | Finds songs in the current playlist with strict matching. |
MPD:playlistid (songid) | Displays a list of songs in the playlist. |
MPD:playlistinfo (spec) | Displays a list of all songs in the playlist, or if the optional argument is given, displays information only for the song SONGPOS or the range of songs START:END |
MPD:playlistsearch (tag, value) | Searches case-sensitively for partial matches in the current playlist. |
MPD:plchanges (version) | Displays changed songs currently in the playlist since VERSION. |
MPD:plchangesposid (version) | Displays changed songs currently in the playlist since VERSION. |
MPD:previous () | Plays previous song in the playlist. |
MPD:receive (rform) | Read and process a response. |
MPD:rename (name, new_name) | Renames the playlist NAME.m3u to NEW_NAME.m3u. |
MPD:replay_gain_status () | Get replay gain options. |
MPD:rescan (uri) | Same as update, but also rescans unmodified files. |
MPD:rm (name) | Removes the playlist NAME.m3u from the playlist directory. |
MPD:save (name) | Saves the current playlist to NAME.m3u in the playlist directory. |
MPD:search (type, what) | Searches for any song that contains WHAT. |
MPD:seek (songpos, time) | Seeks to the position TIME (in seconds) of entry SONGPOS in the playlist. |
MPD:seekid (songid, time) | Seeks to the position TIME (in seconds) of song SONGID. |
MPD:send (cmd) | Send an arbitrary string. |
MPD:set_consume (state) | Set consume state. |
MPD:set_crossfade (seconds) | Sets crossfading between songs (in seconds). |
MPD:set_random (state) | Sets random state to true/false. |
MPD:set_replay_gain_mode (mode) | Sets the replay gain mode. |
MPD:set_single (state) | Sets single state to true/false. |
MPD:set_vol (vol) | Sets volume to VOL, the range of volume is 0-100. |
MPD:shuffle (spec) | Shuffles the current playlist. |
MPD:stats () | Get table with stats. |
MPD:status () | Get table with status. |
MPD:sticker_delete (type, uri, name) | Deletes a sticker value from the specified object. |
MPD:sticker_find (type, uri, name) | Searches the sticker database for stickers with the specified name, below the specified directory (URI). |
MPD:sticker_get (type, uri, name) | Reads a sticker value for the specified object. |
MPD:sticker_list (type, uri) | Lists the stickers for the specified object. |
MPD:sticker_set (type, uri, name, value) | Adds a sticker value to the specified object. |
MPD:stop () | Stop playing. |
MPD:swap (song1, song2) | Swaps the positions of SONG1 and SONG2. |
MPD:swapid (song1, song2) | Swaps the positions of SONG1 and SONG2 (both song ids). |
MPD:tagtypes () | Shows a list of available song metadata. |
MPD:unpause () | Unpause. |
MPD:update (uri) | Updates the music database: find new files, remove deleted files, update modified files. |
MPD:urlhandlers () | Gets a list of available URL handlers. |
connect (host, port, reconnect) | Get an MPD server connection handle. |
Functions
- MPD:add (uri)
-
Adds the file URI to the playlist and increments playlist version. URI can also be a single file or a directory (added recursively).
Parameters
- uri:
- MPD:addid (uri, position)
-
Adds a song to the playlist (non-recursive) and returns the song id. URI is always a single file or URL. For example: addid "foo.mp3" Id: 999 OK
Parameters
- uri:
- position:
- MPD:clear ()
- Clears the current playlist.
- MPD:clearerror ()
- Clear last error.
- MPD:close ()
- Closes the connection to MPD.
- MPD:commands ()
- Shows which commands the current user has access to.
- MPD:connect ()
- Connect (or reconnect) to the server.
- MPD:count (tag, value)
-
Counts the number of songs and their total playtime in the db matching TAG exactly.
Parameters
- tag: One of the tags known, as returned by MPD:tagtypes().
- value:
- MPD:currentsong ()
- Get current song (if any).
- MPD:delete (spec, arg)
-
Deletes a song from the playlist.
Parameters
- spec:
- arg: Optional POS (relative to current) or START:END.
- MPD:deleteid (songid)
-
Deletes the song SONGID from the playlist
Parameters
- songid:
- MPD:disableoutput (arg)
-
Turns an output off.
Parameters
- arg:
- MPD:enableoutput (arg)
-
Turns an output on.
Parameters
- arg:
- MPD:find (type, what)
-
Finds songs in the db that are exactly WHAT.
Parameters
- type: "album", "artist", or "title"
- what: What to find
- MPD:findadd (type, what)
-
Finds songs in the db that are exactly WHAT and adds them to current playlist. TYPE can be any tag supported by MPD. WHAT is what to find.
Parameters
- type:
- what:
- MPD:idle (subsystems)
-
Wait for changes in one or more subsystem(s). Blocking, so polling is not necessary.
Parameters
- subsystems: subsystems can be one or more of: "database", "update", "stored_playlist", "playlist", "player", "mixer", "output_options"
- MPD:kill ()
- Kills MPD.
- MPD:list (type, artist)
-
Lists all tags of the specified type. TYPE should be album or artist.
Parameters
- type: "album" or "artist"
- artist: Optionl. If type is "album", just search for albums by a specific artist (e.g. mpd:list("album", "The Mountain Goats")).
- MPD:listall (uri)
-
Lists all songs and directories in URI.
Parameters
- uri:
- MPD:listallinfo (uri)
-
Same as listall, except it also returns metadata info in the same format as lsinfo.
Parameters
- uri:
- MPD:listplaylist (name)
-
Lists the files in the playlist NAME.m3u.
Parameters
- name:
- MPD:listplaylistinfo (name)
-
Lists songs in the playlist NAME.m3u.
Parameters
- name:
- MPD:listplaylists ()
- Prints a list of the playlist directory. After each playlist name the server sends its last modification time as attribute "Last-Modified" in ISO 8601 format. To avoid problems due to clock differences between clients and the server, clients should not compare this value with their local clock.
- MPD:load (name)
-
Loads the playlist NAME.m3u from the playlist directory.
Parameters
- name:
- MPD:lsinfo (uri)
-
Lists the contents of the directory URI. When listing the root directory, this currently returns the list of stored playlists. This behavior is deprecated; use "listplaylists" instead.
Parameters
- uri:
- MPD:move (pos, to)
-
Moves the song at FROM or song range at START:END to TO in the playlist.
Parameters
- pos: Either a position in the playlist (counting from 0) or a colon-separated range of positions (e.g. "10:15").
- to: Position in playlist.
- MPD:moveid (id, to)
-
Moves the song with FROM (songid) to TO (playlist index) in the playlist. If TO is negative, it is relative to the current song in the playlist (if there is one).
Parameters
- id:
- to:
- MPD:next ()
- Plays next song in the playlist.
- MPD:noidle ()
- Cancel blocking idle command.
- MPD:notcommands ()
- Shows which commands the current user does not have access to.
- MPD:outputs ()
- Shows information about all outputs.
- MPD:password (password)
-
This is used for authentication with the server.
Parameters
- password: the plaintext password.
- MPD:pause (flag)
-
Set pause to true/false.
Parameters
- flag: Defaults to true.
- MPD:ping ()
- Does nothing but return "OK".
- MPD:play (songpos)
-
Begins playing the playlist at song number SONGPOS.
Parameters
- songpos:
- MPD:playid (songid)
-
Begins playing the playlist at song SONGID.
Parameters
- songid: Song ID, which is preserved as playlist is rearranged.
- MPD:playlistadd (name, uri)
-
Adds URI to the playlist NAME.m3u. NAME.m3u will be created if it does not exist.
Parameters
- name:
- uri:
- MPD:playlistclear (name)
-
Clears the playlist NAME.m3u.
Parameters
- name:
- MPD:playlistdelete (name, songpos)
-
Deletes SONGPOS from the playlist NAME.m3u.
Parameters
- name:
- songpos:
- MPD:playlistfind (tag, value)
-
Finds songs in the current playlist with strict matching.
Parameters
- tag: One of the tags known, as returned by MPD:tagtypes().
- value:
- MPD:playlistid (songid)
-
Displays a list of songs in the playlist.
Parameters
- songid: Optional, specifies a single song to display info for.
- MPD:playlistinfo (spec)
-
Displays a list of all songs in the playlist, or if the optional argument is given, displays information only for the song SONGPOS or the range of songs START:END
Parameters
- spec:
- MPD:playlistsearch (tag, value)
-
Searches case-sensitively for partial matches in the current playlist.
Parameters
- tag: One of the tags known, as returned by MPD:tagtypes().
- value:
- MPD:plchanges (version)
-
Displays changed songs currently in the playlist since VERSION. To detect songs that were deleted at the end of the playlist, use playlistlength returned by status command.
Parameters
- version:
- MPD:plchangesposid (version)
-
Displays changed songs currently in the playlist since VERSION. This function only returns the position and the id of the changed song, not the complete metadata. This is more bandwidth efficient. To detect songs that were deleted at the end of the playlist, use playlistlength returned by status command.
Parameters
- version:
- MPD:previous ()
- Plays previous song in the playlist.
- MPD:receive (rform)
-
Read and process a response.
Parameters
- rform:
- MPD:rename (name, new_name)
-
Renames the playlist NAME.m3u to NEW_NAME.m3u.
Parameters
- name:
- new_name:
- MPD:replay_gain_status ()
- Get replay gain options. Currently, only the variable replay_gain_mode is returned.
- MPD:rescan (uri)
-
Same as update, but also rescans unmodified files.
Parameters
- uri:
- MPD:rm (name)
-
Removes the playlist NAME.m3u from the playlist directory.
Parameters
- name:
- MPD:save (name)
-
Saves the current playlist to NAME.m3u in the playlist directory.
Parameters
- name:
- MPD:search (type, what)
-
Searches for any song that contains WHAT. TYPE can be title, artist, album or filename. Search is not case sensitive.
Parameters
- type:
- what:
- MPD:seek (songpos, time)
-
Seeks to the position TIME (in seconds) of entry SONGPOS in the playlist.
Parameters
- songpos:
- time:
- MPD:seekid (songid, time)
-
Seeks to the position TIME (in seconds) of song SONGID.
Parameters
- songid: Song ID, which is preserved as playlist is rearranged.
- time:
- MPD:send (cmd)
-
Send an arbitrary string.
Parameters
- cmd:
- MPD:set_consume (state)
-
Set consume state. When consume is activated, each song played is removed from playlist.
Parameters
- state:
- MPD:set_crossfade (seconds)
-
Sets crossfading between songs (in seconds).
Parameters
- seconds:
- MPD:set_random (state)
-
Sets random state to true/false.
Parameters
- state:
- MPD:set_replay_gain_mode (mode)
-
Sets the replay gain mode. One of "off", "track", "album". Changing the mode during playback may take several seconds, because the new setting does not affect the buffered data. This command triggers the options idle event.
Parameters
- mode:
- MPD:set_single (state)
-
Sets single state to true/false. When single is activated, playback is stopped after current song, or the single song is repeated if the 'repeat' mode is enabled.
Parameters
- state:
- MPD:set_vol (vol)
-
Sets volume to VOL, the range of volume is 0-100.
Parameters
- vol:
- MPD:shuffle (spec)
-
Shuffles the current playlist.
Parameters
- spec: Optional, specifies a range of songs.
- MPD:stats ()
- Get table with stats.
- MPD:status ()
- Get table with status.
- MPD:sticker_delete (type, uri, name)
-
Deletes a sticker value from the specified object. If you do not specify a sticker name, all sticker values are deleted.
Parameters
- type:
- uri:
- name:
- MPD:sticker_find (type, uri, name)
-
Searches the sticker database for stickers with the specified name, below the specified directory (URI). For each matching song, it prints the URI and that one sticker's value.
Parameters
- type:
- uri:
- name:
- MPD:sticker_get (type, uri, name)
-
Reads a sticker value for the specified object.
Parameters
- type:
- uri:
- name:
- MPD:sticker_list (type, uri)
-
Lists the stickers for the specified object.
Parameters
- type:
- uri:
- MPD:sticker_set (type, uri, name, value)
-
Adds a sticker value to the specified object. If a sticker item with that name already exists, it is replaced.
Parameters
- type:
- uri:
- name:
- value:
- MPD:stop ()
- Stop playing.
- MPD:swap (song1, song2)
-
Swaps the positions of SONG1 and SONG2.
Parameters
- song1: Index of song in playlist, indexed from 0.
- song2:
- MPD:swapid (song1, song2)
-
Swaps the positions of SONG1 and SONG2 (both song ids).
Parameters
- song1:
- song2:
- MPD:tagtypes ()
- Shows a list of available song metadata.
- MPD:unpause ()
- Unpause.
- MPD:update (uri)
-
Updates the music database: find new files, remove deleted files, update modified files. URI is a particular directory or song/file to update. If you do not specify it, everything is updated. Prints "updating_db: JOBID" where JOBID is a positive number identifying the update job. You can read the current job id in the status response.
Parameters
- uri:
- MPD:urlhandlers ()
- Gets a list of available URL handlers.
- connect (host, port, reconnect)
-
Get an MPD server connection handle.
Parameters
- host: Default: "localhost"
- port: Default: 6600
- reconnect: Whether to automatically reconnect. Default is true.