notify user if some files failed to be added
[ncmpcpp.git] / doc / ncmpcpp.1
1 .TH "ncmpcpp" "1"
2 .SH "NAME"
3 ncmpcpp \- An ncurses Music Player Daemon (MPD) client.
4 .SH "SYNOPSIS"
5 .B ncmpcpp
6 [options]
7 .SH "DESCRIPTION"
8 ncmpcpp is an ncurses client for MPD (Music Player Daemon), inspired by ncmpc.
9
10 Read more about MPD at http://www.musicpd.org
11 .SH "OPTIONS"
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 \-c, \-\-config
19 Use alternative configuration file
20 .TP
21 .B \-s, \-\-screen <name>
22 Specify the startup screen (<name> may be: help, playlist, browser, search-engine, media-library, playlist-editor, tag-editor, outputs, visualizer, clock)
23 .TP
24 .B \-?, \-\-help
25 Display help.
26 .TP
27 .B \-v, \-\-version
28 Display version information.
29 .TP
30 .B \-\-now\-playing
31 Display now playing song [{{(%l) }{{%a - }%t}}|{%f}}]
32 .TP
33 .B play
34 Start playing and exit.
35 .TP
36 .B pause
37 Pause and exit.
38 .TP
39 .B toggle
40 Toggle playing and exit.
41 .TP
42 .B stop
43 Stop playing and exit.
44 .TP
45 .B next
46 Switch to next song and exit.
47 .TP
48 .B prev
49 Switch to previous song and exit.
50 .TP
51 .B volume [+-]<number>
52 Raise/lower volume by given number of percents and exit.
53 .TP
54 .SH "CONFIGURATION"
55 When ncmpcpp starts, it tries to read user's settings from the ~/.ncmpcpp/config file. If no user's configuration is found, ncmpcpp uses its default configuration. An example configuration file containing all default values is provided with ncmpcpp and can be found usually in /usr/share/doc/ncmpcpp (exact location may depend on used distribution/OS/configure prefix).
56
57 Note: Each config option value must be enclosed in quotation marks (var = "example"). If you want to use quotation mark inside config option, prepend character '\\' to it.
58
59 Note: COLOR has to be the name (not a number) of one of colors 1-8 from SONG FORMAT section.
60
61 Supported configuration options:
62 .TP 
63 .B ncmpcpp_directory = PATH
64 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.
65 .TP 
66 .B lyrics_directory = PATH
67 Directory for storing downloaded lyrics. It defaults to ~/.lyrics since other MPD clients (eg. ncmpc) also use that location.
68 .TP 
69 .B mpd_host = HOST
70 Connect to MPD running on specified host/unix socket. When HOST starts with a '/', it is assumed to be a unix socket.
71 .TP 
72 .B mpd_music_dir = PATH
73 Search for files in specified directory. This is needed for tag editor to work.
74 .TP 
75 .B mpd_port = PORT
76 Connect to MPD on the specified port.
77 .TP 
78 .B mpd_connection_timeout = SECONDS
79 Set connection timeout to MPD to given value.
80 .TP 
81 .B mpd_crossfade_time = SECONDS
82 Default number of seconds to crossfade, if enabled by ncmpcpp.
83 .TP
84 .B visualizer_in_stereo = yes/no
85 Should be set to 'yes', if fifo output's format was set to 44100:16:2.
86 .TP
87 .B visualizer_fifo_path = PATH
88 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)
89 .TP
90 .B visualizer_output_name = NAME
91 Name of output that provides data for visualizer. Needed to keep sound and visualization in sync.
92 .TP
93 .B visualizer_sync_interval = SECONDS
94 Defines interval between syncing visualizer and audio outputs.
95 .TP
96 .B visualizer_type = spectrum/wave
97 Defines default visualizer type (spectrum is available only if ncmpcpp was compiled with fftw support).
98 .TP
99 .B visualizer_look = STRING
100 Defines visualizer's look (string has to be exactly 2 characters long: first one is for wave whereas second for frequency spectrum).
101 .TP
102 .B system_encoding = ENCODING
103 If you use encoding other than utf8, set it in order to handle utf8 encoded strings properly.
104 .TP
105 .B seek_time = SECONDS
106 Base seek time to begin with.
107 .TP 
108 .B volume_change_step = NUMBER
109 Number of percents volume has to be increased/decreased by in volume_up/volume_down.
110 .TP 
111 .B playlist_disable_highlight_delay = SECONDS
112 Delay for highlighting playlist since the last key was pressed. If set to 0, highlighting never fades away.
113 .TP 
114 .B message_delay_time = SECONDS
115 Delay for displayed messages to remain visible.
116 .TP
117 .B song_list_format
118 Format for songs' list.
119 .TP
120 .B song_columns_list_format
121 Format for songs' list displayed in columns.
122 .TP
123 .B song_status_format
124 Song's format for statusbar.
125 .TP
126 .B song_library_format
127 Format for songs in Media library.
128 .TP 
129 .B tag_editor_album_format
130 Format for albums' list in Tag editor.
131 .TP 
132 .B song_window_title_format
133 Song format for window title.
134 .TP
135 .B browser_sort_mode
136 Determines sort mode for browser. Possible values are "name", "mtime" and "format".
137 .TP
138 .B browser_sort_format
139 Format to use for sorting songs in browser. For this option to be effective, browser_sort_mode must be set to "format".
140 .TP 
141 .B external_editor = PATH
142 Path to external editor used to edit lyrics.
143 .TP
144 .B browser_playlist_prefix = TEXT
145 Prefix for playlists in Browser.
146 .TP
147 .B default_tag_editor_pattern = TEXT
148 Default pattern used by Tag editor's parser.
149 .TP 
150 .B now_playing_prefix = TEXT
151 Prefix for currently playing song.
152 .TP 
153 .B now_playing_suffix = TEXT
154 Suffix for currently playing song.
155 .TP 
156 .B selected_item_prefix = TEXT
157 Prefix for selected items.
158 .TP 
159 .B selected_item_suffix = TEXT
160 Suffix for selected items.
161 .TP 
162 .B modified_item_prefix = TEXT
163 Prefix for modified item (tag editor).
164 .TP 
165 .B alternative_header_first_line_format = TEXT
166 Now playing song format for the first line in alternative user interface header window.
167 .TP 
168 .B alternative_header_second_line_format = TEXT
169 Now playing song format for the second line in alternative user interface header window.
170 .TP 
171 .B color1 = COLOR
172 One of colors used in Song info, Tiny tag editor and Search engine.
173 .TP 
174 .B color2 = COLOR
175 One of colors used in Song info, Tiny tag editor and Search engine.
176 .TP 
177 .B colors_enabled = yes/no
178 No need to describe it, huh?
179 .TP 
180 .B header_text_scrolling = yes/no
181 If enabled, text in header window will scroll if its length is longer then actual screen width, otherwise it won't.
182 .TP 
183 .B fancy_scrolling = yes/no
184 If enabled, content of other columns will be updated immediately while scrolling, otherwise only after you stop scrolling.
185 .TP 
186 .B cyclic_scrolling = yes/no
187 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)
188 .TP 
189 .B mouse_list_scroll_whole_page = yes/no
190 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.
191 .TP 
192 .B lines_scrolled = NUMBER
193 Number of lines that are scrolled with mouse wheel.
194 .TP 
195 .B search_engine_default_search_mode = MODE_NUMBER
196 Number of default mode used in search engine.
197 .TP 
198 .B playlist_show_remaining_time = yes/no
199 If enabled, time remaining to end of playlist will be shown after playlist's statistics.
200 .TP 
201 .B playlist_shorten_total_times = yes/no
202 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).
203 .TP 
204 .B playlist_separate_albums = yes/no
205 If enabled, separators will be placed between albums.
206 .TP 
207 .B playlist_display_mode = classic/columns
208 Default display mode for Playlist.
209 .TP 
210 .B browser_display_mode = classic/columns
211 Default display mode for Browser.
212 .TP 
213 .B search_engine_display_mode = classic/columns
214 Default display mode for Search engine.
215 .TP 
216 .B playlist_editor_display_mode = classic/columns
217 Default display mode for Playlist editor.
218 .TP 
219 .B discard_colors_if_item_is_selected = yes/no
220 Indicates whether custom colors of tags have to be discarded if item is selected or not.
221 .TP 
222 .B header_visibility = yes/no
223 If enabled, header window will be displayed, otherwise hidden.
224 .TP 
225 .B statusbar_visibility = yes/no
226 If enabled, statusbar will be displayed, otherwise hidden.
227 .TP 
228 .B titles_visibility = yes/no
229 If enabled, column titles will be displayed, otherwise hidden.
230 .TP 
231 .B autocenter_mode = yes/no
232 Default state for autocenter mode at start.
233 .TP 
234 .B centered_cursor = yes/no
235 If enabled, currently highlighted position in the list will be always centered.
236 .TP 
237 .B progressbar_look = TEXT
238 This variable defines the look of progressbar. Note that it has to be exactly two or three characters long.
239 .TP 
240 .B progressbar_boldness = yes/no
241 This variable defines whether progressbar should be displayed in bold or not.
242 .TP 
243 .B default_find_mode = wrapped/normal
244 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.
245 .TP 
246 .B default_space_mode = select/add
247 If set to "select", space will select items instead of adding them to playlist (although selecting by space is default and the only one action for space in Playlist).
248 .TP 
249 .B incremental_seeking = yes/no
250 If enabled, seek time will increment by one each second of seeking.
251 .TP 
252 .B follow_now_playing_lyrics = yes/no
253 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).
254 .TP
255 .B fetch_lyrics_for_current_song_in_background = yes/no
256 If enabled, each time song changes lyrics fetcher will be automatically run in background in attempt to download lyrics for currently playing song.
257 .TP
258 .B store_lyrics_in_song_dir = yes/no
259 If enabled, lyrics will be saved in song's directory, otherwise in ~/.lyrics. Note that it needs properly set mpd_music_dir.
260 .TP
261 .B generate_win32_compatible_filenames = yes/no
262 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.
263 .TP
264 .B lastfm_preferred_language = ISO 639 alpha-2 language code
265 If set, ncmpcpp will try to get info from last.fm in language you set and if it fails, it will fall back to english. Otherwise it will use english the first time.
266 .TP
267 .B ncmpc_like_songs_adding = yes/no
268 If enabled, pressing space on item, which is already in playlist will remove it, otherwise add it again.
269 .TP 
270 .B show_hidden_files_in_local_browser = yes/no
271 Trigger for displaying in local browser files and directories that begin with '.'
272 .TP 
273 .B default_place_to_search_in = database/playlist
274 If set to "playlist", Search engine will perform searching in current MPD playlist rather than in music database.
275 .TP 
276 .B display_screens_numbers_on_start = yes/no
277 If enabled, screens' names and their keybindings will be shown in header window until key is pressed, otherwise they won't be displayed at all.
278 .TP 
279 .B screen_switcher_mode = SWITCHER_MODE
280 If set to "previous", key_screen_switcher will switch between current and last used screen. If set to "sequence: user_defined_sequence", it will switch between given sequence of screens. Syntax clarification can be found in example config file.
281 .TP 
282 .B locked_screen_width_part = 20-80
283 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.
284 .TP 
285 .B ask_for_locked_screen_width_part = yes/no
286 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.
287 .TP 
288 .B startup_screen = SCREEN_NUMBER
289 Screen that has to be displayed at start (playlist by default).
290 .TP 
291 .B jump_to_now_playing_song_at_start = yes/no
292 If enabled, ncmpcpp will jump at start to now playing song if mpd is playing or paused.
293 .TP 
294 .B ask_before_clearing_main_playlist = yes/no
295 If enabled, user will be asked if he really wants to clear the main playlist after pressing key responsible for that.
296 .TP 
297 .B clock_display_seconds = yes/no
298 If enabled, clock will display time in format hh:mm:ss, otherwise hh:mm.
299 .TP 
300 .B display_volume_level = yes/no
301 If enabled, volume level will be displayed in statusbar, otherwise not.
302 .TP 
303 .B display_bitrate = yes/no
304 If enabled, bitrate of currently playing song will be displayed in statusbar.
305 .TP 
306 .B display_remaining_time = yes/no
307 If enabled, remaining time of currently playing song will be be displayed in statusbar instead of elapsed time.
308 .TP 
309 .B ignore_leading_the = yes/no
310 If enabled, word "the" at the beginning of tags/filenames/sort format will be ignored while sorting items.
311 .TP 
312 .B use_console_editor = yes/no
313 If your external editor is console application, you need to enable it.
314 .TP 
315 .B block_search_constraints_change_if_items_found = yes/no
316 If enabled, fields in Search engine above "Reset" button will be blocked after successful searching, otherwise they won't.
317 .TP 
318 .B mouse_support = yes/no
319 Self-descriptive, isn't it?
320 .TP 
321 .B tag_editor_extended_numeration  = yes/no
322 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.
323 .TP
324 .B enable_window_title = yes/no
325 If enabled, ncmpcpp will override current window title with its own one.
326 .TP
327 .B regular_expressions = basic/extended
328 Type of currently used regular expressions.
329 .TP 
330 .B user_interface = classic/alternative
331 Default user interface used by ncmpcpp at start.
332 .TP 
333 .B media_library_left_column = a/y/g/c/p
334 Default tag type for left column in media library. Legend for possible letters is in  SONG FORMAT section.
335 .TP 
336 .B empty_tag_marker = TEXT
337 Text that will be displayed, if requested tag is not set.
338 .TP 
339 .B tags_separator = TEXT
340 Separator that is placed between tags. Also interpreted by tag editor which splits input string into separate tags using it.
341 .TP 
342 .B empty_tag_color = COLOR
343 Color of empty tag marker.
344 .TP 
345 .B header_window_color = COLOR
346 Color of header window.
347 .TP 
348 .B volume_color = COLOR
349 Color of volume state.
350 .TP 
351 .B state_line_color = COLOR
352 Color of lines separating header and statusbar from main window.
353 .TP 
354 .B state_flags_color = COLOR
355 Color of MPD status flags.
356 .TP 
357 .B main_window_color = COLOR
358 Color of main window.
359 .TP 
360 .B main_window_highlight_color = COLOR
361 Color of main window's highlight.
362 .TP 
363 .B progressbar_color = COLOR
364 Color of progressbar.
365 .TP 
366 .B progressbar_elapsed_color = COLOR
367 Color of part of progressbar that represents elapsed time.
368 .TP 
369 .B statusbar_color = COLOR
370 Color of statusbar.
371 .TP 
372 .B alternative_ui_separator_color = COLOR
373 Color of separators used in alternative user interface.
374 .TP 
375 .B active_column_color = COLOR
376 Color of active column's highlight.
377 .TP 
378 .B visualizer_color = COLOR
379 Color of visualization.
380 .TP 
381 .B active_window_border = COLOR
382 Color of active window's border.
383 .TP 
384 .SH "KEYS"
385 When ncmpcpp starts, it tries to read user's keybindings from ~/.ncmpcpp/keys file. If no user's keybindings is found, ncmpcpp uses its default keybindings. An example keybindings file containing all default values is provided with ncmpcpp and can be found usually in /usr/share/doc/ncmpcpp (exact location may depend on used distribution/OS/configure prefix).
386
387 You can view current ncmpcpp's keybindings by pressing '1' (Help).
388 .SH "SONG FORMAT"
389
390 For song format you can use:
391
392  %l - length
393  %f - filename
394  %D - directory
395  %a - artist
396  %A - album artist
397  %t - title
398  %b - album
399  %y - date
400  %n - track number (01/12 -> 01)
401  %N - full track info (01/12 -> 01/12)
402  %g - genre
403  %c - composer
404  %p - performer
405  %d - disc
406  %C - comment
407  %P - priority
408  $R - begin right alignment
409
410 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.
411
412 \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'.
413
414 \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.
415
416 Text can have different color than the main window, e.g. if you want length to be green, write $3%l$9.
417
418 Available values for colors:
419
420  - 0 - default window color (discards all other colors)
421  - 1 - black
422  - 2 - red
423  - 3 - green
424  - 4 - yellow
425  - 5 - blue
426  - 6 - magenta
427  - 7 - cyan
428  - 8 - white
429  - 9 - end of current color
430
431 \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.
432
433 .SH "BUGS"
434 Report bugs on http://www.musicpd.org/mantis/
435 .SH "NOTE"
436 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).
437 .SH "HOMEPAGE"
438 -> http://unkart.ovh.org/ncmpcpp
439
440 .SH "SEE ALSO"
441 mpc(1), mpd(1)