1ncmpcpp(1)                  General Commands Manual                 ncmpcpp(1)
2
3
4

NAME

6       ncmpcpp - An ncurses Music Player Daemon (MPD) client.
7

SYNOPSIS

9       ncmpcpp [options]
10

DESCRIPTION

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

OPTIONS

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

CONFIGURATION

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

SONG FORMAT

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

BUGS

596       Report bugs on https://github.com/arybczak/ncmpcpp/issues
597

NOTE

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

HOMEPAGE

606       -> http://rybczak.net/ncmpcpp
607
608

SEE ALSO

610       mpc(1), mpd(1)
611
612
613
614                                                                    ncmpcpp(1)
Impressum