Note: the information in this wiki is outdated. Please read the protocol reference in the MPD tarball (doc/protocol.xml) or read the protocol documentation online.

Admin Commands Edit

disableoutputEdit

Usage: disableoutput <int outputid>
Purpose: To turn an output off
Returns: OK if successful, ACK otherwise.
See Also: enableoutput; outputs

enableoutputEdit

Usage: enableoutput <int outputid>
Purpose: To turn an output on
Returns: OK if successful, ACK otherwise.
See Also: disableoutput; outputs

killEdit

Usage: kill
Purpose: Stop MPD from running, in a safe way, write a state file if defined.
Returns: Returns nothing and exits immediately if user has permissions to the kill command, otherwise ACK.

updateEdit

Usage: update [<string path>]
Purpose: Scans the music directory as defined in the MPD configuration file's music_directory setting. Adds new files and their metadata (if any) to the MPD database and removes files and metadata from the database that are no longer in the directory.
Arguments path path is an optional argument that picks an exact directory or file to update, otherwise the root of the music_directory in your MPD configuration file is assumed.

Return

After initiating an update, the update is assigned an update job id and is displayed in status, each update incrementing the update job id by 1. To update a number of paths/songs at once, use command_list, it will be much more faster/efficient. Also, if you use a command_list for updating, only one update job id will be returned per sequence of updates.

updating_db: <int job id>

Informational Commands Edit

statusEdit

Usage

status

Purpose

To report the current status of MPD, and volume level.

Returns

List of statuses as <name>: <value> pairs, terminated with OK if successful; ACK otherwise. The status values returned include:

volume: (0-100)
repeat: (0 or 1)
random: (0 or 1)
playlist: (31-bit unsigned integer, the playlist version number)
playlistlength: (integer, the length of the playlist)
xfade: <int seconds> (crossfade in seconds)
state: ("play", "stop", or "pause")
song: (current song stopped on or playing, playlist song number)
songid: (current song stopped on or playing, playlist songid)
time: <int elapsed>:<time total> (of current playing/paused song)
bitrate: <int bitrate> (instantaneous bitrate in kbps)
audio: <int sampleRate>:<int bits>:<int channels>
updating_db: <int job id>
error: if there is an error, returns message here
nextsong: (next song, playlist song number)
nextsongid: (next song, playlist songid)^[1]

The song, songid, time, bitrate, audio, updating_db, error, nextsong and nextsongid lines are omitted if no appropriate value is available.

See Also

clearerror

↑ Values nextsong and nextsongid are available from mpd 0.15.

statsEdit

Usage

stats

Purpose

Displays statistics.

Returns

List of statistics as <name>: <value> pairs, terminated with OK if successful; ACK otherwise. The following statistics are returned:

artists: number of artists
albums: number of albums
songs: number of songs
uptime: daemon uptime (time since last startup) in seconds
playtime: time length of music played
db_playtime: sum of all song times in db
db_update: last db update in UNIX time

outputsEdit

Usage

outputs

Purpose

Show information about all outputs

Returns

List of outputs, described in three <name>: <value> pairs, terminated by OK. Each output is described with the following fields:

outputid: <int output> the output number
outputname: <str name> the name as defined in the MPD configuration file
outputenabled: <int enabled> 1 if enabled, 0 if disabled

See Also: disableoutput; enableoutput

commandsEdit

Usage: commands
Purpose: Show which commands the current user has access to.
Returns: List of available commands as command: <command name> pairs, terminated with OK if successful; ACK otherwise.
Example Output

command: add
command: addid
command: clear
.
.
.
OK

See Also: notcommands

notcommandsEdit

Usage: notcommands
Purpose: Show which commands the current user does not have access to.
Returns: List of unavailable commands as command: <command name> pairs, terminated with OK if successful; ACK otherwise.
Example Output

command: add
command: addid
command: clear
.
.
.
OK

See Also: commands

tagtypesEdit

Usage

tagtypes

Purpose

Get a list of available song metadata

Returns

List of metadata types.

tagtype: <str name>

See Also: Scope specifiers

urlhandlersEdit

Usage

urlhandlers

Purpose

Get a list of available URL handlers

Returns

List of URL handlers.

handler: <str prefix>

Database Commands Edit

findEdit

Usage: find <string type> <string what>
Purpose: Finds songs in the database with a case sensitive, exact match to <string what>
Arguments <string type> This is the value of the metadata being searched for. A few examples would be album, artist or title. Alternatively, a valid <string type> value is filename.

<string what>

This is the value that is being searched for in <string type>.
Example Output

find artist "Bob Marley"
file: albums/bob_marley/songs_of_freedom/disc_two/18.bob_marley_-_i_shot_the_sheriff_(live).flac
Time: 326
Album: Songs Of Freedom - Disc Two
Artist: Bob Marley
Title: I Shot The Sheriff (Live)
Track: 18
OK

to illustrate that it needs an exact match:

find artist "Bob Marle"
OK

Returns: Returns OK if the command is successful, even if nothing is found, ACK otherwise (i.e. no permission).
See Also: search; Scope specifiers

list Edit

Usage: list <metadata arg1> [<metadata arg2> <search term>]
Purpose: List all metadata of <metadata arg1>
Arguments <metadata arg1> This lists all metadata of <string type>

<metadata arg2>

An optional parameter, required if <search term> is present, this specifies to look for <metadata arg2> in the list of <metadata arg1>

<search term>

An optional parameter, required if <metadata arg2> is present, this specifies to list only matches with the list.
Example Output

list album artist Tool
Album: Lateralus
Album: ænema
OK

See Also: Scope specifiers

listall Edit

Usage: listall [<string path>]
Purpose: Lists all directories and filenames in <string path> recursively.
Arguments <string path> An optional path or directory to act as the root of the list.

Example Output

listall
[lots of output depending on how many files are in database]
file: vocal/onion_radio_news/the_onion_radio_news_-_bastards_pick_wrong_man.mp3
OK

listallinfo Edit

Usage: listallinfo [<string path>]
Purpose: Lists all information in database about all music files in <string path> recursively.
Arguments <string path> An optional path or directory to act as the root of the list.

Example Output

[Lots of output depending on how many files are in the database]
file: vocal/onion_radio_news/the_onion_radio_news_-_bastards_pick_wrong_man.mp3
Time: 36
Artist: Onion Radio News
Title: Bastards Pick Wrong Man to Mess With
Genre: Comedy
OK

lsinfoEdit

Usage: lsinfo [<string directory>]
Purpose: List contents of <string directory>, from the database.
Arguments <string directory> An optional path or directory to act as the root of the list.

Example Output

lsinfo
directory: albums
directory: individuals
directory: live
directory: vocal
OK

searchEdit

Usage

search <string type> <string what>

Purpose

Finds songs in the database with a case insensitive match to <string what>

Arguments

Alternatively, a valid <string type> value is filename.

<string type>

This is the type of metadata you wish to use to refine the search. Examples would be album, artist , title or any.

<string what>

This is the value that is being searched for in <string type>.
Example Output

search filename bastards_pick_wrong_man
file: vocal/onion_radio_news/the_onion_radio_news_-_bastards_pick_wrong_man.mp3
Time: 36
Artist: Onion Radio News 
Title: Bastards Pick Wrong Man to Mess With
Genre: Comedy
OK

Returns: Returns OK if the command successfully runs, even if no results exist, otherwise returns ACK.
See Also: find; Scope specifiers

countEdit

Usage: count <str scope specifier> <str query>
Purpose: Retrieve the number of songs and their total playtime in the database matching <query>
Returns: A list of <int songs>:<int playtime> pairs
See also: Scope specifiers

Playlist Commands Edit

addEdit

Usage: add <string>
Purpose: Add a single file from the database to the end of the playlist. This command increments the playlist version by 1 for each song added to the playlist.
Arguments: A single directory or file. If <string> is a directory or path all files in directory or path are added recursively. Adding all files in the database is as simple as add /.

<string>

Example Output

add new_sound/track08.cdda.flac
OK

Returns: Returns ACK if an incorrect file or more or less than 1 arguments are given. Returns OK otherwise.

addid Edit

Usage: addid <string>; addid <string> [<int pos>](Since SVN r7153)
Purpose: Like add but returns a playlistid.
Returns: Returns Id: (number) on success, ACK on failure.
Example

addid "Albums/2Pac/Greatest Hits/Disc 1/12.2Pac - Hit 'Em Up.flac"
Id: 219

Since SVN r7153, the optional pos argument allows the inserting of a string at that given position.

clearEdit

Usage: clear
Purpose: Clears the current playlist, increment the playlist version by 1.

currentsong Edit

Usage: currentsong
Purpose: Displays the metadata of the current song.
Example Output

currentsong
file: albums/bob_marley/songs_of_freedom/disc_four/12.bob_marley_-_could_you_be_loved_(12"_mix).flac
Time: 327
Album: Songs Of Freedom - Disc Four
Artist: Bob Marley
Title: Could You Be Loved (12" Mix)
Track: 12
Pos: 11
Id: 6601
OK

Returns: Returns OK whether playing or cleared.

deleteEdit

Usage: delete <int song>
Purpose: Delete <int song> from the playlist, increment the playlist version by 1.
See Also: deleteid

deleteidEdit

Usage: deleteid <int songid>
Purpose: Delete song with <int songid> from playlist, increment the playlist version by 1.
See Also: delete

loadEdit

Usage: load <string name>
Purpose: Load the playlist <string_name> from the playlist directory, increment the playlist version by the number of songs added.

renameEdit

Usage: rename <str name> <str new_name>
Purpose: Rename the playlist name to new_name.
Returns: OK on success ACK otherwise.

moveEdit

Usage: move <int from> <int to>
Purpose: Move song at <int from> to <int to> in the playlist, increment the playlist version by 1.
Arguments <int from> The playlist number of the song being moved.

<int to>

The playlist number where the song is being moved to.
See Also: moveid; swap; swapid

Since SVN r7152, the to argument may be a negative number, which is the offset of the song from the currently playing (or to-be-played) song. So -1 would mean the song would be moved to be the next song in the playlist.

moveidEdit

Usage: moveid <int songid from> <int to>
Purpose: Move song <int songid from> to <int to> in the playlist, increment the playlist version by 1.
Arguments <int songid from> The number of the songid of the song being moved.

<int to>

The playlist number the song at <int songid from> is being moved to.
See Also: move; swap; swapid

Since SVN r7152, the to argument may be a negative number, which is the offset of the song from the currently playing (or to-be-played) song. So -1 would mean the song would be moved to be the next song in the playlist.

playlistEdit

This is a deprecated command, is not recommended for use, and may be broken or removed at any time.

Usage: playlist
Replacement Command: playlistinfo

playlistinfoEdit

Usage: playlistinfo [<int song>]
Purpose: Display metadata for songs in the playlist.
Arguments <int song>: An optional number that specifies a single song to display information for.

See Also: playlistid

How to get the available playlists Edit

The available playlists can be retrieved with the lsinfo command. This command reports the available items like directories, files and playlists. Playlists are prefixed with a "playlist:", directories are prefixed with "directory:"

playlistid Edit

Usage: playlistid [<int songid>]
Purpose: Display metadata for songs in the playlist.
Arguments <int songid> Is optional and specifies a single songid to display information for.

See Also: playlistinfo

plchangesEdit

Usage: plchanges <playlist version>
Purpose: Displays changed songs currently in the playlist since <playlist version>.
Arguments <playlist version> The number for the version to display changed songs of the playlist.

Hint: To detect songs that were deleted at the end of the playlist, use playlistlength returned by status command.

plchangesposidEdit

Usage: plchangesposid <playlist version>
Purpose: Displays changed songs currently in the playlist since <playlist version>, but only return the position and the id.
Arguments <playlist version> The number for the version to display changed songs of the playlist.

Hint: To detect songs that were deleted at the end of the playlist, use playlistlength returned by status command.

rm Edit

Usage: rm <string name>
Purpose: Removes the <string playlist name> from the playlist directory.
Arguments <string playlist name> The name of the saved playlist to be removed from the playlist directory.

saveEdit

Usage: save <string playlist name>
Purpose: Saves the current playlist to <string playlist name> in the playlist directory.
Arguments <string playlist name> The name to give the saved playlist.

shuffleEdit

Usage: shuffle
Purpose: Shuffles the current playlist, increments playlist version by 1.

swapEdit

Usage: swap <int song1> <int song2>
Purpose: Swap positions of <int song1> and <int song2>, increments playlist version by 1.
See Also: move; moveid; swapid

swapidEdit

Usage: swapid <int songid1> <int songid2>
Purpose: Swap positions of songs by song id's of <songid1> and <songid2>, increments playlist version by 1.
See Also: move; moveid; swap

listplaylistEdit

Usage: listplaylist <str playlist name>
Purpose: List files in <playlist name>
Returns: A list of file:value pairs on success, ACK otherwise.
Since: 0.13.0

listplaylistinfoEdit

Usage: listplaylistinfo <str playlist name>
Purpose: List songs in <playlist name>
Returns: A list of metadata:value pairs on success, ACK otherwise.
Since: 0.12.0

playlistaddEdit

Usage: playlistadd <str playlist name> <str path>
Purpose: Add <path> to <playlist name>
Returns: OK on success, ACK otherwise
Note: <playlist name> will be created if it does not exist
See also: add
Since: 0.13.0

playlistclearEdit

Usage: playlistclear <str playlist name>
Purpose: Clear <playlist name>
Returns: OK on success, ACK otherwise
See also: clear
Since: 0.13.0

playlistdeleteEdit

Usage: playlistdelete <str playlist name> <int song id>
Purpose: Delete <song id> from <playlist name>
Returns: OK on success, ACK otherwise
See also: delete
Since: 0.13.0

playlistmoveEdit

Usage: playlistmove <str playlist name> <from position> <to position>
Purpose: Move <song id> in <playlist name> to <position>
Returns: OK on success, ACK otherwise
See also: move
Since: 0.13.0

playlistfindEdit

Usage: playlistfind <str scope specifier> <str query>
Purpose: Search for songs in the current playlist with strict matching
Returns: :A list of metadata:value pairs
See also: find; Scope specifiers
Since: 0.13.0

playlistsearchEdit

Usage: playlistsearch <str scope specifier> <str query>
Purpose: Search case-insensitively with partial matches for songs in the current playlist
Returns: A list of metadata:value pairs
See also: search; Scope specifiers
Since: 0.13.0

Playback Commands Edit

crossfadeEdit

Usage: crossfade <int seconds>
Purpose: Sets crossfading (mixing) between songs.
Arguments <int seconds> Sets the number of seconds to mix the two songs.

nextEdit

Usage: next
Purpose: Plays next song in playlist.

pauseEdit

Usage: pause [<bool pause>]
Purpose: Toggle pause / resume playing.
Arguments <bool pause> Should either be 1 (for paused) or 0 (for playing).: == play==
Usage: play [<int song>]
Purpose: Begin playing the playlist.
Arguments <int song> The song to begin playing the playlist at, it is optional, the default is -1.

See Also: playid

playidEdit

Usage: playid [<int songid>]
Purpose: Begin playing playlist.
Arguments <int songid> The songid to begin the playlist playing at, it is optional, the default is 0.

See Also: play

previousEdit

Usage: previous
Purpose: Plays previous song in playlist.

random Edit

Usage: random <int state>
Purpose: Sets 'random' mode, which plays the playlist in a random order.
Arguments <int state> Set random state to <int state>, 1 for random, 0 for ordered.

repeatEdit

Usage: repeat <int state>
Purpose: Repeat the playlist after all songs have been used.
Arguments <int state> Set repeat state to <int state>, 1 for repeat, 0 to stop after all songs are played.

seekEdit

Usage: seek <int song> <int time>
Purpose: Skip to a specified point in a song on the playlist.
Arguments <int song> The song to seek in.

<int time>

The position to seek to (in seconds).
See Also: seekid

seekidEdit

Usage: seekid <int songid> <int time>
Purpose: Skip to a specified point in a song on the playlist.
Arguments <int songid> The songid to seek in.

<int time>

The position to seek to (in seconds).
See Also: seek

setvolEdit

Usage: setvol <int vol>
Purpose: Set the volume.
Arguments <int vol> The range of volume between 0 (minimum) and 100 (maximum)

stopEdit

Usage: stop
Purpose: To halt playing.

volumeEdit

This is a deprecated command, is not recommended for use, and may be broken or removed at any time.

Usage: volume <int change>
Replacement Command: setvol

Miscellaneous Commands Edit

clearerrorEdit

Usage: clearerror
Purpose: Clear the current error message in status (this is also accomplished by any command that starts playback).

closeEdit

Usage: close
Purpose: Close the connection with the MPD host.
Returns: Nothing.

passwordEdit

Usage: password <string password>
Purpose: This is used for authentication with the server, this is enabled or disabled by the administrator in the MPD configuration file.
Arguments <string password> is the password to gain access to the commands setup by the MPD administrator.

Returns: OK if successful, ACK otherwise.

Warning:<string password> is simply the plaintext password.

pingEdit

Usage: ping
Purpose: To return OK (basically to show some life)

Scope specifiers Edit

Commands such as find, list and search require arguments that modify the scope of their actions. Most of the MPD "scope specifiers" are derived from the ID3 Tags used in MP3 files (see http://www.id3.org/). As of this writing, MPD groks the 11 tags defined in "tags.h". They are:

artist - name of the Artist
album - name of the Album from which the song is taken
title - title of the song
track - track number on the album
name - name of an audio stream
genre - keywords that place the song in one or more aesthetic baskets
date - date the song was recorded (not when it was ripped ;-)
composer - who wrote the song
performer - principal soloist or performer
comment - typically something attached by the ripper
disc - disc number (in a set). Derived from the ID3 TPOS tag.

The MPD concept of a tag is not confined to MP3 encoded audio. Vorbis bitstreams, for example, may be prefaced with a comment header from which tag information can be extracted. Ultimately though, the encoder decides what, if any, scope specifying metadata is available.

In addition to the above tags there are two special scope specifiers: filename which matches a song by the name of the file it's stored in and any which is a special token that literally means any available scope.

[0] Values nextsong and nextsongid are available from mpd 0.15.

[1]

Wikia

Contents

Admin Commands Edit

disableoutputEdit

enableoutputEdit

killEdit

updateEdit

Informational Commands Edit

statusEdit

statsEdit

outputsEdit

commandsEdit

notcommandsEdit

tagtypesEdit

urlhandlersEdit

Database Commands Edit

findEdit

list Edit

listall Edit

listallinfo Edit

lsinfoEdit

searchEdit

countEdit

Playlist Commands Edit

addEdit

addid Edit

clearEdit

currentsong Edit

deleteEdit

deleteidEdit

loadEdit

renameEdit

moveEdit

moveidEdit

playlistEdit

playlistinfoEdit

How to get the available playlists Edit

playlistid Edit

plchangesEdit

plchangesposidEdit

rm Edit

saveEdit

shuffleEdit

swapEdit

swapidEdit

listplaylistEdit

listplaylistinfoEdit

playlistaddEdit

playlistclearEdit

playlistdeleteEdit

playlistmoveEdit

playlistfindEdit

playlistsearchEdit

Playback Commands Edit

crossfadeEdit

nextEdit

pauseEdit

playidEdit

previousEdit

random Edit

repeatEdit

seekEdit

seekidEdit

setvolEdit

stopEdit

volumeEdit

Miscellaneous Commands Edit

clearerrorEdit

closeEdit

passwordEdit

pingEdit

Scope specifiers Edit

Photos

Recent Wiki Activity