1NCMPC(1) ncmpc NCMPC(1)
2
3
4
6 ncmpc - ncmpc Documentation
7
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
26 ncmpc [options]
27
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
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
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
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
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
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
326 mpd(1), mpc(1), locale(5), locale(7)
327
329 Max Kellermann
330
332 Copyright (C) 2004-2019 The Music Player Daemon Project
333
334
335
336
3370.36 Jan 29, 2020 NCMPC(1)