Chapter 3. Command reference

Table of Contents

Querying MPD's status
Playback options
Controlling playback
The current playlist
Stored playlists
The music database
Stickers
Connection settings
Audio output devices
Reflection
Client to client

Note

For manipulating playlists and playing, there are two sets of commands. One set uses the song id of a song in the playlist, while another set uses the playlist position of the song. The commands using song ids should be used instead of the commands that manipulate and control playback based on playlist position. Using song ids is a safer method when multiple clients are interacting with MPD.

Querying MPD's status

clearerror

Clears the current error message in status (this is also accomplished by any command that starts playback).

currentsong

Displays the song info of the current song (same song that is identified in status).

idle [SUBSYSTEMS...]

[1] 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.

  • 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

  • player: the player has been started, stopped or seeked

  • mixer: the volume has been changed

  • output: an audio output has been enabled or disabled

  • 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.

If the optional SUBSYSTEMS argument is used, MPD will only send notifications when something changed in one of the specified subsytems.

status

Reports the current status of the player and the volume level.

  • volume: 0-100

  • repeat: 0 or 1

  • random: 0 or 1

  • single: [2] 0 or 1

  • consume: [2] 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: [2] playlist song number of the next song to be played

  • nextsongid: [2] playlist songid of the next song to be played

  • time: total time elapsed (of current playing/paused song)

  • elapsed: [3] Total time elapsed within the current song, but with higher resolution.

  • bitrate: instantaneous bitrate in kbps

  • xfade: crossfade in seconds

  • mixrampdb: mixramp threshold in dB

  • mixrampdelay: mixrampdelay in seconds

  • audio: sampleRate:bits:channels

  • updating_db: job id

  • error: if there is an error, returns message here

stats

Displays statistics.

  • artists: number of artists

  • songs: number of albums

  • 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



[1] Introduced with MPD 0.14

[2] Introduced with MPD 0.15

[3] Introduced with MPD 0.16