1MPC(1)                                mpc                               MPC(1)
2
3
4

NAME

6       mpc - mpc Documentation
7

DESCRIPTION

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

SYNOPSIS

15          mpc [options] <command> [<arguments>]
16

OPTIONS

18       -f, --format
19              Configure the format used to display songs.
20
21              The metadata delimiters are:
22
23                       ┌───────────────┬────────────────────────────┐
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
66
67                       │%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
87              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
95                                   ┌───┬─────────────────┐
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
119              If not given, the value of the environment  variable  MPC_FORMAT
120              is used.
121
122       --wait Wait for operation to finish (e.g. database update).
123
124       --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
130       -q, --quiet, --no-status
131              Prevents the current song status from being printed  on  comple‐
132              tion of some of the commands.
133
134       --verbose
135              Verbose output.
136
137       --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
142              To use a password, provide a value of the form "password@host".
143
144              If  not given, the value of the environment variable MPD_HOST is
145              used.
146
147       --port=PORT, -p PORT
148              The TCP port of the MPD server to connect to.
149
150              If not given, the value of the environment variable MPD_PORT  is
151              used.
152

COMMANDS

154       Commands  can  be used from the least unambiguous prefix (e.g insert or
155       ins).
156
157   Player Commands
158       consume <on|off> - Toggle consume mode if state (on
159              or off) is not specified.
160
161       crossfade [<seconds>] - Gets and sets the current amount of
162              crossfading between songs (0 disables crossfading).
163
164       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
169       queued - Show the currently queued (next) song.
170
171       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
178       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
183       next - Starts playing next song on queue.
184
185       pause - Pauses playing.
186
187       play <position> - Starts playing the song-number
188              specified. If none is specified, plays number 1.
189
190       prev - Starts playing previous song.
191
192       random <on|off> - Toggle random mode if state (on
193              or off) is not specified.
194
195       repeat <on|off> - Toggle repeat mode if state (on
196              or off) is not specified.
197
198       replaygain [<off|track|album>] - Sets the replay gain mode.
199              Without arguments, it prints the replay gain mode.
200
201       single <on|off> - Toggle single mode if state (on
202              or off) is not specified.
203
204       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
210       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
218       stop - Stops playing.
219
220       toggle - Toggles between play and pause. If stopped starts
221              playing.  Does not support start playing  at  song  number  (use
222              play).
223
224   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
229       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
234       clear - Empties the queue.
235
236       crop - Remove all songs except for the currently playing
237              song.
238
239       del <songpos> - Removes a queue number from the queue. Can
240              also read input from pipes (0 deletes the current playing song).
241
242       mv, move <from> <to> - Moves song at position <from> to the
243              position <to> in the queue.
244
245       searchplay <type> <query> [<type> <query>]... - Search the
246              queue for a matching song and play it.
247
248       shuffle - Shuffles all songs on the queue.
249
250   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
254       lsplaylists: - Lists available playlists.
255
256       playlist [<playlist>] - Lists all songs in <playlist>. If
257              no  <playlist>  is  specified,  lists  all  songs in the current
258              queue.
259
260       rm <file> - Deletes a specific playlist.
261
262       save <file> - Saves playlist as <file>.
263
264   Database Commands
265       listall [<file>] - Lists <file> from database.  If no
266              <file> is specified, lists all songs in the database.
267
268       ls [<directory>] - Lists all files/folders in
269              <directory>. If no <directory> is specified, lists all files  in
270              music directory.
271
272       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
278       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
284       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
288       findadd <type> <query> [<type> <query>]... - Same as find,
289              but  add  the  result  to  the current queue instead of printing
290              them.
291
292       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
296       stats - Displays statistics about MPD.
297
298       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
302              With --wait, mpc waits until MPD has finished the update.
303
304       rescan [--wait] [<path>] - Like update, but also rescans
305              unmodified files.
306
307   Mount Commands
308       mount - Lists all mounts.
309
310       mount <uri> <storage> - Create a new mount.
311
312       unmount <uri> - Remove a mount.
313
314   Sticker Commands
315       The sticker command allows you to get and set song stickers.
316
317       sticker <file> set <key> <value> - Set the value of a song
318              sticker.
319
320       sticker <file> get <key> - Print the value of a song
321              sticker.
322
323       sticker <file> list - List all stickers of a song.
324
325       sticker <file> delete <key> - Delete a song sticker.
326
327       sticker <dir> find <key> - Search for stickers with the
328              specified name, below the specified directory.
329
330   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
335       outputs - Lists all available outputs
336
337       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
341       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
345       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
349   Client-to-client Commands
350       channels - List the channels that other clients have
351              subscribed to.
352
353       sendmessage <channel> <message> - Send a message to the
354              specified channel.
355
356       waitmessage <channel> - Wait for at least one message on
357              the specified channel.
358
359       subscribe <channel> - Subscribe to the specified channel
360              and continuously receive messages.
361
362   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
367              If  you  specify a list of events, only these events are consid‐
368              ered.
369
370       idleloop [events] - Similar to idle, but
371              re-enters "idle" state after events have been printed.
372
373              If you specify a list of events, only these events  are  consid‐
374              ered.
375
376       version - Reports the version of MPD.
377

ENVIRONMENT VARIABLES

379       All  environment  variables  are overridden by any values specified via
380       command line switches.
381
382       MPC_FORMAT
383              Configure  the  format  used  to  display  songs.   See   option
384              --format.
385
386       MPD_HOST
387              The MPD server to connect to.  See option --host.
388
389       MPD_PORT
390              The  TCP  port  of  the  MPD  server  to connect to.  See option
391              --port.
392

BUGS

394       Report bugs on https://github.com/MusicPlayerDaemon/mpc/issues
395
396       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

SEE ALSO

403       mpd(1)
404

AUTHOR

406       See
407       https://raw.githubusercontent.com/MusicPlayerDaemon/mpc/master/AUTHORS
408

AUTHOR

410       Max Kellermann
411
413       Copyright 2003-2018 The Music Player Daemon Project
414
415
416
417
4180.33                             Jul 28, 2020                           MPC(1)
Impressum