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: 04/23/2021
   6 .\"    Manual: mpd-sima 0.17.0 User Manual
   7 .\"    Source: mpd-sima
   8 .\"  Language: English
   9 .\"
  10 .TH "MPD\-SIMA" "1" "04/23/2021" "mpd-sima" "mpd-sima 0.17.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 .SH "DESCRIPTION"
  46 .PP
  47 This manual page documents briefly the
  48 \fBmpd\-sima\fR
  49 commands\&.
  50 .PP
  51 At start up default configuration is first overridden by user configuration in mpd_sima\&.cfg (see
  52 the section called \(lqFILES\(rq) and finally command lines options are honored\&. For instance you can override default MPD_HOST set in defaults (localhost) or in your configuration file with
  53 \fB\-S\ \&my_mpd_server\fR
  54 option\&. For default configuration see
  55 the section called \(lqCONFIGURATION\(rq\&. See also environment variables special case for MPD host and port in
  56 the section called \(lqENVIRONMENT\(rq\&.
  57 .SH "EXAMPLE"
  58 .SS "Launch as a system service (d\(aemon)\&."
  59 .PP
  60 Here follows an example on how to launch mpd\-sima as a service on your system, not attach to regular user configuration/database\&.
  61 .PP
  62 \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
  63 .SS "Launch in user land"
  64 .PP
  65 Launching mpd\-sima from/whithin your user account is easy, you can simply call
  66 \fBmpd\-sima\fR
  67 from your shell or one of the following command:
  68 .PP
  69 Background execution (d\(aemonise), log in the specified file, save pid:
  70 .PP
  71 \fBmpd\-sima \-\-daemon \-\-pid=$HOME/var/run/mpd\-sima\&.pid \-\-log=$HOME/var/log/mpd\-sima\&.log\fR
  72 .PP
  73 Foreground execution, connect
  74 \fImy\&.mpd\&.server\&.org\fR, log to std(out|err):
  75 .PP
  76 \fBmpd\-sima \-\-host=my\&.mpd\&.server\&.org\fR
  77 .SH "OPTIONS"
  78 .PP
  79 The program follows the usual GNU command line syntax, with long options starting with two dashes (`\-\*(Aq)\&. A summary of options is included below\&.
  80 .PP
  81 \fB\-h\fR, \fB\-\-help\fR
  82 .RS 4
  83 Print help and exit\&.
  84 .RE
  85 .PP
  86 \fB\-\-version\fR
  87 .RS 4
  88 Print version and exit\&.
  89 .RE
  90 .PP
  91 \fB\-\-daemon\fR
  92 .RS 4
  93 Start as a daemon\&. Log redirected to /dev/null, usually setting
  94 \fB\-\-log\fR
  95 and
  96 \fB\-\-pid\fR
  97 options in daemon mode are a good idea to monitor/stop the process\&.
  98 .RE
  99 .PP
 100 \fB\-p \fR\fB\fIpid_file\fR\fR, \fB\-\-pid=\fR\fB\fIpid_file\fR\fR
 101 .RS 4
 102 Use the specific file
 103 \fIpid_file\fR
 104 to store pid to\&.
 105 .br
 106 Default is not to store pid info\&.
 107 .RE
 108 .PP
 109 \fB\-l \fR\fB\fIlog_file\fR\fR, \fB\-\-log=\fR\fB\fIlog_file\fR\fR
 110 .RS 4
 111 Use the specific file
 112 \fIlog_file\fR
 113 to log messages to\&.
 114 .br
 115 Default is to log to stdout/stderr\&.
 116 .RE
 117 .PP
 118 \fB\-v \fR\fB\fIlog_level\fR\fR, \fB\-\-log\-level=\fR\fB\fIlog_level\fR\fR
 119 .RS 4
 120 Verbosity in [debug,info,warning,error]\&.
 121 .br
 122 Default is to log info messages\&.
 123 .RE
 124 .PP
 125 \fB\-c \fR\fB\fIconf_file\fR\fR, \fB\-\-config=\fR\fB\fIconf_file\fR\fR
 126 .RS 4
 127 Use the specific file
 128 \fIconf_file\fR
 129 to set up configuration instead of looking for the default user configuration file\&.
 130 .br
 131 Default is to look for
 132 \fB$XDG_CONFIG_HOME/mpd_sima/mpd_sima\&.cfg\fR\&.
 133 .br
 134
 135 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\&.
 136 .br
 137
 138 For more details on configuration file cf\&.
 139 \fBmpd_sima.cfg\fR(5), see also
 140 the section called \(lqFILES\(rq\&.
 141 .br
 142
 143 .RE
 144 .PP
 145 \fB\-\-var\-dir=\fR\fB\fIvar_directory\fR\fR
 146 .RS 4
 147 Use the specific path
 148 \fIvar_directory\fR
 149 to look for (or create) var files (ie\&. database) instead of looking at the default user data location\&.
 150 .br
 151 Default is to look in
 152 \fB$XDG_DATA_HOME/mpd_sima/\fR\&. Concerning
 153 \fB$XDG_DATA_HOME\fR
 154 see also
 155 the section called \(lqFILES\(rq\&.
 156 .RE
 157 .PP
 158 \fB\-S \fR\fB\fImpd_host\fR\fR, \fB\-\-host=\fR\fB\fImpd_host\fR\fR
 159 .RS 4
 160 Use the specific host
 161 \fImpd_host\fR
 162 as MPD server\&.
 163 .br
 164 \fImpd_host\fR
 165 can be an
 166 IP
 167 or a fully qualified domain name as long as your system can resolve it\&. This overrides
 168 \fBMPD_HOST\fR
 169 environment variable\&.
 170 .br
 171 Default is
 172 \fIlocalhost\fR\&.
 173 .sp
 174 See also
 175 the section called \(lqENVIRONMENT\(rq\&.
 176 .RE
 177 .PP
 178 \fB\-P \fR\fB\fImpd_port\fR\fR, \fB\-\-port=\fR\fB\fImpd_port\fR\fR
 179 .RS 4
 180 Use the specific port number
 181 \fImpd_port\fR
 182 on MPD server\&. This overrides
 183 \fBMPD_PORT\fR
 184 environment variable\&.
 185 .br
 186 Default is
 187 \fI6600\fR\&.
 188 .sp
 189 See also
 190 the section called \(lqENVIRONMENT\(rq
 191 .RE
 192 .PP
 193 \fBconfig\-test\fR
 194 .RS 4
 195 Test configuration file and exit\&. Uses the configuration file specified with
 196 \fB\-\-config\fR
 197 or default location\&.
 198 .br
 199 Default is to use
 200 \fB$XDG_CONFIG_HOME/mpd_sima/mpd_sima\&.cfg\fR
 201 (see
 202 the section called \(lqFILES\(rq
 203 for more)\&.
 204 .sp
 205 config\-test tests MPD connection and Tags plugin configuration\&.
 206 .RE
 207 .PP
 208 \fBcreate\-db\fR
 209 .RS 4
 210 Create the database and exit\&. Uses folder specified with
 211 \fB\-\-var\-dir\fR
 212 or default directory\&.
 213 .br
 214 Default is to use
 215 \fB$XDG_DATA_HOME/mpd_sima/\fR
 216 (see
 217 the section called \(lqFILES\(rq
 218 for more)\&.
 219 .RE
 220 .PP
 221 \fBgenerate\-config\fR
 222 .RS 4
 223 Generate a sample configuration file according to the current CLI options and env\&. var\&.\&. The configuration is written on stdout\&.
 224 .RE
 225 .PP
 226 \fBpurge\-history\fR
 227 .RS 4
 228 Purge play history in the database and exit\&. Uses folder specified with
 229 \fB\-\-var\-dir\fR
 230 or default directory\&.
 231 .br
 232 Default is to use
 233 \fB$XDG_DATA_HOME/mpd_sima/\fR
 234 (see
 235 the section called \(lqFILES\(rq
 236 for more)\&.
 237 .RE
 238 .SH "FILES"
 239 .PP
 240 ${XDG_CONFIG_HOME}/mpd_sima/mpd_sima\&.cfg
 241 .RS 4
 242 Configuration file\&.
 243 .RE
 244 .PP
 245 ${XDG_DATA_HOME}/mpd_sima/sima\&.db
 246 .RS 4
 247 SQLite DB file\&.
 248 .RE
 249 .PP
 250 ${XDG_DATA_HOME}/mpd_sima/WEB_SERVICE/
 251 .RS 4
 252 Persistent http cache\&.
 253 .RE
 254 .PP
 255 Usually
 256 \fBXDG_DATA_HOME\fR
 257 is set to
 258 ${HOME}/\&.local/share
 259 and
 260 \fBXDG_CONFIG_HOME\fR
 261 to
 262 ${HOME}/\&.config\&.
 263 .br
 264 You may override them using command line option
 265 \fB\-\-var\-dir\fR
 266 and
 267 \fB\-\-config\fR
 268 (cf\&.
 269 \fBmpd-sima\fR(1))
 270 .SH "ENVIRONMENT"
 271 .PP
 272 \fBMPD_HOST\fR, \fBMPD_PORT\fR
 273 .RS 4
 274 mpd\-sima will look for
 275 \fBMPD_HOST\fR
 276 and
 277 \fBMPD_PORT\fR
 278 to override built\-in configuration (set to "localhost:6600")\&.
 279 .sp
 280 mpd\-sima expects
 281 \fBMPD_HOST\fR
 282 syntax as documented in mpc manual, cf\&.
 283 \fBmpc\fR(1)\&.
 284
 285 .br
 286 To use a password, provide a value of the form "password@host"\&.
 287 .RE
 288 .PP
 289 \fBHTTP_PROXY\fR, \fBHTTPS_PROXY\fR
 290 .RS 4
 291 mpd\-sima honors
 292 \fBHTTP_PROXY\fR
 293 environment variables\&.
 294 .RE
 295 .SH "CONFIGURATION"
 296 .PP
 297 mpd_sima\&.cfg
 298 .RS 4
 299 mpd_sima\&.cfg
 300 is read if present\&. Otherwise built\-in defaults are used\&. An example should be provided in the tarball within
 301 doc/examples/\&. On Debian system please look in
 302 /usr/share/doc/mpd\-sima\&.
 303 .RE
 304 .PP
 305 DEFAULTS
 306 .RS 4
 307 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\&.
 308 .sp
 309 The get the defaults as detected by mpd\-sima on your system you can run mpd\-sima to print the config:
 310 .sp
 311 \fBmpd\-sima generate\-config\fR
 312 .RE
 313 .PP
 314 For details about mpd_sima\&.cfg refer to the manual
 315 \fBmpd_sima.cfg\fR(5)
 316 .SH "FEEDBACK/BUGS"
 317 .PP
 318 The maintainer would be more than happy to ear from you, don\*(Aqt hesitate to send feedback,
 319 \m[blue]\fB\%https://kaliko.me/contact/\fR\m[]\&.
 320 .PP
 321 XMPP
 322 users are welcome to join the dedicated chat room at
 323 \m[blue]\fBkaliko\&.me@conf\&.azylum\&.org\fR\m[]\&.
 324 .SH "SEE ALSO"
 325 .PP
 326 \fBmpc\fR(1),
 327 \fBmpd\fR(1)
 328 .PP
 329 /usr/share/doc/mpd\-sima/
 330 .SH "AUTHOR"
 331 .PP
 332 \fBkaliko\fR <\&kaliko@azylum\&.org\&>
 333 .RS 4
 334 Wrote this man page and is currently leading MPD_sima project\&.
 335 .RE
 336 .SH "COPYRIGHT"
 337 .br
 338 Copyright \(co 2009-2021 kaliko
 339 .br
 340 .PP
 341 This manual page was written for the Debian system (and may be used by others)\&.
 342 .PP
 343 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\&.
 344 .PP
 345 On Debian systems, the complete text of the GNU General Public License can be found in
 346 /usr/share/common\-licenses/GPL\&.
 347 .sp