Fix fetching lyrics from and
[ncmpcpp.git] / doc / ncmpcpp.1
1 .TH "ncmpcpp" "1"
2 .SH "NAME"
3 ncmpcpp \- An ncurses Music Player Daemon (MPD) client.
5 .B ncmpcpp
6 [options]
8 ncmpcpp is an ncurses client for MPD (Music Player Daemon), inspired by ncmpc.
10 Read more about MPD at
12 .B \-h, \-\-host
13 Connect to server at host [localhost]
14 .TP
15 .B \-p, \-\-port
16 Connect to server at port [6600]
17 .TP
18 .B \-\-current-song
19 Print current song using given format and exit
20 .TP
21 .B \-c, \-\-config
22 Specify configuration file(s)
23 .TP
24 .B \-\-ignore-config-errors
25 Ignore unknown and invalid options in configuration files
26 .TP
27 .B \-c, \-\-bindings
28 Specify bindings file(s)
29 .TP
30 .B \-s, \-\-screen <name>
31 Specify the startup screen (<name> may be: help, playlist, browser, search_engine, media_library, playlist_editor, tag_editor, outputs, visualizer, clock)
32 .TP
33 .B \-S, \-\-slave-screen <name>
34 Specify the startup slave screen (<name> may be: help, playlist, browser, search_engine, media_library, playlist_editor, tag_editor, outputs, visualizer, clock)
35 .TP
36 .B \-q, \-\-quiet
37 Suppress logs and excess output
38 .TP
39 .B \-?, \-\-help
40 Display help.
41 .TP
42 .B \-v, \-\-version
43 Display version information.
44 .TP
46 When ncmpcpp starts, it tries to read user's settings from $HOME/.ncmpcpp/config and $XDG_CONFIG_HOME/ncmpcpp/config files. If no configuration is found, ncmpcpp uses its default configuration. An example configuration file containing all default values is provided with ncmpcpp and can be usually found in /usr/share/doc/ncmpcpp (exact location may depend on used distribution or configure prefix).
48 Note: Configuration option values can either be enclosed in quotation marks or not.
49  - If they are enclosed, the leftmost and the rightmost quotation marks are treated as delimiters, therefore it is not necessary to escape quotation marks you use within the value itself.
50  - If they are not, any whitespace characters between = and the first printable character of the value, as well as whitespace characters after the last printable character of the value are trimmed.
52 Therefore the rule of thumb is: if you need whitespaces at the beginning or at the end of the value, enclose it in quotation marks. Otherwise, don't.
54 Note: COLOR has to be the name (not a number) of one of colors 1-8 from SONG FORMAT section.
56 Supported configuration options:
57 .TP
58 .B ncmpcpp_directory = PATH
59 Directory for storing ncmpcpp related files. Changing it is useful if you want to store everything somewhere else and provide command line setting for alternative location to config file which defines that while launching ncmpcpp.
60 .TP
61 .B lyrics_directory = PATH
62 Directory for storing downloaded lyrics. It defaults to ~/.lyrics since other MPD clients (eg. ncmpc) also use that location.
63 .TP
64 .B mpd_host = HOST
65 Connect to MPD running on specified host/unix socket. When HOST starts with a '/', it is assumed to be a unix socket. Note: MPD_HOST environment variable overrides this setting.
66 .TP
67 .B mpd_port = PORT
68 Connect to MPD on the specified port. Note: MPD_PORT environment variable overrides this setting.
69 .TP
70 .B mpd_music_dir = PATH
71 Search for files in specified directory. This is needed for tag editor to work.
72 .TP
73 .B mpd_connection_timeout = SECONDS
74 Set connection timeout to MPD to given value.
75 .TP
76 .B mpd_crossfade_time = SECONDS
77 Default number of seconds to crossfade, if enabled by ncmpcpp.
78 .TP
79 .B visualizer_fifo_path = PATH
80 Path to mpd fifo output. This is needed to make music visualizer work (note that output sound format of this fifo has to be either 44100:16:1 or 44100:16:2, depending on whether you want mono or stereo visualization)
81 .TP
82 .B visualizer_output_name = NAME
83 Name of output that provides data for visualizer. Needed to keep sound and visualization in sync.
84 .TP
85 .B visualizer_in_stereo = yes/no
86 Should be set to 'yes', if fifo output's format was set to 44100:16:2.
87 .TP
88 .B visualizer_sync_interval = SECONDS
89 Defines interval between syncing visualizer and audio outputs.
90 .TP
91 .B visualizer_type = spectrum/wave/wave_filled/ellipse
92 Defines default visualizer type (spectrum is available only if ncmpcpp was compiled with fftw support).
93 .TP
94 .B visualizer_look = STRING
95 Defines visualizer's look (string has to be exactly 2 characters long: first one is for wave whereas second for frequency spectrum).
96 .TP
97 .B visualizer_color = COLORS
98 Comma separated list of colors to be used in music visualization.
99 .TP
100 .B system_encoding = ENCODING
101 If you use encoding other than utf8, set it in order to handle utf8 encoded strings properly.
103 .B playlist_disable_highlight_delay = SECONDS
104 Delay for highlighting playlist since the last key was pressed. If set to 0, highlighting never fades away.
106 .B message_delay_time = SECONDS
107 Delay for displayed messages to remain visible.
109 .B song_list_format
110 Song format for lists of songs.
112 .B song_status_format
113 Song format for statusbar.
115 .B song_library_format
116 Song format for media library.
118 .B alternative_header_first_line_format = TEXT
119 Now playing song format for the first line in alternative user interface header window.
121 .B alternative_header_second_line_format = TEXT
122 Now playing song format for the second line in alternative user interface header window.
124 .B current_item_prefix = TEXT
125 Prefix for currently selected item.
127 .B current_item_suffix = TEXT
128 Suffix for currently selected item.
130 .B current_item_inactive_column_prefix = TEXT
131 Prefix for currently selected item in the inactive column.
133 .B current_item_inactive_column_suffix = TEXT
134 Suffix for currently selected item in the inactive column.
136 .B now_playing_prefix = TEXT
137 Prefix for currently playing song.
139 .B now_playing_suffix = TEXT
140 Suffix for currently playing song.
142 .B browser_playlist_prefix = TEXT
143 Prefix for playlists in Browser.
145 .B selected_item_prefix = TEXT
146 Prefix for selected items.
148 .B selected_item_suffix = TEXT
149 Suffix for selected items.
151 .B modified_item_prefix = TEXT
152 Prefix for modified item (tag editor).
154 .B browser_sort_mode
155 Determines sort mode for browser. Possible values are "name", "mtime", "format" and "noop".
157 .B browser_sort_format
158 Format to use for sorting songs in browser. For this option to be effective, browser_sort_mode must be set to "format".
160 .B song_window_title_format
161 Song format for window title.
163 .B song_columns_list_format
164 Format for songs' list displayed in columns.
166 .B execute_on_song_change = COMMAND
167 Shell command to execute on song change.
169 .B execute_on_player_state_change = COMMAND
170 Shell command to execute on player state change. The environment variable
172 is set to the current state (either unknown, play, pause, or stop) for its duration.
174 .B playlist_show_mpd_host = yes/no
175 If enabled, current MPD host will be shown in playlist.
177 .B playlist_show_remaining_time = yes/no
178 If enabled, time remaining to end of playlist will be shown after playlist statistics.
180 .B playlist_shorten_total_times = yes/no
181 If enabled, total/remaining playlist time displayed in statusbar will be shown using shortened units' names (d:h:m:s instead of days:hours:minutes:seconds).
183 .B playlist_separate_albums = yes/no
184 If enabled, separators will be placed between albums.
186 .B playlist_display_mode = classic/columns
187 Default display mode for Playlist.
189 .B browser_display_mode = classic/columns
190 Default display mode for Browser.
192 .B search_engine_display_mode = classic/columns
193 Default display mode for Search engine.
195 .B playlist_editor_display_mode = classic/columns
196 Default display mode for Playlist editor.
198 .B discard_colors_if_item_is_selected = yes/no
199 Indicates whether custom colors of tags have to be discarded if item is selected or not.
201 .B show_duplicate_tags = yes/no
202 Indicates whether ncmpcpp should display multiple tags as-is or remove duplicates.
204 .B incremental_seeking = yes/no
205 If enabled, seek time will increment by one each second of seeking.
207 .B seek_time = SECONDS
208 Base seek time to begin with.
210 .B volume_change_step = NUMBER
211 Number of percents volume has to be increased/decreased by in volume_up/volume_down.
213 .B autocenter_mode = yes/no
214 Default state for autocenter mode at start.
216 .B centered_cursor = yes/no
217 If enabled, currently highlighted position in the list will be always centered.
219 .B progressbar_look = TEXT
220 This variable defines the look of progressbar. Note that it has to be exactly two or three characters long.
222 .B default_place_to_search_in = database/playlist
223 If set to "playlist", Search engine will perform searching in current MPD playlist rather than in music database.
225 .B user_interface = classic/alternative
226 Default user interface used by ncmpcpp at start.
228 .B data_fetching_delay = yes/no
229 If enabled, there will be a 250ms delay between refreshing position in media library or playlist editor and fetching appropriate data from MPD. This limits data fetched from the server and is particularly useful if ncmpcpp is connected to a remote host.
231 .B media_library_primary_tag = artist/album_artist/date/genre/composer/performer
232 Default tag type for leftmost column in media library.
234 .B media_library_albums_split_by_date = yes/no
235 Determines whether albums in media library should be split by date.
237 .B default_find_mode = wrapped/normal
238 If set to "wrapped", going from last found position to next will take you to the first one (same goes for the first position and going to previous one), otherwise no actions will be performed.
240 .B default_tag_editor_pattern = TEXT
241 Default pattern used by Tag editor's parser.
243 .B header_visibility = yes/no
244 If enabled, header window will be displayed, otherwise hidden.
246 .B statusbar_visibility = yes/no
247 If enabled, statusbar will be displayed, otherwise hidden.
249 .B titles_visibility = yes/no
250 If enabled, column titles will be displayed, otherwise hidden.
252 .B header_text_scrolling = yes/no
253 If enabled, text in header window will scroll if its length is longer then actual screen width, otherwise it won't.
255 .B cyclic_scrolling = yes/no
256 If enabled, cyclic scrolling is used (e.g. if you press down arrow being at the end of list, it'll take you to the beginning)
258 .B lines_scrolled = NUMBER
259 Number of lines that are scrolled with mouse wheel.
261 .B lyrics_fetchers = FETCHERS
262 Comma separated list of lyrics fetchers.
264 .B follow_now_playing_lyrics = yes/no
265 If enabled, lyrics will be switched at song's change to currently playing one's (Note: this works only if you are viewing lyrics of item from Playlist).
267 .B fetch_lyrics_for_current_song_in_background = yes/no
268 If enabled, each time song changes lyrics fetcher will be automatically run in background in attempt to download lyrics for currently playing song.
270 .B store_lyrics_in_song_dir = yes/no
271 If enabled, lyrics will be saved in song's directory, otherwise in ~/.lyrics. Note that it needs properly set mpd_music_dir.
273 .B generate_win32_compatible_filenames = yes/no
274 If set to yes, filenames generated by ncmpcpp (with tag editor, for lyrics, artists etc.) will not contain the following characters: \\?*:|\"<> - otherwise only slash (/) will not be used.
276 .B allow_for_physical_item_deletion = yes/no
277 If set to yes, it will be possible to physically delete files and directories from the disk in the browser.
279 .B lastfm_preferred_language = ISO 639 alpha-2 language code
280 If set, ncmpcpp will try to get info from in language you set and if it fails, it will fall back to english. Otherwise it will use english the first time.
282 .B space_add_mode = add_remove/always_add
283 If set to add_remove, attepting to add files that are already in playlist will remove them. Otherwise they can be added multiple times.
285 .B show_hidden_files_in_local_browser = yes/no
286 Trigger for displaying in local browser files and directories that begin with '.'
288 .B screen_switcher_mode = SWITCHER_MODE
289 If set to "previous", key_screen_switcher will switch between current and last used screen. If set to "screen1,...screenN" (a list of screens) it will switch between them in a sequence. Syntax clarification can be found in example config file.
291 .B startup_screen = SCREEN_NAME
292 Screen that has to be displayed at start (playlist by default).
294 .B startup_slave_screen = SCREEN_NAME
295 Slave screen that has to be displayed at start (nothing by default).
297 .B startup_slave_screen_focus = yes/no
298 If set to yes, slave screen will be the active one after startup. Otherwise master screen will be.
299 .TP 
300 .B locked_screen_width_part = 20-80
301 If you want to lock a screen, ncmpcpp asks for % of locked screen's width to be reserved before that and provides a default value, which is the one you can set here.
303 .B ask_for_locked_screen_width_part = yes/no
304 If enabled, ncmpcpp will ask for % of locked screen's width each time you want to lock a screen. If you disable that, it'll silently attempt to use default value.
306 .B jump_to_now_playing_song_at_start = yes/no
307 If enabled, ncmpcpp will jump at start to now playing song if mpd is playing or paused.
309 .B ask_before_clearing_playlists = yes/no
310 If enabled, user will be asked if he really wants to clear the playlist after pressing key responsible for that.
312 .B clock_display_seconds = yes/no
313 If enabled, clock will display time in format hh:mm:ss, otherwise hh:mm.
315 .B display_volume_level = yes/no
316 If enabled, volume level will be displayed in statusbar, otherwise not.
318 .B display_bitrate = yes/no
319 If enabled, bitrate of currently playing song will be displayed in statusbar.
321 .B display_remaining_time = yes/no
322 If enabled, remaining time of currently playing song will be be displayed in statusbar instead of elapsed time.
324 .B regular_expressions = none/basic/extended/perl
325 Type of currently used regular expressions.
327 .B ignore_leading_the = yes/no
328 If enabled, word "the" at the beginning of tags/filenames/sort format will be ignored while sorting items.
330 .B ignore_diacritics = yes/no
331 If enabled, diacritics in strings will be ignored while searching and filtering lists.
333 .B block_search_constraints_change_if_items_found = yes/no
334 If enabled, fields in Search engine above "Reset" button will be blocked after successful searching, otherwise they won't.
336 .B mouse_support = yes/no
337 If set to yes, mouse support will be enabled.
339 .B mouse_list_scroll_whole_page = yes/no
340 If enabled, mouse wheel will scroll the whole page of item list at a time, otherwise the number of lines specified by lines_scrolled variable.
342 .B empty_tag_marker = TEXT
343 Text that will be displayed, if requested tag is not set.
345 .B tags_separator = TEXT
346 Separator that is placed between tags. Also interpreted by tag editor which splits input string into separate tags using it.
348 .B tag_editor_extended_numeration = yes/no
349 If enabled, tag editor will number tracks using format xx/yy (where xx is the current track and yy is total amount of all numbered tracks), not plain xx.
351 .B media_library_sort_by_mtime = yes/no
352 If enabled, media library will be sorted by modification time. Otherwise lexicographic sorting is used.
354 .B enable_window_title = yes/no
355 If enabled, ncmpcpp will override current window title with its own one.
357 .B search_engine_default_search_mode = MODE_NUMBER
358 Number of default mode used in search engine.
360 .B external_editor = PATH
361 Path to external editor used to edit lyrics.
363 .B use_console_editor = yes/no
364 If your external editor is console application, you need to enable it.
366 .B colors_enabled = yes/no
367 No need to describe it, huh?
369 .B empty_tag_color = COLOR
370 Color of empty tag marker.
372 .B header_window_color = COLOR
373 Color of header window.
375 .B volume_color = COLOR
376 Color of volume state.
378 .B state_line_color = COLOR
379 Color of lines separating header and statusbar from main window.
381 .B state_flags_color = COLOR
382 Color of MPD status flags.
384 .B main_window_color = COLOR
385 Color of main window.
387 .B color1 = COLOR
388 One of colors used in Song info, Tiny tag editor and Search engine.
390 .B color2 = COLOR
391 One of colors used in Song info, Tiny tag editor and Search engine.
393 .B progressbar_color = COLOR
394 Color of progressbar.
396 .B progressbar_elapsed_color = COLOR
397 Color of part of progressbar that represents elapsed time.
399 .B statusbar_color = COLOR
400 Color of statusbar.
402 .B statusbar_time_color = COLOR
403 Color of current track time shown in statusbar.
405 .B player_state_color = COLOR
406 Color of player state shown in statusbar.
408 .B alternative_ui_separator_color = COLOR
409 Color of separators used in alternative user interface.
411 .B window_border_color = BORDER
412 Border color of pop-up windows. If set to 'none', no border will be shown.
414 .B active_window_border = COLOR
415 Color of active window's border.
418 When ncmpcpp starts, it tries to read user's bindings from ~/.ncmpcpp/bindings and $XDG_CONFIG_HOME/ncmpcpp/bindings files. If no bindings file is found, ncmpcpp uses the defaults. An example bindings file with the default values can be found usually in /usr/share/doc/ncmpcpp (exact location may depend on used distribution or configure prefix).
420 You can view current keybindings by pressing F1.
423 For song format you can use:
425  %l - length
426  %f - filename
427  %D - directory
428  %a - artist
429  %A - album artist
430  %t - title
431  %b - album
432  %y - date
433  %n - track number (01/12 -> 01)
434  %N - full track info (01/12 -> 01/12)
435  %g - genre
436  %c - composer
437  %p - performer
438  %d - disc
439  %C - comment
440  %P - priority
441  $R - begin right alignment
443 You can also put them in { } and then they will be displayed only if all requested values are available and/or define alternate value with { }|{ } e.g. {%a - %t}|{%f} will check if artist and title tags are available and if they are, display them. Otherwise it'll display filename.
445 \fBNote\fR: If you want to set limit on maximal length of a tag, just put the appropriate number between % and character that defines tag type, e.g. to make album take max. 20 terminal cells, use '%20b'.
447 \fBNote\fR: Format that is similar to "%a - %t" (i.e. without any additional braces) is equal to "{%a - %t}", so if one of the tags is missing, you'll get nothing.
449 Text can have different color than the main window, e.g. if you want length to be green, write $3%l$9.
451 Available values for colors:
453  - 0 - default window color (discards all other colors)
454  - 1 - black
455  - 2 - red
456  - 3 - green
457  - 4 - yellow
458  - 5 - blue
459  - 6 - magenta
460  - 7 - cyan
461  - 8 - white
462  - 9 - end of current color
464 \fBNote\fR: colors can be nested, so if you write $2some$5text$9, it'll disable only usage of blue color and make red the current one.
466 .SH "BUGS"
467 Report bugs on
468 .SH "NOTE"
469 Since MPD uses UTF\-8, ncmpcpp needs to convert characters to the charset used by the local system. If you get character conversion errors while you are running ncmpcpp, you probably need to set up your locale. This is done by setting LANG and LC_ALL/LC_CTYPE environment variables (LC_CTYPE only affects character handling).
471 ->
473 .SH "SEE ALSO"
474 mpc(1), mpd(1)