doc/index.rst

   1 ncmpc
   2 =====
   3
   4
   5 Description
   6 -----------
   7
   8 ncmpc is a command-line client for the `Music Player Daemon
   9 <http://www.musicpd.org/>`__ (MPD).
  10
  11 By default, ncmpc connects to the local MPD instance.  A different MPD
  12 instance can be selected using the command line options
  13 :option:`--host` and :option:`--port`, or by setting the environment
  14 variables :envvar:`MPD_HOST` and :envvar:`MPD_PORT`::
  15
  16  ncmpc --host=musicserver --port=44000
  17
  18 You can connect to a "local" socket by setting the host to a file path
  19 (e.g. ":file:`/run/mpd/socket`").  Abstract sockets can be used with a ":file:`@`"
  20 prefix (e.g. ":file:`@mpd`").
  21
  22 To use a password with MPD, set :envvar:`MPD_HOST` to
  23 :samp:`password@host` or use the command line option
  24 :option:`--password`.  Values from the command line override values
  25 from the environment.
  26
  27
  28 Synopsis
  29 --------
  30
  31  ncmpc [options]
  32
  33
  34 Options
  35 -------
  36
  37 .. option:: -?, --help
  38
  39  Display help.
  40
  41 .. option:: -V, --version
  42
  43  Display version information and build-time configuration.
  44
  45 .. option:: -c, --colors
  46
  47  Enable colors.
  48
  49 .. option:: -C, --no-colors
  50
  51  Disable colors.
  52
  53 .. option:: -m, --mouse
  54
  55  Enable mouse.
  56
  57 .. option:: --host=HOST
  58
  59  The MPD host to connect to.
  60
  61 .. option:: --port=PORT, -p PORT
  62
  63  The port to connect to.
  64
  65 .. option:: -P, --password=PASSWORD
  66
  67  Use password when connecting.
  68
  69 .. option:: -f, --config=FILE
  70
  71  Read configuration from file.
  72
  73 .. option:: -k, --key-file=FILE
  74
  75  Read key bindings from file.
  76
  77
  78 Configuration
  79 -------------
  80
  81 When ncmpc starts it tries to read the user's configuration file,
  82 :file:`~/.ncmpc/config`.  If no user configuration file is found then
  83 ncmpc tries to load the global settings from
  84 :file:`$SYSCONFDIR/ncmpc/config` (the actual path is displayed in the
  85 output of the :option:`--version` option).  An example configuration
  86 file (:file:`config.sample`) is shipped with ncmpc.
  87
  88
  89 Connection
  90 ^^^^^^^^^^
  91
  92 :command:`host = HOST` - The MPD host to connect to.
  93
  94 :command:`port = PORT` - The port to connect to.
  95
  96 :command:`password = PASSWORD` - Use password when connecting.
  97
  98 :command:`timeout = TIMEOUT` - Attempt to reconnect to mpd if a
  99 response to a command is not received within TIMEOUT
 100 seconds. Specifying a value in the configuration file overrides the
 101 ":envvar:`MPD_TIMEOUT`" environment variable.  If no timeout is
 102 specified in the configuration file or in the environment, the default
 103 is 5 seconds.
 104
 105
 106 Interface
 107 ^^^^^^^^^
 108
 109 :command:`enable-mouse = yes|no` - Enable mouse support (if enabled at compile time).
 110
 111 :command:`screen-list = SCREEN1 SCREEN2...` - A list of screens to
 112 cycle through when using the previous/next screen commands.  Valid
 113 choices, if enabled at compile time, are playlist, browse, artist,
 114 help, search, song, keydef, lyrics, outputs, and chat.
 115
 116 :command:`search-mode = MODE` - Default search mode for the search
 117 screen. MODE must be one of title, artist, album, filename, and
 118 artist+title, or an interger index (0 for title, 1 for artist etc.).
 119
 120 :command:`auto-center = yes|no` - Enable/disable auto center
 121 mode. When auto center mode is enabled ncmpc centers the current track
 122 in the playlist window.
 123
 124 :command:`scroll-offset = NUM` - Keep at least NUM lines above and
 125 below the cursor on list windows, if possible.
 126
 127 :command:`find-show-last = yes|no` - Show the most recent query instead of a blank line for a find.
 128
 129 :command:`find-wrap = yes|no` - Wrapped find mode.
 130
 131 :command:`wrap-around = yes|no` - Wrapped cursor movement.
 132
 133 :command:`bell-on-wrap = yes|no` - Ring bell when find wraps around.
 134
 135 :command:`audible-bell = yes|no` - Sound audible bell on alerts.
 136
 137 :command:`visible-bell = yes|no` - Visible bell on alerts.
 138
 139 :command:`crossfade-time = CROSSFADE TIME` - Default crossfade time in
 140 seconds.
 141
 142 :command:`seek-time = NUM` - Seek forward/backward by NUM seconds.
 143
 144 :command:`lyrics-timeout = NUM` - Quits downloading lyrics of a song
 145 after the timeout of NUM seconds is reached, if NUM is greater than
 146 zero.
 147
 148 :command:`jump-prefix-only = yes|no` - When using the jump command,
 149 search for the prefix of an entry.  That means typing "m" will start
 150 to the first entry which begins with "m".
 151
 152 :command:`lyrics-autosave = yes|no` - Automatically save lyrics after
 153 receiving them.
 154
 155 :command:`lyrics-show-plugin = yes|no` - Show the name of the plugin
 156 used to receive lyrics on the lyrics screen.
 157
 158 :command:`text-editor = EDITOR` - The text editor used for editing
 159 lyrics.
 160
 161 :command:`text-editor-ask = yes|no` - Ask before starting an editor.
 162
 163 :command:`chat-prefix = PREFIX` - Prefix messages send with the chat
 164 screen with PREFIX.  By default they are prefixed with the current
 165 user name enclosed by "<" and ">" and a space (i.e. "<name> ").
 166
 167 :command:`second-column = yes|no` - Display song length in a second
 168 column.
 169
 170
 171 Display
 172 ^^^^^^^
 173
 174 :command:`welcome-screen-list = yes|no` - Show a list of the screens
 175 in the top line on startup.
 176
 177 :command:`wide-cursor = yes|no` - Make the cursor as wide as the
 178 screen.
 179
 180 :command:`hardware-cursor = yes|no` - Use the terminal's hardware
 181 cursor instead of inverse colors.
 182
 183 :command:`hide-cursor = NUM` - Hide the playlist cursor after NUM
 184 seconds of inactivity.
 185
 186 :command:`scroll = yes|no` - Scroll the title if it is too long for
 187 the screen.
 188
 189 :command:`scroll-sep = STRING` - the separator to show at the end of
 190 the scrolling title.
 191
 192 :command:`list-format = SONG FORMAT` - The format used to display
 193 songs in the main window.
 194
 195 :command:`search-format = SONG FORMAT` - The format used to display
 196 songs in the search window. Default is to use list-format.
 197
 198 :command:`status-format = SONG FORMAT` - The format used to display
 199 songs on the status line.
 200
 201 :command:`status-message-time = TIME` - The time, in seconds, for
 202 which status messages will be displayed.
 203
 204 :command:`display-time = yes|no` - Display the time in the status bar
 205 when idle.
 206
 207 :command:`timedisplay-type = elapsed/remaining` - Sets whether to
 208 display remaining or elapsed time in the status window.  Default is
 209 elapsed.
 210
 211 :command:`visible-bitrate = yes|no` - Show the bitrate in the status
 212 bar when playing a stream.  :command:`
 213
 214 :command:`set-xterm-title = yes|no` - Change the XTerm title (ncmpc
 215 will not restore the title).
 216
 217 :command:`xterm-title-format = SONG FORMAT` - The format used to for
 218 the xterm title when ncmpc is playing.
 219
 220
 221 Colors
 222 ^^^^^^
 223
 224 :command:`enable-colors = yes|no` - Enable/disable colors.
 225
 226 :command:`color background = COLOR` - Set the background color. If the
 227 background color is assigned to the keyword ":samp:`none`", ncmpc will
 228 not change the background color.  Standard colors are: black, red,
 229 green, yellow, blue, magenta, cyan and white.  Terminal specific
 230 colors can also be given as integers.
 231
 232 :command:`color title = COLOR[,ATTRIBUTE]...` - Set the text color and
 233 attributes for the title row.  Text colors are the same as for the
 234 background. Valid attributes are: standout, underline, reverse, blink,
 235 dim, and bold.
 236
 237 :command:`color title-bold = COLOR[,ATTRIBUTE]...` - Set the text
 238 color for the title row (the bold part).
 239
 240 :command:`color line = COLOR` - Set the color of the line on the
 241 second row.
 242
 243 :command:`color line-flags = COLOR[,ATTRIBUTE]...` - Set the text
 244 color used to indicate mpd flags on the second row.
 245
 246 :command:`color list = COLOR[,ATTRIBUTE]...` - Set the text color in
 247 the main area of ncmpc.
 248
 249 :command:`color list-bold = COLOR[,ATTRIBUTE]...` - Set the bold text
 250 color in the main area of ncmpc.
 251
 252 :command:`color browser-directory = COLOR[,ATTRIBUTE]...` - Set the
 253 text color used to display directories in the browser window.
 254
 255 :command:`color browser-playlist = COLOR[,ATTRIBUTE]...` - Set the
 256 text color used to display playlists in the browser window.
 257
 258 :command:`color progressbar = COLOR[,ATTRIBUTE]...` - Set the color of
 259 the progress indicator.
 260
 261 :command:`color status-state = COLOR[,ATTRIBUTE]...` - Set the text
 262 color used to display mpd status in the status window.
 263
 264 :command:`color status-song = COLOR[,ATTRIBUTE]...` - Set the text
 265 color used to display song names in the status window.
 266
 267 :command:`color status-time = COLOR[,ATTRIBUTE]...` - Set the text
 268 color used to display time the status window.
 269
 270 :command:`color alert = COLOR[,ATTRIBUTE]...` - Set the text color
 271 used to display alerts in the status window.
 272
 273 :command:`colordef COLOR = R, G, B` - Redefine any of the base
 274 colors. The RGB values must be integer values between 0 and 1000.
 275 *Note*: Only some terminals allow redefinitions of colors!
 276
 277
 278
 279 Keys
 280 ----
 281
 282 When ncmpc starts it tries to read user-defined key bindings from the
 283 :file:`~/.ncmpc/keys` file.  If no user-defined key bindings are found
 284 then ncmpc tries to load the global key bindings from
 285 :file:`$SYSCONFDIR/ncmpc/keys` (the actual path is displayed on the
 286 help screen).
 287
 288 You can view ncmpc's key bindings by pressing '1' (help) when ncmpc is
 289 running.  To edit key bindings press 'K' and use the key editor in
 290 ncmpc.
 291
 292
 293 Song Format
 294 -----------
 295
 296 Format of song display for status and the list window.  The metadata
 297 delimiters are: %artist%, %albumartist%, %composer%, %performer%,
 298 %title%, %album%, %shortalbum%, %track%, %disc, %genre%, %name%,
 299 %time%, %date%, %file%, %shortfile%.
 300
 301 The [] operators are used to group output such that if none of the
 302 metadata delimiters between '[' and ']' are matched, then none of the
 303 characters between '[' and ']' are output; literal text is always
 304 output. '&' and '|' are logical operators for AND and OR. '#' is used
 305 to escape characters.
 306
 307 Some useful examples for format are::
 308
 309  "%file%"
 310
 311 and::
 312
 313  "[[%artist% - ]%title%]|%file%"
 314
 315 Another one is::
 316
 317  "[%artist%|(artist n/a)] - [%title%|(title n/a)]"
 318
 319
 320 Chat Protocol
 321 -------------
 322
 323 If ncmpc has been compiled with "chat" support, it uses the
 324 client-to-client protocol available in MPD 0.17 or higher to
 325 communicate with other clients.  In order to receive messages it
 326 subscribes to the channel with the name "chat", and displays any
 327 message sent there as-is.  When the user enters a message, it is first
 328 with the prefix specified by the :command:`chat-prefix` option (or the
 329 default prefix), and then sent to the "chat" channel for others to
 330 read.
 331
 332
 333 Bugs
 334 ----
 335
 336 Report bugs on https://github.com/MusicPlayerDaemon/ncmpc/issues
 337
 338
 339 Note
 340 ---
 341
 342 Since MPD uses UTF-8, ncmpc needs to convert characters to the charset
 343 used by the local system.  If you get character conversion errors when
 344 your running ncmpc you probably need to set up your locale.  This is
 345 done by setting any of the :envvar:`LC_CTYPE`, :envvar:`LANG` or
 346 :envvar:`LC_ALL` environment variables (:envvar:`LC_CTYPE` only
 347 affects character handling).
 348
 349
 350 See also
 351 --------
 352
 353 :manpage:`mpd(1)`, :manpage:`mpc(1)`, :manpage:`locale(5)`,
 354 :manpage:`locale(7)`