Table of Contents
Table of Contents
If arguments contain spaces, they should be surrounded by double quotation marks.
COMMAND [ARG...]
All data between the client and the server is encoded in
UTF-8. (Note: In UTF-8 all standard ansi characters, 0-127 are
the same as a standard ansi encoding. Also, no ansi character
appears in any multi-byte characters. So, you can use
standard C functions like strlen, and
strcpy just fine with UTF-8 encoded
strings. For example: OK encoded in
UTF-8 is simply OK. For more
information on UTF=8:
http://www.cl.cam.ac.uk/~mgk25/unicode.html#utf-8)
A command returns OK on completion or ACK some error on failure. These denote the end of command execution.
To facilitate faster adding of files etc. you can pass a list of commands all at once using a command list. The command list beings with command_list_begin or command_list_ok_begin and ends with command_list_end.
It does not execute any commands until the list has ended. The return value is whatever the return for a list of commands is. On success for all commands, OK is returned. If a command fails, no more commands are executed and the appropriate ACK error is returned. If command_list_begin is used, list_OK is returned for each successful command executed in the command list.
Table of Contents
For manipulating playlists and playing, there are two sets of commands. One set uses the song id of a song in the playlist, while another set uses the playlist position of the song. The commands using song ids should be used instead of the commands that manipulate and control playback based on playlist position. Using song ids is a safer method when multiple clients are interacting with MPD.
clearerror
Clears the current error message in status (this is also accomplished by any command that starts playback).
currentsong
Displays the song info of the current song (same song that is identified in status).
idle [SUBSYSTEMS...]
Waits until there is a noteworthy change in one or more of MPD's subsystems. As soon as there is one, it lists all changed systems in a line in the format changed: SUBSYSTEM, where SUBSYSTEM is one of the following:
database: the song database has been updated
stored_playlist: a stored playlist has been modified, renamed, created or deleted
playlist: the current playlist has been modified
player: the player has been started, stopped or seeked
mixer: the volume has been changed
output: an audio output has been enabled or disabled
options: options like
repeat, random,
crossfade
While a client is waiting for idle results, the server disables timeouts, allowing a client to wait for events as long as mpd runs. The idle command can be canceled by sending the command noidle (no other commands are allowed). MPD will then leave idle mode and print results immediately; might be empty at this time.
If the optional SUBSYSTEMS argument is used,
MPD will only send notifications when something changed in
one of the specified subsytems.
status
Reports the current status of the player and the volume level.
volume:
0-100
repeat:
0 or 1
playlist:
31-bit unsigned integer, the playlist
version number
playlistlength:
integer, the length of the
playlist
state:
play, stop, or pause
song:
playlist song number of the current
song stopped on or playing
songid:
playlist songid of the current song
stopped on or playing
time:
total time elapsed (of current
playing/paused song)
bitrate:
instantaneous bitrate in
kbps
xfade:
crossfade in seconds
audio:
sampleRate:bits:channels
updatings_db:
job id
error:
if there is an error, returns message
here
stats
Displays statistics.
artists: number of artists
songs: number of albums
uptime: daemon uptime in seconds
db_playtime: sum of all song
times in the db
db_update: last db update in UNIX
time
playtime: time length of music played
crossfade {SECONDS}
Sets crossfading between songs.
random {STATE}
Sets random state to STATE,
STATE should be 0 or 1.
repeat {STATE}
Sets repeat state to STATE,
STATE should be 0 or 1.
setvol {VOL}
Sets volume to VOL, the range of
volume is 0-100.
volume {CHANGE}
Changes volume by amount CHANGE.
volume is deprecated, use setvol instead.
next
Plays next song in the playlist.
pause {PAUSE}
Toggles pause/resumes playing, PAUSE is 0 or 1.
The use of pause command w/o the PAUSE argument is deprecated.
play [SONGPOS]
Begins playing the playlist at song number
SONGPOS.
playid [SONGID]
Begins playing the playlist at song
SONGID.
previous
Plays previous song in the playlist.
seek {SONGPOS} {TIME}
Seeks to the position TIME (in
seconds) of entry SONGPOS in the
playlist.
seekid {SONGID} {TIME}
Seeks to the position TIME (in
seconds) of song SONGID.
stop
Stops playing.
add {URI}
Adds the file URI to the playlist
(directories add recursively). URI
can also be a single file.
addid {URI} [POSITION]
Adds a song to the playlist (non-recursive) and returns the song id.
URI is always a single file or
URL. POSITION is optional, a
negative number means it is relative to the currently
playing song in the playlist (if there is one).
For example:
addid "foo.mp3"
Id: 999
OK
clear
Clears the current playlist.
delete {SONGPOS}
Deletes a song from the playlist.
deleteid {SONGID}
Deletes the song SONGID from the
playlist
move {FROM} {TO}
Moves the song at FROM to
TO in the playlist.
moveid {FROM} {TO}
Moves the song with FROM to
TO (both song ids) in the
playlist. If TO is negative, it
is relative to the current song in the playlist (if
there is one).
playlist
Displays the current playlist.
Do not use this, instead use playlistinfo.
playlistfind {TAG} {NEEDLE}
Finds songs in the current playlist with strict matching.
playlistid {SONGID}
Displays a list of songs in the playlist.
SONGID is optional and specifies a
single song to display info for.
playlistinfo [SONGPOS]
Displays a list of songs in the playlist.
SONGPOS is optional and specifies
a single song to display info for.
playlistsearch {TAG} {NEEDLE}
Searches case-sensitively for partial matches in the current playlist.
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.
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.
shuffle
Shuffles the current playlist.
swap {SONG1} {SONG2}
Swaps the positions of SONG1 and
SONG2.
swapid {SONG1} {SONG2}
Swaps the positions of SONG1 and
SONG2 (both song ids).
listplaylist {NAME}
Lists the files in the playlist
NAME.m3u.
listplaylistinfo {NAME}
Lists songs in the playlist NAME.m3u.
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.
load {NAME}
Loads the playlist NAME.m3u from
the playlist directory.
playlistadd {NAME} {URI}
Adds URI to the playlist
NAME.m3u.
NAME.m3u will be created if it does
not exist.
playlistclear {NAME}
Clears the playlist NAME.m3u.
playlistdelete {NAME} {SONGPOS}
Deletes SONGPOS from the
playlist NAME.m3u.
playlistmove {NAME} {SONGID} {SONGPOS}
Moves SONGID in the playlist
NAME.m3u to the position
SONGPOS.
rename {NAME} {NEW_NAME}
Renames the playlist NAME.m3u to NEW_NAME.m3u.
rm {NAME}
Removes the playlist NAME.m3u from
the playlist directory.
save {NAME}
Saves the current playlist to
NAME.m3u in the playlist directory.
count {TAG} {NEEDLE}
Counts the number of songs and their total playtime in
the db matching TAG exactly.
find {TYPE} {WHAT}
Finds songs in the db that are exactly
WHAT. TYPE should
be album,
artist, or
title. WHAT
is what to find.
list {TYPE} [ARTIST]
Lists all tags of the specified type.
TYPE should be album or artist.
ARTIST is an optional parameter when
type is album, this specifies to list albums by an
artist.
listall [URI]
Lists all songs and directories in
URI.
listallinfo [URI]
Same as listall, except it also returns metadata info in the same format as lsinfo.
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.
search {TYPE} {WHAT}
Searches for any song that contains
WHAT. TYPE can be
title,
artist,
album or
filename. Search is not case
sensitive.
update [URI]
Updates the music database.
URI is a particular directory or
song/file to update.
Prints "updating_db: JOBID" where
JOBID is the job id requested for
your update, and is displayed in status, while the
requested update is happening.
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.