Fixed a spelling error (spotted by lintian)
[ncmpc-debian.git] / 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:`$XDG_CONFIG_HOME/ncmpc/config` (usually
83 :file:`~/.config/ncmpc/config`).  If no user configuration file is
84 found then ncmpc tries to load the global settings from
85 :file:`$SYSCONFDIR/ncmpc/config` (the actual path is displayed in the
86 output of the :option:`--version` option).  An example configuration
87 file (:file:`config.sample`) is shipped with ncmpc.
88
89
90 Connection
91 ^^^^^^^^^^
92
93 :command:`host = HOST` - The MPD host to connect to.
94
95 :command:`port = PORT` - The port to connect to.
96
97 :command:`password = PASSWORD` - Use password when connecting.
98
99 :command:`timeout = TIMEOUT` - Attempt to reconnect to mpd if a
100 response to a command is not received within TIMEOUT
101 seconds. Specifying a value in the configuration file overrides the
102 ":envvar:`MPD_TIMEOUT`" environment variable.  If no timeout is
103 specified in the configuration file or in the environment, the default
104 is 5 seconds.
105
106
107 Interface
108 ^^^^^^^^^
109
110 :command:`enable-mouse = yes|no` - Enable mouse support (if enabled at compile time).
111
112 :command:`screen-list = SCREEN1 SCREEN2...` - A list of screens to
113 cycle through when using the previous/next screen commands.  Valid
114 choices, if enabled at compile time, are playlist, browse, library,
115 help, search, song, keydef, lyrics, outputs, and chat.
116
117 :command:`library-page-tags = TAG1 TAG2 ...` - A list of tags to group
118 the library page.  The default is ``artist album``.
119
120 :command:`search-mode = MODE` - Default search mode for the search
121 screen. MODE must be one of title, artist, album, filename, and
122 artist+title, or an integer index (0 for title, 1 for artist etc.).
123
124 :command:`auto-center = yes|no` - Enable/disable auto center
125 mode. When auto center mode is enabled ncmpc centers the current track
126 in the playlist window.
127
128 :command:`scroll-offset = NUM` - Keep at least NUM lines above and
129 below the cursor on list windows, if possible.
130
131 :command:`find-show-last = yes|no` - Show the most recent query instead of a blank line for a find.
132
133 :command:`find-wrap = yes|no` - Wrapped find mode.
134
135 :command:`wrap-around = yes|no` - Wrapped cursor movement.
136
137 :command:`bell-on-wrap = yes|no` - Ring bell when find wraps around.
138
139 :command:`audible-bell = yes|no` - Sound audible bell on alerts.
140
141 :command:`visible-bell = yes|no` - Visible bell on alerts.
142
143 :command:`crossfade-time = CROSSFADE TIME` - Default crossfade time in
144 seconds.
145
146 :command:`seek-time = NUM` - Seek forward/backward by NUM seconds.
147
148 :command:`lyrics-timeout = NUM` - Quits downloading lyrics of a song
149 after the timeout of NUM seconds is reached, if NUM is greater than
150 zero.
151
152 :command:`jump-prefix-only = yes|no` - When using the jump command,
153 search for the prefix of an entry.  That means typing "m" will start
154 to the first entry which begins with "m".
155
156 :command:`lyrics-autosave = yes|no` - Automatically save lyrics after
157 receiving them.
158
159 :command:`lyrics-show-plugin = yes|no` - Show the name of the plugin
160 used to receive lyrics on the lyrics screen.
161
162 :command:`text-editor = EDITOR` - The text editor used for editing
163 lyrics.
164
165 :command:`text-editor-ask = yes|no` - Ask before starting an editor.
166
167 :command:`chat-prefix = PREFIX` - Prefix messages send with the chat
168 screen with PREFIX.  By default they are prefixed with the current
169 user name enclosed by "<" and ">" and a space (i.e. "<name> ").
170
171 :command:`second-column = yes|no` - Display song length in a second
172 column.
173
174
175 Display
176 ^^^^^^^
177
178 :command:`welcome-screen-list = yes|no` - Show a list of the screens
179 in the top line.
180
181 :command:`wide-cursor = yes|no` - Make the cursor as wide as the
182 screen.
183
184 :command:`hardware-cursor = yes|no` - Use the terminal's hardware
185 cursor instead of inverse colors.
186
187 :command:`hide-cursor = NUM` - Hide the playlist cursor after NUM
188 seconds of inactivity.
189
190 :command:`scroll = yes|no` - Scroll the title if it is too long for
191 the screen.
192
193 :command:`scroll-sep = STRING` - the separator to show at the end of
194 the scrolling title.
195
196 :command:`list-format = SONG FORMAT` - The format used to display
197 songs in the main window.
198
199 :command:`search-format = SONG FORMAT` - The format used to display
200 songs in the search window. Default is to use list-format.
201
202 :command:`status-format = SONG FORMAT` - The format used to display
203 songs on the status line.
204
205 :command:`status-message-time = TIME` - The time, in seconds, for
206 which status messages will be displayed.
207
208 :command:`display-time = yes|no` - Display the time in the status bar
209 when idle.
210
211 :command:`timedisplay-type = elapsed/remaining` - Sets whether to
212 display remaining or elapsed time in the status window.  Default is
213 elapsed.
214
215 :command:`visible-bitrate = yes|no` - Show the bitrate in the status
216 bar when playing a stream.
217
218 :command:`set-xterm-title = yes|no` - Change the XTerm title (ncmpc
219 will not restore the title).
220
221 :command:`xterm-title-format = SONG FORMAT` - The format used to for
222 the xterm title when ncmpc is playing.
223
224
225 Colors
226 ^^^^^^
227
228 :command:`enable-colors = yes|no` - Enable/disable colors.  Defaults
229 to ``yes``.
230
231 The colors used by `ncmpc` can be customized.  The ``color`` directive
232 can be used to change how a certain style looks.  It can contain a
233 text color and attributes.  The following standard colors can be
234 specified by name (`official reference
235 <https://invisible-island.net/ncurses/man/curs_color.3x.html>`__):
236
237  ``black``, ``red``, ``green``, ``yellow``, ``blue``, ``magenta``,
238  ``cyan``, ``white``
239
240 Example::
241
242   color list = cyan
243
244 Modern terminals support up to 256 colors, but they are not
245 standardized.  You can select them by specifying the number.
246 Example::
247
248   color title = 42
249
250 The background color can be specified after the text color separated
251 by a slash.  You can omit the text color if you want to change only
252 the background color::
253
254   color title = white/blue
255   color title = /blue
256
257 The color ``none`` uses the terminal's default color.
258
259 Attributes can be used to modify the font appearance.  The following
260 attributes can be specified (`official reference
261 <https://invisible-island.net/ncurses/man/curs_attr.3x.html>`__),
262 though many of them are not supported by prevalent terminals:
263
264  ``standout``, ``underline``, ``reverse``, ``blink``, ``dim``,
265  ``bold``
266
267 Example::
268
269   color alert = red blink
270
271 :command:`color background = COLOR` - Set the default background
272 color.
273
274 :command:`color title = COLOR[,ATTRIBUTE]...` - Set the text color and
275 attributes for the title row.
276
277 :command:`color title-bold = COLOR[,ATTRIBUTE]...` - Set the text
278 color for the title row (the bold part).
279
280 :command:`color line = COLOR` - Set the color of the line on the
281 second row.
282
283 :command:`color line-flags = COLOR[,ATTRIBUTE]...` - Set the text
284 color used to indicate mpd flags on the second row.
285
286 :command:`color list = COLOR[,ATTRIBUTE]...` - Set the text color in
287 the main area of ncmpc.
288
289 :command:`color list-bold = COLOR[,ATTRIBUTE]...` - Set the bold text
290 color in the main area of ncmpc.
291
292 :command:`color browser-directory = COLOR[,ATTRIBUTE]...` - Set the
293 text color used to display directories in the browser window.
294
295 :command:`color browser-playlist = COLOR[,ATTRIBUTE]...` - Set the
296 text color used to display playlists in the browser window.
297
298 :command:`color progressbar = COLOR[,ATTRIBUTE]...` - Set the color of
299 the progress indicator.
300
301 :command:`color progressbar-background = COLOR[,ATTRIBUTE]...` - Set the color of
302 the progress indicator background.
303
304 :command:`color status-state = COLOR[,ATTRIBUTE]...` - Set the text
305 color used to display mpd status in the status window.
306
307 :command:`color status-song = COLOR[,ATTRIBUTE]...` - Set the text
308 color used to display song names in the status window.
309
310 :command:`color status-time = COLOR[,ATTRIBUTE]...` - Set the text
311 color used to display time the status window.
312
313 :command:`color alert = COLOR[,ATTRIBUTE]...` - Set the text color
314 used to display alerts in the status window.
315
316 :command:`colordef COLOR = R, G, B` - Redefine any of the base
317 colors. The RGB values must be integer values between 0 and 1000.
318 *Note*: Only some terminals allow redefinitions of colors!
319
320
321
322 Keys
323 ----
324
325 When ncmpc starts it tries to read user-defined key bindings from the
326 :file:`$XDG_CONFIG_HOME/ncmpc/keys` (usually
327 :file:`~/.config/ncmpc/keys`) file.  If no user-defined key bindings
328 are found then ncmpc tries to load the global key bindings from
329 :file:`$SYSCONFDIR/ncmpc/keys` (the actual path is displayed on the
330 help screen).
331
332 You can view ncmpc's key bindings by pressing '1' (help) when ncmpc is
333 running.  To edit key bindings press 'K' and use the key editor in
334 ncmpc.
335
336
337 Song Format
338 -----------
339
340 Format of song display for status and the list window.  The metadata
341 delimiters are: %artist%, %albumartist%, %composer%, %performer%,
342 %title%, %album%, %shortalbum%, %track%, %disc, %genre%, %name%,
343 %time%, %date%, %file%, %shortfile%.
344
345 The [] operators are used to group output such that if none of the
346 metadata delimiters between '[' and ']' are matched, then none of the
347 characters between '[' and ']' are output; literal text is always
348 output. '&' and '|' are logical operators for AND and OR. '#' is used
349 to escape characters.
350
351 Some useful examples for format are::
352
353  "%file%"
354
355 and::
356
357  "[[%artist% - ]%title%]|%file%"
358
359 Another one is::
360
361  "[%artist%|(artist n/a)] - [%title%|(title n/a)]"
362
363
364 Chat Protocol
365 -------------
366
367 If ncmpc has been compiled with "chat" support, it uses the
368 client-to-client protocol available in MPD 0.17 or higher to
369 communicate with other clients.  In order to receive messages it
370 subscribes to the channel with the name "chat", and displays any
371 message sent there as-is.  When the user enters a message, it is first
372 with the prefix specified by the :command:`chat-prefix` option (or the
373 default prefix), and then sent to the "chat" channel for others to
374 read.
375
376
377 Bugs
378 ----
379
380 Report bugs on https://github.com/MusicPlayerDaemon/ncmpc/issues
381
382
383 Note
384 ---
385
386 Since MPD uses UTF-8, ncmpc needs to convert characters to the charset
387 used by the local system.  If you get character conversion errors when
388 your running ncmpc you probably need to set up your locale.  This is
389 done by setting any of the :envvar:`LC_CTYPE`, :envvar:`LANG` or
390 :envvar:`LC_ALL` environment variables (:envvar:`LC_CTYPE` only
391 affects character handling).
392
393
394 See also
395 --------
396
397 :manpage:`mpd(1)`, :manpage:`mpc(1)`, :manpage:`locale(5)`,
398 :manpage:`locale(7)`