1ncmpcpp(1) General Commands Manual ncmpcpp(1)
2
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 Read more about MPD at http://www.musicpd.org
16
18 Mandatory arguments to long options are mandatory for short options
19 too.
20 -h, --host=HOST
22 Connect to server at host [localhost]
23 -p, --port=PORT
25 Connect to server at port [6600]
26 --current-song[=FORMAT]
28 Print current song using given format and exit
29 -c, --config=FILE
31 Specify configuration file(s)
32 --ignore-config-errors
34 Ignore unknown and invalid options in configuration files
35 -b, --bindings=FILE
37 Specify bindings file(s)
38 -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 -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 -q, --quiet
50 Suppress logs and excess output
51 -?, --help
53 Display help.
54 -v, --version
56 Display version information.
57
60 When ncmpcpp starts, it tries to read settings from $XDG_CON‐
61 FIG_HOME/ncmpcpp/config and $HOME/.ncmpcpp/config files. If no configu‐
62 ration is found, ncmpcpp uses its default configuration. An example
63 configuration file containing all default values is provided with ncm‐
64 pcpp and can be usually found in /usr/share/doc/ncmpcpp (the exact
65 location may depend on your operating system or configure prefix).
66 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 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 Note: COLOR has to be the name (not a number) of one of colors 1-8 from
81 SONG FORMAT section.
82 Supported configuration options:
84 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 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 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 mpd_port = PORT
102 Connect to MPD on the specified port. Note: MPD_PORT environment
103 variable overrides this setting.
104 mpd_music_dir = PATH
106 Search for files in specified directory. This is needed for tag
107 editor to work.
108 mpd_connection_timeout = SECONDS
110 Set connection timeout to MPD to given value.
111 mpd_crossfade_time = SECONDS
113 Default number of seconds to crossfade, if enabled by ncmpcpp.
114 visualizer_data_source = LOCATION
116 Source of data for the visualizer. For MPD it's going to be a
117 fifo output, for Mopidy a udpsink output (see the example con‐
118 figuration file for more details).
119 visualizer_output_name = NAME
121 Name of output that provides data for visualizer. Needed to keep
122 sound and visualization in sync.
123 visualizer_in_stereo = yes/no
125 Should be set to 'yes', if fifo output's format was set to
126 44100:16:2.
127 visualizer_type = spectrum/wave/wave_filled/ellipse
129 Defines default visualizer type (spectrum is available only if
130 ncmpcpp was compiled with fftw support).
131 visualizer_look = STRING
133 Defines visualizer's look (string has to be exactly 2 characters
134 long: first one is for wave whereas second for frequency spec‐
135 trum).
136 visualizer_color = COLORS
138 Comma separated list of colors to be used in music visualiza‐
139 tion.
140 visualizer_fps = FPS
142 The amount of frames per second for the visualizer.
143 visualizer_autoscale = yes/no
145 Automatically scale visualizer size.
146 visualizer_spectrum_smooth_look = yes/no
148 For spectrum visualizer, use unicode block characters for a
149 smoother, more continuous look. This will override the visual‐
150 izer_look option. With transparent terminals and visual‐
151 izer_in_stereo set, artifacts may be visible on the bottom half
152 of the visualization.
153 visualizer_spectrum_dft_size = NUMBER
155 For spectrum visualizer, a value between 1 and 5 inclusive.
156 Specifying a larger value makes the visualizer look at a larger
157 slice of time, which results in less jumpy visualizer output.
158 visualizer_spectrum_gain = dB
160 Gain for spectrum visualizer in dB, larger/smaller values shift
161 bars up/down.
162 visualizer_spectrum_hz_min = Hz
164 For spectrum visualizer, left-most frequency of visualizer, must
165 be less than HZ MAX.
166 visualizer_spectrum_hz_max = Hz
168 For spectrum visualizer, right-most frequency of visualizer,
169 must be greater than HZ MIN.
170 system_encoding = ENCODING
172 If you use encoding other than utf8, set it in order to handle
173 utf8 encoded strings properly.
174 playlist_disable_highlight_delay = SECONDS
176 Delay for highlighting playlist since the last key was pressed.
177 If set to 0, highlighting never fades away.
178 message_delay_time = SECONDS
180 Delay for displayed messages to remain visible.
181 song_list_format
183 Song format for lists of songs.
184 song_status_format
186 Song format for statusbar.
187 song_library_format
189 Song format for media library.
190 alternative_header_first_line_format = TEXT
192 Now playing song format for the first line in alternative user
193 interface header window.
194 alternative_header_second_line_format = TEXT
196 Now playing song format for the second line in alternative user
197 interface header window.
198 current_item_prefix = TEXT
200 Prefix for currently selected item.
201 current_item_suffix = TEXT
203 Suffix for currently selected item.
204 current_item_inactive_column_prefix = TEXT
206 Prefix for currently selected item in the inactive column.
207 current_item_inactive_column_suffix = TEXT
209 Suffix for currently selected item in the inactive column.
210 now_playing_prefix = TEXT
212 Prefix for currently playing song.
213 now_playing_suffix = TEXT
215 Suffix for currently playing song.
216 browser_playlist_prefix = TEXT
218 Prefix for playlists in Browser.
219 selected_item_prefix = TEXT
221 Prefix for selected items.
222 selected_item_suffix = TEXT
224 Suffix for selected items.
225 modified_item_prefix = TEXT
227 Prefix for modified item (tag editor).
228 browser_sort_mode
230 Determines sort mode for browser. Possible values are "type",
231 "name", "mtime", "format" and "none".
232 browser_sort_format
234 Format to use for sorting songs in browser. For this option to
235 be effective, browser_sort_mode must be set to "format".
236 song_window_title_format
238 Song format for window title.
239 song_columns_list_format
241 Format for songs' list displayed in columns.
242 execute_on_song_change = COMMAND
244 Shell command to execute on song change.
245 execute_on_player_state_change = COMMAND
247 Shell command to execute on player state change. The environment
248 variable MPD_PLAYER_STATE is set to the current state (either
249 unknown, play, pause, or stop) for its duration.
250 playlist_show_mpd_host = yes/no
252 If enabled, current MPD host will be shown in playlist.
253 playlist_show_remaining_time = yes/no
255 If enabled, time remaining to end of playlist will be shown
256 after playlist statistics.
257 playlist_shorten_total_times = yes/no
259 If enabled, total/remaining playlist time displayed in statusbar
260 will be shown using shortened units' names (d:h:m:s instead of
261 days:hours:minutes:seconds).
262 playlist_separate_albums = yes/no
264 If enabled, separators will be placed between albums.
265 playlist_display_mode = classic/columns
267 Default display mode for Playlist.
268 browser_display_mode = classic/columns
270 Default display mode for Browser.
271 search_engine_display_mode = classic/columns
273 Default display mode for Search engine.
274 playlist_editor_display_mode = classic/columns
276 Default display mode for Playlist editor.
277 discard_colors_if_item_is_selected = yes/no
279 Indicates whether custom colors of tags have to be discarded if
280 item is selected or not.
281 show_duplicate_tags = yes/no
283 Indicates whether ncmpcpp should display multiple tags as-is or
284 remove duplicates.
285 incremental_seeking = yes/no
287 If enabled, seek time will increment by one each second of seek‐
288 ing.
289 seek_time = SECONDS
291 Base seek time to begin with.
292 volume_change_step = NUMBER
294 Number of percents volume has to be increased/decreased by in
295 volume_up/volume_down.
296 autocenter_mode = yes/no
298 Default state for autocenter mode at start.
299 centered_cursor = yes/no
301 If enabled, currently highlighted position in the list will be
302 always centered.
303 progressbar_look = TEXT
305 This variable defines the look of progressbar. Note that it has
306 to be exactly two or three characters long.
307 default_place_to_search_in = database/playlist
309 If set to "playlist", Search engine will perform searching in
310 current MPD playlist rather than in music database.
311 user_interface = classic/alternative
313 Default user interface used by ncmpcpp at start.
314 data_fetching_delay = yes/no
316 If enabled, there will be a 250ms delay between refreshing posi‐
317 tion in media library or playlist editor and fetching appropri‐
318 ate data from MPD. This limits data fetched from the server and
319 is particularly useful if ncmpcpp is connected to a remote host.
320 media_library_primary_tag = artist/album_artist/date/genre/com‐
322 poser/performer
323 Default tag type for leftmost column in media library.
324 media_library_albums_split_by_date = yes/no
326 Determines whether albums in media library should be split by
327 date.
328 media_library_hide_album_dates = yes/no
330 Determines whether album dates in media library should be hid‐
331 den.
332 default_find_mode = wrapped/normal
334 If set to "wrapped", going from last found position to next will
335 take you to the first one (same goes for the first position and
336 going to previous one), otherwise no actions will be performed.
337 default_tag_editor_pattern = TEXT
339 Default pattern used by Tag editor's parser.
340 header_visibility = yes/no
342 If enabled, header window will be displayed, otherwise hidden.
343 statusbar_visibility = yes/no
345 If enabled, statusbar will be displayed, otherwise hidden.
346 connected_message_on_startup = yes/no
348 Show the "Connected to ..." message on startup
349 titles_visibility = yes/no
351 If enabled, column titles will be displayed, otherwise hidden.
352 header_text_scrolling = yes/no
354 If enabled, text in header window will scroll if its length is
355 longer then actual screen width, otherwise it won't.
356 cyclic_scrolling = yes/no
358 If enabled, cyclic scrolling is used (e.g. if you press down
359 arrow being at the end of list, it'll take you to the beginning)
360 lyrics_fetchers = FETCHERS
362 Comma separated list of lyrics fetchers.
363 follow_now_playing_lyrics = yes/no
365 If enabled, lyrics will be switched at song's change to cur‐
366 rently playing one's (Note: this works only if you are viewing
367 lyrics of item from Playlist).
368 fetch_lyrics_for_current_song_in_background = yes/no
370 If enabled, each time song changes lyrics fetcher will be auto‐
371 matically run in background in attempt to download lyrics for
372 currently playing song.
373 store_lyrics_in_song_dir = yes/no
375 If enabled, lyrics will be saved in song's directory, otherwise
376 in ~/.lyrics. Note that it needs properly set mpd_music_dir.
377 generate_win32_compatible_filenames = yes/no
379 If set to yes, filenames generated by ncmpcpp (with tag editor,
380 for lyrics, artists etc.) will not contain the following charac‐
381 ters: \?*:|
382 allow_for_physical_item_deletion = yes/no
384 If set to yes, it will be possible to physically delete files
385 and directories from the disk in the browser.
386 lastfm_preferred_language = ISO 639 alpha-2 language code
388 If set, ncmpcpp will try to get info from last.fm in language
389 you set and if it fails, it will fall back to English. Otherwise
390 it will use English the first time.
391 space_add_mode = add_remove/always_add
393 If set to add_remove, attempting to add files that are already
394 in playlist will remove them. Otherwise they can be added multi‐
395 ple times.
396 show_hidden_files_in_local_browser = yes/no
398 Trigger for displaying in local browser files and directories
399 that begin with '.'
400 screen_switcher_mode = SWITCHER_MODE
402 If set to "previous", key_screen_switcher will switch between
403 current and last used screen. If set to "screen1,...screenN" (a
404 list of screens) it will switch between them in a sequence. Syn‐
405 tax clarification can be found in example config file.
406 startup_screen = SCREEN_NAME
408 Screen that has to be displayed at start (playlist by default).
409 startup_slave_screen = SCREEN_NAME
411 Slave screen that has to be displayed at start (nothing by
412 default).
413 startup_slave_screen_focus = yes/no
415 If set to yes, slave screen will be the active one after
416 startup. Otherwise master screen will be.
417 locked_screen_width_part = 20-80
419 If you want to lock a screen, ncmpcpp asks for % of locked
420 screen's width to be reserved before that and provides a default
421 value, which is the one you can set here.
422 ask_for_locked_screen_width_part = yes/no
424 If enabled, ncmpcpp will ask for % of locked screen's width each
425 time you want to lock a screen. If you disable that, it'll
426 silently attempt to use default value.
427 jump_to_now_playing_song_at_start = yes/no
429 If enabled, ncmpcpp will jump at start to now playing song if
430 mpd is playing or paused.
431 ask_before_clearing_playlists = yes/no
433 If enabled, user will be asked if he really wants to clear the
434 playlist after pressing key responsible for that.
435 clock_display_seconds = yes/no
437 If enabled, clock will display time in format hh:mm:ss, other‐
438 wise hh:mm.
439 display_volume_level = yes/no
441 If enabled, volume level will be displayed in statusbar, other‐
442 wise not.
443 display_bitrate = yes/no
445 If enabled, bitrate of currently playing song will be displayed
446 in statusbar.
447 display_remaining_time = yes/no
449 If enabled, remaining time of currently playing song will be be
450 displayed in statusbar instead of elapsed time.
451 regular_expressions = none/basic/extended/perl
453 Type of currently used regular expressions.
454 ignore_leading_the = yes/no
456 If enabled, word "the" at the beginning of tags/filenames/sort
457 format will be ignored while sorting items.
458 ignore_diacritics = yes/no
460 If enabled, diacritics in strings will be ignored while search‐
461 ing and filtering lists.
462 block_search_constraints_change_if_items_found = yes/no
464 If enabled, fields in Search engine above "Reset" button will be
465 blocked after successful searching, otherwise they won't.
466 mouse_support = yes/no
468 If set to yes, mouse support will be enabled.
469 mouse_list_scroll_whole_page = yes/no
471 If enabled, mouse wheel will scroll the whole page of item list
472 at a time, otherwise the number of lines specified by
473 lines_scrolled variable.
474 lines_scrolled = NUMBER
476 Number of lines that are scrolled with mouse wheel.
477 empty_tag_marker = TEXT
479 Text that will be displayed, if requested tag is not set.
480 tags_separator = TEXT
482 Separator that is placed between tags. Also interpreted by tag
483 editor which splits input string into separate tags using it.
484 tag_editor_extended_numeration = yes/no
486 If enabled, tag editor will number tracks using format xx/yy
487 (where xx is the current track and yy is total amount of all
488 numbered tracks), not plain xx.
489 media_library_sort_by_mtime = yes/no
491 If enabled, media library will be sorted by modification time.
492 Otherwise lexicographic sorting is used.
493 enable_window_title = yes/no
495 If enabled, ncmpcpp will override current window title with its
496 own one.
497 search_engine_default_search_mode = MODE_NUMBER
499 Number of default mode used in search engine.
500 external_editor = PATH
502 Path to external editor used to edit lyrics.
503 use_console_editor = yes/no
505 If your external editor is console application, you need to
506 enable it.
507 colors_enabled = yes/no
509 No need to describe it, huh?
510 empty_tag_color = COLOR
512 Color of empty tag marker.
513 header_window_color = COLOR
515 Color of header window.
516 volume_color = COLOR
518 Color of volume state.
519 state_line_color = COLOR
521 Color of lines separating header and statusbar from main window.
522 state_flags_color = COLOR
524 Color of MPD status flags.
525 main_window_color = COLOR
527 Color of main window.
528 color1 = COLOR
530 One of colors used in Song info, Tiny tag editor and Search
531 engine.
532 color2 = COLOR
534 One of colors used in Song info, Tiny tag editor and Search
535 engine.
536 progressbar_color = COLOR
538 Color of progressbar.
539 progressbar_elapsed_color = COLOR
541 Color of part of progressbar that represents elapsed time.
542 statusbar_color = COLOR
544 Color of statusbar.
545 statusbar_time_color = COLOR
547 Color of current track time shown in statusbar.
548 player_state_color = COLOR
550 Color of player state shown in statusbar.
551 alternative_ui_separator_color = COLOR
553 Color of separators used in alternative user interface.
554 window_border_color = BORDER
556 Border color of pop-up windows. If set to 'none', no border will
557 be shown.
558 active_window_border = COLOR
560 Color of active window's border.
561 BINDINGS
564 When ncmpcpp starts, it tries to read bindings from $XDG_CON‐
565 FIG_HOME/ncmpcpp/bindings and ~/.ncmpcpp/bindings files. If no
566 bindings file is found, ncmpcpp uses the defaults. An example
567 bindings file with default values can be found usually in
568 /usr/share/doc/ncmpcpp (the exact location may depend on your
569 operating system or configure prefix).
570 You can view current keybindings by pressing F1.
572
574 For song format you can use:
575 %l - length
577 %f - filename
578 %D - directory
579 %a - artist
580 %A - album artist
581 %t - title
582 %b - album
583 %y - date
584 %n - track number (01/12 -> 01)
585 %N - full track info (01/12 -> 01/12)
586 %g - genre
587 %c - composer
588 %p - performer
589 %d - disc
590 %C - comment
591 %P - priority
592 $R - begin right alignment
593 You can also put them in { } and then they will be displayed only if
595 all requested values are available and/or define alternate value with {
596 }|{ } e.g. {%a - %t}|{%f} will check if artist and title tags are
597 available and if they are, display them. Otherwise it'll display file‐
598 name.
599 Note: If you want to set limit on maximal length of a tag, just put the
601 appropriate number between % and character that defines tag type, e.g.
602 to make album take max. 20 terminal cells, use '%20b'.
603 Note: Format that is similar to "%a - %t" (i.e. without any additional
605 braces) is equal to "{%a - %t}", so if one of the tags is missing,
606 you'll get nothing.
607 Text can have different color than the main window, e.g. if you want
609 length to be green, write $3%l$9.
610 Available values for colors:
612 - 0 - default window color (discards all other colors)
614 - 1 - black
615 - 2 - red
616 - 3 - green
617 - 4 - yellow
618 - 5 - blue
619 - 6 - magenta
620 - 7 - cyan
621 - 8 - white
622 - 9 - end of current color
623 Note: colors can be nested, so if you write $2some$5text$9, it'll dis‐
625 able only usage of blue color and make red the current one.
626
629 Report bugs on https://github.com/arybczak/ncmpcpp/issues
630
632 Since MPD uses UTF-8, ncmpcpp needs to convert characters to the
633 charset used by the local system. If you get character conversion
634 errors while you are running ncmpcpp, you probably need to set up your
635 locale. This is done by setting LANG and LC_ALL/LC_CTYPE environment
636 variables (LC_CTYPE only affects character handling).
637
639 -> http://rybczak.net/ncmpcpp
640
643 mpc(1), mpd(1)
644 ncmpcpp(1)