Wikia

Music Player Daemon Community Wiki

MusicPlayerDaemonCommands

Talk0
542pages on
this 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.

Contents

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
  1. 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.

Advertisement | Your ad here

Photos

Add a Photo
136photos on this wiki
See all photos >

Recent Wiki Activity

See more >

Around Wikia's network

Random Wiki