1MPC(1) mpc MPC(1)
2
6 mpc - mpc Documentation
7
9 mpc is a command-line client for the Music Player Daemon (MPD). It
10 connects to a MPD and controls it according to commands and arguments
11 passed to it. If no command is given, the current status is printed
12 (same as "mpc status").
13
15 mpc [options] <command> [<arguments>]
16
18 -f, --format
19 Configure the format of song display for status and the queue.
20 The metadata delimiters are:
21 ┌───────────────┬────────────────────────────┐
23 │Name │ Description │
24 ├───────────────┼────────────────────────────┤
25 │%name% │ Unknown (doesn't produce │
26 │ │ output) │
27 ├───────────────┼────────────────────────────┤
28 │%artist% │ Artist file tag │
29 ├───────────────┼────────────────────────────┤
30 │%album% │ Album file tag │
31 ├───────────────┼────────────────────────────┤
32 │%albumartist% │ Album Artist file tag │
33 ├───────────────┼────────────────────────────┤
34 │%comment% │ Comment file tag (not │
35 │ │ enabled by default in │
36 │ │ mpd.conf's meta‐ │
37 │ │ data_to_use) │
38 ├───────────────┼────────────────────────────┤
39 │%composer% │ Composer file tag │
40 ├───────────────┼────────────────────────────┤
41 │%date% │ Date file tag │
42 ├───────────────┼────────────────────────────┤
43 │%originaldate% │ Original Date file tag │
44 ├───────────────┼────────────────────────────┤
45 │%disc% │ Disc file tag │
46 ├───────────────┼────────────────────────────┤
47 │%genre% │ Genre file tag │
48 ├───────────────┼────────────────────────────┤
49 │%performer% │ Performer file tag │
50 ├───────────────┼────────────────────────────┤
51 │%title% │ Title file tag │
52 ├───────────────┼────────────────────────────┤
53 │%track% │ Track file tag │
54 ├───────────────┼────────────────────────────┤
55 │%time% │ Duration of file │
56 ├───────────────┼────────────────────────────┤
57 │%file% │ Path of file, relative to │
58 │ │ MPD's music_directory │
59 │ │ variable │
60 ├───────────────┼────────────────────────────┤
61 │%position% │ Queue track number │
62 ├───────────────┼────────────────────────────┤
63 │%id% │ Queue track id number │
64 └───────────────┴────────────────────────────┘
65 │%prio% │ Priority in the (random) │
68 │ │ queue. │
69 ├───────────────┼────────────────────────────┤
70 │%mtime% │ Date and time of last file │
71 │ │ modification │
72 ├───────────────┼────────────────────────────┤
73 │%mdate% │ Date of last file modifi‐ │
74 │ │ cation │
75 └───────────────┴────────────────────────────┘
76 The [] operator is used to group output such that if no metadata
78 delimiters are found or matched between [ and ], then none of
79 the characters between [ and ] are output. & and | are logical
80 operators for and and or. # is used to escape characters. Some
81 useful examples for format are: "%file%" and "[[%artist% -
82 ]%title%]|[%file%]". This command also takes the following
83 defined escape sequences:
84 ┌───┬─────────────────┐
86 │\ │ backslash │
87 ├───┼─────────────────┤
88 │\[ │ left bracket │
89 ├───┼─────────────────┤
90 │\] │ right bracket │
91 ├───┼─────────────────┤
92 │\a │ alert │
93 ├───┼─────────────────┤
94 │\b │ backspace │
95 ├───┼─────────────────┤
96 │\e │ escape │
97 ├───┼─────────────────┤
98 │\t │ tab │
99 ├───┼─────────────────┤
100 │\n │ newline │
101 ├───┼─────────────────┤
102 │\v │ vertical tab │
103 ├───┼─────────────────┤
104 │\f │ form-feed │
105 ├───┼─────────────────┤
106 │\r │ carriage return │
107 └───┴─────────────────┘
108 --wait Wait for operation to finish (e.g. database update).
110 -q, --quiet, --no-status
112 Prevents the current song status from being printed on comple‐
113 tion of some of the commands.
114 --verbose
116 Verbose output.
117 --host=HOST
119 The host to connect to; if not given, the value of the environ‐
120 ment variable MPD_HOST is checked before defaulting to local‐
121 host. This default can be changed at compile-time.
122 To use a password, provide a value of the form "password@host".
124 If you specify an absolute path, mpc attempts a connection via
126 Unix Domain Socket.
127 --port=PORT, -p PORT
129 The port to connect to; if not given, the value of the environ‐
130 ment variable MPD_PORT is checked before defaulting to 6600.
131 This default can be changed at compile-time.
132
134 Commands can be used from the least unambiguous prefix (e.g insert or
135 ins).
136 Player Commands
138 consume <on|off> - Toggle consume mode if state (on
139 or off) is not specified.
140 crossfade [<seconds>] - Gets and sets the current amount of
142 crossfading between songs (0 disables crossfading).
143 current [--wait] - Show the currently playing song. With
145 --wait, mpc waits until the song changes (or until playback is
146 started/stopped) before it queries the current song from the
147 server.
148 mixrampdb [<db>] - Gets and sets the volume level at which
150 songs with MixRamp tags will be overlapped. This disables the
151 fading of the crossfade command and simply mixes the songs.
152 -50.0 will effectively remove any gaps, 0.0 will mash tracks
153 together. The amount of overlap is limited by the audio_buf‐
154 fer_size MPD configuration parameter.
155 mixrampdelay [<seconds>] - Gets and sets the current amount
157 of extra delay added to the value computed from the MixRamp
158 tags. (A negative value disables overlapping with MixRamp tagqs
159 and restores the previous value of crossfade).
160 next - Starts playing next song on queue.
162 pause - Pauses playing.
164 play <position> - Starts playing the song-number
166 specified. If none is specified, plays number 1.
167 prev - Starts playing previous song.
169 random <on|off> - Toggle random mode if state (on
171 or off) is not specified.
172 repeat <on|off> - Toggle repeat mode if state (on
174 or off) is not specified.
175 replaygain [<off|track|album>] - Sets the replay gain mode.
177 Without arguments, it prints the replay gain mode.
178 single <on|off> - Toggle single mode if state (on
180 or off) is not specified.
181 seek [+-][<HH:MM:SS>] or <[+-]<0-100>%> - Seeks by hour,
183 minute or seconds, hours or minutes can be omitted. If seeking
184 by percentage, seeks within the current song in the specified
185 manner. If a + or - is used, the seek is done relative to the
186 current song position. Absolute seeking by default.
187 stop - Stops playing.
189 toggle - Toggles between play and pause. If stopped starts
191 playing. Does not support start playing at song number (use
192 play).
193 Queue Commands
195 add <file> - Adds a song from the music database to the
196 queue. Can also read input from pipes. Use "mpc add /" to add
197 all files to the queue.
198 insert <file> - The insert command works similarly to
200 add except it adds song(s) after the currently playing one,
201 rather than at the end. When random mode is enabled, the new
202 song is queued after the current song.
203 clear - Empties the queue.
205 crop - Remove all songs except for the currently playing
207 song.
208 del <songpos> - Removes a queue number from the queue. Can
210 also read input from pipes (0 deletes the current playing song).
211 mv, move <from> <to> - Moves song at position <from> to the
213 position <to> in the queue.
214 searchplay <type> <query> [<type> <query>]... - Search the
216 queue for a matching song and play it.
217 shuffle - Shuffles all songs on the queue.
219 Playlist Commands
221 load <file>: - Loads <file> as queue.
222 lsplaylists: - Lists available playlists.
224 playlist [<playlist>] - Lists all songs in <playlist>. If
226 no <playlist> is specified, lists all songs in the current
227 queue.
228 rm <file> - Deletes a specific playlist.
230 save <file> - Saves playlist as <file>.
232 Database Commands
234 listall [<file>] - Lists <file> from database. If no
235 <file> is specified, lists all songs in the database.
236 ls [<directory>] - Lists all files/folders in
238 <directory>. If no <directory> is specified, lists all files in
239 music directory.
240 search <type> <query> [<type> <query>]... - Searches for
242 substrings in song tags. Any number of tag type and query com‐
243 binations can be specified. Possible tag types are: artist,
244 album, title, track, name, genre, date, composer, performer,
245 comment, disc, filename, or any (to match any tag).
246 find <type> <query> [<type> <query>]... - Same as search,
248 but tag values must match <query>s exactly instead of doing a
249 substring match.
250 findadd <type> <query> [<type> <query>]... - Same as find,
252 but add the result to the current queue instead of printing
253 them.
254 list <type> [<type> <query>]... - Return a list of all tags
256 of given tag <type>. Optional search <type>s/<query>s limit
257 results in a way similar to search.
258 stats - Displays statistics about MPD.
260 update [--wait] [<path>] - Scans for updated files in the
262 music directory. The optional parameter <path> (relative to the
263 music directory) may limit the scope of the update.
264 With --wait, mpc waits until MPD has finished the update.
266 rescan [--wait] [<path>] - Like update, but also rescans
268 unmodified files.
269 Sticker Commands
271 The sticker command allows you to get and set song stickers.
272 sticker <file> set <key> <value> - Set the value of a song
274 sticker.
275 sticker <file> get <key> - Print the value of a song
277 sticker.
278 sticker <file> list - List all stickers of a song.
280 sticker <file> delete <key> - Delete a song sticker.
282 sticker <dir> find <key> - Search for stickers with the
284 specified name, below the specified directory.
285 Output Commands
287 volume [+-]<num> - Sets the volume to <num> (0-100). If
288 + or - is used, then it adjusts the volume relative to the cur‐
289 rent volume.
290 outputs - Lists all available outputs
292 disable [only] <output # or name> [...] - Disables the
294 output(s); a list of one or more names or numbers is required.
295 If "only" is the first argument, all other outputs are enabled.
296 enable [only] <output # or name> [...] - Enables the
298 output(s); a list of one or more names or numbers is required.
299 If "only" is the first argument, all other outputs are disabled.
300 toggleoutput <output # or name> [...] - Changes the
302 status for the given output(s); a list of one or more names or
303 numbers is required.
304 Client-to-client Commands
306 channels - List the channels that other clients have
307 subscribed to.
308 sendmessage <channel> <message> - Send a message to the
310 specified channel.
311 waitmessage <channel> - Wait for at least one message on
313 the specified channel.
314 subscribe <channel> - Subscribe to the specified channel
316 and continuously receive messages.
317 Other Commands
319 idle [events] - Waits until an event occurs. Prints a list
320 of event names, one per line. See the MPD protocol documenta‐
321 tion for further information.
322 If you specify a list of events, only these events are consid‐
324 ered.
325 idleloop [events] - Similar to idle, but
327 re-enters "idle" state after events have been printed.
328 If you specify a list of events, only these events are consid‐
330 ered.
331 version - Reports the version of MPD.
333
335 All environment variables are overridden by any values specified via
336 command line switches.
337 MPC_FORMAT
339 Specifies the format of song display for status and the queue.
340 MPD_HOST
342 Specifies the hostname of the mpd server. This can be a host‐
343 name, IP address or an absolute path. If it is an absolute
344 path, mpc will use Unix Domain Sockets instead of TCP/IP.
345 If the server requires a password, it can be specified using
347 password@host in the MPD_HOST variable.
348 MPD_PORT
350 Specifies the port the MPD server is listening on.
351
353 Report bugs on https://github.com/MusicPlayerDaemon/mpc/issues
354 Since MPD uses UTF-8, mpc needs to convert characters to the charset
356 used by the local system. If you get character conversion errors when
357 you're running mpc you probably need to set up your locale. This is
358 done by setting any of the LC_CTYPE, LANG or LC_ALL environment vari‐
359 ables (LC_CTYPE only affects character handling).
360
362 mpd(1)
363
365 See
366 https://raw.githubusercontent.com/MusicPlayerDaemon/mpc/master/AUTHORS
367
369 Max Kellermann
370
372 Copyright (C) 2003-2017 The Music Player Daemon Project
3730.30 Jul 18, 2018 MPC(1)