MusicPlayerDaemonCommands
From Music Player Daemon Community Wiki
[edit] Admin Commands
[edit] disableoutput
Usage:
- disableoutput <int outputid>
Purpose:
- To turn an output off
Returns:
- OK if successful, ACK otherwise.
See Also:
[edit] enableoutput
Usage:
- enableoutput <int outputid>
Purpose:
- To turn an output on
Returns:
- OK if successful, ACK otherwise.
See Also:
[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
The song, songid, time, bitrate, audio, updating_db and error lines are omitted if no appropriate value is available.
See Also:
[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> 0 if enabled, 1 if disabled
See Also:
[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:
[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:
[edit] tagtypes
Usage:
- tagtypes
Purpose:
- Get a list of available song metadata
Returns:
- List of metadata types.
- tagtype: <str name>
See Also:
[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:
[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:
[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:
[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:
[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 /.
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:
[edit] deleteid
Usage:
- deleteid <int songid>
Purpose:
- Delete song with <int songid> from playlist, increment the playlist version by 1.
See Also:
[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.
See Also:
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.
See Also:
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:
[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:
[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:
[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:
[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:
[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:
Since: 0.13.0
[edit] playlistclear
Usage:
- playlistclear <str playlist name>
Purpose:
- Clear <playlist name>
Returns:
- OK on success, ACK otherwise
See also:
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:
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:
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:
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:
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 0.
See Also:
[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:
[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:
[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:
[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:
[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.
