1 <?xml version='1.0' encoding="utf-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "docbook/dtd/xml/4.2/docbookx.dtd">
5 <title>The Music Player Daemon protocol</title>
8 <title>General protocol syntax</title>
11 <title>Requests</title>
14 If arguments contain spaces, they should be surrounded by double quotation
19 <command>COMMAND</command>
20 <arg rep="repeat"><replaceable>ARG</replaceable></arg>
24 All data between the client and the server is encoded in
25 UTF-8. (Note: In UTF-8 all standard ansi characters, 0-127 are
26 the same as a standard ansi encoding. Also, no ansi character
27 appears in any multi-byte characters. So, you can use
28 standard C functions like <function>strlen</function>, and
29 <function>strcpy</function> just fine with UTF-8 encoded
30 strings. For example: <returnvalue>OK</returnvalue> encoded in
31 UTF-8 is simply <returnvalue>OK</returnvalue>. For more
33 http://www.cl.cam.ac.uk/~mgk25/unicode.html#utf-8)
38 <title>Responses</title>
41 A command returns <returnvalue>OK</returnvalue> on completion
42 or <returnvalue>ACK some error</returnvalue> on failure.
43 These denote the end of command execution.
48 <title>Command lists</title>
51 To facilitate faster adding of files etc. you can pass a list
52 of commands all at once using a command list. The command
53 list begins with <command>command_list_begin</command> or
54 <command>command_list_ok_begin</command> and ends with
55 <command>command_list_end</command>.
59 It does not execute any commands until the list has ended.
60 The return value is whatever the return for a list of commands
61 is. On success for all commands,
62 <returnvalue>OK</returnvalue> is returned. If a command
63 fails, no more commands are executed and the appropriate
64 <returnvalue>ACK</returnvalue> error is returned. If
65 <command>command_list_ok_begin</command> is used,
66 <returnvalue>list_OK</returnvalue> is returned for each
67 successful command executed in the command list.
75 Some commands (e.g. <link
76 linkend="command_delete"><command>delete</command></link>)
77 allow specifying a range in the form
78 <parameter>START:END</parameter> (the <varname>END</varname>
79 item is not included in the range, similar to ranges in the
80 Python programming language). If <varname>END</varname> is
81 omitted, then the maximum possible value is assumed.
87 <title>Command reference</title>
91 For manipulating playlists and playing, there are two sets of
92 commands. One set uses the song id of a song in the playlist,
93 while another set uses the playlist position of the song. The
94 commands using song ids should be used instead of the commands
95 that manipulate and control playback based on playlist
96 position. Using song ids is a safer method when multiple
97 clients are interacting with MPD.
102 <title>Querying MPD's status</title>
105 <varlistentry id="command_clearerror">
108 <command>clearerror</command>
113 Clears the current error message in status (this is also
114 accomplished by any command that starts playback).
118 <varlistentry id="command_currentsong">
121 <command>currentsong</command>
126 Displays the song info of the current song (same song that
127 is identified in status).
131 <varlistentry id="command_idle">
134 <command>idle</command>
135 <arg choice="opt" rep="repeat"><replaceable>SUBSYSTEMS</replaceable></arg>
140 <footnote id="since_0_14"><simpara>Introduced with MPD 0.14</simpara></footnote>
141 Waits until there is a noteworthy change in one or more
142 of MPD's subsystems. As soon as there is one, it lists
143 all changed systems in a line in the format
144 <returnvalue>changed: SUBSYSTEM</returnvalue>, where
145 SUBSYSTEM is one of the following:
150 <returnvalue>database</returnvalue>: the song database
151 has been modified after <command>update</command>.
156 <returnvalue>update</returnvalue>: a database update
157 has started or finished. If the database was
158 modified during the update, the
159 <returnvalue>database</returnvalue> event is also
165 <returnvalue>stored_playlist</returnvalue>: a stored
166 playlist has been modified, renamed, created or
172 <returnvalue>playlist</returnvalue>: the current
173 playlist has been modified
178 <returnvalue>player</returnvalue>: the player has been
179 started, stopped or seeked
184 <returnvalue>mixer</returnvalue>: the volume has been
190 <returnvalue>output</returnvalue>: an audio output has
191 been enabled or disabled
196 <returnvalue>options</returnvalue>: options like
197 <option>repeat</option>, <option>random</option>,
198 <option>crossfade</option>, replay gain
203 While a client is waiting for <command>idle</command>
204 results, the server disables timeouts, allowing a client
205 to wait for events as long as mpd runs. The
206 <command>idle</command> command can be canceled by
207 sending the command <command>noidle</command> (no other
208 commands are allowed). MPD will then leave
209 <command>idle</command> mode and print results
210 immediately; might be empty at this time.
213 If the optional <varname>SUBSYSTEMS</varname> argument is used,
214 MPD will only send notifications when something changed in
215 one of the specified subsytems.
219 <varlistentry id="command_status">
222 <command>status</command>
227 Reports the current status of the player and the volume
233 <varname>volume</varname>:
234 <returnvalue>0-100</returnvalue>
239 <varname>repeat</varname>:
240 <returnvalue>0 or 1</returnvalue>
245 <varname>single</varname>:
246 <footnote id="since_0_15"><simpara>Introduced with MPD 0.15</simpara></footnote>
247 <returnvalue>0 or 1</returnvalue>
252 <varname>consume</varname>:
253 <footnoteref linkend="since_0_15"/>
254 <returnvalue>0 or 1</returnvalue>
259 <varname>playlist</varname>:
260 <returnvalue>31-bit unsigned integer, the playlist
261 version number</returnvalue>
266 <varname>playlistlength</varname>:
267 <returnvalue>integer, the length of the
268 playlist</returnvalue>
273 <varname>state</varname>:
274 <returnvalue>play, stop, or pause</returnvalue>
279 <varname>song</varname>:
280 <returnvalue> playlist song number of the current
281 song stopped on or playing
287 <varname>songid</varname>:
288 <returnvalue>playlist songid of the current song
289 stopped on or playing
295 <varname>nextsong</varname>:
296 <footnoteref linkend="since_0_15"/>
297 <returnvalue> playlist song number of the next
304 <varname>nextsongid</varname>:
305 <footnoteref linkend="since_0_15"/>
306 <returnvalue>playlist songid of the next song
313 <varname>time</varname>:
314 <returnvalue>total time elapsed (of current
315 playing/paused song)</returnvalue>
320 <varname>elapsed</varname>:
321 <footnote id="since_0_16"><simpara>Introduced with MPD 0.16</simpara></footnote>
323 Total time elapsed within the current song, but
324 with higher resolution.
330 <varname>bitrate</varname>:
331 <returnvalue>instantaneous bitrate in
337 <varname>xfade</varname>:
338 <returnvalue>crossfade in seconds</returnvalue>
343 <varname>mixrampdb</varname>:
344 <returnvalue>mixramp threshold in dB</returnvalue>
349 <varname>mixrampdelay</varname>:
350 <returnvalue>mixrampdelay in seconds</returnvalue>
355 <varname>audio</varname>:
356 <returnvalue>sampleRate:bits:channels</returnvalue>
361 <varname>updatings_db</varname>:
362 <returnvalue>job id</returnvalue>
367 <varname>error</varname>:
368 <returnvalue>if there is an error, returns message
375 <varlistentry id="command_stats">
378 <command>stats</command>
388 <varname>artists</varname>: number of artists
393 <varname>songs</varname>: number of albums
398 <varname>uptime</varname>: daemon uptime in seconds
403 <varname>db_playtime</varname>: sum of all song
409 <varname>db_update</varname>: last db update in UNIX
415 <varname>playtime</varname>: time length of music played
425 <title>Playback options</title>
428 <varlistentry id="command_consume">
431 <command>consume</command>
432 <arg choice="req"><replaceable>STATE</replaceable></arg>
437 <footnoteref linkend="since_0_15"/>
438 Sets consume state to <varname>STATE</varname>,
439 <varname>STATE</varname> should be 0 or 1.
440 When consume is activated, each song played is removed from playlist.
444 <varlistentry id="command_crossfade">
447 <command>crossfade</command>
448 <arg choice="req"><replaceable>SECONDS</replaceable></arg>
453 Sets crossfading between songs.
457 <varlistentry id="command_mixrampdb">
460 <command>mixrampdb</command>
461 <arg choice="req"><replaceable>deciBels</replaceable></arg>
466 Sets the threshold at which songs will be overlapped. Like crossfading but doesn't fade the track volume, just overlaps. The songs need to have MixRamp tags added by an external tool. 0dB is the normalized maximum volume so use negative values, I prefer -17dB. In the absence of mixramp tags crossfading will be used. See http://sourceforge.net/projects/mixramp
470 <varlistentry id="command_mixrampdelay">
473 <command>mixrampdelay</command>
474 <arg choice="req"><replaceable>SECONDS</replaceable></arg>
479 Additional time subtracted from the overlap calculated by mixrampdb. A value of "nan" disables MixRamp overlapping and falls back to crossfading.
483 <varlistentry id="command_random">
486 <command>random</command>
487 <arg choice="req"><replaceable>STATE</replaceable></arg>
492 Sets random state to <varname>STATE</varname>,
493 <varname>STATE</varname> should be 0 or 1.
497 <varlistentry id="command_repeat">
500 <command>repeat</command>
501 <arg choice="req"><replaceable>STATE</replaceable></arg>
506 Sets repeat state to <varname>STATE</varname>,
507 <varname>STATE</varname> should be 0 or 1.
511 <varlistentry id="command_setvol">
514 <command>setvol</command>
515 <arg choice="req"><replaceable>VOL</replaceable></arg>
520 Sets volume to <varname>VOL</varname>, the range of
525 <varlistentry id="command_single">
528 <command>single</command>
529 <arg choice="req"><replaceable>STATE</replaceable></arg>
534 <footnoteref linkend="since_0_15"/>
535 Sets single state to <varname>STATE</varname>,
536 <varname>STATE</varname> should be 0 or 1.
537 When single is activated, playback is stopped after current song, or
538 song is repeated if the 'repeat' mode is enabled.
542 <varlistentry id="command_replay_gain_mode">
545 <command>replay_gain_mode</command>
546 <arg choice="req"><replaceable>MODE</replaceable></arg>
551 Sets the replay gain mode. One of
552 <parameter>off</parameter>,
553 <parameter>track</parameter>,
554 <parameter>album</parameter>.
557 Changing the mode during playback may take several
558 seconds, because the new settings does not affect the
562 This command triggers the
563 <returnvalue>options</returnvalue> idle event.
567 <varlistentry id="command_replay_gain_status">
570 <command>replay_gain_status</command>
575 Prints replay gain options. Currently, only the
576 variable <varname>replay_gain_mode</varname> is
585 <title>Controlling playback</title>
588 <varlistentry id="command_next">
591 <command>next</command>
596 Plays next song in the playlist.
600 <varlistentry id="command_pause">
603 <command>pause</command>
604 <arg choice="req"><replaceable>PAUSE</replaceable></arg>
609 Toggles pause/resumes playing, <varname>PAUSE</varname> is 0 or 1.
613 The use of pause command w/o the PAUSE argument is
619 <varlistentry id="command_play">
622 <command>play</command>
623 <arg><replaceable>SONGPOS</replaceable></arg>
628 Begins playing the playlist at song number
629 <varname>SONGPOS</varname>.
633 <varlistentry id="command_playid">
636 <command>playid</command>
637 <arg><replaceable>SONGID</replaceable></arg>
642 Begins playing the playlist at song
643 <varname>SONGID</varname>.
647 <varlistentry id="command_previous">
650 <command>previous</command>
655 Plays previous song in the playlist.
660 <varlistentry id="command_seek">
663 <command>seek</command>
664 <arg choice="req"><replaceable>SONGPOS</replaceable></arg>
665 <arg choice="req"><replaceable>TIME</replaceable></arg>
670 Seeks to the position <varname>TIME</varname> (in
671 seconds) of entry <varname>SONGPOS</varname> in the
676 <varlistentry id="command_seekid">
679 <command>seekid</command>
680 <arg choice="req"><replaceable>SONGID</replaceable></arg>
681 <arg choice="req"><replaceable>TIME</replaceable></arg>
686 Seeks to the position <varname>TIME</varname> (in
687 seconds) of song <varname>SONGID</varname>.
691 <varlistentry id="command_stop">
694 <command>stop</command>
707 <title>The current playlist</title>
710 <varlistentry id="command_add">
713 <command>add</command>
714 <arg choice="req"><replaceable>URI</replaceable></arg>
719 Adds the file <varname>URI</varname> to the playlist
720 (directories add recursively). <varname>URI</varname>
721 can also be a single file.
725 <varlistentry id="command_addid">
728 <command>addid</command>
729 <arg choice="req"><replaceable>URI</replaceable></arg>
730 <arg><replaceable>POSITION</replaceable></arg>
735 Adds a song to the playlist (non-recursive) and returns the song id.
738 <varname>URI</varname> is always a single file or
748 <varlistentry id="command_clear">
751 <command>clear</command>
756 Clears the current playlist.
760 <varlistentry id="command_delete">
763 <command>delete</command>
765 <arg choice="req"><replaceable>POS</replaceable></arg>
766 <arg choice="req"><replaceable>START:END</replaceable></arg>
772 Deletes a song from the playlist.
776 <varlistentry id="command_deleteid">
779 <command>deleteid</command>
780 <arg choice="req"><replaceable>SONGID</replaceable></arg>
785 Deletes the song <varname>SONGID</varname> from the
790 <varlistentry id="command_move">
793 <command>move</command>
795 <arg choice="req"><replaceable>FROM</replaceable></arg>
796 <arg choice="req"><replaceable>START:END</replaceable></arg>
798 <arg choice="req"><replaceable>TO</replaceable></arg>
803 Moves the song at <varname>FROM</varname> or range of songs
804 at <varname>START:END</varname> to <varname>TO</varname>
806 <footnote id="range_since_0_15">
807 <simpara>Ranges are supported since MPD 0.15</simpara>
812 <varlistentry id="command_moveid">
815 <command>moveid</command>
816 <arg choice="req"><replaceable>FROM</replaceable></arg>
817 <arg choice="req"><replaceable>TO</replaceable></arg>
822 Moves the song with <varname>FROM</varname> (songid) to
823 <varname>TO</varname> (playlist index) in the
824 playlist. If <varname>TO</varname> is negative, it
825 is relative to the current song in the playlist (if
830 <varlistentry id="command_playlist">
833 <command>playlist</command>
838 Displays the current playlist.
842 Do not use this, instead use <command>playlistinfo</command>.
847 <varlistentry id="command_playlistfind">
850 <command>playlistfind</command>
851 <arg choice="req"><replaceable>TAG</replaceable></arg>
852 <arg choice="req"><replaceable>NEEDLE</replaceable></arg>
857 Finds songs in the current playlist with strict
862 <varlistentry id="command_playlistid">
865 <command>playlistid</command>
866 <arg choice="req"><replaceable>SONGID</replaceable></arg>
871 Displays a list of songs in the playlist.
872 <varname>SONGID</varname> is optional and specifies a
873 single song to display info for.
877 <varlistentry id="command_playlistinfo">
880 <command>playlistinfo</command>
882 <arg><replaceable>SONGPOS</replaceable></arg>
883 <arg><replaceable>START:END</replaceable></arg>
889 Displays a list of all songs in the playlist, or if the optional
890 argument is given, displays information only for the song
891 <varname>SONGPOS</varname> or the range of songs
892 <varname>START:END</varname>
893 <footnoteref linkend="range_since_0_15"/>
897 <varlistentry id="command_playlistsearch">
900 <command>playlistsearch</command>
901 <arg choice="req"><replaceable>TAG</replaceable></arg>
902 <arg choice="req"><replaceable>NEEDLE</replaceable></arg>
907 Searches case-sensitively for partial matches in the
912 <varlistentry id="command_plchanges">
915 <command>plchanges</command>
916 <arg choice="req"><replaceable>VERSION</replaceable></arg>
921 Displays changed songs currently in the playlist since
922 <varname>VERSION</varname>.
925 To detect songs that were deleted at the end of the
926 playlist, use playlistlength returned by status command.
930 <varlistentry id="command_plchangesposid">
933 <command>plchangesposid</command>
934 <arg choice="req"><replaceable>VERSION</replaceable></arg>
939 Displays changed songs currently in the playlist since
940 <varname>VERSION</varname>. This function only
941 returns the position and the id of the changed song, not
942 the complete metadata. This is more bandwidth efficient.
945 To detect songs that were deleted at the end of the
946 playlist, use playlistlength returned by status command.
950 <varlistentry id="command_shuffle">
953 <command>shuffle</command>
954 <arg><replaceable>START:END</replaceable></arg>
959 Shuffles the current playlist.
960 <varname>START:END</varname> is optional and specifies
965 <varlistentry id="command_swap">
968 <command>swap</command>
969 <arg choice="req"><replaceable>SONG1</replaceable></arg>
970 <arg choice="req"><replaceable>SONG2</replaceable></arg>
975 Swaps the positions of <varname>SONG1</varname> and
976 <varname>SONG2</varname>.
980 <varlistentry id="command_swapid">
983 <command>swapid</command>
984 <arg choice="req"><replaceable>SONG1</replaceable></arg>
985 <arg choice="req"><replaceable>SONG2</replaceable></arg>
990 Swaps the positions of <varname>SONG1</varname> and
991 <varname>SONG2</varname> (both song ids).
999 <title>Stored playlists</title>
1002 Playlists are stored inside the configured playlist directory.
1003 They are addressed with their file name (without the directory
1004 and without the <filename>.m3u</filename> suffix).
1008 Some of the commands described in this section can be used to
1009 run playlist plugins instead of the hard-coded simple
1010 <filename>m3u</filename> parser. They can access playlists in
1011 the music directory (relative path including the suffix) or
1012 remote playlists (absolute URI with a supported scheme).
1016 <varlistentry id="command_listplaylist">
1019 <command>listplaylist</command>
1020 <arg choice="req"><replaceable>NAME</replaceable></arg>
1025 Lists the songs in the playlist. Playlist plugins are
1030 <varlistentry id="command_listplaylistinfo">
1033 <command>listplaylistinfo</command>
1034 <arg choice="req"><replaceable>NAME</replaceable></arg>
1039 Lists the songs with metadata in the playlist. Playlist
1040 plugins are supported.
1044 <varlistentry id="command_listplaylists">
1047 <command>listplaylists</command>
1052 Prints a list of the playlist directory.
1055 After each playlist name the server sends its last
1056 modification time as attribute "Last-Modified" in ISO
1057 8601 format. To avoid problems due to clock differences
1058 between clients and the server, clients should not
1059 compare this value with their local clock.
1063 <varlistentry id="command_load">
1066 <command>load</command>
1067 <arg choice="req"><replaceable>NAME</replaceable></arg>
1072 Loads the playlist into the current queue. Playlist
1073 plugins are supported.
1077 <varlistentry id="command_playlistadd">
1080 <command>playlistadd</command>
1081 <arg choice="req"><replaceable>NAME</replaceable></arg>
1082 <arg choice="req"><replaceable>URI</replaceable></arg>
1087 Adds <varname>URI</varname> to the playlist
1088 <filename>NAME.m3u</filename>.
1091 <filename>NAME.m3u</filename> will be created if it does
1096 <varlistentry id="command_playlistclear">
1099 <command>playlistclear</command>
1100 <arg choice="req"><replaceable>NAME</replaceable></arg>
1105 Clears the playlist <filename>NAME.m3u</filename>.
1109 <varlistentry id="command_playlistdelete">
1112 <command>playlistdelete</command>
1113 <arg choice="req"><replaceable>NAME</replaceable></arg>
1114 <arg choice="req"><replaceable>SONGPOS</replaceable></arg>
1119 Deletes <varname>SONGPOS</varname> from the
1120 playlist <filename>NAME.m3u</filename>.
1124 <varlistentry id="command_playlistmove">
1127 <command>playlistmove</command>
1128 <arg choice="req"><replaceable>NAME</replaceable></arg>
1129 <arg choice="req"><replaceable>SONGID</replaceable></arg>
1130 <arg choice="req"><replaceable>SONGPOS</replaceable></arg>
1135 Moves <varname>SONGID</varname> in the playlist
1136 <filename>NAME.m3u</filename> to the position
1137 <varname>SONGPOS</varname>.
1141 <varlistentry id="command_rename">
1144 <command>rename</command>
1145 <arg choice="req"><replaceable>NAME</replaceable></arg>
1146 <arg choice="req"><replaceable>NEW_NAME</replaceable></arg>
1151 Renames the playlist <filename>NAME.m3u</filename> to <filename>NEW_NAME.m3u</filename>.
1155 <varlistentry id="command_rm">
1158 <command>rm</command>
1159 <arg choice="req"><replaceable>NAME</replaceable></arg>
1164 Removes the playlist <filename>NAME.m3u</filename> from
1165 the playlist directory.
1169 <varlistentry id="command_save">
1172 <command>save</command>
1173 <arg choice="req"><replaceable>NAME</replaceable></arg>
1178 Saves the current playlist to
1179 <filename>NAME.m3u</filename> in the playlist directory.
1187 <title>The music database</title>
1190 <varlistentry id="command_count">
1193 <command>count</command>
1194 <arg choice="req"><replaceable>TAG</replaceable></arg>
1195 <arg choice="req"><replaceable>NEEDLE</replaceable></arg>
1200 Counts the number of songs and their total playtime in
1201 the db matching <varname>TAG</varname> exactly.
1205 <varlistentry id="command_find">
1208 <command>find</command>
1209 <arg choice="req"><replaceable>TYPE</replaceable></arg>
1210 <arg choice="req"><replaceable>WHAT</replaceable></arg>
1215 Finds songs in the db that are exactly
1216 <varname>WHAT</varname>. <varname>TYPE</varname> should
1217 be <parameter>album</parameter>,
1218 <parameter>artist</parameter>, or
1219 <parameter>title</parameter>. <varname>WHAT</varname>
1224 <varlistentry id="command_findadd">
1227 <command>findadd</command>
1228 <arg choice="req"><replaceable>TYPE</replaceable></arg>
1229 <arg choice="req"><replaceable>WHAT</replaceable></arg>
1234 Finds songs in the db that are exactly
1235 <varname>WHAT</varname> and adds them to current playlist.
1236 <varname>TYPE</varname> can be any tag supported by MPD.
1237 <varname>WHAT</varname> is what to find.
1241 <varlistentry id="command_list">
1244 <command>list</command>
1245 <arg choice="req"><replaceable>TYPE</replaceable></arg>
1246 <arg><replaceable>ARTIST</replaceable></arg>
1251 Lists all tags of the specified type.
1252 <varname>TYPE</varname> should be album or artist.
1255 <varname>ARTIST</varname> is an optional parameter when
1256 type is album, this specifies to list albums by an
1261 <varlistentry id="command_listall">
1264 <command>listall</command>
1265 <arg><replaceable>URI</replaceable></arg>
1270 Lists all songs and directories in
1271 <varname>URI</varname>.
1275 <varlistentry id="command_listallinfo">
1278 <command>listallinfo</command>
1279 <arg><replaceable>URI</replaceable></arg>
1284 Same as <command>listall</command>, except it also
1285 returns metadata info in the same format as
1286 <command>lsinfo</command>.
1290 <varlistentry id="command_lsinfo">
1293 <command>lsinfo</command>
1294 <arg><replaceable>URI</replaceable></arg>
1299 Lists the contents of the directory
1300 <varname>URI</varname>.
1303 When listing the root directory, this currently returns
1304 the list of stored playlists. This behavior is
1305 deprecated; use "listplaylists" instead.
1309 <varlistentry id="command_search">
1312 <command>search</command>
1313 <arg choice="req"><replaceable>TYPE</replaceable></arg>
1314 <arg choice="req"><replaceable>WHAT</replaceable></arg>
1319 Searches for any song that contains
1320 <varname>WHAT</varname>. <varname>TYPE</varname> can be
1321 <parameter>title</parameter>,
1322 <parameter>artist</parameter>,
1323 <parameter>album</parameter> or
1324 <parameter>filename</parameter>. Search is not case
1329 <varlistentry id="command_update">
1332 <command>update</command>
1333 <arg choice="opt"><replaceable>URI</replaceable></arg>
1338 Updates the music database: find new files, remove
1339 deleted files, update modified files.
1342 <varname>URI</varname> is a particular directory or
1343 song/file to update. If you do not specify it,
1344 everything is updated.
1347 Prints "updating_db: JOBID" where
1348 <varname>JOBID</varname> is a positive number
1349 identifying the update job. You can read the current
1350 job id in the <command>status</command> response.
1354 <varlistentry id="command_rescan">
1357 <command>rescan</command>
1358 <arg choice="opt"><replaceable>URI</replaceable></arg>
1363 Same as <command>update</command>, but also rescans
1372 <title>Stickers</title>
1375 "Stickers"<footnoteref linkend="since_0_15"/> are pieces of
1376 information attached to existing MPD objects (e.g. song files,
1377 directories, albums). Clients can create arbitrary name/value
1378 pairs. MPD itself does not assume any special meaning in
1383 The goal is to allow clients to share additional (possibly
1384 dynamic) information about songs, which is neither stored on
1385 the client (not available to other clients), nor stored in the
1386 song files (MPD has no write access).
1390 Client developers should create a standard for common sticker
1391 names, to ensure interoperability.
1395 Objects which may have stickers are addressed by their object
1396 type ("song" for song objects) and their URI (the path within
1397 the database for songs).
1401 <varlistentry id="command_sticker_get">
1404 <command>sticker</command>
1405 <arg choice="plain">get</arg>
1406 <arg choice="req"><replaceable>TYPE</replaceable></arg>
1407 <arg choice="req"><replaceable>URI</replaceable></arg>
1408 <arg choice="req"><replaceable>NAME</replaceable></arg>
1413 Reads a sticker value for the specified object.
1417 <varlistentry id="command_sticker_set">
1420 <command>sticker</command>
1421 <arg choice="plain">set</arg>
1422 <arg choice="req"><replaceable>TYPE</replaceable></arg>
1423 <arg choice="req"><replaceable>URI</replaceable></arg>
1424 <arg choice="req"><replaceable>NAME</replaceable></arg>
1425 <arg choice="req"><replaceable>VALUE</replaceable></arg>
1430 Adds a sticker value to the specified object. If a
1431 sticker item with that name already exists, it is
1436 <varlistentry id="command_sticker_delete">
1439 <command>sticker</command>
1440 <arg choice="plain">delete</arg>
1441 <arg choice="req"><replaceable>TYPE</replaceable></arg>
1442 <arg choice="req"><replaceable>URI</replaceable></arg>
1443 <arg choice="opt"><replaceable>NAME</replaceable></arg>
1448 Deletes a sticker value from the specified object. If
1449 you do not specify a sticker name, all sticker values
1454 <varlistentry id="command_sticker_list">
1457 <command>sticker</command>
1458 <arg choice="plain">list</arg>
1459 <arg choice="req"><replaceable>TYPE</replaceable></arg>
1460 <arg choice="req"><replaceable>URI</replaceable></arg>
1465 Lists the stickers for the specified object.
1469 <varlistentry id="command_sticker_find">
1472 <command>sticker</command>
1473 <arg choice="plain">find</arg>
1474 <arg choice="req"><replaceable>TYPE</replaceable></arg>
1475 <arg choice="req"><replaceable>URI</replaceable></arg>
1476 <arg choice="req"><replaceable>NAME</replaceable></arg>
1481 Searches the sticker database for stickers with the
1482 specified name, below the specified directory (URI).
1483 For each matching song, it prints the URI and that one
1492 <title>Connection settings</title>
1495 <varlistentry id="command_close">
1498 <command>close</command>
1503 Closes the connection to MPD.
1507 <varlistentry id="command_kill">
1510 <command>kill</command>
1519 <varlistentry id="command_password">
1522 <command>password</command>
1523 <arg choice="req"><replaceable>PASSWORD</replaceable></arg>
1528 This is used for authentication with the server.
1529 <varname>PASSWORD</varname> is simply the plaintext
1534 <varlistentry id="command_ping">
1537 <command>ping</command>
1542 Does nothing but return "OK".
1550 <title>Audio output devices</title>
1553 <varlistentry id="command_disableoutput">
1556 <command>disableoutput</command>
1561 Turns an output off.
1565 <varlistentry id="command_enableoutput">
1568 <command>enableoutput</command>
1577 <varlistentry id="command_outputs">
1580 <command>outputs</command>
1585 Shows information about all outputs.
1593 <title>Reflection</title>
1596 <varlistentry id="command_commands">
1599 <command>commands</command>
1604 Shows which commands the current user has access to.
1608 <varlistentry id="command_notcommands">
1611 <command>notcommands</command>
1616 Shows which commands the current user does not have
1621 <varlistentry id="command_tagtypes">
1624 <command>tagtypes</command>
1629 Shows a list of available song metadata.
1633 <varlistentry id="command_urlhandlers">
1636 <command>urlhandlers</command>
1641 Gets a list of available URL handlers.
1645 <varlistentry id="command_decoders">
1648 <command>decoders</command>
1653 Print a list of decoder plugins, followed by their
1654 supported suffixes and MIME types. Example response:
1656 <programlisting>plugin: mad
1659 mime_type: audio/mpeg
1661 suffix: mpc</programlisting>