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 -h, --host Connect to server at host [localhost]
19 -p, --port
21 Connect to server at port [6600]
22 -s, --screen <name>
24 Specify the startup screen (<name> may be: help, playlist,
25 browser, search-engine, media-library, playlist-editor, tag-edi‐
26 tor, outputs, visualizer, clock)
27 -?, --help
29 Display help.
30 -v, --version
32 Display version information.
33 --now-playing
35 Display now playing song [{{(%l) }{{%a - }%t}}|{%f}}]
36 play Start playing and exit.
38 pause Pause and exit.
40 toggle Toggle playing and exit.
42 stop Stop playing and exit.
44 next Switch to next song and exit.
46 prev Switch to previous song and exit.
48 volume [+-]<number>
50 Raise/lower volume by given number of percents and exit.
51 CONFIGURATION
54 When ncmpcpp starts, it tries to read user's settings from the
55 ~/.ncmpcpp/config file. If no user's configuration is found,
56 ncmpcpp uses its default configuration. An example configuration
57 file containing all default values is provided with ncmpcpp and
58 can be found usually in /usr/share/doc/ncmpcpp (exact location
59 may depend on used distribution/OS/configure prefix).
60 Note: Each config option value must be enclosed in quotation
62 marks (var = "example"). If you want to use quotation mark
63 inside config option, prepend character '\' to it.
64 Note: COLOR has to be the name (not a number) of one of colors
66 1-8 from SONG FORMAT section.
67 Supported configuration options:
69 mpd_host = HOST
71 Connect to MPD running on specified host/unix socket. When HOST
72 starts with a '/', it is assumed to be a unix socket.
73 mpd_music_dir = PATH
75 Search for files in specified directory. This is needed for tag
76 editor to work.
77 mpd_port = PORT
79 Connect to MPD on the specified port.
80 mpd_connection_timeout = SECONDS
82 Set connection timeout to MPD to given value.
83 mpd_crossfade_time = SECONDS
85 Default number of seconds to crossfade, if enabled by ncmpcpp.
86 mpd_communication_mode = MODE
88 If set to 'polling', ncmpcpp will constantly poll mpd for its
89 status. If set to 'notifications', ncmppcp will make use of
90 'idle' command and wait for events. This is more efficient and
91 responsive, but may cause some trouble with <mpd-0.15, so if you
92 run such version and encounter strange bugs (e.g. current track
93 time not being updated), you will either have to use 'polling'
94 or upgrade your mpd.
95 visualizer_fifo_path = PATH
97 Path to mpd fifo output. This is needed to make music visualizer
98 work (note that output sound format of this fifo has to be
99 44100:16:1)
100 visualizer_output_name = NAME
102 Name of output that provides data for visualizer. Needed to keep
103 sound and visualization in sync.
104 visualizer_sync_interval = SECONDS
106 Defines interval between syncing visualizer and audio outputs.
107 visualizer_type = spectrum/wave
109 Defines default visualizer type (spectrum is available only if
110 ncmpcpp was compiled with fftw support).
111 system_encoding = ENCODING
113 If you use encoding other than utf8, set it in order to handle
114 utf8 encoded strings properly.
115 seek_time = SECONDS
117 Base seek time to begin with.
118 playlist_disable_highlight_delay = SECONDS
120 Delay for highlighting playlist since the last key was pressed.
121 If set to 0, highlighting never fades away.
122 message_delay_time = SECONDS
124 Delay for displayed messages to remain visible.
125 song_list_format
127 Format for songs' list.
128 song_columns_list_format
130 Format for songs' list displayed in columns.
131 song_status_format
133 Song's format for statusbar.
134 song_library_format
136 Format for songs in Media library.
137 tag_editor_album_format
139 Format for albums' list in Tag editor.
140 song_window_title_format
142 Song format for window title.
143 external_editor = PATH
145 Path to external editor used to edit lyrics.
146 browser_playlist_prefix = TEXT
148 Prefix for playlists in Browser.
149 default_tag_editor_pattern = TEXT
151 Default pattern used by Tag editor's parser.
152 now_playing_prefix = TEXT
154 Prefix for currently playing song.
155 now_playing_suffix = TEXT
157 Suffix for currently playing song.
158 selected_item_prefix = TEXT
160 Prefix for selected items.
161 selected_item_suffix = TEXT
163 Suffix for selected items.
164 alternative_header_first_line_format = TEXT
166 Now playing song format for the first line in alternative user
167 interface header window.
168 alternative_header_second_line_format = TEXT
170 Now playing song format for the second line in alternative user
171 interface header window.
172 color1 = COLOR
174 One of colors used in Song info, Tiny tag editor and Search
175 engine.
176 color2 = COLOR
178 One of colors used in Song info, Tiny tag editor and Search
179 engine.
180 colors_enabled = yes/no
182 No need to describe it, huh?
183 header_text_scrolling = yes/no
185 If enabled, text in header window will scroll if its length is
186 longer then actual screen width, otherwise it won't.
187 fancy_scrolling = yes/no
189 If enabled, content of other columns will be updated immediately
190 while scrolling, otherwise only after you stop scrolling.
191 cyclic_scrolling = yes/no
193 If enabled, cyclic scrolling is used (e.g. if you press down
194 arrow being at the end of list, it'll take you to the beginning)
195 mouse_list_scroll_whole_page = yes/no
197 If enabled, mouse wheel will scroll the whole page of item list
198 at a time, otherwise the number of lines specified by
199 lines_scrolled variable.
200 lines_scrolled = NUMBER
202 Number of lines that are scrolled with mouse wheel.
203 search_engine_default_search_mode = MODE_NUMBER
205 Number of default mode used in search engine.
206 playlist_show_remaining_time = yes/no
208 If enabled, time remaining to end of playlist will be shown
209 after playlist's statistics.
210 playlist_shorten_total_times = yes/no
212 If enabled, total/remaining playlist time displayed in statusbar
213 will be shown using shortened units' names (d:h:m:s instead of
214 days:hours:minutes:seconds).
215 playlist_separate_albums = yes/no
217 If enabled, separators will be placed between albums.
218 playlist_display_mode = classic/columns
220 Default display mode for Playlist.
221 browser_display_mode = classic/columns
223 Default display mode for Browser.
224 search_engine_display_mode = classic/columns
226 Default display mode for Search engine.
227 discard_colors_if_item_is_selected = yes/no
229 Indicates whether custom colors of tags have to be discarded if
230 item is selected or not.
231 header_visibility = yes/no
233 If enabled, header window will be displayed, otherwise hidden.
234 statusbar_visibility = yes/no
236 If enabled, statusbar will be displayed, otherwise hidden.
237 titles_visibility = yes/no
239 If enabled, column titles will be displayed, otherwise hidden.
240 autocenter_mode = yes/no
242 Default state for autocenter mode at start.
243 centered_cursor = yes/no
245 If enabled, currently highlighted position in the list will be
246 always centered.
247 progressbar_look = TEXT
249 This variable defines the look of progressbar. Note that it has
250 to be exactly two or three characters long.
251 default_find_mode = wrapped/normal
253 If set to "wrapped", going from last found position to next will
254 take you to the first one (same goes for the first position and
255 going to previous one), otherwise no actions will be performed.
256 default_space_mode = select/add
258 If set to "select", space will select items instead of adding
259 them to playlist (although selecting by space is default and the
260 only one action for space in Playlist).
261 default_tag_editor_left_col = albums/dirs
263 If set to "albums", tag editor will display list of all albums
264 from database, otherwise it'll allow you to browse the database.
265 incremental_seeking = yes/no
267 If enabled, seek time will increment by one each second of seek‐
268 ing.
269 follow_now_playing_lyrics = yes/no
271 If enabled, lyrics will be switched at song's change to cur‐
272 rently playing one's (Note: this works only if you are viewing
273 lyrics of item from Playlist).
274 store_lyrics_in_song_dir = yes/no
276 If enabled, lyrics will be saved in song's directory, otherwise
277 in ~/.lyrics. Note that it needs properly set mpd_music_dir.
278 lastfm_preferred_language = ISO 639 alpha-2 language code
280 If set, ncmpcpp will try to get info from last.fm in language
281 you set and if it fails, it will fall back to english. Otherwise
282 it will use english the first time.
283 ncmpc_like_songs_adding = yes/no
285 If enabled, pressing space on item, which is already in playlist
286 will remove it, otherwise add it again.
287 show_hidden_files_in_local_browser = yes/no
289 Trigger for displaying in local browser files and directories
290 that begin with '.'
291 default_place_to_search_in = database/playlist
293 If set to "playlist", Search engine will perform searching in
294 current MPD playlist rather than in music database.
295 display_screens_numbers_on_start = yes/no
297 If enabled, screens' names and their keybindings will be shown
298 in header window until key is pressed, otherwise they won't be
299 displayed at all.
300 screen_switcher_previous = SWITCHER_MODE
302 If set to "previous", key_screen_switcher will switch between
303 current and last used screen. If set to "sequence:
304 user_defined_sequence", it will switch between given sequence of
305 screens. Syntax clarification can be found in example config
306 file.
307 startup_screen = SCREEN_NUMBER
309 Screen that has to be displayed at start (playlist by default).
310 jump_to_now_playing_song_at_start = yes/no
312 If enabled, ncmpcpp will jump at start to now playing song if
313 mpd is playing or paused.
314 ask_before_clearing_main_playlist = yes/no
316 If enabled, user will be asked if he really wants to clear the
317 main playlist after pressing key responsible for that.
318 clock_display_seconds = yes/no
320 If enabled, clock will display time in format hh:mm:ss, other‐
321 wise hh:mm.
322 display_volume_level = yes/no
324 If enabled, volume level will be displayed in statusbar, other‐
325 wise not.
326 display_bitrate = yes/no
328 If enabled, bitrate of currently playing song will be displayed
329 in statusbar.
330 display_remaining_time = yes/no
332 If enabled, remaining time of currently playing song will be be
333 displayed in statusbar instead of elapsed time.
334 ignore_leading_the = yes/no
336 If enabled, word "the" at the beginning of tags/filenames will
337 be ignored while sorting items.
338 use_console_editor = yes/no
340 If your external editor is console application, you need to
341 enable it.
342 block_search_constraints_change_if_items_found = yes/no
344 If enabled, fields in Search engine above "Reset" button will be
345 blocked after successful searching, otherwise they won't.
346 mouse_support = yes/no
348 Self-descriptive, isn't it?
349 allow_physical_files_deletion = yes/no
351 If enabled, ncmpcpp will be able to delete files using its
352 browser screen.
353 allow_physical_directories_deletion = yes/no
355 If enabled, ncmpcpp will be able to delete directories using its
356 browser screen.
357 tag_editor_extended_numeration = yes/no
359 If enabled, tag editor will number tracks using format xx/yy
360 (where xx is the current track and yy is total amount of all
361 numbered tracks), not plain xx.
362 media_library_display_date = yes/no
364 If enabled, dates of albums in media library will be displayed
365 and respected in searching, otherwise not.
366 media_library_display_empty_tag = yes/no
368 If enabled, left column will contain entry for 'empty' tag, oth‐
369 erwise not.
370 media_library_disable_two_column_mode = yes/no
372 If enabled, pressing the key for the media library twice won't
373 switch it to two column mode.
374 enable_window_title = yes/no
376 If enabled, ncmpcpp will override current window title with its
377 own one.
378 regular_expressions = basic/extended
380 Type of currently used regular expressions.
381 user_interface = classic/alternative
383 Default user interface used by ncmpcpp at start.
384 media_library_left_column = a/y/g/c/p
386 Default tag type for left column in media library. Legend for
387 possible letters is in SONG FORMAT section.
388 empty_tag_marker = TEXT
390 Text that will be displayed, if requested tag is not set.
391 empty_tag_color = COLOR
393 Color of empty tag marker.
394 header_window_color = COLOR
396 Color of header window.
397 volume_color = COLOR
399 Color of volume state.
400 state_line_color = COLOR
402 Color of lines separating header and statusbar from main window.
403 state_flags_color = COLOR
405 Color of MPD status flags.
406 main_window_color = COLOR
408 Color of main window.
409 main_window_highlight_color = COLOR
411 Color of main window's highlight.
412 progressbar_color = COLOR
414 Color of progressbar.
415 statusbar_color = COLOR
417 Color of statusbar.
418 alternative_ui_separator_color = COLOR
420 Color of separators used in alternative user interface.
421 active_column_color = COLOR
423 Color of active column's highlight.
424 visualizer_color = COLOR
426 Color of visualization.
427 active_window_border = COLOR
429 Color of active window's border.
430 KEYS When ncmpcpp starts, it tries to read user's keybindings from
433 ~/.ncmpcpp/keys file. If no user's keybindings is found, ncmpcpp
434 uses its default keybindings. An example keybindings file con‐
435 taining all default values is provided with ncmpcpp and can be
436 found usually in /usr/share/doc/ncmpcpp (exact location may
437 depend on used distribution/OS/configure prefix).
438 You can view current ncmpcpp's keybindings by pressing '1'
440 (Help).
441
443 For song format you can use:
444 %l - length
446 %f - filename
447 %D - directory
448 %a - artist
449 %A - album artist
450 %t - title
451 %b - album
452 %y - year
453 %n - track number (01/12 -> 01)
454 %N - full track info (01/12 -> 01/12)
455 %g - genre
456 %c - composer
457 %p - performer
458 %d - disc
459 %C - comment
460 $R - begin right alignment
461 You can also put them in { } and then they will be displayed only if
463 all requested values are available and/or define alternate value with {
464 }|{ } e.g. {%a - %t}|{%f} will check if artist and title tags are
465 available and if they are, display them. Otherwise it'll display file‐
466 name.
467 Note: If you want to set limit on maximal length of a tag, just put the
469 appropriate number between % and character that defines tag type, e.g.
470 to make album take max. 20 terminal cells, use '%20b'.
471 Note: Format that is similar to "%a - %t" (i.e. without any additional
473 braces) is equal to "{%a - %t}", so if one of the tags is missing,
474 you'll get nothing.
475 Text can have different color than the main window, e.g. if you want
477 length to be green, write $3%l$9.
478 Available values for colors:
480 - 0 - default window color (discards all other colors)
482 - 1 - black
483 - 2 - red
484 - 3 - green
485 - 4 - yellow
486 - 5 - blue
487 - 6 - magenta
488 - 7 - cyan
489 - 8 - white
490 - 9 - end of current color
491 Note: colors can be nested, so if you write $2some$5text$9, it'll dis‐
493 able only usage of blue color and make red the current one.
494
497 Report bugs on http://www.musicpd.org/mantis/
498
500 Since MPD uses UTF-8, ncmpcpp needs to convert characters to the
501 charset used by the local system. If you get character conversion
502 errors while you are running ncmpcpp, you probably need to set up your
503 locale. This is done by setting LANG and LC_ALL/LC_CTYPE environment
504 variables (LC_CTYPE only affects character handling).
505
507 -> http://unkart.ovh.org/ncmpcpp
508
511 mpc(1), mpd(1)
512 ncmpcpp(1)