doc/protocol.xml

   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">
   4 <book>
   5   <title>The Music Player Daemon protocol</title>
   6
   7   <chapter>
   8     <title>General protocol syntax</title>
   9
  10     <section>
  11       <title>Requests</title>
  12
  13       <para>
  14         If arguments contain spaces, they should be surrounded by double quotation
  15         marks.
  16       </para>
  17
  18       <cmdsynopsis>
  19         <command>COMMAND</command>
  20         <arg rep="repeat"><replaceable>ARG</replaceable></arg>
  21       </cmdsynopsis>
  22
  23       <para>
  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
  32         information on UTF=8:
  33         http://www.cl.cam.ac.uk/~mgk25/unicode.html#utf-8)
  34       </para>
  35     </section>
  36
  37     <section>
  38       <title>Responses</title>
  39
  40       <para>
  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.
  44       </para>
  45     </section>
  46
  47     <section>
  48       <title>Command lists</title>
  49
  50       <para>
  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>.
  56       </para>
  57
  58       <para>
  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.
  68       </para>
  69     </section>
  70   </chapter>
  71
  72   <chapter>
  73     <title>Command reference</title>
  74
  75     <note>
  76       <para>
  77         For manipulating playlists and playing, there are two sets of
  78         commands.  One set uses the song id of a song in the playlist,
  79         while another set uses the playlist position of the song. The
  80         commands using song ids should be used instead of the commands
  81         that manipulate and control playback based on playlist
  82         position. Using song ids is a safer method when multiple
  83         clients are interacting with MPD.
  84       </para>
  85     </note>
  86
  87     <section>
  88       <title>Querying MPD's status</title>
  89
  90       <variablelist>
  91         <varlistentry id="command_clearerror">
  92           <term>
  93             <cmdsynopsis>
  94               <command>clearerror</command>
  95             </cmdsynopsis>
  96           </term>
  97           <listitem>
  98             <para>
  99               Clears the current error message in status (this is also
 100               accomplished by any command that starts playback).
 101             </para>
 102           </listitem>
 103         </varlistentry>
 104         <varlistentry id="command_currentsong">
 105           <term>
 106             <cmdsynopsis>
 107               <command>currentsong</command>
 108             </cmdsynopsis>
 109           </term>
 110           <listitem>
 111             <para>
 112               Displays the song info of the current song (same song that
 113               is identified in status).
 114             </para>
 115           </listitem>
 116         </varlistentry>
 117         <varlistentry id="command_idle">
 118           <term>
 119             <cmdsynopsis>
 120               <command>idle</command>
 121               <arg choice="opt" rep="repeat"><replaceable>SUBSYSTEMS</replaceable></arg>
 122             </cmdsynopsis>
 123           </term>
 124           <listitem>
 125             <para>
 126               <footnote id="since_0_14"><simpara>Introduced with MPD 0.14</simpara></footnote>
 127               Waits until there is a noteworthy change in one or more
 128               of MPD's subsystems.  As soon as there is one, it lists
 129               all changed systems in a line in the format
 130               <returnvalue>changed: SUBSYSTEM</returnvalue>, where
 131               SUBSYSTEM is one of the following:
 132             </para>
 133             <itemizedlist>
 134               <listitem>
 135                 <para>
 136                   <returnvalue>database</returnvalue>: the song database
 137                   has been modified after <command>update</command>.
 138                 </para>
 139               </listitem>
 140               <listitem>
 141                 <para>
 142                   <returnvalue>update</returnvalue>: a database update
 143                   has started or finished.  If the database was
 144                   modified during the update, the
 145                   <returnvalue>database</returnvalue> event is also
 146                   emitted.
 147                 </para>
 148               </listitem>
 149               <listitem>
 150                 <para>
 151                   <returnvalue>stored_playlist</returnvalue>: a stored
 152                   playlist has been modified, renamed, created or
 153                   deleted
 154                 </para>
 155               </listitem>
 156               <listitem>
 157                 <para>
 158                   <returnvalue>playlist</returnvalue>: the current
 159                   playlist has been modified
 160                 </para>
 161               </listitem>
 162               <listitem>
 163                 <para>
 164                   <returnvalue>player</returnvalue>: the player has been
 165                   started, stopped or seeked
 166                 </para>
 167               </listitem>
 168               <listitem>
 169                 <para>
 170                   <returnvalue>mixer</returnvalue>: the volume has been
 171                   changed
 172                 </para>
 173               </listitem>
 174               <listitem>
 175                 <para>
 176                   <returnvalue>output</returnvalue>: an audio output has
 177                   been enabled or disabled
 178                 </para>
 179               </listitem>
 180               <listitem>
 181                 <para>
 182                   <returnvalue>options</returnvalue>: options like
 183                   <option>repeat</option>, <option>random</option>,
 184                   <option>crossfade</option>
 185                 </para>
 186               </listitem>
 187             </itemizedlist>
 188             <para>
 189               While a client is waiting for <command>idle</command>
 190               results, the server disables timeouts, allowing a client
 191               to wait for events as long as mpd runs.  The
 192               <command>idle</command> command can be canceled by
 193               sending the command <command>noidle</command> (no other
 194               commands are allowed). MPD will then leave
 195               <command>idle</command> mode and print results
 196               immediately; might be empty at this time.
 197             </para>
 198             <para>
 199               If the optional <varname>SUBSYSTEMS</varname> argument is used,
 200               MPD will only send notifications when something changed in
 201               one of the specified subsytems.
 202             </para>
 203           </listitem>
 204         </varlistentry>
 205         <varlistentry id="command_status">
 206           <term>
 207             <cmdsynopsis>
 208               <command>status</command>
 209             </cmdsynopsis>
 210           </term>
 211           <listitem>
 212             <para>
 213               Reports the current status of the player and the volume
 214               level.
 215             </para>
 216             <itemizedlist>
 217               <listitem>
 218                 <para>
 219                   <varname>volume</varname>:
 220                   <returnvalue>0-100</returnvalue>
 221                 </para>
 222               </listitem>
 223               <listitem>
 224                 <para>
 225                   <varname>repeat</varname>:
 226                   <returnvalue>0 or 1</returnvalue>
 227                 </para>
 228               </listitem>
 229               <listitem>
 230                <para>
 231                 <varname>single</varname>:
 232                 <footnote id="since_0_15"><simpara>Introduced with MPD 0.15</simpara></footnote>
 233                 <returnvalue>0 or 1</returnvalue>
 234                </para>
 235               </listitem>
 236               <listitem>
 237                <para>
 238                 <varname>consume</varname>:
 239                 <footnoteref linkend="since_0_15"/>
 240                 <returnvalue>0 or 1</returnvalue>
 241                </para>
 242               </listitem>
 243               <listitem>
 244                 <para>
 245                   <varname>playlist</varname>:
 246                   <returnvalue>31-bit unsigned integer, the playlist
 247                   version number</returnvalue>
 248                 </para>
 249               </listitem>
 250               <listitem>
 251                 <para>
 252                   <varname>playlistlength</varname>:
 253                   <returnvalue>integer, the length of the
 254                   playlist</returnvalue>
 255                 </para>
 256               </listitem>
 257               <listitem>
 258                 <para>
 259                   <varname>state</varname>:
 260                   <returnvalue>play, stop, or pause</returnvalue>
 261                 </para>
 262               </listitem>
 263               <listitem>
 264                 <para>
 265                   <varname>song</varname>:
 266                   <returnvalue> playlist song number of the current
 267                   song stopped on or playing
 268                   </returnvalue>
 269                 </para>
 270               </listitem>
 271               <listitem>
 272                 <para>
 273                   <varname>songid</varname>:
 274                   <returnvalue>playlist songid of the current song
 275                   stopped on or playing
 276                   </returnvalue>
 277                 </para>
 278               </listitem>
 279               <listitem>
 280                 <para>
 281                   <varname>time</varname>:
 282                   <returnvalue>total time elapsed (of current
 283                   playing/paused song)</returnvalue>
 284                 </para>
 285               </listitem>
 286               <listitem>
 287                 <para>
 288                   <varname>elapsed</varname>:
 289                   <footnote id="since_0_16"><simpara>Introduced with MPD 0.16</simpara></footnote>
 290                   <returnvalue>
 291                     Total time elapsed within the current song, but
 292                     with higher resolution.
 293                   </returnvalue>
 294                 </para>
 295               </listitem>
 296               <listitem>
 297                 <para>
 298                   <varname>bitrate</varname>:
 299                   <returnvalue>instantaneous bitrate in
 300                   kbps</returnvalue>
 301                 </para>
 302               </listitem>
 303               <listitem>
 304                 <para>
 305                   <varname>xfade</varname>:
 306                   <returnvalue>crossfade in seconds</returnvalue>
 307                 </para>
 308               </listitem>
 309               <listitem>
 310                 <para>
 311                   <varname>audio</varname>:
 312                   <returnvalue>sampleRate:bits:channels</returnvalue>
 313                 </para>
 314               </listitem>
 315               <listitem>
 316                 <para>
 317                   <varname>updatings_db</varname>:
 318                   <returnvalue>job id</returnvalue>
 319                 </para>
 320               </listitem>
 321               <listitem>
 322                 <para>
 323                   <varname>error</varname>:
 324                   <returnvalue>if there is an error, returns message
 325                   here</returnvalue>
 326                 </para>
 327                 </listitem>
 328             </itemizedlist>
 329           </listitem>
 330         </varlistentry>
 331         <varlistentry id="command_stats">
 332           <term>
 333             <cmdsynopsis>
 334               <command>stats</command>
 335             </cmdsynopsis>
 336           </term>
 337           <listitem>
 338             <para>
 339               Displays statistics.
 340             </para>
 341             <itemizedlist>
 342               <listitem>
 343                 <para>
 344                   <varname>artists</varname>: number of artists
 345                 </para>
 346               </listitem>
 347               <listitem>
 348                 <para>
 349                   <varname>songs</varname>: number of albums
 350                 </para>
 351               </listitem>
 352               <listitem>
 353                 <para>
 354                   <varname>uptime</varname>: daemon uptime in seconds
 355                 </para>
 356               </listitem>
 357               <listitem>
 358                 <para>
 359                   <varname>db_playtime</varname>: sum of all song
 360                   times in the db
 361                 </para>
 362               </listitem>
 363               <listitem>
 364                 <para>
 365                   <varname>db_update</varname>: last db update in UNIX
 366                   time
 367                 </para>
 368               </listitem>
 369               <listitem>
 370                 <para>
 371                   <varname>playtime</varname>: time length of music played
 372                 </para>
 373               </listitem>
 374             </itemizedlist>
 375           </listitem>
 376         </varlistentry>
 377       </variablelist>
 378     </section>
 379
 380     <section>
 381       <title>Playback options</title>
 382
 383       <variablelist>
 384         <varlistentry id="command_consume">
 385           <term>
 386             <cmdsynopsis>
 387               <command>consume</command>
 388               <arg choice="req"><replaceable>STATE</replaceable></arg>
 389             </cmdsynopsis>
 390           </term>
 391           <listitem>
 392             <para>
 393               <footnoteref linkend="since_0_15"/>
 394               Sets consume state to <varname>STATE</varname>,
 395               <varname>STATE</varname> should be 0 or 1.
 396               When consume is activated, each song played is removed from playlist.
 397             </para>
 398           </listitem>
 399         </varlistentry>
 400         <varlistentry id="command_crossfade">
 401           <term>
 402             <cmdsynopsis>
 403               <command>crossfade</command>
 404               <arg choice="req"><replaceable>SECONDS</replaceable></arg>
 405             </cmdsynopsis>
 406           </term>
 407           <listitem>
 408             <para>
 409               Sets crossfading between songs.
 410             </para>
 411           </listitem>
 412         </varlistentry>
 413         <varlistentry id="command_random">
 414           <term>
 415             <cmdsynopsis>
 416               <command>random</command>
 417               <arg choice="req"><replaceable>STATE</replaceable></arg>
 418             </cmdsynopsis>
 419           </term>
 420           <listitem>
 421             <para>
 422               Sets random state to <varname>STATE</varname>,
 423               <varname>STATE</varname> should be 0 or 1.
 424             </para>
 425           </listitem>
 426         </varlistentry>
 427         <varlistentry id="command_repeat">
 428           <term>
 429             <cmdsynopsis>
 430               <command>repeat</command>
 431               <arg choice="req"><replaceable>STATE</replaceable></arg>
 432             </cmdsynopsis>
 433           </term>
 434           <listitem>
 435             <para>
 436               Sets repeat state to <varname>STATE</varname>,
 437               <varname>STATE</varname> should be 0 or 1.
 438             </para>
 439           </listitem>
 440         </varlistentry>
 441         <varlistentry id="command_setvol">
 442           <term>
 443             <cmdsynopsis>
 444               <command>setvol</command>
 445               <arg choice="req"><replaceable>VOL</replaceable></arg>
 446             </cmdsynopsis>
 447           </term>
 448           <listitem>
 449             <para>
 450               Sets volume to <varname>VOL</varname>, the range of
 451               volume is 0-100.
 452             </para>
 453           </listitem>
 454         </varlistentry>
 455         <varlistentry id="command_single">
 456           <term>
 457             <cmdsynopsis>
 458               <command>single</command>
 459               <arg choice="req"><replaceable>STATE</replaceable></arg>
 460             </cmdsynopsis>
 461           </term>
 462           <listitem>
 463             <para>
 464               <footnoteref linkend="since_0_15"/>
 465               Sets single state to <varname>STATE</varname>,
 466               <varname>STATE</varname> should be 0 or 1.
 467               When single is activated, playback is stopped after current song, or
 468               song is repeated if the 'repeat' mode is enabled.
 469             </para>
 470           </listitem>
 471         </varlistentry>
 472       </variablelist>
 473     </section>
 474
 475     <section>
 476       <title>Controlling playback</title>
 477
 478       <variablelist>
 479         <varlistentry id="command_next">
 480           <term>
 481             <cmdsynopsis>
 482               <command>next</command>
 483             </cmdsynopsis>
 484           </term>
 485           <listitem>
 486             <para>
 487               Plays next song in the playlist.
 488             </para>
 489           </listitem>
 490         </varlistentry>
 491         <varlistentry id="command_pause">
 492           <term>
 493             <cmdsynopsis>
 494               <command>pause</command>
 495               <arg choice="req"><replaceable>PAUSE</replaceable></arg>
 496             </cmdsynopsis>
 497           </term>
 498           <listitem>
 499             <para>
 500               Toggles pause/resumes playing, <varname>PAUSE</varname> is 0 or 1.
 501             </para>
 502             <note>
 503               <para>
 504                 The use of pause command w/o the PAUSE argument is
 505                 deprecated.
 506               </para>
 507             </note>
 508           </listitem>
 509         </varlistentry>
 510         <varlistentry id="command_play">
 511           <term>
 512             <cmdsynopsis>
 513               <command>play</command>
 514               <arg><replaceable>SONGPOS</replaceable></arg>
 515             </cmdsynopsis>
 516           </term>
 517           <listitem>
 518             <para>
 519               Begins playing the playlist at song number
 520               <varname>SONGPOS</varname>.
 521             </para>
 522           </listitem>
 523         </varlistentry>
 524         <varlistentry id="command_playid">
 525           <term>
 526             <cmdsynopsis>
 527               <command>playid</command>
 528               <arg><replaceable>SONGID</replaceable></arg>
 529             </cmdsynopsis>
 530           </term>
 531           <listitem>
 532             <para>
 533               Begins playing the playlist at song
 534               <varname>SONGID</varname>.
 535             </para>
 536           </listitem>
 537         </varlistentry>
 538         <varlistentry id="command_previous">
 539           <term>
 540             <cmdsynopsis>
 541               <command>previous</command>
 542             </cmdsynopsis>
 543           </term>
 544           <listitem>
 545             <para>
 546               Plays previous song in the playlist.
 547             </para>
 548           </listitem>
 549         </varlistentry>
 550
 551         <varlistentry id="command_seek">
 552           <term>
 553             <cmdsynopsis>
 554               <command>seek</command>
 555               <arg choice="req"><replaceable>SONGPOS</replaceable></arg>
 556               <arg choice="req"><replaceable>TIME</replaceable></arg>
 557             </cmdsynopsis>
 558           </term>
 559           <listitem>
 560             <para>
 561               Seeks to the position <varname>TIME</varname> (in
 562               seconds) of entry <varname>SONGPOS</varname> in the
 563               playlist.
 564             </para>
 565           </listitem>
 566         </varlistentry>
 567         <varlistentry id="command_seekid">
 568           <term>
 569             <cmdsynopsis>
 570               <command>seekid</command>
 571               <arg choice="req"><replaceable>SONGID</replaceable></arg>
 572               <arg choice="req"><replaceable>TIME</replaceable></arg>
 573             </cmdsynopsis>
 574           </term>
 575           <listitem>
 576             <para>
 577               Seeks to the position <varname>TIME</varname> (in
 578               seconds) of song <varname>SONGID</varname>.
 579             </para>
 580           </listitem>
 581         </varlistentry>
 582         <varlistentry id="command_stop">
 583           <term>
 584             <cmdsynopsis>
 585               <command>stop</command>
 586             </cmdsynopsis>
 587           </term>
 588           <listitem>
 589             <para>
 590               Stops playing.
 591             </para>
 592           </listitem>
 593         </varlistentry>
 594       </variablelist>
 595     </section>
 596
 597     <section>
 598       <title>The current playlist</title>
 599
 600       <variablelist>
 601         <varlistentry id="command_add">
 602           <term>
 603             <cmdsynopsis>
 604               <command>add</command>
 605               <arg choice="req"><replaceable>URI</replaceable></arg>
 606             </cmdsynopsis>
 607           </term>
 608           <listitem>
 609             <para>
 610               Adds the file <varname>URI</varname> to the playlist
 611               (directories add recursively). <varname>URI</varname>
 612               can also be a single file.
 613             </para>
 614           </listitem>
 615         </varlistentry>
 616         <varlistentry id="command_addid">
 617           <term>
 618             <cmdsynopsis>
 619               <command>addid</command>
 620               <arg choice="req"><replaceable>URI</replaceable></arg>
 621               <arg><replaceable>POSITION</replaceable></arg>
 622             </cmdsynopsis>
 623           </term>
 624           <listitem>
 625             <para>
 626               Adds a song to the playlist (non-recursive) and returns the song id.
 627             </para>
 628             <para>
 629               <varname>URI</varname> is always a single file or
 630               URL.  <varname>POSITION</varname> is optional, a
 631               negative number means it is relative to the currently
 632               playing song in the playlist (if there is one).
 633               For example:
 634             </para>
 635             <screen>
 636 addid "foo.mp3"
 637 Id: 999
 638 OK
 639             </screen>
 640           </listitem>
 641         </varlistentry>
 642         <varlistentry id="command_clear">
 643           <term>
 644             <cmdsynopsis>
 645               <command>clear</command>
 646             </cmdsynopsis>
 647           </term>
 648           <listitem>
 649             <para>
 650               Clears the current playlist.
 651             </para>
 652           </listitem>
 653         </varlistentry>
 654         <varlistentry id="command_delete">
 655           <term>
 656             <cmdsynopsis>
 657               <command>delete</command>
 658               <arg choice="req"><replaceable>SONGPOS</replaceable></arg>
 659             </cmdsynopsis>
 660           </term>
 661           <listitem>
 662             <para>
 663               Deletes a song from the playlist.
 664             </para>
 665           </listitem>
 666         </varlistentry>
 667         <varlistentry id="command_deleteid">
 668           <term>
 669             <cmdsynopsis>
 670               <command>deleteid</command>
 671               <arg choice="req"><replaceable>SONGID</replaceable></arg>
 672             </cmdsynopsis>
 673           </term>
 674           <listitem>
 675             <para>
 676               Deletes the song <varname>SONGID</varname> from the
 677               playlist
 678             </para>
 679           </listitem>
 680         </varlistentry>
 681         <varlistentry id="command_move">
 682           <term>
 683             <cmdsynopsis>
 684               <command>move</command>
 685               <group>
 686                   <arg choice="req"><replaceable>FROM</replaceable></arg>
 687                   <arg choice="req"><replaceable>START:END</replaceable></arg>
 688               </group>
 689               <arg choice="req"><replaceable>TO</replaceable></arg>
 690             </cmdsynopsis>
 691           </term>
 692           <listitem>
 693             <para>
 694               Moves the song at <varname>FROM</varname> or range of songs
 695               at <varname>START:END</varname> to <varname>TO</varname>
 696               in the playlist.
 697               <footnote id="range_since_0_15">
 698                 <simpara>Ranges are supported since MPD 0.15</simpara>
 699               </footnote>
 700             </para>
 701           </listitem>
 702         </varlistentry>
 703         <varlistentry id="command_moveid">
 704           <term>
 705             <cmdsynopsis>
 706               <command>moveid</command>
 707               <arg choice="req"><replaceable>FROM</replaceable></arg>
 708               <arg choice="req"><replaceable>TO</replaceable></arg>
 709             </cmdsynopsis>
 710           </term>
 711           <listitem>
 712             <para>
 713               Moves the song with <varname>FROM</varname> (songid) to
 714               <varname>TO</varname> (playlist index) in the
 715               playlist.  If <varname>TO</varname> is negative, it
 716               is relative to the current song in the playlist (if
 717               there is one).
 718             </para>
 719           </listitem>
 720         </varlistentry>
 721         <varlistentry id="command_playlist">
 722           <term>
 723             <cmdsynopsis>
 724               <command>playlist</command>
 725             </cmdsynopsis>
 726           </term>
 727           <listitem>
 728             <para>
 729               Displays the current playlist.
 730             </para>
 731             <note>
 732               <para>
 733                 Do not use this, instead use <command>playlistinfo</command>.
 734               </para>
 735             </note>
 736           </listitem>
 737         </varlistentry>
 738         <varlistentry id="command_playlistfind">
 739           <term>
 740             <cmdsynopsis>
 741               <command>playlistfind</command>
 742               <arg choice="req"><replaceable>TAG</replaceable></arg>
 743               <arg choice="req"><replaceable>NEEDLE</replaceable></arg>
 744             </cmdsynopsis>
 745           </term>
 746           <listitem>
 747             <para>
 748               Finds songs in the current playlist with strict
 749               matching.
 750             </para>
 751           </listitem>
 752         </varlistentry>
 753         <varlistentry id="command_playlistid">
 754           <term>
 755             <cmdsynopsis>
 756               <command>playlistid</command>
 757               <arg choice="req"><replaceable>SONGID</replaceable></arg>
 758             </cmdsynopsis>
 759           </term>
 760           <listitem>
 761             <para>
 762               Displays a list of songs in the playlist.
 763               <varname>SONGID</varname> is optional and specifies a
 764               single song to display info for.
 765             </para>
 766           </listitem>
 767         </varlistentry>
 768         <varlistentry id="command_playlistinfo">
 769           <term>
 770             <cmdsynopsis>
 771               <command>playlistinfo</command>
 772               <group>
 773                   <arg><replaceable>SONGPOS</replaceable></arg>
 774                   <arg><replaceable>START:END</replaceable></arg>
 775               </group>
 776             </cmdsynopsis>
 777           </term>
 778           <listitem>
 779             <para>
 780               Displays a list of all songs in the playlist, or if the optional
 781               argument is given, displays information only for the song
 782               <varname>SONGPOS</varname> or the range of songs
 783               <varname>START:END</varname>
 784               <footnoteref linkend="range_since_0_15"/>
 785             </para>
 786           </listitem>
 787         </varlistentry>
 788         <varlistentry id="command_playlistsearch">
 789           <term>
 790             <cmdsynopsis>
 791               <command>playlistsearch</command>
 792               <arg choice="req"><replaceable>TAG</replaceable></arg>
 793               <arg choice="req"><replaceable>NEEDLE</replaceable></arg>
 794             </cmdsynopsis>
 795           </term>
 796           <listitem>
 797             <para>
 798               Searches case-sensitively for partial matches in the
 799               current playlist.
 800             </para>
 801           </listitem>
 802         </varlistentry>
 803         <varlistentry id="command_plchanges">
 804           <term>
 805             <cmdsynopsis>
 806               <command>plchanges</command>
 807               <arg choice="req"><replaceable>VERSION</replaceable></arg>
 808             </cmdsynopsis>
 809           </term>
 810           <listitem>
 811             <para>
 812               Displays changed songs currently in the playlist since
 813               <varname>VERSION</varname>.
 814             </para>
 815             <para>
 816               To detect songs that were deleted at the end of the
 817               playlist, use playlistlength returned by status command.
 818             </para>
 819           </listitem>
 820         </varlistentry>
 821         <varlistentry id="command_plchangesposid">
 822           <term>
 823             <cmdsynopsis>
 824               <command>plchangesposid</command>
 825               <arg choice="req"><replaceable>VERSION</replaceable></arg>
 826             </cmdsynopsis>
 827           </term>
 828           <listitem>
 829             <para>
 830               Displays changed songs currently in the playlist since
 831               <varname>VERSION</varname>.  This function only
 832               returns the position and the id of the changed song, not
 833               the complete metadata. This is more bandwidth efficient.
 834             </para>
 835             <para>
 836               To detect songs that were deleted at the end of the
 837               playlist, use playlistlength returned by status command.
 838             </para>
 839           </listitem>
 840         </varlistentry>
 841         <varlistentry id="command_shuffle">
 842           <term>
 843             <cmdsynopsis>
 844               <command>shuffle</command>
 845               <arg><replaceable>START:END</replaceable></arg>
 846             </cmdsynopsis>
 847           </term>
 848           <listitem>
 849             <para>
 850               Shuffles the current playlist.
 851               <varname>START:END</varname> is optional and specifies
 852               a range of songs.
 853             </para>
 854           </listitem>
 855         </varlistentry>
 856         <varlistentry id="command_swap">
 857           <term>
 858             <cmdsynopsis>
 859               <command>swap</command>
 860               <arg choice="req"><replaceable>SONG1</replaceable></arg>
 861               <arg choice="req"><replaceable>SONG2</replaceable></arg>
 862             </cmdsynopsis>
 863           </term>
 864           <listitem>
 865             <para>
 866               Swaps the positions of <varname>SONG1</varname> and
 867               <varname>SONG2</varname>.
 868             </para>
 869           </listitem>
 870         </varlistentry>
 871         <varlistentry id="command_swapid">
 872           <term>
 873             <cmdsynopsis>
 874               <command>swapid</command>
 875               <arg choice="req"><replaceable>SONG1</replaceable></arg>
 876               <arg choice="req"><replaceable>SONG2</replaceable></arg>
 877             </cmdsynopsis>
 878           </term>
 879           <listitem>
 880             <para>
 881               Swaps the positions of <varname>SONG1</varname> and
 882               <varname>SONG2</varname> (both song ids).
 883             </para>
 884           </listitem>
 885         </varlistentry>
 886       </variablelist>
 887     </section>
 888
 889     <section>
 890       <title>Stored playlists</title>
 891
 892       <variablelist>
 893         <varlistentry id="command_listplaylist">
 894           <term>
 895             <cmdsynopsis>
 896               <command>listplaylist</command>
 897               <arg choice="req"><replaceable>NAME</replaceable></arg>
 898             </cmdsynopsis>
 899           </term>
 900           <listitem>
 901             <para>
 902               Lists the files in the playlist
 903               <filename>NAME.m3u</filename>.
 904             </para>
 905           </listitem>
 906         </varlistentry>
 907         <varlistentry id="command_listplaylistinfo">
 908           <term>
 909             <cmdsynopsis>
 910               <command>listplaylistinfo</command>
 911               <arg choice="req"><replaceable>NAME</replaceable></arg>
 912             </cmdsynopsis>
 913           </term>
 914           <listitem>
 915             <para>
 916               Lists songs in the playlist <filename>NAME.m3u</filename>.
 917             </para>
 918           </listitem>
 919         </varlistentry>
 920         <varlistentry id="command_listplaylists">
 921           <term>
 922             <cmdsynopsis>
 923               <command>listplaylists</command>
 924             </cmdsynopsis>
 925           </term>
 926           <listitem>
 927             <para>
 928               Prints a list of the playlist directory.
 929             </para>
 930             <para>
 931               After each playlist name the server sends its last
 932               modification time as attribute "Last-Modified" in ISO
 933               8601 format.  To avoid problems due to clock differences
 934               between clients and the server, clients should not
 935               compare this value with their local clock.
 936             </para>
 937           </listitem>
 938         </varlistentry>
 939         <varlistentry id="command_load">
 940           <term>
 941             <cmdsynopsis>
 942               <command>load</command>
 943               <arg choice="req"><replaceable>NAME</replaceable></arg>
 944             </cmdsynopsis>
 945           </term>
 946           <listitem>
 947             <para>
 948               Loads the playlist <filename>NAME.m3u</filename> from
 949               the playlist directory.
 950             </para>
 951           </listitem>
 952         </varlistentry>
 953         <varlistentry id="command_playlistadd">
 954           <term>
 955             <cmdsynopsis>
 956               <command>playlistadd</command>
 957               <arg choice="req"><replaceable>NAME</replaceable></arg>
 958               <arg choice="req"><replaceable>URI</replaceable></arg>
 959             </cmdsynopsis>
 960           </term>
 961           <listitem>
 962             <para>
 963               Adds <varname>URI</varname> to the playlist
 964               <filename>NAME.m3u</filename>.
 965             </para>
 966             <para>
 967              <filename>NAME.m3u</filename> will be created if it does
 968              not exist.
 969             </para>
 970           </listitem>
 971         </varlistentry>
 972         <varlistentry id="command_playlistclear">
 973           <term>
 974             <cmdsynopsis>
 975               <command>playlistclear</command>
 976               <arg choice="req"><replaceable>NAME</replaceable></arg>
 977             </cmdsynopsis>
 978           </term>
 979           <listitem>
 980             <para>
 981               Clears the playlist <filename>NAME.m3u</filename>.
 982             </para>
 983           </listitem>
 984         </varlistentry>
 985         <varlistentry id="command_playlistdelete">
 986           <term>
 987             <cmdsynopsis>
 988               <command>playlistdelete</command>
 989               <arg choice="req"><replaceable>NAME</replaceable></arg>
 990               <arg choice="req"><replaceable>SONGPOS</replaceable></arg>
 991             </cmdsynopsis>
 992           </term>
 993           <listitem>
 994             <para>
 995               Deletes <varname>SONGPOS</varname> from the
 996               playlist <filename>NAME.m3u</filename>.
 997             </para>
 998           </listitem>
 999         </varlistentry>
1000         <varlistentry id="command_playlistmove">
1001           <term>
1002             <cmdsynopsis>
1003               <command>playlistmove</command>
1004               <arg choice="req"><replaceable>NAME</replaceable></arg>
1005               <arg choice="req"><replaceable>SONGID</replaceable></arg>
1006               <arg choice="req"><replaceable>SONGPOS</replaceable></arg>
1007             </cmdsynopsis>
1008           </term>
1009           <listitem>
1010             <para>
1011               Moves <varname>SONGID</varname> in the playlist
1012               <filename>NAME.m3u</filename> to the position
1013               <varname>SONGPOS</varname>.
1014             </para>
1015           </listitem>
1016         </varlistentry>
1017         <varlistentry id="command_rename">
1018           <term>
1019             <cmdsynopsis>
1020               <command>rename</command>
1021               <arg choice="req"><replaceable>NAME</replaceable></arg>
1022               <arg choice="req"><replaceable>NEW_NAME</replaceable></arg>
1023             </cmdsynopsis>
1024           </term>
1025           <listitem>
1026             <para>
1027               Renames the playlist <filename>NAME.m3u</filename> to <filename>NEW_NAME.m3u</filename>.
1028             </para>
1029           </listitem>
1030         </varlistentry>
1031         <varlistentry id="command_rm">
1032           <term>
1033             <cmdsynopsis>
1034               <command>rm</command>
1035               <arg choice="req"><replaceable>NAME</replaceable></arg>
1036             </cmdsynopsis>
1037           </term>
1038           <listitem>
1039             <para>
1040               Removes the playlist <filename>NAME.m3u</filename> from
1041               the playlist directory.
1042             </para>
1043           </listitem>
1044         </varlistentry>
1045         <varlistentry id="command_save">
1046           <term>
1047             <cmdsynopsis>
1048               <command>save</command>
1049               <arg choice="req"><replaceable>NAME</replaceable></arg>
1050             </cmdsynopsis>
1051           </term>
1052           <listitem>
1053             <para>
1054               Saves the current playlist to
1055               <filename>NAME.m3u</filename> in the playlist directory.
1056             </para>
1057           </listitem>
1058         </varlistentry>
1059       </variablelist>
1060     </section>
1061
1062     <section>
1063       <title>The music database</title>
1064
1065       <variablelist>
1066         <varlistentry id="command_count">
1067           <term>
1068             <cmdsynopsis>
1069               <command>count</command>
1070               <arg choice="req"><replaceable>TAG</replaceable></arg>
1071               <arg choice="req"><replaceable>NEEDLE</replaceable></arg>
1072             </cmdsynopsis>
1073           </term>
1074           <listitem>
1075             <para>
1076               Counts the number of songs and their total playtime in
1077               the db matching <varname>TAG</varname> exactly.
1078             </para>
1079           </listitem>
1080         </varlistentry>
1081         <varlistentry id="command_find">
1082           <term>
1083             <cmdsynopsis>
1084               <command>find</command>
1085               <arg choice="req"><replaceable>TYPE</replaceable></arg>
1086               <arg choice="req"><replaceable>WHAT</replaceable></arg>
1087             </cmdsynopsis>
1088           </term>
1089           <listitem>
1090             <para>
1091               Finds songs in the db that are exactly
1092               <varname>WHAT</varname>.  <varname>TYPE</varname> should
1093               be <parameter>album</parameter>,
1094               <parameter>artist</parameter>, or
1095               <parameter>title</parameter>.  <varname>WHAT</varname>
1096               is what to find.
1097             </para>
1098           </listitem>
1099         </varlistentry>
1100         <varlistentry id="command_findadd">
1101           <term>
1102             <cmdsynopsis>
1103               <command>findadd</command>
1104               <arg choice="req"><replaceable>TYPE</replaceable></arg>
1105               <arg choice="req"><replaceable>WHAT</replaceable></arg>
1106             </cmdsynopsis>
1107           </term>
1108           <listitem>
1109             <para>
1110               Finds songs in the db that are exactly
1111               <varname>WHAT</varname> and adds them to current playlist.
1112               <varname>TYPE</varname> can be any tag supported by MPD.
1113               <varname>WHAT</varname> is what to find.
1114             </para>
1115           </listitem>
1116         </varlistentry>
1117         <varlistentry id="command_list">
1118           <term>
1119             <cmdsynopsis>
1120               <command>list</command>
1121               <arg choice="req"><replaceable>TYPE</replaceable></arg>
1122               <arg><replaceable>ARTIST</replaceable></arg>
1123             </cmdsynopsis>
1124           </term>
1125           <listitem>
1126             <para>
1127               Lists all tags of the specified type.
1128               <varname>TYPE</varname> should be album or artist.
1129             </para>
1130             <para>
1131               <varname>ARTIST</varname> is an optional parameter when
1132               type is album, this specifies to list albums by an
1133               artist.
1134             </para>
1135           </listitem>
1136         </varlistentry>
1137         <varlistentry id="command_listall">
1138           <term>
1139             <cmdsynopsis>
1140               <command>listall</command>
1141               <arg><replaceable>URI</replaceable></arg>
1142             </cmdsynopsis>
1143           </term>
1144           <listitem>
1145             <para>
1146               Lists all songs and directories in
1147               <varname>URI</varname>.
1148             </para>
1149           </listitem>
1150         </varlistentry>
1151         <varlistentry id="command_listallinfo">
1152           <term>
1153             <cmdsynopsis>
1154               <command>listallinfo</command>
1155               <arg><replaceable>URI</replaceable></arg>
1156             </cmdsynopsis>
1157           </term>
1158           <listitem>
1159             <para>
1160               Same as <command>listall</command>, except it also
1161               returns metadata info in the same format as
1162               <command>lsinfo</command>.
1163             </para>
1164           </listitem>
1165         </varlistentry>
1166         <varlistentry id="command_lsinfo">
1167           <term>
1168             <cmdsynopsis>
1169               <command>lsinfo</command>
1170               <arg><replaceable>URI</replaceable></arg>
1171             </cmdsynopsis>
1172           </term>
1173           <listitem>
1174             <para>
1175               Lists the contents of the directory
1176               <varname>URI</varname>.
1177             </para>
1178             <para>
1179               When listing the root directory, this currently returns
1180               the list of stored playlists.  This behavior is
1181               deprecated; use "listplaylists" instead.
1182             </para>
1183           </listitem>
1184         </varlistentry>
1185         <varlistentry id="command_search">
1186           <term>
1187             <cmdsynopsis>
1188               <command>search</command>
1189               <arg choice="req"><replaceable>TYPE</replaceable></arg>
1190               <arg choice="req"><replaceable>WHAT</replaceable></arg>
1191             </cmdsynopsis>
1192           </term>
1193           <listitem>
1194             <para>
1195               Searches for any song that contains
1196               <varname>WHAT</varname>.  <varname>TYPE</varname> can be
1197               <parameter>title</parameter>,
1198               <parameter>artist</parameter>,
1199               <parameter>album</parameter> or
1200               <parameter>filename</parameter>.  Search is not case
1201               sensitive.
1202             </para>
1203           </listitem>
1204         </varlistentry>
1205         <varlistentry id="command_update">
1206           <term>
1207             <cmdsynopsis>
1208               <command>update</command>
1209               <arg><replaceable>URI</replaceable></arg>
1210             </cmdsynopsis>
1211           </term>
1212           <listitem>
1213             <para>
1214               Updates the music database.
1215             </para>
1216             <para>
1217               <varname>URI</varname> is a particular directory or
1218               song/file to update.
1219             </para>
1220             <para>
1221               Prints "updating_db: JOBID" where
1222               <varname>JOBID</varname> is the job id requested for
1223               your update, and is displayed in status, while the
1224               requested update is happening.
1225             </para>
1226             <para>
1227               To update a number of paths/songs at once, use
1228               command_list, it will be much more faster/efficient.
1229               Also, if you use a command_list for updating, only one
1230               <command>update</command> job id will be returned per
1231               sequence of updates.
1232             </para>
1233           </listitem>
1234         </varlistentry>
1235       </variablelist>
1236     </section>
1237
1238     <section>
1239       <title>Stickers</title>
1240
1241       <para>
1242         "Stickers"<footnoteref linkend="since_0_15"/> are pieces of
1243         information attached to existing MPD objects (e.g. song files,
1244         directories, albums).  Clients can create arbitrary name/value
1245         pairs.  MPD itself does not assume any special meaning in
1246         them.
1247       </para>
1248
1249       <para>
1250         The goal is to allow clients to share additional (possibly
1251         dynamic) information about songs, which is neither stored on
1252         the client (not available to other clients), nor stored in the
1253         song files (MPD has no write access).
1254       </para>
1255
1256       <para>
1257         Client developers should create a standard for common sticker
1258         names, to ensure interoperability.
1259       </para>
1260
1261       <para>
1262         Objects which may have stickers are addressed by their object
1263         type ("song" for song objects) and their URI (the path within
1264         the database for songs).
1265       </para>
1266
1267       <variablelist>
1268         <varlistentry id="command_sticker_get">
1269           <term>
1270             <cmdsynopsis>
1271               <command>sticker</command>
1272               <arg choice="plain">get</arg>
1273               <arg choice="req"><replaceable>TYPE</replaceable></arg>
1274               <arg choice="req"><replaceable>URI</replaceable></arg>
1275               <arg choice="req"><replaceable>NAME</replaceable></arg>
1276             </cmdsynopsis>
1277           </term>
1278           <listitem>
1279             <para>
1280               Reads a sticker value for the specified object.
1281             </para>
1282           </listitem>
1283         </varlistentry>
1284         <varlistentry id="command_sticker_set">
1285           <term>
1286             <cmdsynopsis>
1287               <command>sticker</command>
1288               <arg choice="plain">set</arg>
1289               <arg choice="req"><replaceable>TYPE</replaceable></arg>
1290               <arg choice="req"><replaceable>URI</replaceable></arg>
1291               <arg choice="req"><replaceable>NAME</replaceable></arg>
1292               <arg choice="req"><replaceable>VALUE</replaceable></arg>
1293             </cmdsynopsis>
1294           </term>
1295           <listitem>
1296             <para>
1297               Adds a sticker value to the specified object.  If a
1298               sticker item with that name already exists, it is
1299               replaced.
1300             </para>
1301           </listitem>
1302         </varlistentry>
1303         <varlistentry id="command_sticker_delete">
1304           <term>
1305             <cmdsynopsis>
1306               <command>sticker</command>
1307               <arg choice="plain">delete</arg>
1308               <arg choice="req"><replaceable>TYPE</replaceable></arg>
1309               <arg choice="req"><replaceable>URI</replaceable></arg>
1310               <arg choice="opt"><replaceable>NAME</replaceable></arg>
1311             </cmdsynopsis>
1312           </term>
1313           <listitem>
1314             <para>
1315               Deletes a sticker value from the specified object.  If
1316               you do not specify a sticker name, all sticker values
1317               are deleted.
1318             </para>
1319           </listitem>
1320         </varlistentry>
1321         <varlistentry id="command_sticker_list">
1322           <term>
1323             <cmdsynopsis>
1324               <command>sticker</command>
1325               <arg choice="plain">list</arg>
1326               <arg choice="req"><replaceable>TYPE</replaceable></arg>
1327               <arg choice="req"><replaceable>URI</replaceable></arg>
1328             </cmdsynopsis>
1329           </term>
1330           <listitem>
1331             <para>
1332               Lists the stickers for the specified object.
1333             </para>
1334           </listitem>
1335         </varlistentry>
1336         <varlistentry id="command_sticker_find">
1337           <term>
1338             <cmdsynopsis>
1339               <command>sticker</command>
1340               <arg choice="plain">find</arg>
1341               <arg choice="req"><replaceable>TYPE</replaceable></arg>
1342               <arg choice="req"><replaceable>URI</replaceable></arg>
1343               <arg choice="req"><replaceable>NAME</replaceable></arg>
1344             </cmdsynopsis>
1345           </term>
1346           <listitem>
1347             <para>
1348               Searches the sticker database for stickers with the
1349               specified name, below the specified directory (URI).
1350               For each matching song, it prints the URI and that one
1351               sticker's value.
1352             </para>
1353           </listitem>
1354         </varlistentry>
1355       </variablelist>
1356     </section>
1357
1358     <section>
1359       <title>Connection settings</title>
1360
1361       <variablelist>
1362         <varlistentry id="command_close">
1363           <term>
1364             <cmdsynopsis>
1365               <command>close</command>
1366             </cmdsynopsis>
1367           </term>
1368           <listitem>
1369             <para>
1370               Closes the connection to MPD.
1371             </para>
1372           </listitem>
1373         </varlistentry>
1374         <varlistentry id="command_kill">
1375           <term>
1376             <cmdsynopsis>
1377               <command>kill</command>
1378             </cmdsynopsis>
1379           </term>
1380           <listitem>
1381             <para>
1382               Kills MPD.
1383             </para>
1384           </listitem>
1385         </varlistentry>
1386         <varlistentry id="command_password">
1387           <term>
1388             <cmdsynopsis>
1389               <command>password</command>
1390               <arg choice="req"><replaceable>PASSWORD</replaceable></arg>
1391             </cmdsynopsis>
1392           </term>
1393           <listitem>
1394             <para>
1395               This is used for authentication with the server.
1396               <varname>PASSWORD</varname> is simply the plaintext
1397               password.
1398             </para>
1399           </listitem>
1400         </varlistentry>
1401         <varlistentry id="command_ping">
1402           <term>
1403             <cmdsynopsis>
1404               <command>ping</command>
1405             </cmdsynopsis>
1406           </term>
1407           <listitem>
1408             <para>
1409               Does nothing but return "OK".
1410             </para>
1411           </listitem>
1412         </varlistentry>
1413       </variablelist>
1414     </section>
1415
1416     <section>
1417       <title>Audio output devices</title>
1418
1419       <variablelist>
1420         <varlistentry id="command_disableoutput">
1421           <term>
1422             <cmdsynopsis>
1423               <command>disableoutput</command>
1424             </cmdsynopsis>
1425           </term>
1426           <listitem>
1427             <para>
1428               Turns an output off.
1429             </para>
1430           </listitem>
1431         </varlistentry>
1432         <varlistentry id="command_enableoutput">
1433           <term>
1434             <cmdsynopsis>
1435               <command>enableoutput</command>
1436             </cmdsynopsis>
1437           </term>
1438           <listitem>
1439             <para>
1440               Turns an output on.
1441             </para>
1442           </listitem>
1443         </varlistentry>
1444         <varlistentry id="command_outputs">
1445           <term>
1446             <cmdsynopsis>
1447               <command>outputs</command>
1448             </cmdsynopsis>
1449           </term>
1450           <listitem>
1451             <para>
1452               Shows information about all outputs.
1453             </para>
1454           </listitem>
1455         </varlistentry>
1456       </variablelist>
1457     </section>
1458
1459     <section>
1460       <title>Reflection</title>
1461
1462       <variablelist>
1463         <varlistentry id="command_commands">
1464           <term>
1465             <cmdsynopsis>
1466               <command>commands</command>
1467             </cmdsynopsis>
1468           </term>
1469           <listitem>
1470             <para>
1471               Shows which commands the current user has access to.
1472             </para>
1473           </listitem>
1474         </varlistentry>
1475         <varlistentry id="command_notcommands">
1476           <term>
1477             <cmdsynopsis>
1478               <command>notcommands</command>
1479             </cmdsynopsis>
1480           </term>
1481           <listitem>
1482             <para>
1483               Shows which commands the current user does not have
1484               access to.
1485             </para>
1486           </listitem>
1487         </varlistentry>
1488         <varlistentry id="command_tagtypes">
1489           <term>
1490             <cmdsynopsis>
1491               <command>tagtypes</command>
1492             </cmdsynopsis>
1493           </term>
1494           <listitem>
1495             <para>
1496               Shows a list of available song metadata.
1497             </para>
1498           </listitem>
1499         </varlistentry>
1500         <varlistentry id="command_urlhandlers">
1501           <term>
1502             <cmdsynopsis>
1503               <command>urlhandlers</command>
1504             </cmdsynopsis>
1505           </term>
1506           <listitem>
1507             <para>
1508               Gets a list of available URL handlers.
1509             </para>
1510           </listitem>
1511         </varlistentry>
1512       </variablelist>
1513     </section>
1514   </chapter>
1515 </book>