1ncmpcpp(1) General Commands Manual ncmpcpp(1)
2
3
4
6 ncmpcpp - An ncurses Music Player Daemon (MPD) client.
7
9 ncmpcpp [options]
10
12 ncmpcpp is an ncurses client for MPD (Music Player Daemon), inspired by
13 ncmpc.
14
15 Read more about MPD at http://www.musicpd.org
16
18 Mandatory arguments to long options are mandatory for short options
19 too.
20
21 -h, --host=HOST
22 Connect to server at host [localhost]
23
24 -p, --port=PORT
25 Connect to server at port [6600]
26
27 --current-song[=FORMAT]
28 Print current song using given format and exit
29
30 -c, --config=FILE
31 Specify configuration file(s)
32
33 --ignore-config-errors
34 Ignore unknown and invalid options in configuration files
35
36 -c, --bindings=FILE
37 Specify bindings file(s)
38
39 -s, --screen <name>
40 Specify the startup screen (<name> may be: help, playlist,
41 browser, search_engine, media_library, playlist_editor, tag_edi‐
42 tor, outputs, visualizer, clock)
43
44 -S, --slave-screen <name>
45 Specify the startup slave screen (<name> may be: help, playlist,
46 browser, search_engine, media_library, playlist_editor, tag_edi‐
47 tor, outputs, visualizer, clock)
48
49 -q, --quiet
50 Suppress logs and excess output
51
52 -?, --help
53 Display help.
54
55 -v, --version
56 Display version information.
57
58
60 When ncmpcpp starts, it tries to read user's settings from $HOME/.ncm‐
61 pcpp/config and $XDG_CONFIG_HOME/ncmpcpp/config files. If no configura‐
62 tion is found, ncmpcpp uses its default configuration. An example con‐
63 figuration file containing all default values is provided with ncmpcpp
64 and can be usually found in /usr/share/doc/ncmpcpp (exact location may
65 depend on used distribution or configure prefix).
66
67 Note: Configuration option values can either be enclosed in quotation
68 marks or not.
69 - If they are enclosed, the leftmost and the rightmost quotation marks
70 are treated as delimiters, therefore it is not necessary to escape quo‐
71 tation marks you use within the value itself.
72 - If they are not, any whitespace characters between = and the first
73 printable character of the value, as well as whitespace characters
74 after the last printable character of the value are trimmed.
75
76 Therefore the rule of thumb is: if you need whitespaces at the begin‐
77 ning or at the end of the value, enclose it in quotation marks. Other‐
78 wise, don't.
79
80 Note: COLOR has to be the name (not a number) of one of colors 1-8 from
81 SONG FORMAT section.
82
83 Supported configuration options:
84
85 ncmpcpp_directory = PATH
86 Directory for storing ncmpcpp related files. Changing it is use‐
87 ful if you want to store everything somewhere else and provide
88 command line setting for alternative location to config file
89 which defines that while launching ncmpcpp.
90
91 lyrics_directory = PATH
92 Directory for storing downloaded lyrics. It defaults to
93 ~/.lyrics since other MPD clients (eg. ncmpc) also use that
94 location.
95
96 mpd_host = HOST
97 Connect to MPD running on specified host/unix socket. When HOST
98 starts with a '/', it is assumed to be a unix socket. Note:
99 MPD_HOST environment variable overrides this setting.
100
101 mpd_port = PORT
102 Connect to MPD on the specified port. Note: MPD_PORT environment
103 variable overrides this setting.
104
105 mpd_music_dir = PATH
106 Search for files in specified directory. This is needed for tag
107 editor to work.
108
109 mpd_connection_timeout = SECONDS
110 Set connection timeout to MPD to given value.
111
112 mpd_crossfade_time = SECONDS
113 Default number of seconds to crossfade, if enabled by ncmpcpp.
114
115 visualizer_fifo_path = PATH
116 Path to mpd fifo output. This is needed to make music visualizer
117 work (note that output sound format of this fifo has to be
118 either 44100:16:1 or 44100:16:2, depending on whether you want
119 mono or stereo visualization)
120
121 visualizer_output_name = NAME
122 Name of output that provides data for visualizer. Needed to keep
123 sound and visualization in sync.
124
125 visualizer_in_stereo = yes/no
126 Should be set to 'yes', if fifo output's format was set to
127 44100:16:2.
128
129 visualizer_sync_interval = SECONDS
130 Defines interval between syncing visualizer and audio outputs.
131
132 visualizer_type = spectrum/wave/wave_filled/ellipse
133 Defines default visualizer type (spectrum is available only if
134 ncmpcpp was compiled with fftw support).
135
136 visualizer_look = STRING
137 Defines visualizer's look (string has to be exactly 2 characters
138 long: first one is for wave whereas second for frequency spec‐
139 trum).
140
141 visualizer_color = COLORS
142 Comma separated list of colors to be used in music visualiza‐
143 tion.
144
145 system_encoding = ENCODING
146 If you use encoding other than utf8, set it in order to handle
147 utf8 encoded strings properly.
148
149 playlist_disable_highlight_delay = SECONDS
150 Delay for highlighting playlist since the last key was pressed.
151 If set to 0, highlighting never fades away.
152
153 message_delay_time = SECONDS
154 Delay for displayed messages to remain visible.
155
156 song_list_format
157 Song format for lists of songs.
158
159 song_status_format
160 Song format for statusbar.
161
162 song_library_format
163 Song format for media library.
164
165 alternative_header_first_line_format = TEXT
166 Now playing song format for the first line in alternative user
167 interface header window.
168
169 alternative_header_second_line_format = TEXT
170 Now playing song format for the second line in alternative user
171 interface header window.
172
173 current_item_prefix = TEXT
174 Prefix for currently selected item.
175
176 current_item_suffix = TEXT
177 Suffix for currently selected item.
178
179 current_item_inactive_column_prefix = TEXT
180 Prefix for currently selected item in the inactive column.
181
182 current_item_inactive_column_suffix = TEXT
183 Suffix for currently selected item in the inactive column.
184
185 now_playing_prefix = TEXT
186 Prefix for currently playing song.
187
188 now_playing_suffix = TEXT
189 Suffix for currently playing song.
190
191 browser_playlist_prefix = TEXT
192 Prefix for playlists in Browser.
193
194 selected_item_prefix = TEXT
195 Prefix for selected items.
196
197 selected_item_suffix = TEXT
198 Suffix for selected items.
199
200 modified_item_prefix = TEXT
201 Prefix for modified item (tag editor).
202
203 browser_sort_mode
204 Determines sort mode for browser. Possible values are "name",
205 "mtime", "format" and "noop".
206
207 browser_sort_format
208 Format to use for sorting songs in browser. For this option to
209 be effective, browser_sort_mode must be set to "format".
210
211 song_window_title_format
212 Song format for window title.
213
214 song_columns_list_format
215 Format for songs' list displayed in columns.
216
217 execute_on_song_change = COMMAND
218 Shell command to execute on song change.
219
220 execute_on_player_state_change = COMMAND
221 Shell command to execute on player state change. The environment
222 variable MPD_PLAYER_STATE is set to the current state (either
223 unknown, play, pause, or stop) for its duration.
224
225 playlist_show_mpd_host = yes/no
226 If enabled, current MPD host will be shown in playlist.
227
228 playlist_show_remaining_time = yes/no
229 If enabled, time remaining to end of playlist will be shown
230 after playlist statistics.
231
232 playlist_shorten_total_times = yes/no
233 If enabled, total/remaining playlist time displayed in statusbar
234 will be shown using shortened units' names (d:h:m:s instead of
235 days:hours:minutes:seconds).
236
237 playlist_separate_albums = yes/no
238 If enabled, separators will be placed between albums.
239
240 playlist_display_mode = classic/columns
241 Default display mode for Playlist.
242
243 browser_display_mode = classic/columns
244 Default display mode for Browser.
245
246 search_engine_display_mode = classic/columns
247 Default display mode for Search engine.
248
249 playlist_editor_display_mode = classic/columns
250 Default display mode for Playlist editor.
251
252 discard_colors_if_item_is_selected = yes/no
253 Indicates whether custom colors of tags have to be discarded if
254 item is selected or not.
255
256 show_duplicate_tags = yes/no
257 Indicates whether ncmpcpp should display multiple tags as-is or
258 remove duplicates.
259
260 incremental_seeking = yes/no
261 If enabled, seek time will increment by one each second of seek‐
262 ing.
263
264 seek_time = SECONDS
265 Base seek time to begin with.
266
267 volume_change_step = NUMBER
268 Number of percents volume has to be increased/decreased by in
269 volume_up/volume_down.
270
271 autocenter_mode = yes/no
272 Default state for autocenter mode at start.
273
274 centered_cursor = yes/no
275 If enabled, currently highlighted position in the list will be
276 always centered.
277
278 progressbar_look = TEXT
279 This variable defines the look of progressbar. Note that it has
280 to be exactly two or three characters long.
281
282 default_place_to_search_in = database/playlist
283 If set to "playlist", Search engine will perform searching in
284 current MPD playlist rather than in music database.
285
286 user_interface = classic/alternative
287 Default user interface used by ncmpcpp at start.
288
289 data_fetching_delay = yes/no
290 If enabled, there will be a 250ms delay between refreshing posi‐
291 tion in media library or playlist editor and fetching appropri‐
292 ate data from MPD. This limits data fetched from the server and
293 is particularly useful if ncmpcpp is connected to a remote host.
294
295 media_library_primary_tag = artist/album_artist/date/genre/com‐
296 poser/performer
297 Default tag type for leftmost column in media library.
298
299 media_library_albums_split_by_date = yes/no
300 Determines whether albums in media library should be split by
301 date.
302
303 default_find_mode = wrapped/normal
304 If set to "wrapped", going from last found position to next will
305 take you to the first one (same goes for the first position and
306 going to previous one), otherwise no actions will be performed.
307
308 default_tag_editor_pattern = TEXT
309 Default pattern used by Tag editor's parser.
310
311 header_visibility = yes/no
312 If enabled, header window will be displayed, otherwise hidden.
313
314 statusbar_visibility = yes/no
315 If enabled, statusbar will be displayed, otherwise hidden.
316
317 titles_visibility = yes/no
318 If enabled, column titles will be displayed, otherwise hidden.
319
320 header_text_scrolling = yes/no
321 If enabled, text in header window will scroll if its length is
322 longer then actual screen width, otherwise it won't.
323
324 cyclic_scrolling = yes/no
325 If enabled, cyclic scrolling is used (e.g. if you press down
326 arrow being at the end of list, it'll take you to the beginning)
327
328 lines_scrolled = NUMBER
329 Number of lines that are scrolled with mouse wheel.
330
331 lyrics_fetchers = FETCHERS
332 Comma separated list of lyrics fetchers.
333
334 follow_now_playing_lyrics = yes/no
335 If enabled, lyrics will be switched at song's change to cur‐
336 rently playing one's (Note: this works only if you are viewing
337 lyrics of item from Playlist).
338
339 fetch_lyrics_for_current_song_in_background = yes/no
340 If enabled, each time song changes lyrics fetcher will be auto‐
341 matically run in background in attempt to download lyrics for
342 currently playing song.
343
344 store_lyrics_in_song_dir = yes/no
345 If enabled, lyrics will be saved in song's directory, otherwise
346 in ~/.lyrics. Note that it needs properly set mpd_music_dir.
347
348 generate_win32_compatible_filenames = yes/no
349 If set to yes, filenames generated by ncmpcpp (with tag editor,
350 for lyrics, artists etc.) will not contain the following charac‐
351 ters: \?*:|
352
353 allow_for_physical_item_deletion = yes/no
354 If set to yes, it will be possible to physically delete files
355 and directories from the disk in the browser.
356
357 lastfm_preferred_language = ISO 639 alpha-2 language code
358 If set, ncmpcpp will try to get info from last.fm in language
359 you set and if it fails, it will fall back to English. Otherwise
360 it will use English the first time.
361
362 space_add_mode = add_remove/always_add
363 If set to add_remove, attempting to add files that are already
364 in playlist will remove them. Otherwise they can be added multi‐
365 ple times.
366
367 show_hidden_files_in_local_browser = yes/no
368 Trigger for displaying in local browser files and directories
369 that begin with '.'
370
371 screen_switcher_mode = SWITCHER_MODE
372 If set to "previous", key_screen_switcher will switch between
373 current and last used screen. If set to "screen1,...screenN" (a
374 list of screens) it will switch between them in a sequence. Syn‐
375 tax clarification can be found in example config file.
376
377 startup_screen = SCREEN_NAME
378 Screen that has to be displayed at start (playlist by default).
379
380 startup_slave_screen = SCREEN_NAME
381 Slave screen that has to be displayed at start (nothing by
382 default).
383
384 startup_slave_screen_focus = yes/no
385 If set to yes, slave screen will be the active one after
386 startup. Otherwise master screen will be.
387
388 locked_screen_width_part = 20-80
389 If you want to lock a screen, ncmpcpp asks for % of locked
390 screen's width to be reserved before that and provides a default
391 value, which is the one you can set here.
392
393 ask_for_locked_screen_width_part = yes/no
394 If enabled, ncmpcpp will ask for % of locked screen's width each
395 time you want to lock a screen. If you disable that, it'll
396 silently attempt to use default value.
397
398 jump_to_now_playing_song_at_start = yes/no
399 If enabled, ncmpcpp will jump at start to now playing song if
400 mpd is playing or paused.
401
402 ask_before_clearing_playlists = yes/no
403 If enabled, user will be asked if he really wants to clear the
404 playlist after pressing key responsible for that.
405
406 clock_display_seconds = yes/no
407 If enabled, clock will display time in format hh:mm:ss, other‐
408 wise hh:mm.
409
410 display_volume_level = yes/no
411 If enabled, volume level will be displayed in statusbar, other‐
412 wise not.
413
414 display_bitrate = yes/no
415 If enabled, bitrate of currently playing song will be displayed
416 in statusbar.
417
418 display_remaining_time = yes/no
419 If enabled, remaining time of currently playing song will be be
420 displayed in statusbar instead of elapsed time.
421
422 regular_expressions = none/basic/extended/perl
423 Type of currently used regular expressions.
424
425 ignore_leading_the = yes/no
426 If enabled, word "the" at the beginning of tags/filenames/sort
427 format will be ignored while sorting items.
428
429 ignore_diacritics = yes/no
430 If enabled, diacritics in strings will be ignored while search‐
431 ing and filtering lists.
432
433 block_search_constraints_change_if_items_found = yes/no
434 If enabled, fields in Search engine above "Reset" button will be
435 blocked after successful searching, otherwise they won't.
436
437 mouse_support = yes/no
438 If set to yes, mouse support will be enabled.
439
440 mouse_list_scroll_whole_page = yes/no
441 If enabled, mouse wheel will scroll the whole page of item list
442 at a time, otherwise the number of lines specified by
443 lines_scrolled variable.
444
445 empty_tag_marker = TEXT
446 Text that will be displayed, if requested tag is not set.
447
448 tags_separator = TEXT
449 Separator that is placed between tags. Also interpreted by tag
450 editor which splits input string into separate tags using it.
451
452 tag_editor_extended_numeration = yes/no
453 If enabled, tag editor will number tracks using format xx/yy
454 (where xx is the current track and yy is total amount of all
455 numbered tracks), not plain xx.
456
457 media_library_sort_by_mtime = yes/no
458 If enabled, media library will be sorted by modification time.
459 Otherwise lexicographic sorting is used.
460
461 enable_window_title = yes/no
462 If enabled, ncmpcpp will override current window title with its
463 own one.
464
465 search_engine_default_search_mode = MODE_NUMBER
466 Number of default mode used in search engine.
467
468 external_editor = PATH
469 Path to external editor used to edit lyrics.
470
471 use_console_editor = yes/no
472 If your external editor is console application, you need to
473 enable it.
474
475 colors_enabled = yes/no
476 No need to describe it, huh?
477
478 empty_tag_color = COLOR
479 Color of empty tag marker.
480
481 header_window_color = COLOR
482 Color of header window.
483
484 volume_color = COLOR
485 Color of volume state.
486
487 state_line_color = COLOR
488 Color of lines separating header and statusbar from main window.
489
490 state_flags_color = COLOR
491 Color of MPD status flags.
492
493 main_window_color = COLOR
494 Color of main window.
495
496 color1 = COLOR
497 One of colors used in Song info, Tiny tag editor and Search
498 engine.
499
500 color2 = COLOR
501 One of colors used in Song info, Tiny tag editor and Search
502 engine.
503
504 progressbar_color = COLOR
505 Color of progressbar.
506
507 progressbar_elapsed_color = COLOR
508 Color of part of progressbar that represents elapsed time.
509
510 statusbar_color = COLOR
511 Color of statusbar.
512
513 statusbar_time_color = COLOR
514 Color of current track time shown in statusbar.
515
516 player_state_color = COLOR
517 Color of player state shown in statusbar.
518
519 alternative_ui_separator_color = COLOR
520 Color of separators used in alternative user interface.
521
522 window_border_color = BORDER
523 Border color of pop-up windows. If set to 'none', no border will
524 be shown.
525
526 active_window_border = COLOR
527 Color of active window's border.
528
529
530 BINDINGS
531 When ncmpcpp starts, it tries to read user's bindings from
532 ~/.ncmpcpp/bindings and $XDG_CONFIG_HOME/ncmpcpp/bindings files.
533 If no bindings file is found, ncmpcpp uses the defaults. An
534 example bindings file with the default values can be found usu‐
535 ally in /usr/share/doc/ncmpcpp (exact location may depend on
536 used distribution or configure prefix).
537
538 You can view current keybindings by pressing F1.
539
541 For song format you can use:
542
543 %l - length
544 %f - filename
545 %D - directory
546 %a - artist
547 %A - album artist
548 %t - title
549 %b - album
550 %y - date
551 %n - track number (01/12 -> 01)
552 %N - full track info (01/12 -> 01/12)
553 %g - genre
554 %c - composer
555 %p - performer
556 %d - disc
557 %C - comment
558 %P - priority
559 $R - begin right alignment
560
561 You can also put them in { } and then they will be displayed only if
562 all requested values are available and/or define alternate value with {
563 }|{ } e.g. {%a - %t}|{%f} will check if artist and title tags are
564 available and if they are, display them. Otherwise it'll display file‐
565 name.
566
567 Note: If you want to set limit on maximal length of a tag, just put the
568 appropriate number between % and character that defines tag type, e.g.
569 to make album take max. 20 terminal cells, use '%20b'.
570
571 Note: Format that is similar to "%a - %t" (i.e. without any additional
572 braces) is equal to "{%a - %t}", so if one of the tags is missing,
573 you'll get nothing.
574
575 Text can have different color than the main window, e.g. if you want
576 length to be green, write $3%l$9.
577
578 Available values for colors:
579
580 - 0 - default window color (discards all other colors)
581 - 1 - black
582 - 2 - red
583 - 3 - green
584 - 4 - yellow
585 - 5 - blue
586 - 6 - magenta
587 - 7 - cyan
588 - 8 - white
589 - 9 - end of current color
590
591 Note: colors can be nested, so if you write $2some$5text$9, it'll dis‐
592 able only usage of blue color and make red the current one.
593
594
596 Report bugs on https://github.com/arybczak/ncmpcpp/issues
597
599 Since MPD uses UTF-8, ncmpcpp needs to convert characters to the
600 charset used by the local system. If you get character conversion
601 errors while you are running ncmpcpp, you probably need to set up your
602 locale. This is done by setting LANG and LC_ALL/LC_CTYPE environment
603 variables (LC_CTYPE only affects character handling).
604
606 -> http://rybczak.net/ncmpcpp
607
608
610 mpc(1), mpd(1)
611
612
613
614 ncmpcpp(1)