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