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

KEYS

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

SONG FORMAT

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

CHAT PROTOCOL

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

BUGS

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

SEE ALSO

326       mpd(1), mpc(1), locale(5), locale(7)
327

AUTHOR

329       Max Kellermann
330
332       Copyright (C) 2004-2019 The Music Player Daemon Project
333
334
335
336
3370.36                             Nov 12, 2019                         NCMPC(1)
Impressum