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 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 The default is playlist browser, i.e. the "Tab" key cycles only between
92 those two pages.
93 library-page-tags = TAG1 TAG2 ... - A list of tags to group the library
95 page. The default is artist album.
96 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 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 scroll-offset = NUM - Keep at least NUM lines above and below the cur‐
106 sor on list windows, if possible.
107 find-show-last = yes|no - Show the most recent query instead of a blank
109 line for a find.
110 find-wrap = yes|no - Wrapped find mode.
112 wrap-around = yes|no - Wrapped cursor movement.
114 bell-on-wrap = yes|no - Ring bell when find wraps around.
116 audible-bell = yes|no - Sound audible bell on alerts.
118 visible-bell = yes|no - Visible bell on alerts.
120 crossfade-time = CROSSFADE TIME - Default crossfade time in seconds.
122 seek-time = NUM - Seek forward/backward by NUM seconds.
124 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 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 en‐
130 try which begins with "m".
131 lyrics-autosave = yes|no - Automatically save lyrics after receiving
133 them.
134 lyrics-show-plugin = yes|no - Show the name of the plugin used to re‐
136 ceive lyrics on the lyrics screen.
137 text-editor = EDITOR - The text editor used for editing lyrics.
139 text-editor-ask = yes|no - Ask before starting an editor.
141 chat-prefix = PREFIX - Prefix messages send with the chat screen with
143 PREFIX. By default they are prefixed with the current user name en‐
144 closed by < and > and a space (i.e. "<name> ").
145 second-column = yes|no - Display song length in a second column.
147 Display
149 welcome-screen-list = yes|no - Show a list of the screens in the top
150 line.
151 wide-cursor = yes|no - Make the cursor as wide as the screen.
153 hardware-cursor = yes|no - Use the terminal's hardware cursor instead
155 of inverse colors.
156 hide-cursor = NUM - Hide the playlist cursor after NUM seconds of inac‐
158 tivity.
159 scroll = yes|no - Scroll the title if it is too long for the screen.
161 scroll-sep = STRING - the separator to show at the end of the scrolling
163 title.
164 list-format = SONG FORMAT - The format used to display songs in the
166 main window.
167 search-format = SONG FORMAT - The format used to display songs in the
169 search window. Default is to use list-format.
170 status-format = SONG FORMAT - The format used to display songs on the
172 status line.
173 status-message-time = TIME - The time, in seconds, for which status
175 messages will be displayed.
176 display-time = yes|no - Display the time in the status bar when idle.
178 timedisplay-type = elapsed|remaining|none - Sets whether to display re‐
180 maining or elapsed time in the status window. Default is elapsed.
181 none doesn't show the time at all.
182 visible-bitrate = yes|no - Show the bitrate in the status bar when
184 playing a stream.
185 set-xterm-title = yes|no - Change the XTerm title (ncmpc will not re‐
187 store the title).
188 xterm-title-format = SONG FORMAT - The format used to for the xterm ti‐
190 tle when ncmpc is playing.
191 Colors
193 enable-colors = yes|no - Enable/disable colors. Defaults to yes.
194 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 Example:
202 color list = cyan
204 Modern terminals support up to 256 colors, but they are not standard‐
206 ized. You can select them by specifying the number. Example:
207 color title = 42
209 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 color title = white/blue
215 color title = /blue
216 The color none uses the terminal's default color.
218 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 Example:
225 color alert = red blink
227 color background = COLOR - Set the default background color.
229 color title = COLOR[,ATTRIBUTE]... - Set the text color and attributes
231 for the title row, which displays the page names.
232 color title-bold = COLOR[,ATTRIBUTE]... - Like title, but refers to em‐
234 phasized parts of the title row, i.e. the hot keys for switching to a
235 specific page.
236 color line = COLOR - Set the color of the line on the second row.
238 color line-flags = COLOR[,ATTRIBUTE]... - Set the text color used to
240 indicate mpd flags on the second row.
241 color list = COLOR[,ATTRIBUTE]... - Set the text color in the main area
243 of ncmpc.
244 color list-bold = COLOR[,ATTRIBUTE]... - Set the bold text color in the
246 main area of ncmpc.
247 color browser-directory = COLOR[,ATTRIBUTE]... - Set the text color
249 used to display directories in the browser window.
250 color browser-playlist = COLOR[,ATTRIBUTE]... - Set the text color used
252 to display playlists in the browser window.
253 color progressbar = COLOR[,ATTRIBUTE]... - Set the color of the
255 progress indicator.
256 color progressbar-background = COLOR[,ATTRIBUTE]... - Set the color of
258 the progress indicator background.
259 color status-state = COLOR[,ATTRIBUTE]... - Set the text color used to
261 display mpd status in the status window.
262 color status-song = COLOR[,ATTRIBUTE]... - Set the text color used to
264 display song names in the status window.
265 color status-time = COLOR[,ATTRIBUTE]... - Set the text color used to
267 display time the status window.
268 color alert = COLOR[,ATTRIBUTE]... - Set the text color used to display
270 alerts in the status window.
271 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
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 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
288 Format of song display for status and the list window. The metadata
289 delimiters are: %artist%, %albumartist%, %composer%, %performer%, %ti‐
290 tle%, %album%, %shortalbum%, %track%, %disc, %genre%, %name%, %time%,
291 %date%, %file%, %shortfile%.
292 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 Some useful examples for format are:
300 "%file%"
302 and:
304 "[[%artist% - ]%title%]|%file%"
306 Another one is:
308 "[%artist%|(artist n/a)] - [%title%|(title n/a)]"
310
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
321 Report bugs on https://github.com/MusicPlayerDaemon/ncmpc/issues
322 Note ---
324 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
332 mpd(1), mpc(1), locale(5), locale(7)
333
335 Max Kellermann
336
338 Copyright 2004-2021 The Music Player Daemon Project
3390.45 Sep 23, 2021 NCMPC(1)