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 \-?, \-\-help
  19 Display help.
  20 .TP
  21 .B \-v, \-\-version
  22 Display version information.
  23 .TP
  24 .B \-\-now\-playing
  25 Display now playing song [{{(%l) }{{%a - }%t}}|{%f}}]
  26 .TP
  27 .B play
  28 Start playing and exit.
  29 .TP
  30 .B pause
  31 Pause and exit.
  32 .TP
  33 .B toggle
  34 Toggle playing and exit.
  35 .TP
  36 .B stop
  37 Stop playing and exit.
  38 .TP
  39 .B next
  40 Switch to next song and exit.
  41 .TP
  42 .B prev
  43 Switch to previous song and exit.
  44 .TP
  45 .B volume [+-]<number>
  46 Raise/lower volume by given number of percents and exit.
  47 .TP
  48 .SH "CONFIGURATION"
  49 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).
  50
  51 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.
  52
  53 Note: COLOR has to be the name (not a number) of one of colors 1-8 from SONG FORMAT section.
  54
  55 Supported configuration options:
  56 .TP
  57 .B mpd_host = HOST
  58 Connect to MPD running on specified host/unix socket.
  59 .TP
  60 .B mpd_music_dir = PATH
  61 Search for files in specified directory. This is needed for tag editor to work.
  62 .TP
  63 .B mpd_port = PORT
  64 Connect to MPD on the specified port.
  65 .TP
  66 .B mpd_connection_timeout = SECONDS
  67 Set connection timeout to MPD to given value.
  68 .TP
  69 .B mpd_crossfade_time = SECONDS
  70 Default number of seconds to crossfade, if enabled by ncmpcpp.
  71 .TP
  72 .B mpd_communication_mode = MODE
  73 If set to 'polling', ncmpcpp will constantly poll mpd for its status. If set to 'notifications', ncmppcp will make use of 'idle' command and wait for events. This is more efficient and responsive, but kinda experimental. If you decide to use it, you may want to run the latest mpd version available.
  74 .TP
  75 .B visualizer_fifo_path = PATH
  76 Path to mpd fifo output. This is needed to make music visualizer work (note that output sound format of this fifo has to be 44100:16:1)
  77 .TP
  78 .B visualizer_output_name = NAME
  79 Name of output that provides data for visualizer. Needed to keep sound and visualization in sync.
  80 .TP
  81 .B visualizer_type = spectrum/wave
  82 Defines default visualizer type (spectrum is available only if ncmpcpp was compiled with fftw support).
  83 .TP
  84 .B system_encoding = ENCODING
  85 If you use encoding other than utf8, set it in order to handle utf8 encoded strings properly.
  86 .TP
  87 .B seek_time = SECONDS
  88 Base seek time to begin with.
  89 .TP
  90 .B playlist_disable_highlight_delay = SECONDS
  91 Delay for highlighting playlist since the last key was pressed. If set to 0, highlighting never fades away.
  92 .TP
  93 .B message_delay_time = SECONDS
  94 Delay for displayed messages to remain visible.
  95 .TP
  96 .B song_list_format
  97 Format for songs' list.
  98 .TP
  99 .B song_columns_list_format
 100 Format for songs' list displayed in columns.
 101 .TP
 102 .B song_status_format
 103 Song's format for statusbar.
 104 .TP
 105 .B song_library_format
 106 Format for songs in Media library.
 107 .TP
 108 .B tag_editor_album_format
 109 Format for albums' list in Tag editor.
 110 .TP
 111 .B song_window_title_format
 112 Song format for window title.
 113 .TP
 114 .B external_editor = PATH
 115 Path to external editor used to edit lyrics.
 116 .TP
 117 .B browser_playlist_prefix = TEXT
 118 Prefix for playlists in Browser.
 119 .TP
 120 .B default_tag_editor_pattern = TEXT
 121 Deafult pattern used by Tag editor's parser.
 122 .TP
 123 .B now_playing_prefix = TEXT
 124 Prefix for currently playing song.
 125 .TP
 126 .B now_playing_suffix = TEXT
 127 Suffix for currently playing song.
 128 .TP
 129 .B selected_item_prefix = TEXT
 130 Prefix for selected items.
 131 .TP
 132 .B selected_item_suffix = TEXT
 133 Suffix for selected items.
 134 .TP
 135 .B alternative_header_first_line_format = TEXT
 136 Now playing song format for the first line in alternative user interface header window.
 137 .TP
 138 .B alternative_header_second_line_format = TEXT
 139 Now playing song format for the second line in alternative user interface header window.
 140 .TP
 141 .B color1 = COLOR
 142 One of colors used in Song info, Tiny tag editor and Search engine.
 143 .TP
 144 .B color2 = COLOR
 145 One of colors used in Song info, Tiny tag editor and Search engine.
 146 .TP
 147 .B colors_enabled = yes/no
 148 No need to describe it, huh?
 149 .TP
 150 .B header_text_scrolling = yes/no
 151 If enabled, text in header window will scroll if its length is longer then actual screen width, otherwise it won't.
 152 .TP
 153 .B fancy_scrolling = yes/no
 154 If enabled, content of other columns will be updated immediately while scrolling, otherwise only after you stop scrolling.
 155 .TP
 156 .B cyclic_scrolling = yes/no
 157 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)
 158 .TP
 159 .B mouse_list_scroll_whole_page = yes/no
 160 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.
 161 .TP
 162 .B lines_scrolled = NUMBER
 163 Number of lines that are scrolled with mouse wheel.
 164 .TP
 165 .B search_engine_default_search_mode = MODE_NUMBER
 166 Number of default mode used in search engine.
 167 .TP
 168 .B playlist_show_remaining_time = yes/no
 169 If enabled, time remaining to end of playlist will be shown after playlist's statistics.
 170 .TP
 171 .B playlist_display_mode = classic/columns
 172 Default display mode for Playlist.
 173 .TP
 174 .B browser_display_mode = classic/columns
 175 Default display mode for Browser.
 176 .TP
 177 .B search_engine_display_mode = classic/columns
 178 Default display mode for Search engine.
 179 .TP
 180 .B header_visibility = yes/no
 181 If enabled, header window will be displayed, otherwise hidden.
 182 .TP
 183 .B statusbar_visibility = yes/no
 184 If enabled, statusbar will be displayed, otherwise hidden.
 185 .TP
 186 .B autocenter_mode = yes/no
 187 Default state for autocenter mode at start.
 188 .TP
 189 .B centered_cursor = yes/no
 190 If enabled, currently highlighted position in the list will be always centered.
 191 .TP
 192 .B progressbar_look = TEXT
 193 This variable defines the look of progressbar. Note that it has to be exactly two characters long.
 194 .TP
 195 .B default_find_mode = wrapped/normal
 196 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.
 197 .TP
 198 .B default_space_mode = select/add
 199 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).
 200 .TP
 201 .B default_tag_editor_left_col = albums/dirs
 202 If set to "albums", tag editor will display list of all albums from database, otherwise it'll allow you to browse the database.
 203 .TP
 204 .B incremental_seeking = yes/no
 205 If enabled, seek time will increment by one each second of seeking.
 206 .TP
 207 .B follow_now_playing_lyrics = yes/no
 208 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).
 209 .TP
 210 .B ncmpc_like_songs_adding = yes/no
 211 If enabled, pressing space on item, which is already in playlist will remove it, otherwise add it again.
 212 .TP
 213 .B show_hidden_files_in_local_browser = yes/no
 214 Trigger for displaying in local browser files and directories that begin with '.'
 215 .TP
 216 .B default_place_to_search_in = database/playlist
 217 If set to "playlist", Search engine will perform searching in current MPD playlist rather than in music database.
 218 .TP
 219 .B display_screens_numbers_on_start = yes/no
 220 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.
 221 .TP
 222 .B screen_switcher_browser_only = yes/no
 223 If enabled, the "screen_switcher" key (<Tab> by default) will only switch between the playlist and browser screens. If disabled, the last active screen will be remembered, and the "screen_switcher" key will jump back.
 224 .TP
 225 .B jump_to_now_playing_song_at_start = yes/no
 226 If enabled, ncmpcpp will jump at start to now playing song if mpd is playing or paused.
 227 .TP
 228 .B ask_before_clearing_main_playlist = yes/no
 229 If enabled, user will be asked if he really wants to clear the main playlist after pressing key responsible for that.
 230 .TP
 231 .B clock_display_seconds = yes/no
 232 If enabled, clock will display time in format hh:mm:ss, otherwise hh:mm.
 233 .TP
 234 .B display_bitrate = yes/no
 235 If enabled, bitrate of currently playing song will be displayed in statusbar.
 236 .TP
 237 .B display_remaining_time = yes/no
 238 If enabled, remaining time of currently playing song will be be displayed in statusbar instead of elapsed time.
 239 .TP
 240 .B ignore_leading_the = yes/no
 241 If enabled, word "the" at the beginning of tags/filenames will be ignored while sorting items.
 242 .TP
 243 .B use_console_editor = yes/no
 244 If your external editor is console application, you need to enable it.
 245 .TP
 246 .B block_search_constraints_change_if_items_found = yes/no
 247 If enabled, fields in Search engine above "Reset" button will be blocked after succesful searching, otherwise they won't.
 248 .TP
 249 .B mouse_support = yes/no
 250 Self-descriptive, isn't it?
 251 .TP
 252 .B allow_physical_files_deletion = yes/no
 253 If enabled, ncmpcpp will be able to delete files using its browser screen.
 254 .TP
 255 .B allow_physical_directories_deletion = yes/no
 256 If enabled, ncmpcpp will be able to delete directories using its browser screen.
 257 .TP
 258 .B tag_editor_extended_numeration  = yes/no
 259 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.
 260 .TP
 261 .B media_library_display_date  = yes/no
 262 If enabled, dates of albums in media library will be displayed and respected in searching, otherwise not.
 263 .TP
 264 .B enable_window_title = yes/no
 265 If enabled, ncmpcpp will override current window title with its own one.
 266 .TP
 267 .B regular_expressions = basic/extended
 268 Type of currently used regular expressions.
 269 .TP
 270 .B lyrics_database = NUMBER
 271 Number of lyrics database in use. Currently supported DBs are:
 272  1 - lyricsplugin.com
 273 .TP
 274 .B user_interface = classic/alternative
 275 Default user interface used by ncmpcpp at start.
 276 .TP
 277 .B media_library_left_column = a/y/g/c/p
 278 Default tag type for left column in media library. Legend for possible letters is in  SONG FORMAT section.
 279 .TP
 280 .B empty_tag_marker = TEXT
 281 Text that will be displayed, if requested tag is not set.
 282 .TP
 283 .B empty_tag_color = COLOR
 284 Color of empty tag marker.
 285 .TP
 286 .B header_window_color = COLOR
 287 Color of header window.
 288 .TP
 289 .B volume_color = COLOR
 290 Color of volume state.
 291 .TP
 292 .B state_line_color = COLOR
 293 Color of lines separating header and statusbar from main window.
 294 .TP
 295 .B state_flags_color = COLOR
 296 Color of MPD status flags.
 297 .TP
 298 .B main_window_color = COLOR
 299 Color of main window.
 300 .TP
 301 .B main_window_highlight_color = COLOR
 302 Color of main window's highlight.
 303 .TP
 304 .B progressbar_color = COLOR
 305 Color of progressbar.
 306 .TP
 307 .B statusbar_color = COLOR
 308 Color of statusbar.
 309 .TP
 310 .B alternative_ui_separator_color = COLOR
 311 Color of separators used in alternative user interface.
 312 .TP
 313 .B active_column_color = COLOR
 314 Color of active column's highlight.
 315 .TP
 316 .B active_window_border = COLOR
 317 Color of active window's border.
 318 .TP
 319 .SH "KEYS"
 320 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).
 321
 322 You can view current ncmpcpp's keybindings by pressing '1' (Help).
 323 .SH "SONG FORMAT"
 324
 325 For song format you can use:
 326
 327  %l - length
 328  %f - filename
 329  %D - directory
 330  %a - artist
 331  %t - title
 332  %b - album
 333  %y - year
 334  %n - track number (01/12 -> 01)
 335  %N - full track info (01/12 -> 01/12)
 336  %g - genre
 337  %c - composer
 338  %p - performer
 339  %d - disc
 340  %C - comment
 341  $R - begin right alignment
 342
 343 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.
 344
 345 \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.
 346
 347 Text can have different color than the main window, e.g. if you want length to be green, write $3%l$9.
 348
 349 Available values for colors:
 350
 351  - 0 - default window color (discards all other colors)
 352  - 1 - black
 353  - 2 - red
 354  - 3 - green
 355  - 4 - yellow
 356  - 5 - blue
 357  - 6 - magenta
 358  - 7 - cyan
 359  - 8 - white
 360  - 9 - end of current color
 361
 362 \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.
 363
 364 .SH "BUGS"
 365 Report bugs on http://www.musicpd.org/mantis/
 366 .SH "NOTE"
 367 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 enviroment variables (LC_CTYPE only affects character handling).
 368 .SH "HOMEPAGE"
 369 -> http://unkart.ovh.org/ncmpcpp
 370
 371 .SH "SEE ALSO"
 372 mpc(1), mpd(1)