doc/ncmpc.1: migrate to Sphinx
[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:`~/.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)`