1NCMPC(1)                             ncmpc                            NCMPC(1)
2
3
4

NAME

6       ncmpc - ncmpc Documentation
7

DESCRIPTION

9       ncmpc is a command-line client for the Music Player Daemon (MPD).
10
11       By  default, ncmpc connects to the local MPD instance.  A different MPD
12       instance can be selected using the  command  line  options  --host  and
13       --port, or by setting the environment variables MPD_HOST and MPD_PORT:
14
15          ncmpc --host=musicserver --port=44000
16
17       You  can connect to a "local" socket by setting the host to a file path
18       (e.g. "/run/mpd/socket").  Abstract sockets can be used with a "@" pre‐
19       fix (e.g. "@mpd").
20
21       To  use  a  password with MPD, set MPD_HOST to password@host or use the
22       command line option --password.  Values from the command line  override
23       values from the environment.
24

SYNOPSIS

26          ncmpc [options]
27

OPTIONS

29       -?, --help
30              Display help.
31
32       -V, --version
33              Display version information and build-time configuration.
34
35       -c, --colors
36              Enable colors.
37
38       -C, --no-colors
39              Disable colors.
40
41       -m, --mouse
42              Enable mouse.
43
44       --host=HOST
45              The MPD host to connect to.
46
47       --port=PORT, -p PORT
48              The port to connect to.
49
50       -P, --password=PASSWORD
51              Use password when connecting.
52
53       -f, --config=FILE
54              Read configuration from file.
55
56       -k, --key-file=FILE
57              Read key bindings from file.
58

CONFIGURATION

60       When  ncmpc  starts  it  tries  to  read the user's configuration file,
61       $XDG_CONFIG_HOME/ncmpc/config (usually ~/.config/ncmpc/config).  If  no
62       user  configuration  file  is found then ncmpc tries to load the global
63       settings from $SYSCONFDIR/ncmpc/config (the actual path is displayed in
64       the  output  of  the  --version option).  An example configuration file
65       (config.sample) is shipped with ncmpc.
66
67   Connection
68       host = HOST - The MPD host to connect to.
69
70       port = PORT - The port to connect to.
71
72       password = PASSWORD - Use password when connecting.
73
74       timeout = TIMEOUT - Attempt to reconnect to mpd if a response to a com‐
75       mand  is not received within TIMEOUT seconds. Specifying a value in the
76       configuration file overrides the  "MPD_TIMEOUT"  environment  variable.
77       If no timeout is specified in the configuration file or in the environ‐
78       ment, the default is 5 seconds.
79
80   Interface
81       enable-mouse = yes|no - Enable mouse support  (if  enabled  at  compile
82       time).
83
84       screen-list  =  SCREEN1 SCREEN2... - A list of screens to cycle through
85       when using the commands screen-next (bound to  "Tab"  by  default)  and
86       screen-prev  ("Shift+Tab").  Valid choices, if enabled at compile time,
87       are:
88          help, playlist, browse,  library,  search,  lyrics,  outputs,  chat,
89          song, keydef
90
91       The default is playlist browser, i.e. the "Tab" key cycles only between
92       those two pages.
93
94       library-page-tags = TAG1 TAG2 ... - A list of tags to group the library
95       page.  The default is artist album.
96
97       search-mode  =  MODE  - Default search mode for the search screen. MODE
98       must be one of title, artist, album, filename, and artist+title, or  an
99       integer index (0 for title, 1 for artist etc.).
100
101       auto-center  = yes|no - Enable/disable auto center mode. When auto cen‐
102       ter mode is enabled ncmpc centers the current  track  in  the  playlist
103       window.
104
105       scroll-offset  = NUM - Keep at least NUM lines above and below the cur‐
106       sor on list windows, if possible.
107
108       find-show-last = yes|no - Show the most recent query instead of a blank
109       line for a find.
110
111       find-wrap = yes|no - Wrapped find mode.
112
113       wrap-around = yes|no - Wrapped cursor movement.
114
115       bell-on-wrap = yes|no - Ring bell when find wraps around.
116
117       audible-bell = yes|no - Sound audible bell on alerts.
118
119       visible-bell = yes|no - Visible bell on alerts.
120
121       crossfade-time = CROSSFADE TIME - Default crossfade time in seconds.
122
123       seek-time = NUM - Seek forward/backward by NUM seconds.
124
125       lyrics-timeout  =  NUM  -  Quits downloading lyrics of a song after the
126       timeout of NUM seconds is reached, if NUM is greater than zero.
127
128       jump-prefix-only = yes|no - When using the jump command, search for the
129       prefix  of  an  entry.   That  means typing "m" will start to the first
130       entry which begins with "m".
131
132       lyrics-autosave = yes|no - Automatically save  lyrics  after  receiving
133       them.
134
135       lyrics-show-plugin  =  yes|no  -  Show  the  name of the plugin used to
136       receive lyrics on the lyrics screen.
137
138       text-editor = EDITOR - The text editor used for editing lyrics.
139
140       text-editor-ask = yes|no - Ask before starting an editor.
141
142       chat-prefix = PREFIX - Prefix messages send with the chat  screen  with
143       PREFIX.   By  default  they  are  prefixed  with  the current user name
144       enclosed by < and > and a space (i.e. "<name> ").
145
146       second-column = yes|no - Display song length in a second column.
147
148   Display
149       welcome-screen-list = yes|no - Show a list of the screens  in  the  top
150       line.
151
152       wide-cursor = yes|no - Make the cursor as wide as the screen.
153
154       hardware-cursor  =  yes|no - Use the terminal's hardware cursor instead
155       of inverse colors.
156
157       hide-cursor = NUM - Hide the playlist cursor after NUM seconds of inac‐
158       tivity.
159
160       scroll = yes|no - Scroll the title if it is too long for the screen.
161
162       scroll-sep = STRING - the separator to show at the end of the scrolling
163       title.
164
165       list-format = SONG FORMAT - The format used to  display  songs  in  the
166       main window.
167
168       search-format  =  SONG FORMAT - The format used to display songs in the
169       search window. Default is to use list-format.
170
171       status-format = SONG FORMAT - The format used to display songs  on  the
172       status line.
173
174       status-message-time  =  TIME  -  The time, in seconds, for which status
175       messages will be displayed.
176
177       display-time = yes|no - Display the time in the status bar when idle.
178
179       timedisplay-type = elapsed|remaining|none -  Sets  whether  to  display
180       remaining  or  elapsed  time in the status window.  Default is elapsed.
181       none doesn't show the time at all.
182
183       visible-bitrate = yes|no - Show the bitrate  in  the  status  bar  when
184       playing a stream.
185
186       set-xterm-title  =  yes|no  -  Change  the  XTerm title (ncmpc will not
187       restore the title).
188
189       xterm-title-format = SONG FORMAT - The format used  to  for  the  xterm
190       title when ncmpc is playing.
191
192   Colors
193       enable-colors = yes|no - Enable/disable colors.  Defaults to yes.
194
195       The colors used by ncmpc can be customized.  The color directive can be
196       used to change how a certain style looks.  It can contain a text  color
197       and attributes.  The following standard colors can be specified by name
198       (official reference):
199          black, red, green, yellow, blue, magenta, cyan, white
200
201       Example:
202
203          color list = cyan
204
205       Modern terminals support up to 256 colors, but they are  not  standard‐
206       ized.  You can select them by specifying the number.  Example:
207
208          color title = 42
209
210       The background color can be specified after the text color separated by
211       a slash.  You can omit the text color if you want to  change  only  the
212       background color:
213
214          color title = white/blue
215          color title = /blue
216
217       The color none uses the terminal's default color.
218
219       Attributes  can  be  used to modify the font appearance.  The following
220       attributes can be specified (official reference), though many  of  them
221       are not supported by prevalent terminals:
222          standout, underline, reverse, blink, dim, bold
223
224       Example:
225
226          color alert = red blink
227
228       color background = COLOR - Set the default background color.
229
230       color  title = COLOR[,ATTRIBUTE]... - Set the text color and attributes
231       for the title row, which displays the page names.
232
233       color title-bold = COLOR[,ATTRIBUTE]... - Like  title,  but  refers  to
234       emphasized parts of the title row, i.e. the hot keys for switching to a
235       specific page.
236
237       color line = COLOR - Set the color of the line on the second row.
238
239       color line-flags = COLOR[,ATTRIBUTE]... - Set the text  color  used  to
240       indicate mpd flags on the second row.
241
242       color list = COLOR[,ATTRIBUTE]... - Set the text color in the main area
243       of ncmpc.
244
245       color list-bold = COLOR[,ATTRIBUTE]... - Set the bold text color in the
246       main area of ncmpc.
247
248       color  browser-directory  =  COLOR[,ATTRIBUTE]...  - Set the text color
249       used to display directories in the browser window.
250
251       color browser-playlist = COLOR[,ATTRIBUTE]... - Set the text color used
252       to display playlists in the browser window.
253
254       color  progressbar  =  COLOR[,ATTRIBUTE]...  -  Set  the  color  of the
255       progress indicator.
256
257       color progressbar-background = COLOR[,ATTRIBUTE]... - Set the color  of
258       the progress indicator background.
259
260       color  status-state = COLOR[,ATTRIBUTE]... - Set the text color used to
261       display mpd status in the status window.
262
263       color status-song = COLOR[,ATTRIBUTE]... - Set the text color  used  to
264       display song names in the status window.
265
266       color  status-time  = COLOR[,ATTRIBUTE]... - Set the text color used to
267       display time the status window.
268
269       color alert = COLOR[,ATTRIBUTE]... - Set the text color used to display
270       alerts in the status window.
271
272       colordef  COLOR  =  R,  G, B - Redefine any of the base colors. The RGB
273       values must be integer values between 0 and 1000.  Note: Only some ter‐
274       minals allow redefinitions of colors!
275

KEYS

277       When  ncmpc  starts it tries to read user-defined key bindings from the
278       $XDG_CONFIG_HOME/ncmpc/keys (usually ~/.config/ncmpc/keys) file.  If no
279       user-defined key bindings are found then ncmpc tries to load the global
280       key bindings from $SYSCONFDIR/ncmpc/keys (the actual path is  displayed
281       on the help screen).
282
283       You  can view ncmpc's key bindings by pressing '1' (help) when ncmpc is
284       running.  To edit key bindings press 'K' and  use  the  key  editor  in
285       ncmpc.
286

SONG FORMAT

288       Format  of  song  display for status and the list window.  The metadata
289       delimiters  are:  %artist%,  %albumartist%,  %composer%,   %performer%,
290       %title%,   %album%,  %shortalbum%,  %track%,  %disc,  %genre%,  %name%,
291       %time%, %date%, %file%, %shortfile%.
292
293       The [] operators are used to group output such  that  if  none  of  the
294       metadata delimiters between [ and ] are matched, then none of the char‐
295       acters between [ and ] are output; literal text is  always  output.   &
296       and  | are logical operators for and and or.  # is used to escape char‐
297       acters.
298
299       Some useful examples for format are:
300
301          "%file%"
302
303       and:
304
305          "[[%artist% - ]%title%]|%file%"
306
307       Another one is:
308
309          "[%artist%|(artist n/a)] - [%title%|(title n/a)]"
310

CHAT PROTOCOL

312       If  ncmpc  has  been  compiled  with  "chat"  support,  it   uses   the
313       client-to-client  protocol  available in MPD 0.17 or higher to communi‐
314       cate with other clients.  In order to receive messages it subscribes to
315       the  channel  with the name "chat", and displays any message sent there
316       as-is.  When the user enters a message, it is  first  with  the  prefix
317       specified  by  the chat-prefix option (or the default prefix), and then
318       sent to the "chat" channel for others to read.
319

BUGS

321       Report bugs on https://github.com/MusicPlayerDaemon/ncmpc/issues
322
323       Note ---
324
325       Since MPD uses UTF-8, ncmpc needs to convert characters to the  charset
326       used  by the local system.  If you get character conversion errors when
327       your running ncmpc you probably need to set up your  locale.   This  is
328       done  by  setting any of the LC_CTYPE, LANG or LC_ALL environment vari‐
329       ables (LC_CTYPE only affects character handling).
330

SEE ALSO

332       mpd(1), mpc(1), locale(5), locale(7)
333

AUTHOR

335       Max Kellermann
336
338       Copyright 2004-2021 The Music Player Daemon Project
339
340
341
342
3430.45                             Feb 18, 2021                         NCMPC(1)
Impressum