MusicPlayerDaemonProtocolOutline

From Music Player Daemon Community Wiki

[edit] Protocol overview

The MPD command protocol exchanges line-based text records between client and server over TCP. By default, the server listens for TCP connections on port 6600 of any interface that it is bound to. The server may be configured to use specific interfaces and/or a different port at invocation time.

All data to be sent between the client and server must be encoded in UTF-8.

The standard ansi characters, 0-127, are interpreted identically in UTF-8 so you can use standard C functions like strlen(3C) and strcpy(3C) to manipulate MPD data. For more information on UTF-8 visit http://www.utf-8.com/.

When an MPD client first establishes a connection to the server, the server responds with:

OK MPD version\n

where "version" is a version identifier such as 0.12.2. This version identifier is the version of the protocol spoken, not the real version of the daemon. (There is no way to retrieve this real version identifier from the connection.)

From this point on the client and the server conduct a conversation until the client closes the connection. The conversation flow is always initiated by the client. The client transmits a command sequence, terminated by a newline. The server will respond with one or more lines, the last of which will be a completion code.

Some commands, such as "status", stand alone. Others require one or more arguments that either specify or modify the behaviour of the command. Argument strings are separated from the command and any other arguments by linear white-space (' ' or '\t'). If a single argument contains white space, the whole argument string must be enclosed in double quotation marks ('"'). e.g. search artist "art ensemble of chicago".

This Wiki contains complete list of all the MPD Commands. The entry for each command describes the number, type and meaning of any arguments that the command might take.

[edit] Server responses

Each server response ends with a completion code. There are two codes: OK and ACK. The latter indicates that an error has occurred. The nature of the error can be gleaned from the information that follows the "ACK".

ACK lines are of the form:

ACK [error@command_listNum] {current_command} message_text\n

These responses are generated by a call to main.c:commandError(). They contain four separate terms. Let's look at each of them:

error 

this is the numeric value of one of the ACK_ERROR constants defined in "ack.h".

command_listNum 

is the offset of the command that caused the error in a Command List. An error will always cause a command list to terminate at the command that causes the error.

current_command 

is the name of the command, in a Command List, that was executing when the error occurred.

message_text 

is some (hopefully) informative text that describes the nature of the error.

An example might help. Consider the following sequence sent from the client to the server.

	command_list_begin
	volume 86
	play 10240
	status
	command_list_end

The server responds with:

	ACK [50@1] {play} song doesn't exist: "10240"

This tells us that the play command, which was the second in the list (the first or only command is numbered 0), failed with error 50. The number 50 translates to ACK_ERROR_NO_EXIST--the song doesn't exist. This is reiterated by the message text which also tells us which song doesn't exist.