@@ -69,37 +71,35 @@ terms. Let's look at each of them:
of the ``ACK_ERROR`` constants defined
in `src/protocol/Ack.hxx`.
- ``command_listNum``:
offset of the command that caused the error in a `Command List <command_lists>`.
An error will always cause a command list to terminate
at the command that causes the error.
- ``command_listNum``: offset of the command that caused the error in
a :ref:`Command List <command_lists>`. An error will always cause a
command list to terminate at the command that causes the error.
- ``current_command``:
name of the command, in a `Command List <command_lists>`,
that was executing when the error occurred.
- ``current_command``: name of the command, in a :ref:`Command List
<command_lists>`, that was executing when the error occurred.
- ``message_text``:
some (hopefully) informative text that describes the
nature of the error.
foo
~~~
An example might help. Consider the following sequence
sent from the client to the server.
An example might help. Consider the following sequence
sent from the client to the server::
CMDSYN: command_list_begin volume 86 play 10240 status command_list_end
command_list_begin
volume 86
play 10240
status
command_list_end
The server responds with:
The server responds with::
``ACK \[50@1] {play} song doesn't exist: "10240"``
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.
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.
.. _command_lists:
...
...
@@ -125,26 +125,24 @@ successful command executed in the command list.
Ranges
======
Some commands (e.g. `delete` <command_delete>`)
allow specifying a range in the form
*START:END* (the ``END``
item is not included in the range, similar to ranges in the
Python programming language). If ``END`` is
omitted, then the maximum possible value is assumed.
Some commands (e.g. :ref:`delete <command_delete>`) allow specifying a
range in the form ``START:END`` (the ``END`` item is not included in
the range, similar to ranges in the Python programming language). If
``END`` is omitted, then the maximum possible value is assumed.
.. _filter_syntax:
Filters
=======
All commands which search for songs (e.g. `find` <command_find>` and
`searchadd` <command_searchadd>`)
share a common filter syntax:
All commands which search for songs (e.g. :ref:`find <command_find>`
and :ref:`searchadd <command_searchadd>`) share a common filter
syntax::
CMDSYN: find EXPRESSION
find EXPRESSION
``EXPRESSION`` is a string enclosed in
parantheses which can be one of:
``EXPRESSION`` is a string enclosed in parantheses which can be one
of:
- ``(TAG == 'VALUE')``: match a tag value.
``(TAG != 'VALUE')``: mismatch a tag value.
...
...
@@ -182,9 +180,9 @@ parantheses which can be one of:
- ``(EXPRESSION1 AND EXPRESSION2 ...)``: combine two or
more expressions with logical "and".
Prior to MPD 0.21, the syntax looked like this:
Prior to MPD 0.21, the syntax looked like this::
CMDSYN: find TYPE VALUE
find TYPE VALUE
.. _tags:
...
...
@@ -194,6 +192,28 @@ Tags
The following tags are supported by
``MPD``:
* **artist**: the artist name. Its meaning is not well-defined; see "*composer*" and "*performer*" for more specific tags.
* **artistsort**: same as artist, but for sorting. This usually omits prefixes such as "The".
* **album**: the album name.
* **albumsort**: same as album, but for sorting.
* **albumartist**: on multi-artist albums, this is the artist name which shall be used for the whole album. The exact meaning of this tag is not well-defined.
* **albumartistsort**: same as albumartist, but for sorting.
* **title**: the song title.
* **track**: the decimal track number within the album.
* **name**: a name for this song. This is not the song title. The exact meaning of this tag is not well-defined. It is often used by badly configured internet radio stations with broken tags to squeeze both the artist name and the song title in one tag.
* **genre**: the music genre.
* **date**: the song's release date. This is usually a 4-digit year.
* **composer**: the artist who composed the song.
* **performer**: the artist who performed the song.
* **comment**: a human-readable comment about this song. The exact meaning of this tag is not well-defined.
* **disc**: the decimal disc number in a multi-disc album.
* **musicbrainz_artistid**: the artist id in the `MusicBrainz <https://picard.musicbrainz.org/docs/mappings/>`_ database.
* **musicbrainz_albumid**: the album id in the `MusicBrainz <https://picard.musicbrainz.org/docs/mappings/>`_ database.
* **musicbrainz_albumartistid**: the album artist id in the `MusicBrainz <https://picard.musicbrainz.org/docs/mappings/>`_ database.
* **musicbrainz_trackid**: the track id in the `MusicBrainz <https://picard.musicbrainz.org/docs/mappings/>`_ database.
* **musicbrainz_releasetrackid**: the release track id in the `MusicBrainz <https://picard.musicbrainz.org/docs/mappings/>`_ database.
* **musicbrainz_workid**: the work id in the `MusicBrainz <https://picard.musicbrainz.org/docs/mappings/>`_ database.
There can be multiple values for some of these tags. For
example, ``MPD`` may return multiple
lines with a ``performer`` tag. A tag value is
...
...
@@ -204,9 +224,8 @@ a UTF-8 string.
Other Metadata
==============
The response to `lsinfo` <command_lsinfo>` and
similar commands may contain `song
tags <tags>` and other metadata, specifically:
The response to :ref:`lsinfo <command_lsinfo>` and similar commands
may contain :ref:`song tags <tags>` and other metadata, specifically:
- ``duration``: the duration of the song in
seconds; may contain a fractional part.
...
...
@@ -215,22 +234,17 @@ tags <tags>` and other metadata, specifically:
but as integer value. This is deprecated and is only here
for compatibility with older clients. Do not use.
- ``Range``: if this is a queue item
referring only to a portion of the song file, then this
attribute contains the time range in the form
*START-END* or
*START-* (open ended); both
*START* and
*END* are time stamps within the song
in seconds (may contain a fractional part). Example:
"*60-120*" plays only the second
minute; "*180*" skips the first three
minutes.
- ``Range``: if this is a queue item referring only to a portion of
the song file, then this attribute contains the time range in the
form ``START-END`` or ``START-`` (open ended); both ``START`` and
``END`` are time stamps within the song in seconds (may contain a
fractional part). Example: ``60-120`` plays only the second minute;
"``180`` skips the first three minutes.
- ``Format``: the audio format of the song
(or an approximation to a format supported by MPD and the
decoder plugin being used). When playing this file, the
``audio`` value in the `status` <command_status>`
``audio`` value in the :ref:`status <command_status>`
response should be the same.
- ``Last-Modified``: the time stamp of the
...
...
@@ -244,15 +258,14 @@ Recipes
Queuing
=======
Often, users run ``MPD`` with ``random`` enabled, but want to
be able to insert songs "before" the rest of the playlist.
Often, users run ``MPD`` with :ref:`random <command_random>` enabled,
but want to be able to insert songs "before" the rest of the playlist.
That is commonly called "queuing".
``MPD`` implements this by allowing the client to specify a
"priority" for each song in the playlist (commands ``priod`` <command_prio>` and
``priodid`` <command_prioid>`). A
higher priority means that the song is going to be played
before the other songs.
``MPD`` implements this by allowing the client to specify a "priority"
for each song in the playlist (commands :ref:`priod <command_prio>`
and :ref:`priodid <command_prioid>`). A higher priority means that
the song is going to be played before the other songs.
In "random" mode, ``MPD`` maintains an
internal randomized sequence of songs. In this sequence,
...
...
@@ -284,24 +297,25 @@ Command reference
Querying ``MPD``'s status
================================
CMDSYN: clearerror
:command:`clearerror`
Clears the current error message in status (this is also
accomplished by any command that starts playback).
CMDSYN: currentsong
:command:`currentsong`
Displays the song info of the current song (same song that
is identified in status).
CMDSYN: idle SUBSYSTEMS
Introduced with
``MPD`` 0.14
.. _command_idle:
:command:`idle [SUBSYSTEMS...]` [#since_0_14]_
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 modified after `update` <command_update>`.
- ``database``: the song database has been modified after :ref:`update <command_update>`.
- ``update``: a database update has started or finished. If the database was modified during the update, the ``database`` event is also emitted.
- ``stored_playlist``: a stored playlist has been modified, renamed, created or deleted
- ``playlist``: the current playlist has been modified
...
...
@@ -313,12 +327,13 @@ CMDSYN: idle SUBSYSTEMS
- ``sticker``: the sticker database has been modified.
- ``subscription``: a client has subscribed or unsubscribed to a channel
- ``message``: a message was received on a channel this client is subscribed to; this event is only emitted when the queue is empty
Change events accumulate, even while the connection is
not in "idle" mode; no events gets lost while the client
is doing something else with the connection. If an
event had already occurred since the last call, the new
`idle` <command_idle>`
Change events accumulate, even while the connection is not in
"idle" mode; no events gets lost while the client is doing
something else with the connection. If an event had already
occurred since the last call, the new :ref:`idle <command_idle>`
command will return immediately.
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
...
...
@@ -332,24 +347,27 @@ CMDSYN: idle SUBSYSTEMS
notifications when something changed in one of the
specified subsytems.
CMDSYN: status
.. _command_status:
:command:`status`
Reports the current status of the player and the volume
level.
- ``volume``: ``0-100`` or ``-1`` if the volume cannot be determined
- ``repeat``: ``0`` or ``1``
- ``random``: ``0`` or ``1``
- ``single``: Introduced with ``MPD`` 0.15 (oneshot introduced with 0.20). ``0``, ``1``, or ``oneshot``
- ``consume``: ``0`` or ``1``
- ``single`` [#since_0_15]_: ``0``, ``1``, or ``oneshot`` [#since_0_20]_
- ``consume`` [#since_0_15]_: ``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
- ``nextsong``: playlist song number of the next song to be played
- ``nextsongid``: playlist songid of the next song to be played
- ``nextsong`` [#since_0_15]_: playlist song number of the next song to be played
- ``nextsongid`` [#since_0_15]_: playlist songid of the next song to be played
- ``time``: total time elapsed (of current playing/paused song)
- ``elapsed``: Introduced with ``MPD`` 0.16. Total time elapsed within the current song, but with higher resolution.
- ``duration``: Introduced with ``MPD`` 0.20. Duration of the current song in seconds.
- ``elapsed`` [#since_0_16]_: Total time elapsed within the current song, but with higher resolution.
- ``duration`` [#since_0_20]_: Duration of the current song in seconds.
- ``bitrate``: instantaneous bitrate in kbps
- ``xfade``: ``crossfade`` in seconds
- ``mixrampdb``: ``mixramp`` threshold in dB
...
...
@@ -358,8 +376,9 @@ CMDSYN: status
- ``updating_db``: ``job id``
- ``error``: if there is an error, returns message here
CMDSYN: stats
:command:`stats`
Displays statistics.
- ``artists``: number of artists
- ``albums``: number of albums
- ``songs``: number of songs
...
...
@@ -371,45 +390,48 @@ CMDSYN: stats
Playback options
================
CMDSYN: consume STATE
:command:`consume {STATE}` [#since_0_15]_
Sets consume state to ``STATE``,
``STATE`` should be 0 or 1.
When consume is activated, each song played is removed from playlist.
CMDSYN: crossfade SECONDS
:command:`crossfade {SECONDS}`
Sets crossfading between songs.
CMDSYN: mixrampdb deciBels
:command:`mixrampdb {deciBels}`
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
CMDSYN: mixrampdelay SECONDS
:command:`mixrampdelay {SECONDS}`
Additional time subtracted from the overlap calculated by mixrampdb. A value of "nan" disables MixRamp overlapping and falls back to crossfading.
CMDSYN: random STATE
.. _command_random:
:command:`random {STATE}`
Sets random state to ``STATE``,
``STATE`` should be 0 or 1.
CMDSYN: repeat STATE
:command:`repeat {STATE}`
Sets repeat state to ``STATE``,
``STATE`` should be 0 or 1.
CMDSYN: setvol VOL
.. _command_setvol:
:command:`setvol {VOL}`
Sets volume to ``VOL``, the range of
volume is 0-100.
CMDSYN: single STATE
:command:`single {STATE}` [#since_0_15]_
Sets single state to ``STATE``,
``STATE`` should be 0 or 1.
When single is activated, playback is stopped after current song, or
song is repeated if the 'repeat' mode is enabled.
CMDSYN: replay_gain_mode MODE
:command:`replay_gain_mode {MODE}` [#since_0_16]_
Sets the replay gain mode. One of
*off*,
*track*,
*album*,
*auto*
added in ``MPD`` 0.16
``off``,
``track``,
``album``,
``auto``
.
Changing the mode during playback may take several
seconds, because the new settings does not affect the
