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 of song display for status and  the  queue.
20              The metadata delimiters are:
21
22                       ┌───────────────┬────────────────────────────┐
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
66
67                       │%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
77              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
85                                   ┌───┬─────────────────┐
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
109       --wait Wait for operation to finish (e.g. database update).
110
111       -q, --quiet, --no-status
112              Prevents the current song status from being printed  on  comple‐
113              tion of some of the commands.
114
115       --verbose
116              Verbose output.
117
118       --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
123              To use a password, provide a value of the form "password@host".
124
125              If  you  specify an absolute path, mpc attempts a connection via
126              Unix Domain Socket.
127
128       --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

COMMANDS

134       Commands can be used from the least unambiguous prefix (e.g  insert  or
135       ins).
136
137   Player Commands
138       consume <on|off> - Toggle consume mode if state (on
139              or off) is not specified.
140
141       crossfade [<seconds>] - Gets and sets the current amount of
142              crossfading between songs (0 disables crossfading).
143
144       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
149       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
156       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
161       next - Starts playing next song on queue.
162
163       pause - Pauses playing.
164
165       play <position> - Starts playing the song-number
166              specified. If none is specified, plays number 1.
167
168       prev - Starts playing previous song.
169
170       random <on|off> - Toggle random mode if state (on
171              or off) is not specified.
172
173       repeat <on|off> - Toggle repeat mode if state (on
174              or off) is not specified.
175
176       replaygain [<off|track|album>] - Sets the replay gain mode.
177              Without arguments, it prints the replay gain mode.
178
179       single <on|off> - Toggle single mode if state (on
180              or off) is not specified.
181
182       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
188       stop - Stops playing.
189
190       toggle - Toggles between play and pause. If stopped starts
191              playing.  Does not support start playing  at  song  number  (use
192              play).
193
194   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
199       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
204       clear - Empties the queue.
205
206       crop - Remove all songs except for the currently playing
207              song.
208
209       del <songpos> - Removes a queue number from the queue. Can
210              also read input from pipes (0 deletes the current playing song).
211
212       mv, move <from> <to> - Moves song at position <from> to the
213              position <to> in the queue.
214
215       searchplay <type> <query> [<type> <query>]... - Search the
216              queue for a matching song and play it.
217
218       shuffle - Shuffles all songs on the queue.
219
220   Playlist Commands
221       load <file>: - Loads <file> as queue.
222
223       lsplaylists: - Lists available playlists.
224
225       playlist [<playlist>] - Lists all songs in <playlist>. If
226              no <playlist> is specified,  lists  all  songs  in  the  current
227              queue.
228
229       rm <file> - Deletes a specific playlist.
230
231       save <file> - Saves playlist as <file>.
232
233   Database Commands
234       listall [<file>] - Lists <file> from database.  If no
235              <file> is specified, lists all songs in the database.
236
237       ls [<directory>] - Lists all files/folders in
238              <directory>.  If no <directory> is specified, lists all files in
239              music directory.
240
241       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
247       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
251       findadd <type> <query> [<type> <query>]... - Same as find,
252              but add the result to the  current  queue  instead  of  printing
253              them.
254
255       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
259       stats - Displays statistics about MPD.
260
261       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
265              With --wait, mpc waits until MPD has finished the update.
266
267       rescan [--wait] [<path>] - Like update, but also rescans
268              unmodified files.
269
270   Sticker Commands
271       The sticker command allows you to get and set song stickers.
272
273       sticker <file> set <key> <value> - Set the value of a song
274              sticker.
275
276       sticker <file> get <key> - Print the value of a song
277              sticker.
278
279       sticker <file> list - List all stickers of a song.
280
281       sticker <file> delete <key> - Delete a song sticker.
282
283       sticker <dir> find <key> - Search for stickers with the
284              specified name, below the specified directory.
285
286   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
291       outputs - Lists all available outputs
292
293       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
297       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
301       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
305   Client-to-client Commands
306       channels - List the channels that other clients have
307              subscribed to.
308
309       sendmessage <channel> <message> - Send a message to the
310              specified channel.
311
312       waitmessage <channel> - Wait for at least one message on
313              the specified channel.
314
315       subscribe <channel> - Subscribe to the specified channel
316              and continuously receive messages.
317
318   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
323              If you specify a list of events, only these events  are  consid‐
324              ered.
325
326       idleloop [events] - Similar to idle, but
327              re-enters "idle" state after events have been printed.
328
329              If  you  specify a list of events, only these events are consid‐
330              ered.
331
332       version - Reports the version of MPD.
333

ENVIRONMENT VARIABLES

335       All environment variables are overridden by any  values  specified  via
336       command line switches.
337
338       MPC_FORMAT
339              Specifies the format of song display for status and the queue.
340
341       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
346              If  the  server  requires  a password, it can be specified using
347              password@host in the MPD_HOST variable.
348
349       MPD_PORT
350              Specifies the port the MPD server is listening on.
351

BUGS

353       Report bugs on https://github.com/MusicPlayerDaemon/mpc/issues
354
355       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

SEE ALSO

362       mpd(1)
363

AUTHOR

365       See
366       https://raw.githubusercontent.com/MusicPlayerDaemon/mpc/master/AUTHORS
367

AUTHOR

369       Max Kellermann
370
372       Copyright (C) 2003-2017 The Music Player Daemon Project
373
374
375
376
3770.30                             Jul 18, 2018                           MPC(1)
Impressum