MusicPlayerDaemonCommands
From Music Player Daemon Community Wiki
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.
[edit] Admin Commands
[edit] disableoutput
- Usage
- disableoutput <int outputid>
- Purpose
- To turn an output off
- Returns
- OK if successful, ACK otherwise.
- See Also
- enableoutput
- outputs
[edit] enableoutput
- Usage
- enableoutput <int outputid>
- Purpose
- To turn an output on
- Returns
- OK if successful, ACK otherwise.
- See Also
- disableoutput
- outputs
[edit] kill
- 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.
[edit] update
- 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
- updating_db: <int job id>
- 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.
[edit] Informational Commands
[edit] status
- 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 song and songid lines are omitted if no appropriate value is available.
- See Also
- clearerror
- ↑ Values nextsong and nextsongid are available from mpd 0.15.
[edit] stats
- 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
[edit] outputs
- 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
[edit] commands
- 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
[edit] notcommands
- 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
[edit] tagtypes
- Usage
- tagtypes
- Purpose
- Get a list of available song metadata
- Returns
- List of metadata types.
- tagtype: <str name>
- See Also
- Scope specifiers
[edit] urlhandlers
- Usage
- urlhandlers
- Purpose
- Get a list of available URL handlers
- Returns
- List of URL handlers.
- handler: <str prefix>
[edit] Database Commands
[edit] find
- 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
[edit] list
- 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
[edit] listall
- 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
[edit] listallinfo
- 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
[edit] lsinfo
- 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
[edit] search
- Usage
- search <string type> <string what>
- Purpose
- Finds songs in the database with a case insensitive match to <string what>
- Arguments
- <string type>
- This is the type of metadata you wish to use to refine the search. Examples would be album, artist , title or any.
- Alternatively, a valid <string type> value is filename.
- <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
[edit] count
- 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
[edit] Playlist Commands
[edit] add
- Usage
- add <string>
- Purpose
- Add a single file from the database to the playlist. This command increments the playlist version by 1 for each song added to the playlist.
- Arguments
- * <string>
- 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.
[edit] addid
- 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.
[edit] clear
- Usage
- clear
- Purpose
- Clears the current playlist, increment the playlist version by 1.
[edit] currentsong
- 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.
[edit] delete
- Usage
- delete <int song>
- Purpose
- Delete <int song> from the playlist, increment the playlist version by 1.
- See Also
- deleteid
[edit] deleteid
- Usage
- deleteid <int songid>
- Purpose
- Delete song with <int songid> from playlist, increment the playlist version by 1.
- See Also
- delete
[edit] load
- Usage
- load <string name>
- Purpose
- Load the playlist <string_name> from the playlist directory, increment the playlist version by the number of songs added.
[edit] rename
- Usage
- rename <str name> <str new_name>
- Purpose
- Rename the playlist name to new_name.
- Returns
- OK on success ACK otherwise.
[edit] move
- 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.
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.
[edit] moveid
- 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.
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.
[edit] playlist
This is a deprecated command, is not recommended for use, and may be broken or removed at any time.
- Usage
- playlist
- Replacement Command
- playlistinfo
[edit] playlistinfo
- 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
[edit] How to get the available playlists
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:"
[edit] playlistid
- 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
[edit] plchanges
- 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.
[edit] plchangesposid
- 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.
[edit] rm
- 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.
[edit] save
- 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.
[edit] shuffle
- Usage
- shuffle
- Purpose
- Shuffles the current playlist, increments playlist version by 1.
[edit] swap
- 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
[edit] swapid
- 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
[edit] listplaylist
- 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
[edit] listplaylistinfo
- 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
[edit] playlistadd
- 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
[edit] playlistclear
- Usage
- playlistclear <str playlist name>
- Purpose
- Clear <playlist name>
- Returns
- OK on success, ACK otherwise
- See also
- clear
- Since
- 0.13.0
[edit] playlistdelete
- 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
[edit] playlistmove
- Usage
- playlistmove <str playlist name> <int song id> <int position>
- Purpose
- Move <song id> in <playlist name> to <position>
- Returns
- OK on success, ACK otherwise
- See also
- move
- Since
- 0.13.0
[edit] playlistfind
- 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
[edit] playlistsearch
- 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
[edit] Playback Commands
[edit] crossfade
- Usage
- crossfade <int seconds>
- Purpose
- Sets crossfading (mixing) between songs.
- Arguments
- <int seconds>
- Sets the number of seconds to mix the two songs.
[edit] next
- Usage
- next
- Purpose
- Plays next song in playlist.
[edit] pause
- Usage
- pause [<bool pause>]
- Purpose
- Toggle pause / resume playing.
- Arguments
- <bool pause>
- Should either be 1 (for paused) or 0 (for playing).
[edit] 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
[edit] playid
- 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
[edit] previous
- Usage
- previous
- Purpose
- Plays previous song in playlist.
[edit] random
- 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.
[edit] repeat
- 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.
[edit] seek
- 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
[edit] seekid
- 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
[edit] setvol
- Usage
- setvol <int vol>
- Purpose
- Set the volume.
- Arguments
- <int vol>
- The range of volume between 0 (minimum) and 100 (maximum)
[edit] stop
- Usage
- stop
- Purpose
- To halt playing.
[edit] volume
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
[edit] Miscellaneous Commands
[edit] clearerror
- Usage
- clearerror
- Purpose
- Clear the current error message in status (this is also accomplished by any command that starts playback).
[edit] close
- Usage
- close
- Purpose
- Close the connection with the MPD host.
- Returns
- Nothing.
[edit] password
- 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.
[edit] ping
- Usage
- ping
- Purpose
- To return OK (basically to show some life)
[edit] Scope specifiers
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.
