Skip to content

M
mpd
Unverified Commit 00602d28 authored by EdJoPaTo's avatar EdJoPaTo
Browse files
Options

doc/protocol.rst: ensure all commands have targets

parent 7a568371
Hide whitespace changes
Inline Side-by-side
Showing with 187 additions and 1 deletion
doc/protocol.rst
View file @ 00602d28
......@@ -383,10 +383,14 @@ Command reference
Querying :program:`MPD`'s status
================================
.. _command_clearerror:
:command:`clearerror`
Clears the current error message in status (this is also
accomplished by any command that starts playback).
.. _command_currentsong:
:command:`currentsong`
Displays the song info of the current song (same song that
is identified in status). Information about the current song
......@@ -477,6 +481,8 @@ Querying :program:`MPD`'s status
:program:`MPD` versions used to have a "magic" value for
"unknown", e.g. ":samp:`volume: -1`".
.. _command_stats:
:command:`stats`
Displays statistics.
......@@ -492,17 +498,25 @@ Querying :program:`MPD`'s status
Playback options
================
.. _command_consume:
: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.
.. _command_crossfade:
:command:`crossfade {SECONDS}`
Sets crossfading between songs.
.. _command_mixrampdb:
: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
.. _command_mixrampdelay:
:command:`mixrampdelay {SECONDS}`
Additional time subtracted from the overlap calculated by mixrampdb. A value of "nan" disables MixRamp overlapping and falls back to crossfading.
......@@ -512,6 +526,8 @@ Playback options
Sets random state to ``STATE``,
``STATE`` should be 0 or 1.
.. _command_repeat:
:command:`repeat {STATE}`
Sets repeat state to ``STATE``,
``STATE`` should be 0 or 1.
......@@ -522,6 +538,8 @@ Playback options
Sets volume to ``VOL``, the range of
volume is 0-100.
.. _command_getvol:
:command:`getvol`
Read the volume. The result is a ``volume:`` line like in
......@@ -532,12 +550,16 @@ Playback options
volume: 42
OK
.. _command_single:
:command:`single {STATE}` [#since_0_15]_
Sets single state to ``STATE``,
``STATE`` should be ``0``, ``1`` or ``oneshot`` [#since_0_20]_.
When single is activated, playback is stopped after current song, or
song is repeated if the 'repeat' mode is enabled.
.. _command_replay_gain_mode:
:command:`replay_gain_mode {MODE}` [#since_0_16]_
Sets the replay gain mode. One of
``off``,
......@@ -551,11 +573,15 @@ Playback options
This command triggers the
``options`` idle event.
.. _command_replay_gain_status:
:command:`replay_gain_status`
Prints replay gain options. Currently, only the
variable ``replay_gain_mode`` is
returned.
.. _command_volume:
:command:`volume {CHANGE}`
Changes volume by amount ``CHANGE``.
Deprecated, use :ref:`setvol <command_setvol>` instead.
......@@ -563,41 +589,59 @@ Playback options
Controlling playback
====================
.. _command_next:
:command:`next`
Plays next song in the playlist.
.. _command_pause:
:command:`pause {STATE}`
Pause or resume playback. Pass :samp:`1` to pause playback or
:samp:`0` to resume playback. Without the parameter, the pause
state is toggled.
.. _command_play:
:command:`play [SONGPOS]`
Begins playing the playlist at song number
``SONGPOS``.
.. _command_playid:
:command:`playid [SONGID]`
Begins playing the playlist at song
``SONGID``.
.. _command_previous:
:command:`previous`
Plays previous song in the playlist.
.. _command_seek:
:command:`seek {SONGPOS} {TIME}`
Seeks to the position ``TIME`` (in
seconds; fractions allowed) of entry
``SONGPOS`` in the playlist.
.. _command_seekid:
:command:`seekid {SONGID} {TIME}`
Seeks to the position ``TIME`` (in
seconds; fractions allowed) of song
``SONGID``.
.. _command_seekcur:
:command:`seekcur {TIME}`
Seeks to the position ``TIME`` (in
seconds; fractions allowed) within the current song. If
prefixed by ``+`` or ``-``, then the time is relative to the
current playing position.
.. _command_stop:
:command:`stop`
Stops playing.
......@@ -632,11 +676,15 @@ client can always be sure the correct song is being used.
Many commands come in two flavors, one for each address type.
Whenever possible, ids should be used.
.. _command_add:
:command:`add {URI}`
Adds the file ``URI`` to the playlist
(directories add recursively). ``URI``
can also be a single file.
.. _command_addid:
:command:`addid {URI} [POSITION]`
Adds a song to the playlist (non-recursive) and returns the
song id. ``URI`` is always a single file or URL. For example::
......@@ -645,6 +693,8 @@ Whenever possible, ids should be used.
Id: 999
OK
.. _command_clear:
:command:`clear`
Clears the queue.
......@@ -653,15 +703,21 @@ Whenever possible, ids should be used.
:command:`delete [{POS} | {START:END}]`
Deletes a song from the playlist.
.. _command_deleteid:
:command:`deleteid {SONGID}`
Deletes the song ``SONGID`` from the
playlist
.. _command_move:
:command:`move [{FROM} | {START:END}] {TO}`
Moves the song at ``FROM`` or range of songs
at ``START:END`` [#since_0_15]_ to ``TO``
in the playlist.
.. _command_moveid:
:command:`moveid {FROM} {TO}`
Moves the song with ``FROM`` (songid) to
``TO`` (playlist index) in the
......@@ -669,6 +725,8 @@ Whenever possible, ids should be used.
is relative to the current song in the playlist (if
there is one).
.. _command_playlist:
:command:`playlist`
Displays the queue.
......@@ -676,10 +734,14 @@ Whenever possible, ids should be used.
Do not use this, instead use :ref:`playlistinfo
<command_playlistinfo>`.
.. _command_playlistfind:
:command:`playlistfind {TAG} {NEEDLE}`
Finds songs in the queue with strict
matching.
.. _command_playlistid:
:command:`playlistid {SONGID}`
Displays a list of songs in the playlist.
``SONGID`` is optional and specifies a
......@@ -693,10 +755,14 @@ Whenever possible, ids should be used.
``SONGPOS`` or the range of songs
``START:END`` [#since_0_15]_
.. _command_playlistsearch:
:command:`playlistsearch {TAG} {NEEDLE}`
Searches case-insensitively for partial matches in the
queue.
.. _command_plchanges:
:command:`plchanges {VERSION} [START:END]`
Displays changed songs currently in the playlist since
``VERSION``. Start and end positions may
......@@ -706,6 +772,8 @@ Whenever possible, ids should be used.
To detect songs that were deleted at the end of the
playlist, use playlistlength returned by status command.
.. _command_plchangesposid:
:command:`plchangesposid {VERSION} [START:END]`
Displays changed songs currently in the playlist since
``VERSION``. This function only
......@@ -731,6 +799,8 @@ Whenever possible, ids should be used.
Same as :ref:`priod <command_prio>`,
but address the songs with their id.
.. _command_rangeid:
:command:`rangeid {ID} {START:END}` [#since_0_19]_
Since :program:`MPD`
0.19 Specifies the portion of the
......@@ -741,19 +811,27 @@ Whenever possible, ids should be used.
range, play everything". A song that is currently
playing cannot be manipulated this way.
.. _command_shuffle:
:command:`shuffle [START:END]`
Shuffles the queue.
``START:END`` is optional and specifies
a range of songs.
.. _command_swap:
:command:`swap {SONG1} {SONG2}`
Swaps the positions of ``SONG1`` and
``SONG2``.
.. _command_swapid:
:command:`swapid {SONG1} {SONG2}`
Swaps the positions of ``SONG1`` and
``SONG2`` (both song ids).
.. _command_addtagid:
:command:`addtagid {SONGID} {TAG} {VALUE}`
Adds a tag to the specified song. Editing song tags is
only possible for remote songs. This change is
......@@ -761,6 +839,8 @@ Whenever possible, ids should be used.
the server, and the data is gone when the song gets
removed from the queue.
.. _command_cleartagid:
:command:`cleartagid {SONGID} [TAG]`
Removes tags from the specified song. If
``TAG`` is not specified, then all tag
......@@ -782,14 +862,20 @@ playlists in arbitrary location (absolute path including the suffix;
allowed only for clients that are connected via local socket), or
remote playlists (absolute URI with a supported scheme).
.. _command_listplaylist:
:command:`listplaylist {NAME}`
Lists the songs in the playlist. Playlist plugins are
supported.
.. _command_listplaylistinfo:
:command:`listplaylistinfo {NAME}`
Lists the songs with metadata in the playlist. Playlist
plugins are supported.
.. _command_listplaylists:
:command:`listplaylists`
Prints a list of the playlist directory.
After each playlist name the server sends its last
......@@ -805,27 +891,39 @@ remote playlists (absolute URI with a supported scheme).
plugins are supported. A range may be specified to load
only a part of the playlist.
.. _command_playlistadd:
:command:`playlistadd {NAME} {URI}`
Adds ``URI`` to the playlist
`NAME.m3u`.
`NAME.m3u` will be created if it does
not exist.
.. _command_playlistclear:
:command:`playlistclear {NAME}`
Clears the playlist `NAME.m3u`.
.. _command_playlistdelete:
:command:`playlistdelete {NAME} {SONGPOS}`
Deletes ``SONGPOS`` from the
playlist `NAME.m3u`.
.. _command_playlistmove:
:command:`playlistmove {NAME} {FROM} {TO}`
Moves the song at position ``FROM`` in
the playlist `NAME.m3u` to the
position ``TO``.
.. _command_rename:
:command:`rename {NAME} {NEW_NAME}`
Renames the playlist `NAME.m3u` to `NEW_NAME.m3u`.
.. _command_rm:
:command:`rm {NAME}`
Removes the playlist `NAME.m3u` from
the playlist directory.
......@@ -839,6 +937,8 @@ remote playlists (absolute URI with a supported scheme).
The music database
==================
.. _command_albumart:
:command:`albumart {URI} {OFFSET}`
Locate album art for the given song and return a chunk of an album
art image file at offset ``OFFSET``.
......@@ -860,6 +960,8 @@ The music database
<8192 bytes>
OK
.. _command_count:
:command:`count {FILTER} [group {GROUPTYPE}]`
Count the number of songs and their total playtime in
the database matching ``FILTER`` (see
......@@ -882,6 +984,8 @@ The music database
don't have this group tag. It exists only if at least one such song is
found.
.. _command_getfingerprint:
:command:`getfingerprint {URI}`
Calculate the song's audio fingerprint. Example (abbreviated fingerprint)::
......@@ -972,6 +1076,8 @@ The music database
:program:`MPD` whenever you need
something.
.. _command_listfiles:
:command:`listfiles {URI}`
Lists the contents of the directory
``URI``, including files are not
......@@ -1008,6 +1114,8 @@ The music database
use this command to read the tags of an arbitrary local
file (URI is an absolute path).
.. _command_readcomments:
:command:`readcomments {URI}`
Read "comments" (i.e. key-value pairs) from the file
specified by "URI". This "URI" can be a path relative
......@@ -1024,6 +1132,8 @@ The music database
decoder plugins support it. For example, on Ogg files,
this lists the Vorbis comments.
.. _command_readpicture:
:command:`readpicture {URI} {OFFSET}`
Locate a picture for the given song and return a chunk of the
image file at offset ``OFFSET``. This is usually implemented by
......@@ -1065,6 +1175,8 @@ The music database
Parameters have the same meaning as for :ref:`search <command_search>`.
.. _command_searchaddpl:
:command:`searchaddpl {NAME} {FILTER} [sort {TYPE}] [window {START:END}]`
Search the database for songs matching
``FILTER`` (see :ref:`Filters <filter_syntax>`) and add them to
......@@ -1090,6 +1202,8 @@ The music database
job id in the :ref:`status <command_status>`
response.
.. _command_rescan:
:command:`rescan [URI]`
Same as :ref:`update <command_update>`,
but also rescans unmodified files.
......@@ -1116,11 +1230,15 @@ only inside the :program:`MPD` process.
mount foo nfs://192.168.1.4/export/mp3
.. _command_unmount:
:command:`unmount {PATH}`
Unmounts the specified path. Example::
unmount foo
.. _command_listmounts:
:command:`listmounts`
Queries a list of all mounts. By default, this contains
just the configured ``music_directory``.
......@@ -1133,6 +1251,8 @@ only inside the :program:`MPD` process.
storage: nfs://192.168.1.4/export/mp3
OK
.. _command_listneighbors:
:command:`listneighbors`
Queries a list of "neighbors" (e.g. accessible file
servers on the local net). Items on that list may be
......@@ -1168,28 +1288,40 @@ Objects which may have stickers are addressed by their object
type ("song" for song objects) and their URI (the path within
the database for songs).
.. _command_sticker_get:
:command:`sticker get {TYPE} {URI} {NAME}`
Reads a sticker value for the specified object.
.. _command_sticker_set:
:command:`sticker set {TYPE} {URI} {NAME} {VALUE}`
Adds a sticker value to the specified object. If a
sticker item with that name already exists, it is
replaced.
.. _command_sticker_delete:
:command:`sticker delete {TYPE} {URI} [NAME]`
Deletes a sticker value from the specified object. If
you do not specify a sticker name, all sticker values
are deleted.
.. _command_sticker_list:
:command:`sticker list {TYPE} {URI}`
Lists the stickers for the specified object.
.. _command_sticker_find:
:command:`sticker find {TYPE} {URI} {NAME}`
Searches the sticker database for stickers with the
specified name, below the specified directory (URI).
For each matching song, it prints the URI and that one
sticker's value.
.. _command_sticker_find_value:
:command:`sticker find {TYPE} {URI} {NAME} = {VALUE}`
Searches for stickers with the given value.
......@@ -1199,6 +1331,8 @@ the database for songs).
Connection settings
===================
.. _command_close:
:command:`close`
Closes the connection to :program:`MPD`.
:program:`MPD` will try to send the
......@@ -1209,6 +1343,8 @@ Connection settings
Clients should not use this command; instead, they should just
close the socket.
.. _command_kill:
:command:`kill`
Kills :program:`MPD`.
......@@ -1216,14 +1352,20 @@ Connection settings
instead, or better: let your service manager handle :program:`MPD`
shutdown (e.g. :command:`systemctl stop mpd`).
.. _command_password:
:command:`password {PASSWORD}`
This is used for authentication with the server.
``PASSWORD`` is simply the plaintext
password.
.. _command_ping:
:command:`ping`
Does nothing but return "OK".
.. _command_tagtypes:
:command:`tagtypes`
Shows a list of available tag types. It is an
intersection of the ``metadata_to_use``
......@@ -1236,21 +1378,29 @@ Connection settings
``tagtypes`` sub commands configure this
list.
.. _command_tagtypes_disable:
:command:`tagtypes disable {NAME...}`
Remove one or more tags from the list of tag types the
client is interested in. These will be omitted from
responses to this client.
.. _command_tagtypes_enable:
:command:`tagtypes enable {NAME...}`
Re-enable one or more tags from the list of tag types
for this client. These will no longer be hidden from
responses to this client.
.. _command_tagtypes_clear:
:command:`tagtypes clear`
Clear the list of tag types this client is interested
in. This means that :program:`MPD` will
not send any tags to this client.
.. _command_tagtypes_all:
:command:`tagtypes all`
Announce that this client is interested in all tag
types. This is the default setting for new clients.
......@@ -1265,34 +1415,50 @@ These commands allow a client to inspect and manage
MPD process: it has separate queue, player and outputs. A
client is assigned to one partition at a time.
.. _command_partition:
:command:`partition {NAME}`
Switch the client to a different partition.
.. _command_listpartitions:
:command:`listpartitions`
Print a list of partitions. Each partition starts with
a ``partition`` keyword and the
partition's name, followed by information about the
partition.
.. _command_newpartition:
:command:`newpartition {NAME}`
Create a new partition.
.. _command_delpartition:
:command:`delpartition {NAME}`
Delete a partition. The partition must be empty (no connected
clients and no outputs).
.. _command_moveoutput:
:command:`moveoutput {OUTPUTNAME}`
Move an output to the current partition.
Audio output devices
====================
.. _command_disableoutput:
:command:`disableoutput {ID}`
Turns an output off.
.. _command_enableoutput:
:command:`enableoutput {ID}`
Turns an output on.
.. _command_toggleoutput:
:command:`toggleoutput {ID}`
Turns an output on or off, depending on the current
state.
......@@ -1301,7 +1467,7 @@ Audio output devices
:command:`outputs`
Shows information about all outputs.
::
outputid: 0
......@@ -1317,6 +1483,8 @@ Audio output devices
- ``outputname``: Name of the output. It can be any.
- ``outputenabled``: Status of the output. 0 if disabled, 1 if enabled.
.. _command_outputset:
:command:`outputset {ID} {NAME} {VALUE}`
Set a runtime attribute. These are specific to the
output plugin, and supported values are usually printed
......@@ -1326,6 +1494,8 @@ Audio output devices
Reflection
==========
.. _command_config:
:command:`config`
Dumps configuration values that may be interesting for
the client. This command is only permitted to "local"
......@@ -1335,16 +1505,24 @@ Reflection
- ``music_directory``: The absolute path of the music directory.
.. _command_commands:
:command:`commands`
Shows which commands the current user has access to.
.. _command_notcommands:
:command:`notcommands`
Shows which commands the current user does not have
access to.
.. _command_urlhandlers:
:command:`urlhandlers`
Gets a list of available URL handlers.
.. _command_decoders:
:command:`decoders`
Print a list of decoder plugins, followed by their
supported suffixes and MIME types. Example response::
......@@ -1376,12 +1554,16 @@ idle event.
If your MPD instance has multiple partitions, note that
client-to-client messages are local to the current partition.
.. _command_subscribe:
:command:`subscribe {NAME}`
Subscribe to a channel. The channel is created if it
does not exist already. The name may consist of
alphanumeric ASCII characters plus underscore, dash, dot
and colon.
.. _command_unsubscribe:
:command:`unsubscribe {NAME}`
Unsubscribe from a channel.
......@@ -1391,10 +1573,14 @@ client-to-client messages are local to the current partition.
Obtain a list of all channels. The response is a list
of "channel:" lines.
.. _command_readmessages:
:command:`readmessages`
Reads messages for this client. The response is a list
of "channel:" and "message:" lines.
.. _command_sendmessage:
:command:`sendmessage {CHANNEL} {TEXT}`
Send a message to the specified channel.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment