1NCMPC(1) ncmpc NCMPC(1)
2
6 ncmpc - ncmpc Documentation
7
9 ncmpc is a command-line client for the Music Player Daemon (MPD).
10 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 ncmpc --host=musicserver --port=44000
16 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 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 -V, --version
33 Display version information and build-time configuration.
34 -c, --colors
36 Enable colors.
37 -C, --no-colors
39 Disable colors.
40 -m, --mouse
42 Enable mouse.
43 --host=HOST
45 The MPD host to connect to.
46 --port=PORT, -p PORT
48 The port to connect to.
49 -P, --password=PASSWORD
51 Use password when connecting.
52 -f, --config=FILE
54 Read configuration from file.
55 -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 Connection
68 host = HOST - The MPD host to connect to.
69 port = PORT - The port to connect to.
71 password = PASSWORD - Use password when connecting.
73 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 Interface
81 enable-mouse = yes|no - Enable mouse support (if enabled at compile
82 time).
83 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 library-page-tags = TAG1 TAG2 ... - A list of tags to group the library
90 page. The default is artist album.
91 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 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 scroll-offset = NUM - Keep at least NUM lines above and below the cur‐
101 sor on list windows, if possible.
102 find-show-last = yes|no - Show the most recent query instead of a blank
104 line for a find.
105 find-wrap = yes|no - Wrapped find mode.
107 wrap-around = yes|no - Wrapped cursor movement.
109 bell-on-wrap = yes|no - Ring bell when find wraps around.
111 audible-bell = yes|no - Sound audible bell on alerts.
113 visible-bell = yes|no - Visible bell on alerts.
115 crossfade-time = CROSSFADE TIME - Default crossfade time in seconds.
117 seek-time = NUM - Seek forward/backward by NUM seconds.
119 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 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 lyrics-autosave = yes|no - Automatically save lyrics after receiving
128 them.
129 lyrics-show-plugin = yes|no - Show the name of the plugin used to
131 receive lyrics on the lyrics screen.
132 text-editor = EDITOR - The text editor used for editing lyrics.
134 text-editor-ask = yes|no - Ask before starting an editor.
136 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 second-column = yes|no - Display song length in a second column.
142 Display
144 welcome-screen-list = yes|no - Show a list of the screens in the top
145 line.
146 wide-cursor = yes|no - Make the cursor as wide as the screen.
148 hardware-cursor = yes|no - Use the terminal's hardware cursor instead
150 of inverse colors.
151 hide-cursor = NUM - Hide the playlist cursor after NUM seconds of inac‐
153 tivity.
154 scroll = yes|no - Scroll the title if it is too long for the screen.
156 scroll-sep = STRING - the separator to show at the end of the scrolling
158 title.
159 list-format = SONG FORMAT - The format used to display songs in the
161 main window.
162 search-format = SONG FORMAT - The format used to display songs in the
164 search window. Default is to use list-format.
165 status-format = SONG FORMAT - The format used to display songs on the
167 status line.
168 status-message-time = TIME - The time, in seconds, for which status
170 messages will be displayed.
171 display-time = yes|no - Display the time in the status bar when idle.
173 timedisplay-type = elapsed/remaining - Sets whether to display remain‐
175 ing or elapsed time in the status window. Default is elapsed.
176 visible-bitrate = yes|no - Show the bitrate in the status bar when
178 playing a stream.
179 set-xterm-title = yes|no - Change the XTerm title (ncmpc will not
181 restore the title).
182 xterm-title-format = SONG FORMAT - The format used to for the xterm
184 title when ncmpc is playing.
185 Colors
187 enable-colors = yes|no - Enable/disable colors. Defaults to yes.
188 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 Example:
196 color list = cyan
198 Modern terminals support up to 256 colors, but they are not standard‐
200 ized. You can select them by specifying the number. Example:
201 color title = 42
203 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 color title = white/blue
209 color title = /blue
210 The color none uses the terminal's default color.
212 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 Example:
219 color alert = red blink
221 color background = COLOR - Set the default background color.
223 color title = COLOR[,ATTRIBUTE]... - Set the text color and attributes
225 for the title row, which displays the page names.
226 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 color line = COLOR - Set the color of the line on the second row.
232 color line-flags = COLOR[,ATTRIBUTE]... - Set the text color used to
234 indicate mpd flags on the second row.
235 color list = COLOR[,ATTRIBUTE]... - Set the text color in the main area
237 of ncmpc.
238 color list-bold = COLOR[,ATTRIBUTE]... - Set the bold text color in the
240 main area of ncmpc.
241 color browser-directory = COLOR[,ATTRIBUTE]... - Set the text color
243 used to display directories in the browser window.
244 color browser-playlist = COLOR[,ATTRIBUTE]... - Set the text color used
246 to display playlists in the browser window.
247 color progressbar = COLOR[,ATTRIBUTE]... - Set the color of the
249 progress indicator.
250 color progressbar-background = COLOR[,ATTRIBUTE]... - Set the color of
252 the progress indicator background.
253 color status-state = COLOR[,ATTRIBUTE]... - Set the text color used to
255 display mpd status in the status window.
256 color status-song = COLOR[,ATTRIBUTE]... - Set the text color used to
258 display song names in the status window.
259 color status-time = COLOR[,ATTRIBUTE]... - Set the text color used to
261 display time the status window.
262 color alert = COLOR[,ATTRIBUTE]... - Set the text color used to display
264 alerts in the status window.
265 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 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 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 Some useful examples for format are:
294 "%file%"
296 and:
298 "[[%artist% - ]%title%]|%file%"
300 Another one is:
302 "[%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 Note ---
318 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
3330.36 Nov 12, 2019 NCMPC(1)