1ncmpc(1) ncmpc(1)
2
6 ncmpc - curses Music Player Daemon (MPD) client.
7
9 ncmpc [options]
10
12 ncmpc is a client for MPD, the Music Player Daemon. ncmpc connects to
13 a MPD running on a machine on the local network.
14 By default, ncmpc connects to localhost:6600. This can be changed
16 either at compile-time, or by exporting the MPD_HOST and MPD_PORT envi‐
17 ronment variables, or by the command line options --host and --port.
18 $ ncmpc --host=musicserver --port=44000
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 overrides
23 values from the environment.
24 Read more about MPD on http://www.musicpd.org
26
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 -M, --no-mouse
45 Disable mouse.
46 -h, --host=HOSTNAME
48 Specify MPD host.
49 -p, --port=PORT
51 Connect to server on PORT.
52 -P, --password=PASSWORD
54 Use password when connecting.
55 -f, --config=FILE
57 Read configuration from file.
58 -k, --key-file=FILE
60 Read key bindings from FILE.
61 Mandatory or optional arguments to long options are also mandatory or
63 optional for any corresponding short options.
64
66 When ncmpc starts it tries to read the user's configuration file,
67 ~/.ncmpc/config. If no user configuration file is found then ncmpc
68 tries to load the global settings from $SYSCONFDIR/ncmpc/config (the
69 actual path is displayed in the output of the --version option). An
70 example configuration file (config.sample) should be provided with
71 ncmpc.
72 Connection
77 host = HOST
78 Connect to mpd running on the specified host.
79 port = PORT
81 Connect to mpd on the specified port.
82 password = PASSWORD
84 Connect to mpd using the specified password.
85 timeout = TIMEOUT
87 Attempt to reconnect to mpd if a response to a command is not
88 received within TIMEOUT seconds. Specifying a value in the con‐
89 figuration file overrides the "MPD_TIMEOUT" environment vari‐
90 able. If no timeout is specified in the configuration file or in
91 the environment, the default is 5 seconds.
92 Interface
94 enable-mouse = yes|no
95 Enable mouse support (if enabled at compile time).
96 screen-list = SCREEN1 SCREEN2...
98 A list of screens to cycle through when using the previous/next
99 screen commands. Valid choices, if enabled at compile time, are
100 playlist, browse, artist, help, search, song, keydef, lyrics,
101 outputs, and chat.
102 search-mode = MODE
104 Default search mode for the search screen. MODE must be one of
105 title, artist, album, filename, and artist+title, or an interger
106 index (0 for title, 1 for artist etc.).
107 auto-center = yes|no
109 Enable/disable auto center mode. When auto center mode is
110 enabled ncmpc centers the current track in the playlist window.
111 scroll-offset = NUM
113 Keep at least NUM lines above and below the cursor on list win‐
114 dows, if possible.
115 find-show-last = yes|no
117 Show the most recent query instead of a blank line for a find.
118 find-wrap = yes|no
120 Wrapped find mode.
121 wrap-around = yes|no
123 Wrapped cursor movement.
124 bell-on-wrap = yes|no
126 Ring bell when find wraps around.
127 audible-bell = yes|no
129 Sound audible bell on alerts.
130 visible-bell = yes|no
132 Visible bell on alerts.
133 crossfade-time = CROSSFADE TIME
135 Default crossfade time in seconds.
136 seek-time = NUM
138 Seek forward/backward by NUM seconds.
139 lyrics-timeout = NUM
141 Quits downloading lyrics of a song after the timeout of NUM sec‐
142 onds is reached, if NUM is greater than zero.
143 jump-prefix-only = yes|no
145 When using the jump command, search for the prefix of an entry.
146 That means typing "m" will start to the first entry which begins
147 with "m".
148 lyrics-autosave = yes|no
150 Automatically save lyrics after receiving them.
151 lyrics-show-plugin = yes|no
153 Show the name of the plugin used to receive lyrics on the lyrics
154 screen.
155 text-editor = EDITOR
157 The text editor used for editing lyrics.
158 text-editor-ask = yes|no
160 Ask before starting an editor.
161 chat-prefix = PREFIX
163 Prefix messages send with the chat screen with PREFIX. By
164 default they are prefixed with the current user name enclosed by
165 < and > and a space (i.e. "<name> ").
166 second-column = yes|no
168 Display song length in a second column.
169 Display
171 welcome-screen-list = yes|no
172 Show a list of the screens in the top line on startup.
173 wide-cursor = yes|no
175 Make the cursor as wide as the screen.
176 hardware-cursor = yes|no
178 Use the terminal's hardware cursor instead of inverse colors.
179 hide-cursor = NUM
181 Hide the playlist cursor after NUM seconds of inactivity.
182 scroll = yes|no
184 Scroll the title if it is too long for the screen.
185 scroll-sep = STRING
187 the separator to show at the end of the scrolling title.
188 list-format = SONG FORMAT
190 The format used to display songs in the main window.
191 search-format = SONG FORMAT
193 The format used to display songs in the search window. Default
194 is to use list-format.
195 status-format = SONG FORMAT
197 The format used to display songs on the status line.
198 status-message-time = TIME
200 The time, in seconds, for which status messages will be dis‐
201 played.
202 display-time = yes|no
204 Display the time in the status bar when idle.
205 timedisplay-type = elapsed/remaining
207 Sets whether to display remaining or elapsed time in the status
208 window. Default is elapsed.
209 visible-bitrate = yes|no
211 Show the bitrate in the status bar when playing a stream.
212 set-xterm-title = yes|no
214 Change the XTerm title (ncmpc will not restore the title).
215 xterm-title-format = SONG FORMAT
217 The format used to for the xterm title when ncmpc is playing.
218 Colors
220 enable-colors = yes|no
221 Enable/disable colors.
222 color background = COLOR
224 Set the background color. If the background color is assigned to
225 the keyword none, ncmpc will not change the background color.
226 Standard colors are: black, red, green, yellow, blue, magenta,
227 cyan and white. Terminal specific colors can also be given as
228 integers.
229 color title = COLOR[,ATTRIBUTE]...
231 Set the text color and attributes for the title row. Text colors
232 are the same as for the background. Valid attributes are: stand‐
233 out, underline, reverse, blink, dim, and bold.
234 color title-bold = COLOR[,ATTRIBUTE]...
236 Set the text color for the title row (the bold part).
237 color line = COLOR
239 Set the color of the line on the second row.
240 color line-flags = COLOR[,ATTRIBUTE]...
242 Set the text color used to indicate mpd flags on the second row.
243 color list = COLOR[,ATTRIBUTE]...
245 Set the text color in the main area of ncmpc.
246 color list-bold = COLOR[,ATTRIBUTE]...
248 Set the bold text color in the main area of ncmpc.
249 color browser-directory = COLOR[,ATTRIBUTE]...
251 Set the text color used to display directories in the browser
252 window.
253 color browser-playlist = COLOR[,ATTRIBUTE]...
255 Set the text color used to display playlists in the browser win‐
256 dow.
257 color progressbar = COLOR[,ATTRIBUTE]...
259 Set the color of the progress indicator.
260 color status-state = COLOR[,ATTRIBUTE]...
262 Set the text color used to display mpd status in the status win‐
263 dow.
264 color status-song = COLOR[,ATTRIBUTE]...
266 Set the text color used to display song names in the status win‐
267 dow.
268 color status-time = COLOR[,ATTRIBUTE]...
270 Set the text color used to display time the status window.
271 color alert = COLOR[,ATTRIBUTE]...
273 Set the text color used to display alerts in the status window.
274 colordef COLOR = R, G, B
276 Redefine any of the base colors. The RGB values must be integer
277 values between 0 and 1000. Note: Only some terminals allow
278 redefinitions of colors!
279
282 When ncmpc starts it tries to read user-defined key bindings from the
283 ~/.ncmpc/keys file. If no user-defined key bindings are found then
284 ncmpc tries to load the global key bindings from $SYSCONFDIR/ncmpc/keys
285 (the actual path is displayed on the help screen).
286 You can view ncmpc's key bindings by pressing '1' (help) when ncmpc is
288 running. To edit key bindings press 'K' and use the key editor in
289 ncmpc.
290
292 Format of song display for status and the list window. The metadata
293 delimiters are: %artist%, %albumartist%, %composer%, %performer%,
294 %title%, %album%, %shortalbum%, %track%, %disc, %genre%, %name%,
295 %time%, %date%, %file%, %shortfile%.
296 The [] operators are used to group output such that if none of the
298 metadata delimiters between '[' and ']' are matched, then none of the
299 characters between '[' and ']' are output; literal text is always out‐
300 put. '&' and '|' are logical operators for AND and OR. '#' is used to
301 escape characters.
302 Some useful examples for format are:
304 "%file%"
306 and
308 "[[%artist% - ]%title%]|%file%"
310 Another one is:
312 "[%artist%|(artist n/a)] - [%title%|(title n/a)]"
314
317 If ncmpc has been compiled with "chat" support, it uses the client-to-
318 client protocol available in MPD 0.17 or higher to communicate with
319 other clients. In order to receive messages it subscribes to the chan‐
320 nel with the name "chat", and displays any message sent there as-is.
321 When the user enters a message, it is first with the prefix specified
322 by the chat-prefix option (or the default prefix), and then sent to the
323 "chat" channel for others to read.
324
326 Report bugs on http://www.musicpd.org/mantis/
327
329 Since MPD uses UTF-8, ncmpc needs to convert characters to the charset
330 used by the local system. If you get character conversion errors when
331 your running ncmpc you probably need to set up your locale. This is
332 done by setting any of the LC_CTYPE, LANG or LC_ALL environment vari‐
333 ables (LC_CTYPE only affects character handling).
334
337 mpc(1), mpd(1), locale(5), locale(7)
338 June 2005 ncmpc(1)