MPD_COMMANDS.md in mpd_client-0.0.3 vs MPD_COMMANDS.md in mpd_client-0.0.4

- old
+ new

@@ -1,7 +1,18 @@ -### Status Commands +* [Status Commands](#status-commands) +* [Playback Option Commands](#playback-option-commands) +* [Playback Control Commands](#playback-control-commands) +* [Playlist Commands](#playlist-commands) +* [Stored Playlist Commands](#stored-playlist-commands) +* [Database Commands](#database-commands) +* [Sticker Commands](#sticker-commands) +* [Connection Commands](#connection-commands) +* [Reflection Commands](#reflection-commands) +* [Client to client](#client-to-client) +### Status Commands ### + --- `clearerror => fetch_nothing` > Clears the current error message in status (this is also accomplished by any command that starts playback). @@ -25,11 +36,11 @@ * `options`: options like repeat, random, crossfade, replay gain * `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 -> 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 `idle` command can be canceled by sending the command `noidle` (no other commands are allowed). MPD will then leave `idle` mode and print results immediately; might be empty at this time. +> 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 `idle` command can be canceled by sending the command `noidle` (no other commands are allowed). MPD will then leave `idle` mode and print results immediately; might be empty at this time. > If the optional `SUBSYSTEMS` argument is used, MPD will only send notifications when something changed in one of the specified subsytems. --- `noidle` @@ -73,11 +84,11 @@ * `uptime`: daemon uptime in seconds * `db_playtime`: sum of all song times in the db * `db_update`: last db update in UNIX time * `playtime`: time length of music played -### Playback Option Commands +### Playback Option Commands ### --- `consume {STATE} => fetch_nothing` > Sets consume state to `STATE`, `STATE` should be 0 or 1. When consume is activated, each song played is removed from playlist. @@ -88,11 +99,11 @@ > Sets crossfading between songs. --- `mixrampdb {deciBels} => fetch_nothing` -> 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 +> 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 --- `mixrampdelay {SECONDS} => fetch_nothing` > Additional time subtracted from the overlap calculated by `mixrampdb`. A value of "nan" disables MixRamp overlapping and falls back to crossfading. @@ -113,11 +124,11 @@ > Sets volume to `VOL`, the range of volume is 0-100. --- `single {STATE} => fetch_nothing` -> 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. +> 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. --- `replay_gain_mode {MODE} => fetch_nothing` > Sets the replay gain mode. One of `off`, `track`, `album`, `auto`. @@ -129,13 +140,17 @@ --- `replay_gain_status => fetch_item` > Prints replay gain options. Currently, only the variable `replay_gain_mode` is returned. +--- +`volume {CHANGE} => fetch_nothing` -### Playback Control Commands +> Changes volume by amount `CHANGE`. +### Playback Control Commands ### + --- `next => fetch_nothing` > Plays next song in the playlist. @@ -179,11 +194,11 @@ `stop => fetch_nothing` > Stops playing. -### Playlist Commands +### Playlist Commands ### --- `add {URI} => fetch_nothing` > Adds the file `URI` to the playlist (directories add recursively). `URI` can also be a single file. @@ -255,11 +270,11 @@ > To detect songs that were deleted at the end of the playlist, use `playlistlength` returned by status command. --- `plchangesposid {VERSION} => fetch_changes` -> Displays changed songs currently in the playlist since `VERSION`. This function only returns the position and the id of the changed song, not the complete metadata. This is more bandwidth efficient. +> Displays changed songs currently in the playlist since `VERSION`. This function only returns the position and the id of the changed song, not the complete metadata. This is more bandwidth efficient. > To detect songs that were deleted at the end of the playlist, use `playlistlength` returned by status command. --- `prio {PRIORITY} {START:END...} => fetch_nothing` @@ -286,11 +301,11 @@ --- `swapid {SONG1} {SONG2} => fetch_nothing` Swaps the positions of `SONG1` and `SONG2` (both song ids). -### Stored Playlist Commands +### Stored Playlist Commands ### Playlists are stored inside the configured playlist directory. They are addressed with their file name (without the directory and without the .m3u suffix). Some of the commands described in this section can be used to run playlist plugins instead of the hard-coded simple m3u parser. They can access playlists in the music directory (relative path including the suffix) or remote playlists (absolute URI with a supported scheme). @@ -307,11 +322,11 @@ --- `listplaylists => fetch_playlists` > Prints a list of the playlist directory. -> After each playlist name the server sends its last modification time as attribute "Last-Modified" in ISO 8601 format. To avoid problems due to clock differences between clients and the server, clients should not compare this value with their local clock. +> After each playlist name the server sends its last modification time as attribute "Last-Modified" in ISO 8601 format. To avoid problems due to clock differences between clients and the server, clients should not compare this value with their local clock. --- `load {NAME} [START:END] => fetch_nothing` > Loads the playlist into the current queue. Playlist plugins are supported. A range may be specified to load only a part of the playlist. @@ -351,21 +366,21 @@ --- `save {NAME} => fetch_nothing` > Saves the current playlist to `NAME.m3u` in the playlist directory. -### Database Commands +### Database Commands ### --- `count {TAG} {NEEDLE} => fetch_object` > Counts the number of songs and their total playtime in the db matching `TAG` exactly. --- `find {TYPE} {WHAT} [...] => fetch_songs` -> Finds songs in the db that are exactly `WHAT`. `TYPE` can be any tag supported by MPD, or one of the two special parameters — file to search by full path (relative to database root), and any to match against all available tags. `WHAT` is what to find. +> Finds songs in the db that are exactly `WHAT`. `TYPE` can be any tag supported by MPD, or one of the two special parameters — file to search by full path (relative to database root), and any to match against all available tags. `WHAT` is what to find. --- `findadd {TYPE} {WHAT} [...] => fetch_nothing` > Finds songs in the db that are exactly `WHAT` and adds them to current playlist. Parameters have the same meaning as for find. @@ -429,14 +444,23 @@ --- `rescan [URI] => fetch_item` > Same as `update`, but also rescans unmodified files. -### Sticker Commands +--- +`readcomments [URI] => fetch_object` -"Stickers" are pieces of information attached to existing MPD objects (e.g. song files, directories, albums). Clients can create arbitrary name/value pairs. MPD itself does not assume any special meaning in them. +> Read "comments" (i.e. key-value pairs) from the file specified by `URI`. This `URI` can be a path relative to the music directory or a URL in the form `file:///foo/bar.ogg`. +> The response consists of lines in the form "KEY: VALUE". Comments with suspicious characters (e.g. newlines) are ignored silently. + +> The meaning of these depends on the codec, and not all decoder plugins support it. For example, on Ogg files, this lists the Vorbis comments. + +### Sticker Commands ### + +"Stickers" are pieces of information attached to existing MPD objects (e.g. song files, directories, albums). Clients can create arbitrary name/value pairs. MPD itself does not assume any special meaning in them. + The goal is to allow clients to share additional (possibly dynamic) information about songs, which is neither stored on the client (not available to other clients), nor stored in the song files (MPD has no write access). Client developers should create a standard for common sticker names, to ensure interoperability. 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). @@ -464,11 +488,11 @@ --- `sticker find {TYPE} {URI} {NAME} => fetch_songs` > 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. -### Connection Commands +### Connection Commands ### --- `close` > Closes the connection to MPD. @@ -503,12 +527,18 @@ --- `outputs => fetch_outputs` > Shows information about all outputs. -### Reflection Commands +--- +`toggleoutput {ID} => fetch_nothing` +> Turns an output on or off, depending on the current state. + + +### Reflection Commands ### + --- `config => fetch_item` > Dumps configuration values that may be interesting for the client. This command is only permitted to "local" clients (connected via UNIX domain socket). @@ -542,14 +572,14 @@ --- `decoders => fetch_plugins` > Print a list of decoder plugins, followed by their supported suffixes and MIME types. -### Client to client +### Client to client ### -Clients can communicate with each others over "channels". A channel is created by a client subscribing to it. More than one client can be subscribed to a channel at a time; all of them will receive the messages which get sent to it. +Clients can communicate with each others over "channels". A channel is created by a client subscribing to it. More than one client can be subscribed to a channel at a time; all of them will receive the messages which get sent to it. -Each time a client subscribes or unsubscribes, the global idle event subscription is generated. In conjunction with the channels command, this may be used to auto-detect clients providing additional services. +Each time a client subscribes or unsubscribes, the global idle event subscription is generated. In conjunction with the channels command, this may be used to auto-detect clients providing additional services. New messages are indicated by the message idle event. --- `subscribe {NAME} => fetch_nothing`