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 used to display songs.
20 The metadata delimiters are:
22 ┌───────────────┬────────────────────────────┐
24 │Name │ Description │
25 ├───────────────┼────────────────────────────┤
26 │%name% │ A name for this song. │
27 │ │ This is not the song │
28 │ │ title. The exact meaning │
29 │ │ of this tag is not │
30 │ │ well-defined. It is often │
31 │ │ used by badly configured │
32 │ │ internet radio stations │
33 │ │ with broken tags to │
34 │ │ squeeze both the artist │
35 │ │ name and the song title in │
36 │ │ one tag. │
37 ├───────────────┼────────────────────────────┤
38 │%artist% │ Artist file tag │
39 ├───────────────┼────────────────────────────┤
40 │%album% │ Album file tag │
41 ├───────────────┼────────────────────────────┤
42 │%albumartist% │ Album Artist file tag │
43 ├───────────────┼────────────────────────────┤
44 │%comment% │ Comment file tag (not │
45 │ │ enabled by default in │
46 │ │ mpd.conf's meta‐ │
47 │ │ data_to_use) │
48 ├───────────────┼────────────────────────────┤
49 │%composer% │ Composer file tag │
50 ├───────────────┼────────────────────────────┤
51 │%date% │ Date file tag │
52 ├───────────────┼────────────────────────────┤
53 │%originaldate% │ Original Date file tag │
54 ├───────────────┼────────────────────────────┤
55 │%disc% │ Disc file tag │
56 ├───────────────┼────────────────────────────┤
57 │%genre% │ Genre file tag │
58 ├───────────────┼────────────────────────────┤
59 │%performer% │ Performer file tag │
60 ├───────────────┼────────────────────────────┤
61 │%title% │ Title file tag │
62 ├───────────────┼────────────────────────────┤
63 │%track% │ Track file tag │
64 └───────────────┴────────────────────────────┘
65 │%time% │ Duration of file │
68 ├───────────────┼────────────────────────────┤
69 │%file% │ Path of file, relative to │
70 │ │ MPD's music_directory │
71 │ │ variable │
72 ├───────────────┼────────────────────────────┤
73 │%position% │ Queue track number │
74 ├───────────────┼────────────────────────────┤
75 │%id% │ Queue track id number │
76 ├───────────────┼────────────────────────────┤
77 │%prio% │ Priority in the (random) │
78 │ │ queue. │
79 ├───────────────┼────────────────────────────┤
80 │%mtime% │ Date and time of last file │
81 │ │ modification │
82 ├───────────────┼────────────────────────────┤
83 │%mdate% │ Date of last file modifi‐ │
84 │ │ cation │
85 └───────────────┴────────────────────────────┘
86 The [] operator is used to group output such that if no metadata
88 delimiters are found or matched between [ and ], then none of
89 the characters between [ and ] are output. & and | are logical
90 operators for and and or. # is used to escape characters. Some
91 useful examples for format are: "%file%" and "[[%artist% -
92 ]%title%]|[%file%]". This command also takes the following
93 defined escape sequences:
94 ┌───┬─────────────────┐
96 │\ │ backslash │
97 ├───┼─────────────────┤
98 │\[ │ left bracket │
99 ├───┼─────────────────┤
100 │\] │ right bracket │
101 ├───┼─────────────────┤
102 │\a │ alert │
103 ├───┼─────────────────┤
104 │\b │ backspace │
105 ├───┼─────────────────┤
106 │\e │ escape │
107 ├───┼─────────────────┤
108 │\t │ tab │
109 ├───┼─────────────────┤
110 │\n │ newline │
111 ├───┼─────────────────┤
112 │\v │ vertical tab │
113 ├───┼─────────────────┤
114 │\f │ form-feed │
115 ├───┼─────────────────┤
116 │\r │ carriage return │
117 └───┴─────────────────┘
118 If not given, the value of the environment variable MPC_FORMAT
120 is used.
121 --wait Wait for operation to finish (e.g. database update).
123 --range=[START]:[END]
125 Operate on a range (e.g. when loading a playlist). START is the
126 first index of the range, END is the first index after the range
127 (i.e. excluding). START and END may be omitted, making the
128 range open to that end. Indexes start with zero.
129 -q, --quiet, --no-status
131 Prevents the current song status from being printed on comple‐
132 tion of some of the commands.
133 --verbose
135 Verbose output.
136 --host=HOST
138 The MPD server to connect to. This can be a hostname, IPv4/IPv6
139 address, an absolute path (i.e. local socket) or a name starting
140 with @ (i.e. an abstract socket, Linux only).
141 To use a password, provide a value of the form "password@host".
143 If not given, the value of the environment variable MPD_HOST is
145 used.
146 --port=PORT, -p PORT
148 The TCP port of the MPD server to connect to.
149 If not given, the value of the environment variable MPD_PORT is
151 used.
152
154 Commands can be used from the least unambiguous prefix (e.g insert or
155 ins).
156 Player Commands
158 consume <on|off> - Toggle consume mode if state (on
159 or off) is not specified.
160 crossfade [<seconds>] - Gets and sets the current amount of
162 crossfading between songs (0 disables crossfading).
163 current [--wait] - Show the currently playing song. With
165 --wait, mpc waits until the song changes (or until playback is
166 started/stopped) before it queries the current song from the
167 server.
168 queued - Show the currently queued (next) song.
170 mixrampdb [<db>] - Gets and sets the volume level at which
172 songs with MixRamp tags will be overlapped. This disables the
173 fading of the crossfade command and simply mixes the songs.
174 -50.0 will effectively remove any gaps, 0.0 will mash tracks
175 together. The amount of overlap is limited by the audio_buf‐
176 fer_size MPD configuration parameter.
177 mixrampdelay [<seconds>] - Gets and sets the current amount
179 of extra delay added to the value computed from the MixRamp
180 tags. (A negative value disables overlapping with MixRamp tagqs
181 and restores the previous value of crossfade).
182 next - Starts playing next song on queue.
184 pause - Pauses playing.
186 play <position> - Starts playing the song-number
188 specified. If none is specified, plays number 1.
189 prev - Starts playing previous song.
191 random <on|off> - Toggle random mode if state (on
193 or off) is not specified.
194 repeat <on|off> - Toggle repeat mode if state (on
196 or off) is not specified.
197 replaygain [<off|track|album>] - Sets the replay gain mode.
199 Without arguments, it prints the replay gain mode.
200 single <on|off> - Toggle single mode if state (on
202 or off) is not specified.
203 seek [+-][<HH:MM:SS>] or <[+-]<0-100>%> - Seeks by hour,
205 minute or seconds, hours or minutes can be omitted. If seeking
206 by percentage, seeks within the current song in the specified
207 manner. If a + or - is used, the seek is done relative to the
208 current song position. Absolute seeking by default.
209 seekthrough [+-][<HH:MM:SS>] - Seeks by hour,
211 minute or seconds, hours or minutes can be omitted, relatively
212 to the current position. If the duration exceeds the limit of
213 the current song, the seek command proceeds to seek through the
214 playlist until the duration is reached. If a + is used, the
215 seek is forward. If a - is used, the seek is backward. Forward
216 seeking by default.
217 stop - Stops playing.
219 toggle - Toggles between play and pause. If stopped starts
221 playing. Does not support start playing at song number (use
222 play).
223 Queue Commands
225 add <file> - Adds a song from the music database to the
226 queue. Can also read input from pipes. Use "mpc add /" to add
227 all files to the queue.
228 insert <file> - The insert command works similarly to
230 add except it adds song(s) after the currently playing one,
231 rather than at the end. When random mode is enabled, the new
232 song is queued after the current song.
233 clear - Empties the queue.
235 crop - Remove all songs except for the currently playing
237 song.
238 del <songpos> - Removes a queue number from the queue. Can
240 also read input from pipes (0 deletes the current playing song).
241 mv, move <from> <to> - Moves song at position <from> to the
243 position <to> in the queue.
244 searchplay <type> <query> [<type> <query>]... - Search the
246 queue for a matching song and play it.
247 shuffle - Shuffles all songs on the queue.
249 Playlist Commands
251 load <file> - Loads <file> as queue. The option --range may be used to
252 load only a portion of the file (requires libmpdclient 2.16).
253 lsplaylists: - Lists available playlists.
255 playlist [<playlist>] - Lists all songs in <playlist>. If
257 no <playlist> is specified, lists all songs in the current
258 queue.
259 rm <file> - Deletes a specific playlist.
261 save <file> - Saves playlist as <file>.
263 Database Commands
265 listall [<file>] - Lists <file> from database. If no
266 <file> is specified, lists all songs in the database.
267 ls [<directory>] - Lists all files/folders in
269 <directory>. If no <directory> is specified, lists all files in
270 music directory.
271 search <type> <query> [<type> <query>]... - Searches for
273 substrings in song tags. Any number of tag type and query com‐
274 binations can be specified. Possible tag types are: artist,
275 album, title, track, name, genre, date, composer, performer,
276 comment, disc, filename, or any (to match any tag).
277 search <expression> - Searches with a filter expression, e.g. mpc
279 search '((artist == "Kraftwerk") AND (title == "Metall auf Metall"))'.
280 Check the MPD protocol documentation for details. This syntax can be
281 used with find andd findadd as well. (Requires libmpdclient 2.16 and
282 MPD 0.21)
283 find <type> <query> [<type> <query>]... - Same as search,
285 but tag values must match <query>s exactly instead of doing a
286 substring match.
287 findadd <type> <query> [<type> <query>]... - Same as find,
289 but add the result to the current queue instead of printing
290 them.
291 list <type> [<type> <query>]... - Return a list of all tags
293 of given tag <type>. Optional search <type>s/<query>s limit
294 results in a way similar to search.
295 stats - Displays statistics about MPD.
297 update [--wait] [<path>] - Scans for updated files in the
299 music directory. The optional parameter <path> (relative to the
300 music directory) may limit the scope of the update.
301 With --wait, mpc waits until MPD has finished the update.
303 rescan [--wait] [<path>] - Like update, but also rescans
305 unmodified files.
306 Mount Commands
308 mount - Lists all mounts.
309 mount <uri> <storage> - Create a new mount.
311 unmount <uri> - Remove a mount.
313 Sticker Commands
315 The sticker command allows you to get and set song stickers.
316 sticker <file> set <key> <value> - Set the value of a song
318 sticker.
319 sticker <file> get <key> - Print the value of a song
321 sticker.
322 sticker <file> list - List all stickers of a song.
324 sticker <file> delete <key> - Delete a song sticker.
326 sticker <dir> find <key> - Search for stickers with the
328 specified name, below the specified directory.
329 Output Commands
331 volume [+-]<num> - Sets the volume to <num> (0-100). If
332 + or - is used, then it adjusts the volume relative to the cur‐
333 rent volume.
334 outputs - Lists all available outputs
336 disable [only] <output # or name> [...] - Disables the
338 output(s); a list of one or more names or numbers is required.
339 If "only" is the first argument, all other outputs are enabled.
340 enable [only] <output # or name> [...] - Enables the
342 output(s); a list of one or more names or numbers is required.
343 If "only" is the first argument, all other outputs are disabled.
344 toggleoutput <output # or name> [...] - Changes the
346 status for the given output(s); a list of one or more names or
347 numbers is required.
348 Client-to-client Commands
350 channels - List the channels that other clients have
351 subscribed to.
352 sendmessage <channel> <message> - Send a message to the
354 specified channel.
355 waitmessage <channel> - Wait for at least one message on
357 the specified channel.
358 subscribe <channel> - Subscribe to the specified channel
360 and continuously receive messages.
361 Other Commands
363 idle [events] - Waits until an event occurs. Prints a list
364 of event names, one per line. See the MPD protocol documenta‐
365 tion for further information.
366 If you specify a list of events, only these events are consid‐
368 ered.
369 idleloop [events] - Similar to idle, but
371 re-enters "idle" state after events have been printed.
372 If you specify a list of events, only these events are consid‐
374 ered.
375 version - Reports the version of MPD.
377
379 All environment variables are overridden by any values specified via
380 command line switches.
381 MPC_FORMAT
383 Configure the format used to display songs. See option
384 --format.
385 MPD_HOST
387 The MPD server to connect to. See option --host.
388 MPD_PORT
390 The TCP port of the MPD server to connect to. See option
391 --port.
392
394 Report bugs on https://github.com/MusicPlayerDaemon/mpc/issues
395 Since MPD uses UTF-8, mpc needs to convert characters to the charset
397 used by the local system. If you get character conversion errors when
398 you're running mpc you probably need to set up your locale. This is
399 done by setting any of the LC_CTYPE, LANG or LC_ALL environment vari‐
400 ables (LC_CTYPE only affects character handling).
401
403 mpd(1)
404
406 See
407 https://raw.githubusercontent.com/MusicPlayerDaemon/mpc/master/AUTHORS
408
410 Max Kellermann
411
413 Copyright 2003-2018 The Music Player Daemon Project
4140.33 Jul 28, 2020 MPC(1)