]> kaliko git repositories - mpd-sima.git/blob - data/man/mpd-sima.1
8e1b63d994336e3091a5f35bf4d7550e2711918a
[mpd-sima.git] / data / man / mpd-sima.1
1 '\" t
2 .\"     Title: mpd-sima
3 .\"    Author: kaliko <kaliko@azylum.org>
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\"      Date: 11/16/2021
6 .\"    Manual: mpd-sima 0.18.0 User Manual
7 .\"    Source: mpd-sima
8 .\"  Language: English
9 .\"
10 .TH "MPD\-SIMA" "1" "11/16/2021" "mpd-sima" "mpd-sima 0.18.0 User Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el       .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 mpd-sima \- mpd\-sima will try to maintain some titles ahead in the queue following different policies\&.
32 .SH "SYNOPSIS"
33 .HP \w'\fBmpd\-sima\fR\ 'u
34 \fBmpd\-sima\fR [\fB\-\-daemon\fR] [\fB\-\-config=\fR\fIconf_file\fR] [\fB\-\-var\-dir=\fR\fIvar_directory\fR] [\fB\-\-pid=\fR\fIpid_file\fR] [\fB\-\-log=\fR\fIlog_file\fR] [\fB\-\-log\-level=\fR\fIlog_level\fR] [\fB\-\-host=\fR\fImpd_host\fR] [\fB\-\-mpd_port=\fR\fImpd_port\fR]
35 .HP \w'\fBmpd\-sima\fR\ 'u
36 \fBmpd\-sima\fR {{\fB\-h\fR\ |\ \fB\-\-help\fR}\ \fB\-\-version\fR} 
37 .HP \w'\fBmpd\-sima\fR\ 'u
38 \fBmpd\-sima\fR config\-test [\fB\-\-config=\fR\fIconf_file\fR]
39 .HP \w'\fBmpd\-sima\fR\ 'u
40 \fBmpd\-sima\fR create\-db [\fB\-\-var\-dir=\fR\fIvar_directory\fR]
41 .HP \w'\fBmpd\-sima\fR\ 'u
42 \fBmpd\-sima\fR generate\-config [\fB\&...\fR]
43 .HP \w'\fBmpd\-sima\fR\ 'u
44 \fBmpd\-sima\fR purge\-history [\fB\-\-var\-dir=\fR\fIvar_directory\fR]
45 .HP \w'\fBmpd\-sima\fR\ 'u
46 \fBmpd\-sima\fR bl\-view
47 .HP \w'\fBmpd\-sima\fR\ 'u
48 \fBmpd\-sima\fR bl\-add\-artist [\fBartist\fR]
49 .HP \w'\fBmpd\-sima\fR\ 'u
50 \fBmpd\-sima\fR bl\-add\-album [\fBalbum\fR]
51 .HP \w'\fBmpd\-sima\fR\ 'u
52 \fBmpd\-sima\fR bl\-add\-track [\fBtrack\fR]
53 .HP \w'\fBmpd\-sima\fR\ 'u
54 \fBmpd\-sima\fR bl\-delete \fBid\fR
55 .SH "DESCRIPTION"
56 .PP
57 This manual page documents briefly the
58 \fBmpd\-sima\fR
59 commands\&.
60 .PP
61 At start up default configuration is first overridden by user configuration in mpd_sima\&.cfg (see
62 the section called \(lqFILES\(rq) and finally command lines options are honored\&. For instance you can override default MPD host (localhost) in your configuration file or with
63 \fB\-S\ \&my_mpd_server\fR
64 option\&. For default configuration see
65 the section called \(lqCONFIGURATION\(rq\&. See also environment variables special case for MPD host and port in
66 the section called \(lqENVIRONMENT\(rq\&.
67 .SH "EXAMPLE"
68 .SS "Launch as a system service (d\(aemon)\&."
69 .PP
70 Here follows an example on how to launch mpd\-sima as a service on your system, not attach to regular user configuration/database\&.
71 .PP
72 \fBmpd\-sima \-\-daemon \-\-conf=/etc/mpd_sima\&.cfg \-\-var\-dir=/var/cache/mpd\-sima/ \-\-pid=/run/mpd\-sima\&.pid \-\-log=/var/log/mpd\-sima\&.log\fR
73 .SS "Launch in user land"
74 .PP
75 Launching mpd\-sima from/whithin your user account is easy, you can simply call
76 \fBmpd\-sima\fR
77 from your shell or one of the following command:
78 .PP
79 Background execution (d\(aemonise), log in the specified file, save pid:
80 .PP
81 \fBmpd\-sima \-\-daemon \-\-pid=$HOME/var/run/mpd\-sima\&.pid \-\-log=$HOME/var/log/mpd\-sima\&.log\fR
82 .PP
83 Foreground execution, connect
84 \fImy\&.mpd\&.server\&.org\fR, log to std(out|err):
85 .PP
86 \fBmpd\-sima \-\-host=my\&.mpd\&.server\&.org\fR
87 .SH "OPTIONS"
88 .PP
89 The program follows the usual GNU command line syntax, with long options starting with two dashes (`\-\*(Aq)\&. A summary of options is included below\&.
90 .PP
91 \fB\-h\fR, \fB\-\-help\fR
92 .RS 4
93 Print help and exit\&.
94 .RE
95 .PP
96 \fB\-\-version\fR
97 .RS 4
98 Print version and exit\&.
99 .RE
100 .PP
101 \fB\-\-daemon\fR
102 .RS 4
103 Start as a daemon\&. Log redirected to /dev/null, usually setting
104 \fB\-\-log\fR
105 and
106 \fB\-\-pid\fR
107 options in daemon mode are a good idea to monitor/stop the process\&.
108 .RE
109 .PP
110 \fB\-p \fR\fB\fIpid_file\fR\fR, \fB\-\-pid=\fR\fB\fIpid_file\fR\fR
111 .RS 4
112 Use the specific file
113 \fIpid_file\fR
114 to store pid to\&.
115 .br
116 Default is not to store pid info\&.
117 .RE
118 .PP
119 \fB\-l \fR\fB\fIlog_file\fR\fR, \fB\-\-log=\fR\fB\fIlog_file\fR\fR
120 .RS 4
121 Use the specific file
122 \fIlog_file\fR
123 to log messages to\&.
124 .br
125 Default is to log to stdout/stderr\&.
126 .RE
127 .PP
128 \fB\-v \fR\fB\fIlog_level\fR\fR, \fB\-\-log\-level=\fR\fB\fIlog_level\fR\fR
129 .RS 4
130 Verbosity in [debug,info,warning,error]\&.
131 .br
132 Default is to log info messages\&.
133 .RE
134 .PP
135 \fB\-c \fR\fB\fIconf_file\fR\fR, \fB\-\-config=\fR\fB\fIconf_file\fR\fR
136 .RS 4
137 Use the specific file
138 \fIconf_file\fR
139 to set up configuration instead of looking for the default user configuration file\&.
140 .br
141 Default is to look for
142 \fB$XDG_CONFIG_HOME/mpd_sima/mpd_sima\&.cfg\fR\&.
143 .br
144
145 CLI option overrides any equivalent mentioned in configuration file, ie\&. launching mpd\-sima with \*(Aq\fB\-\-port\fR\*(Aq CLI option will ignore port setting in configuration file\&.
146 .br
147
148 For more details on configuration file cf\&.
149 \fBmpd_sima.cfg\fR(5), see also
150 the section called \(lqFILES\(rq\&.
151 .br
152
153 .RE
154 .PP
155 \fB\-\-var\-dir=\fR\fB\fIvar_directory\fR\fR
156 .RS 4
157 Use the specific path
158 \fIvar_directory\fR
159 to look for (or create) var files (ie\&. database) instead of looking at the default user data location\&.
160 .br
161 Default is to look in
162 \fB$XDG_DATA_HOME/mpd_sima/\fR\&. Concerning
163 \fB$XDG_DATA_HOME\fR
164 see also
165 the section called \(lqFILES\(rq\&.
166 .RE
167 .PP
168 \fB\-S \fR\fB\fImpd_host\fR\fR, \fB\-\-host=\fR\fB\fImpd_host\fR\fR
169 .RS 4
170 Use the specific host
171 \fImpd_host\fR
172 as MPD server\&.
173 .br
174 \fImpd_host\fR
175 can be an
176 IP
177 or a fully qualified domain name as long as your system can resolve it\&. This overrides
178 \fBMPD_HOST\fR
179 environment variable\&.
180 .br
181 Default is
182 \fIlocalhost\fR\&.
183 .sp
184 See also
185 the section called \(lqENVIRONMENT\(rq\&.
186 .RE
187 .PP
188 \fB\-P \fR\fB\fImpd_port\fR\fR, \fB\-\-port=\fR\fB\fImpd_port\fR\fR
189 .RS 4
190 Use the specific port number
191 \fImpd_port\fR
192 on MPD server\&. This overrides
193 \fBMPD_PORT\fR
194 environment variable\&.
195 .br
196 Default is
197 \fI6600\fR\&.
198 .sp
199 See also
200 the section called \(lqENVIRONMENT\(rq
201 .RE
202 .PP
203 \fBconfig\-test\fR
204 .RS 4
205 Test configuration file and exit\&. Uses the configuration file specified with
206 \fB\-\-config\fR
207 or default location\&.
208 .br
209 Default is to use
210 \fB$XDG_CONFIG_HOME/mpd_sima/mpd_sima\&.cfg\fR
211 (see
212 the section called \(lqFILES\(rq
213 for more)\&.
214 .sp
215 config\-test tests MPD connection and Tags plugin configuration\&.
216 .RE
217 .PP
218 \fBcreate\-db\fR
219 .RS 4
220 Create the database and exit\&. Uses folder specified with
221 \fB\-\-var\-dir\fR
222 or default directory\&.
223 .br
224 Default is to use
225 \fB$XDG_DATA_HOME/mpd_sima/\fR
226 (see
227 the section called \(lqFILES\(rq
228 for more)\&.
229 .RE
230 .PP
231 \fBgenerate\-config\fR
232 .RS 4
233 Generate a sample configuration file according to the current CLI options and env\&. var\&.\&. The configuration is written on stdout\&.
234 .RE
235 .PP
236 \fBpurge\-history\fR
237 .RS 4
238 Purge play history in the database and exit\&. Uses folder specified with
239 \fB\-\-var\-dir\fR
240 or default directory\&.
241 .br
242 Default is to use
243 \fB$XDG_DATA_HOME/mpd_sima/\fR
244 (see
245 the section called \(lqFILES\(rq
246 for more)\&.
247 .RE
248 .PP
249 \fBbl\-view\fR
250 .RS 4
251 View blocklist, useful to get entry IDs to remove with delete command\&.
252 .RE
253 .PP
254 \fBbl\-add\-artist \fR\fB\fIartist\fR\fR
255 .RS 4
256 Add artist to the blocklist\&. If
257 \fIartist\fR
258 is not provided, try to get the currently playing artist\&.
259 .RE
260 .PP
261 \fBbl\-add\-album \fR\fB\fIalbum\fR\fR
262 .RS 4
263 Add album to the blocklist\&. If
264 \fIalbum\fR
265 is not provided, try to get the currently playing album\&.
266 .RE
267 .PP
268 \fBbl\-add\-track \fR\fB\fItrack\fR\fR
269 .RS 4
270 Add track to the blocklist\&. If
271 \fItrack\fR
272 is not provided, try to get the currently playing track\&.
273 .RE
274 .PP
275 \fBbl\-delete \fR\fB\fIid\fR\fR
276 .RS 4
277 Remove blocklist entry referenced by its
278 \fIid\fR\&. Use bloclist view command to get the id\&.
279 .RE
280 .SH "FILES"
281 .PP
282 ${XDG_CONFIG_HOME}/mpd_sima/mpd_sima\&.cfg
283 .RS 4
284 Configuration file\&.
285 .RE
286 .PP
287 ${XDG_DATA_HOME}/mpd_sima/sima\&.db
288 .RS 4
289 SQLite DB file\&.
290 .RE
291 .PP
292 ${XDG_DATA_HOME}/mpd_sima/WEB_SERVICE/
293 .RS 4
294 Persistent http cache\&.
295 .RE
296 .PP
297 Usually
298 \fBXDG_DATA_HOME\fR
299 is set to
300 ${HOME}/\&.local/share
301 and
302 \fBXDG_CONFIG_HOME\fR
303 to
304 ${HOME}/\&.config\&.
305 .br
306 You may override them using command line option
307 \fB\-\-var\-dir\fR
308 and
309 \fB\-\-config\fR
310 (cf\&.
311 \fBmpd-sima\fR(1))
312 .SH "ENVIRONMENT"
313 .PP
314 \fBMPD_HOST\fR, \fBMPD_PORT\fR
315 .RS 4
316 mpd\-sima will look for
317 \fBMPD_HOST\fR
318 and
319 \fBMPD_PORT\fR
320 to override built\-in configuration (set to "localhost:6600")\&.
321 .sp
322 mpd\-sima expects
323 \fBMPD_HOST\fR
324 syntax as documented in mpc manual, cf\&.
325 \fBmpc\fR(1)\&.
326
327 .br
328 To use a password, provide a value of the form "password@host"\&.
329 .RE
330 .PP
331 \fBHTTP_PROXY\fR, \fBHTTPS_PROXY\fR
332 .RS 4
333 mpd\-sima honors
334 \fBHTTP_PROXY\fR
335 environment variables\&.
336 .RE
337 .SH "CONFIGURATION"
338 .PP
339 mpd_sima\&.cfg
340 .RS 4
341 mpd_sima\&.cfg
342 is read if present\&. Otherwise built\-in defaults are used\&. An example should be provided in the tarball within
343 doc/examples/\&. On Debian system please look in
344 /usr/share/doc/mpd_sima\&.
345 .RE
346 .PP
347 DEFAULTS
348 .RS 4
349 Default is to look for MPD server at localhost:6600 (or MPD_HOST/MPD_PORT env\&. var\&. if set)\&. The default plugins will use Last\&.fm to find similar tracks to queue and fallback to random if nothing if found\&.
350 .sp
351 The get the defaults as detected by mpd\-sima on your system you can run mpd\-sima to print the config:
352 .sp
353 \fBmpd_sima generate\-config\fR
354 .RE
355 .PP
356 For details about mpd_sima\&.cfg refer to the manual
357 \fBmpd_sima.cfg\fR(5)
358 .SH "FEEDBACK/BUGS"
359 .PP
360 The maintainer would be more than happy to ear from you, don\*(Aqt hesitate to send feedback,
361 \m[blue]\fB\%https://kaliko.me/contact/\fR\m[]\&.
362 .PP
363 XMPP
364 users are welcome to join the dedicated chat room at
365 \m[blue]\fBkaliko\&.me@conf\&.azylum\&.org\fR\m[]\&.
366 .SH "SEE ALSO"
367 .PP
368 \fBmpc\fR(1),
369 \fBmpd\fR(1)
370 .PP
371 /usr/share/doc/mpd\-sima/
372 .SH "AUTHOR"
373 .PP
374 \fBkaliko\fR <\&kaliko@azylum\&.org\&>
375 .RS 4
376 Wrote this man page and is currently leading MPD_sima project\&.
377 .RE
378 .SH "COPYRIGHT"
379 .br
380 Copyright \(co 2009-2021 kaliko
381 .br
382 .PP
383 This manual page was written for the Debian system (and may be used by others)\&.
384 .PP
385 Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 3 published by the Free Software Foundation\&.
386 .PP
387 On Debian systems, the complete text of the GNU General Public License can be found in
388 /usr/share/common\-licenses/GPL\&.
389 .sp