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       -b, --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  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
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_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
120       visualizer_output_name = NAME
121              Name of output that provides data for visualizer. Needed to keep
122              sound and visualization in sync.
123
124       visualizer_in_stereo = yes/no
125              Should be set to 'yes', if  fifo  output's  format  was  set  to
126              44100:16:2.
127
128       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
132       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
137       visualizer_color = COLORS
138              Comma separated list of colors to be used  in  music  visualiza‐
139              tion.
140
141       visualizer_fps = FPS
142              The amount of frames per second for the visualizer.
143
144       visualizer_autoscale = yes/no
145              Automatically scale visualizer size.
146
147       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
154       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
159       visualizer_spectrum_gain = dB
160              Gain  for spectrum visualizer in dB, larger/smaller values shift
161              bars up/down.
162
163       visualizer_spectrum_hz_min = Hz
164              For spectrum visualizer, left-most frequency of visualizer, must
165              be less than HZ MAX.
166
167       visualizer_spectrum_hz_max = Hz
168              For  spectrum  visualizer,  right-most  frequency of visualizer,
169              must be greater than HZ MIN.
170
171       system_encoding = ENCODING
172              If you use encoding other than utf8, set it in order  to  handle
173              utf8 encoded strings properly.
174
175       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
179       message_delay_time = SECONDS
180              Delay for displayed messages to remain visible.
181
182       song_list_format
183              Song format for lists of songs.
184
185       song_status_format
186              Song format for statusbar.
187
188       song_library_format
189              Song format for media library.
190
191       alternative_header_first_line_format = TEXT
192              Now playing song format for the first line in  alternative  user
193              interface header window.
194
195       alternative_header_second_line_format = TEXT
196              Now  playing song format for the second line in alternative user
197              interface header window.
198
199       current_item_prefix = TEXT
200              Prefix for currently selected item.
201
202       current_item_suffix = TEXT
203              Suffix for currently selected item.
204
205       current_item_inactive_column_prefix = TEXT
206              Prefix for currently selected item in the inactive column.
207
208       current_item_inactive_column_suffix = TEXT
209              Suffix for currently selected item in the inactive column.
210
211       now_playing_prefix = TEXT
212              Prefix for currently playing song.
213
214       now_playing_suffix = TEXT
215              Suffix for currently playing song.
216
217       browser_playlist_prefix = TEXT
218              Prefix for playlists in Browser.
219
220       selected_item_prefix = TEXT
221              Prefix for selected items.
222
223       selected_item_suffix = TEXT
224              Suffix for selected items.
225
226       modified_item_prefix = TEXT
227              Prefix for modified item (tag editor).
228
229       browser_sort_mode
230              Determines sort mode for browser. Possible  values  are  "type",
231              "name", "mtime", "format" and "none".
232
233       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
237       song_window_title_format
238              Song format for window title.
239
240       song_columns_list_format
241              Format for songs' list displayed in columns.
242
243       execute_on_song_change = COMMAND
244              Shell command to execute on song change.
245
246       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
251       playlist_show_mpd_host = yes/no
252              If enabled, current MPD host will be shown in playlist.
253
254       playlist_show_remaining_time = yes/no
255              If enabled, time remaining to end  of  playlist  will  be  shown
256              after playlist statistics.
257
258       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
263       playlist_separate_albums = yes/no
264              If enabled, separators will be placed between albums.
265
266       playlist_display_mode = classic/columns
267              Default display mode for Playlist.
268
269       browser_display_mode = classic/columns
270              Default display mode for Browser.
271
272       search_engine_display_mode = classic/columns
273              Default display mode for Search engine.
274
275       playlist_editor_display_mode = classic/columns
276              Default display mode for Playlist editor.
277
278       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
282       show_duplicate_tags = yes/no
283              Indicates whether ncmpcpp should display multiple tags as-is  or
284              remove duplicates.
285
286       incremental_seeking = yes/no
287              If enabled, seek time will increment by one each second of seek‐
288              ing.
289
290       seek_time = SECONDS
291              Base seek time to begin with.
292
293       volume_change_step = NUMBER
294              Number of percents volume has to be  increased/decreased  by  in
295              volume_up/volume_down.
296
297       autocenter_mode = yes/no
298              Default state for autocenter mode at start.
299
300       centered_cursor = yes/no
301              If  enabled,  currently highlighted position in the list will be
302              always centered.
303
304       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
308       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
312       user_interface = classic/alternative
313              Default user interface used by ncmpcpp at start.
314
315       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
321       media_library_primary_tag     =     artist/album_artist/date/genre/com‐
322       poser/performer
323              Default tag type for leftmost column in media library.
324
325       media_library_albums_split_by_date = yes/no
326              Determines whether albums in media library should  be  split  by
327              date.
328
329       media_library_hide_album_dates = yes/no
330              Determines  whether  album dates in media library should be hid‐
331              den.
332
333       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
338       default_tag_editor_pattern = TEXT
339              Default pattern used by Tag editor's parser.
340
341       header_visibility = yes/no
342              If enabled, header window will be displayed, otherwise hidden.
343
344       statusbar_visibility = yes/no
345              If enabled, statusbar will be displayed, otherwise hidden.
346
347       connected_message_on_startup = yes/no
348              Show the "Connected to ..." message on startup
349
350       titles_visibility = yes/no
351              If enabled, column titles will be displayed, otherwise hidden.
352
353       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
357       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
361       lyrics_fetchers = FETCHERS
362              Comma separated list of lyrics fetchers.
363
364       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
369       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
374       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
378       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
383       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
387       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
392       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
397       show_hidden_files_in_local_browser = yes/no
398              Trigger for displaying in local browser  files  and  directories
399              that begin with '.'
400
401       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
407       startup_screen = SCREEN_NAME
408              Screen that has to be displayed at start (playlist by default).
409
410       startup_slave_screen = SCREEN_NAME
411              Slave screen that has to  be  displayed  at  start  (nothing  by
412              default).
413
414       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
418       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
423       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
428       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
432       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
436       clock_display_seconds = yes/no
437              If enabled, clock will display time in format  hh:mm:ss,  other‐
438              wise hh:mm.
439
440       display_volume_level = yes/no
441              If  enabled, volume level will be displayed in statusbar, other‐
442              wise not.
443
444       display_bitrate = yes/no
445              If enabled, bitrate of currently playing song will be  displayed
446              in statusbar.
447
448       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
452       regular_expressions = none/basic/extended/perl
453              Type of currently used regular expressions.
454
455       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
459       ignore_diacritics = yes/no
460              If  enabled, diacritics in strings will be ignored while search‐
461              ing and filtering lists.
462
463       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
467       mouse_support = yes/no
468              If set to yes, mouse support will be enabled.
469
470       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
475       lines_scrolled = NUMBER
476              Number of lines that are scrolled with mouse wheel.
477
478       empty_tag_marker = TEXT
479              Text that will be displayed, if requested tag is not set.
480
481       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
485       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
490       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
494       enable_window_title = yes/no
495              If  enabled, ncmpcpp will override current window title with its
496              own one.
497
498       search_engine_default_search_mode = MODE_NUMBER
499              Number of default mode used in search engine.
500
501       external_editor = PATH
502              Path to external editor used to edit lyrics.
503
504       use_console_editor = yes/no
505              If your external editor is  console  application,  you  need  to
506              enable it.
507
508       colors_enabled = yes/no
509              No need to describe it, huh?
510
511       empty_tag_color = COLOR
512              Color of empty tag marker.
513
514       header_window_color = COLOR
515              Color of header window.
516
517       volume_color = COLOR
518              Color of volume state.
519
520       state_line_color = COLOR
521              Color of lines separating header and statusbar from main window.
522
523       state_flags_color = COLOR
524              Color of MPD status flags.
525
526       main_window_color = COLOR
527              Color of main window.
528
529       color1 = COLOR
530              One  of  colors  used  in  Song info, Tiny tag editor and Search
531              engine.
532
533       color2 = COLOR
534              One of colors used in Song info,  Tiny  tag  editor  and  Search
535              engine.
536
537       progressbar_color = COLOR
538              Color of progressbar.
539
540       progressbar_elapsed_color = COLOR
541              Color of part of progressbar that represents elapsed time.
542
543       statusbar_color = COLOR
544              Color of statusbar.
545
546       statusbar_time_color = COLOR
547              Color of current track time shown in statusbar.
548
549       player_state_color = COLOR
550              Color of player state shown in statusbar.
551
552       alternative_ui_separator_color = COLOR
553              Color of separators used in alternative user interface.
554
555       window_border_color = BORDER
556              Border color of pop-up windows. If set to 'none', no border will
557              be shown.
558
559       active_window_border = COLOR
560              Color of active window's border.
561
562
563       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
571              You can view current keybindings by pressing F1.
572

SONG FORMAT

574       For song format you can use:
575
576        %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
594       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
600       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
604       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
608       Text  can  have  different color than the main window, e.g. if you want
609       length to be green, write $3%l$9.
610
611       Available values for colors:
612
613        - 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
624       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
627

BUGS

629       Report bugs on https://github.com/arybczak/ncmpcpp/issues
630

NOTE

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

HOMEPAGE

639       -> http://rybczak.net/ncmpcpp
640
641

SEE ALSO

643       mpc(1), mpd(1)
644
645
646
647                                                                    ncmpcpp(1)
Impressum