smoketest:
stage: test
script:
- - pip install requests python-musicpd
+ - pip install requests python-musicpd sphinx
- python setup.py test
# build wheel and source
- python setup.py bdist_wheel sdist
+ # manual and HTML documentation
+ - python setup.py build_sphinx
# install
- pip install dist/*.whl
# smoke test
+++ /dev/null
-# Packages needed on debian:
-# * xsltproc
-# * docbook-xsl-ns (which depends on docbook-xsl-doc-html and docbook5-xml)
-# * libxml2-utils
-#
-
-XSL=/usr/share/xml/docbook/stylesheet/docbook-xsl-ns/manpages/docbook.xsl
-HXSL=/usr/share/xml/docbook/stylesheet/docbook-xsl-ns/html/docbook.xsl
-CONV5XSL="/usr/share/xml/docbook/stylesheet/docbook5/db4-upgrade.xsl"
-XP=/usr/bin/xsltproc
-OPTIONS=--nonet\
- --param make.year.ranges 1\
- --param make.single.year.ranges 1 \
- --param man.charmap.use.subset 0 \
- --novalid \
-
-all: man
-
-mpd_sima: mpd_sima.1.xml
- xmllint --xinclude --nowarning --noent $< | $(XP) $(OPTIONS) $(XSL) -
-
-mpd_sima.cfg: mpd_sima.cfg.5.xml
- xmllint --xinclude --nowarning --noent $< | $(XP) $(OPTIONS) $(XSL) -
-
-mpd_sima_html:
- xmllint --xinclude --nowarning --noent mpd_sima.1.xml | $(XP) $(HXSL) - > ./mpd_sima.1.html
-
-mpd_sima.cfg_html:
- xmllint --xinclude --nowarning --noent mpd_sima.cfg.5.xml | $(XP) $(HXSL) - > ./mpd_sima.cfg.5.html
-
-man: mpd_sima mpd_sima.cfg
-
-html: simadb_cli_html mpd_sima_html mpd_sima.cfg_html
-
-pdf: mpd-sima.1 mpd-sima.cfg.5
- /usr/bin/man -l -Tps mpd-sima.1 | /usr/bin/ps2pdf - ./mpd_sima.pdf
- /usr/bin/man -l -Tps mpd-sima.cfg.5 | /usr/bin/ps2pdf - ./mpd_sima.cfg.pdf
-
-valid:
- xmllint --noout --valid ./*.xml
-
-clean_mpd_sima:
- rm -rf mpd-sima.1 mpd_sima.1.html
-
-clean_mpd_sima.cfg:
- rm -rf mpd_sima.cfg.5 mpd_sima.cfg.5.html
-
-clean: clean_mpd_sima clean_simadb_cli clean_mpd_sima.cfg
- rm -rf ./*.pdf
+++ /dev/null
-[MPD]
-host=example.org
-port=8000
-
-[sima]
-history_duration=48 # 2 days
-queue_length=5
-
-[lastfm]
-queue_mode=album
-album_to_add=2
-
-[crop]
-# keep 30 played tracks in playlist
-consume=30
+++ /dev/null
-<?xml version='1.0' encoding='UTF-8'?>
- <refsect1 id="feedback">
- <title>FEEDBACK/BUGS</title>
- <para>The maintainer would be more than happy to ear from you, don't hesitate to send feedback, <ulink url="https://kaliko.me/contact/"/>.</para>
- <para><acronym>XMPP</acronym> users are welcome to join the dedicated chat room at <ulink type="xmpp" url="kaliko.me@conf.azylum.org">kaliko.me@conf.azylum.org</ulink>.</para>
- </refsect1>
- <!-- vim:filetype=docbk
- -->
+++ /dev/null
-<?xml version='1.0' encoding='UTF-8'?>
- <refsect1 id="files">
- <title>FILES</title>
- <variablelist>
- <varlistentry>
- <term><filename>${XDG_CONFIG_HOME}/mpd_sima/mpd_sima.cfg</filename></term>
- <listitem>
- <para>Configuration file.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>${XDG_DATA_HOME}/mpd_sima/sima.db</filename></term>
- <listitem>
- <para>SQLite DB file.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>${XDG_DATA_HOME}/mpd_sima/WEB_SERVICE/</filename></term>
- <listitem>
- <para>Persistent http cache.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>Usually <envar>XDG_DATA_HOME</envar> is set to
- <filename>${HOME}/.local/share</filename> and <envar>XDG_CONFIG_HOME</envar> to
- <filename>${HOME}/.config</filename>.<sbr />You may override them using
- command line option <option>--var-dir</option> and <option>--config</option> (cf.
- <citerefentry><refentrytitle>mpd-sima</refentrytitle>
- <manvolnum>1</manvolnum></citerefentry>)</para>
- </refsect1>
-<!-- vim:filetype=docbk
--->
+++ /dev/null
-<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE info [
- <!ENTITY dhfirstname "Jack">
- <!ENTITY dhsurname "kaliko">
- <!ENTITY dhemail "kaliko@azylum.org">
- <!ENTITY dhusername "&dhsurname;">
- <!ENTITY dhpackage "mpd-sima">
- <!ENTITY release "0.18.1.dev0">
- <!-- TITLE should be something like "User commands" or similar (see
- http://www.tldp.org/HOWTO/Man-Page/q2.html). -->
- <!ENTITY dhtitle "&dhpackage; &release; User Manual">
- ]>
- <info>
- <title>&dhtitle;</title>
- <productname>&dhpackage;</productname>
- <authorgroup>
- <author>
- <surname>&dhsurname;</surname>
- <contrib>Wrote this man page and is currently leading MPD_sima project.</contrib>
- <address>
- <email>&dhemail;</email>
- </address>
- </author>
- </authorgroup>
- <copyright>
- <year>2009</year>
- <year>2010</year>
- <year>2011</year>
- <year>2012</year>
- <year>2013</year>
- <year>2014</year>
- <year>2015</year>
- <year>2016</year>
- <year>2017</year>
- <year>2018</year>
- <year>2019</year>
- <year>2020</year>
- <year>2021</year>
- <holder>&dhusername;</holder>
- </copyright>
- <legalnotice>
- <para>This manual page was written for the Debian system
- (and may be used by others).</para>
- <para>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.</para>
- <para>On Debian systems, the complete text of the GNU General Public
- License can be found in
- <filename>/usr/share/common-licenses/GPL</filename>.</para>
- </legalnotice>
- </info>
+++ /dev/null
-'\" t
-.\" Title: mpd-sima
-.\" Author: kaliko <kaliko@azylum.org>
-.\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
-.\" Date: 11/16/2021
-.\" Manual: mpd-sima 0.18.0 User Manual
-.\" Source: mpd-sima
-.\" Language: English
-.\"
-.TH "MPD\-SIMA" "1" "11/16/2021" "mpd-sima" "mpd-sima 0.18.0 User Manual"
-.\" -----------------------------------------------------------------
-.\" * Define some portability stuff
-.\" -----------------------------------------------------------------
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" http://bugs.debian.org/507673
-.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.ie \n(.g .ds Aq \(aq
-.el .ds Aq '
-.\" -----------------------------------------------------------------
-.\" * set default formatting
-.\" -----------------------------------------------------------------
-.\" disable hyphenation
-.nh
-.\" disable justification (adjust text to left margin only)
-.ad l
-.\" -----------------------------------------------------------------
-.\" * MAIN CONTENT STARTS HERE *
-.\" -----------------------------------------------------------------
-.SH "NAME"
-mpd-sima \- mpd\-sima will try to maintain some titles ahead in the queue following different policies\&.
-.SH "SYNOPSIS"
-.HP \w'\fBmpd\-sima\fR\ 'u
-\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]
-.HP \w'\fBmpd\-sima\fR\ 'u
-\fBmpd\-sima\fR {{\fB\-h\fR\ |\ \fB\-\-help\fR}\ \fB\-\-version\fR}
-.HP \w'\fBmpd\-sima\fR\ 'u
-\fBmpd\-sima\fR config\-test [\fB\-\-config=\fR\fIconf_file\fR]
-.HP \w'\fBmpd\-sima\fR\ 'u
-\fBmpd\-sima\fR create\-db [\fB\-\-var\-dir=\fR\fIvar_directory\fR]
-.HP \w'\fBmpd\-sima\fR\ 'u
-\fBmpd\-sima\fR generate\-config [\fB\&...\fR]
-.HP \w'\fBmpd\-sima\fR\ 'u
-\fBmpd\-sima\fR purge\-history [\fB\-\-var\-dir=\fR\fIvar_directory\fR]
-.HP \w'\fBmpd\-sima\fR\ 'u
-\fBmpd\-sima\fR bl\-view
-.HP \w'\fBmpd\-sima\fR\ 'u
-\fBmpd\-sima\fR bl\-add\-artist [\fBartist\fR]
-.HP \w'\fBmpd\-sima\fR\ 'u
-\fBmpd\-sima\fR bl\-add\-album [\fBalbum\fR]
-.HP \w'\fBmpd\-sima\fR\ 'u
-\fBmpd\-sima\fR bl\-add\-track [\fBtrack\fR]
-.HP \w'\fBmpd\-sima\fR\ 'u
-\fBmpd\-sima\fR bl\-delete \fBid\fR
-.SH "DESCRIPTION"
-.PP
-This manual page documents briefly the
-\fBmpd\-sima\fR
-commands\&.
-.PP
-At start up default configuration is first overridden by user configuration in mpd_sima\&.cfg (see
-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
-\fB\-S\ \&my_mpd_server\fR
-option\&. For default configuration see
-the section called \(lqCONFIGURATION\(rq\&. See also environment variables special case for MPD host and port in
-the section called \(lqENVIRONMENT\(rq\&.
-.SH "EXAMPLE"
-.SS "Launch as a system service (d\(aemon)\&."
-.PP
-Here follows an example on how to launch mpd\-sima as a service on your system, not attach to regular user configuration/database\&.
-.PP
-\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
-.SS "Launch in user land"
-.PP
-Launching mpd\-sima from/whithin your user account is easy, you can simply call
-\fBmpd\-sima\fR
-from your shell or one of the following command:
-.PP
-Background execution (d\(aemonise), log in the specified file, save pid:
-.PP
-\fBmpd\-sima \-\-daemon \-\-pid=$HOME/var/run/mpd\-sima\&.pid \-\-log=$HOME/var/log/mpd\-sima\&.log\fR
-.PP
-Foreground execution, connect
-\fImy\&.mpd\&.server\&.org\fR, log to std(out|err):
-.PP
-\fBmpd\-sima \-\-host=my\&.mpd\&.server\&.org\fR
-.SH "OPTIONS"
-.PP
-The program follows the usual GNU command line syntax, with long options starting with two dashes (`\-\*(Aq)\&. A summary of options is included below\&.
-.PP
-\fB\-h\fR, \fB\-\-help\fR
-.RS 4
-Print help and exit\&.
-.RE
-.PP
-\fB\-\-version\fR
-.RS 4
-Print version and exit\&.
-.RE
-.PP
-\fB\-\-daemon\fR
-.RS 4
-Start as a daemon\&. Log redirected to /dev/null, usually setting
-\fB\-\-log\fR
-and
-\fB\-\-pid\fR
-options in daemon mode are a good idea to monitor/stop the process\&.
-.RE
-.PP
-\fB\-p \fR\fB\fIpid_file\fR\fR, \fB\-\-pid=\fR\fB\fIpid_file\fR\fR
-.RS 4
-Use the specific file
-\fIpid_file\fR
-to store pid to\&.
-.br
-Default is not to store pid info\&.
-.RE
-.PP
-\fB\-l \fR\fB\fIlog_file\fR\fR, \fB\-\-log=\fR\fB\fIlog_file\fR\fR
-.RS 4
-Use the specific file
-\fIlog_file\fR
-to log messages to\&.
-.br
-Default is to log to stdout/stderr\&.
-.RE
-.PP
-\fB\-v \fR\fB\fIlog_level\fR\fR, \fB\-\-log\-level=\fR\fB\fIlog_level\fR\fR
-.RS 4
-Verbosity in [debug,info,warning,error]\&.
-.br
-Default is to log info messages\&.
-.RE
-.PP
-\fB\-c \fR\fB\fIconf_file\fR\fR, \fB\-\-config=\fR\fB\fIconf_file\fR\fR
-.RS 4
-Use the specific file
-\fIconf_file\fR
-to set up configuration instead of looking for the default user configuration file\&.
-.br
-Default is to look for
-\fB$XDG_CONFIG_HOME/mpd_sima/mpd_sima\&.cfg\fR\&.
-.br
-
-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\&.
-.br
-
-For more details on configuration file cf\&.
-\fBmpd_sima.cfg\fR(5), see also
-the section called \(lqFILES\(rq\&.
-.br
-
-.RE
-.PP
-\fB\-\-var\-dir=\fR\fB\fIvar_directory\fR\fR
-.RS 4
-Use the specific path
-\fIvar_directory\fR
-to look for (or create) var files (ie\&. database) instead of looking at the default user data location\&.
-.br
-Default is to look in
-\fB$XDG_DATA_HOME/mpd_sima/\fR\&. Concerning
-\fB$XDG_DATA_HOME\fR
-see also
-the section called \(lqFILES\(rq\&.
-.RE
-.PP
-\fB\-S \fR\fB\fImpd_host\fR\fR, \fB\-\-host=\fR\fB\fImpd_host\fR\fR
-.RS 4
-Use the specific host
-\fImpd_host\fR
-as MPD server\&.
-.br
-\fImpd_host\fR
-can be an
-IP
-or a fully qualified domain name as long as your system can resolve it\&. This overrides
-\fBMPD_HOST\fR
-environment variable\&.
-.br
-Default is
-\fIlocalhost\fR\&.
-.sp
-See also
-the section called \(lqENVIRONMENT\(rq\&.
-.RE
-.PP
-\fB\-P \fR\fB\fImpd_port\fR\fR, \fB\-\-port=\fR\fB\fImpd_port\fR\fR
-.RS 4
-Use the specific port number
-\fImpd_port\fR
-on MPD server\&. This overrides
-\fBMPD_PORT\fR
-environment variable\&.
-.br
-Default is
-\fI6600\fR\&.
-.sp
-See also
-the section called \(lqENVIRONMENT\(rq
-.RE
-.PP
-\fBconfig\-test\fR
-.RS 4
-Test configuration file and exit\&. Uses the configuration file specified with
-\fB\-\-config\fR
-or default location\&.
-.br
-Default is to use
-\fB$XDG_CONFIG_HOME/mpd_sima/mpd_sima\&.cfg\fR
-(see
-the section called \(lqFILES\(rq
-for more)\&.
-.sp
-config\-test tests MPD connection and Tags plugin configuration\&.
-.RE
-.PP
-\fBcreate\-db\fR
-.RS 4
-Create the database and exit\&. Uses folder specified with
-\fB\-\-var\-dir\fR
-or default directory\&.
-.br
-Default is to use
-\fB$XDG_DATA_HOME/mpd_sima/\fR
-(see
-the section called \(lqFILES\(rq
-for more)\&.
-.RE
-.PP
-\fBgenerate\-config\fR
-.RS 4
-Generate a sample configuration file according to the current CLI options and env\&. var\&.\&. The configuration is written on stdout\&.
-.RE
-.PP
-\fBpurge\-history\fR
-.RS 4
-Purge play history in the database and exit\&. Uses folder specified with
-\fB\-\-var\-dir\fR
-or default directory\&.
-.br
-Default is to use
-\fB$XDG_DATA_HOME/mpd_sima/\fR
-(see
-the section called \(lqFILES\(rq
-for more)\&.
-.RE
-.PP
-\fBbl\-view\fR
-.RS 4
-View blocklist, useful to get entry IDs to remove with delete command\&.
-.RE
-.PP
-\fBbl\-add\-artist \fR\fB\fIartist\fR\fR
-.RS 4
-Add artist to the blocklist\&. If
-\fIartist\fR
-is not provided, try to get the currently playing artist\&.
-.RE
-.PP
-\fBbl\-add\-album \fR\fB\fIalbum\fR\fR
-.RS 4
-Add album to the blocklist\&. If
-\fIalbum\fR
-is not provided, try to get the currently playing album\&.
-.RE
-.PP
-\fBbl\-add\-track \fR\fB\fItrack\fR\fR
-.RS 4
-Add track to the blocklist\&. If
-\fItrack\fR
-is not provided, try to get the currently playing track\&.
-.RE
-.PP
-\fBbl\-delete \fR\fB\fIid\fR\fR
-.RS 4
-Remove blocklist entry referenced by its
-\fIid\fR\&. Use bloclist view command to get the id\&.
-.RE
-.SH "FILES"
-.PP
-${XDG_CONFIG_HOME}/mpd_sima/mpd_sima\&.cfg
-.RS 4
-Configuration file\&.
-.RE
-.PP
-${XDG_DATA_HOME}/mpd_sima/sima\&.db
-.RS 4
-SQLite DB file\&.
-.RE
-.PP
-${XDG_DATA_HOME}/mpd_sima/WEB_SERVICE/
-.RS 4
-Persistent http cache\&.
-.RE
-.PP
-Usually
-\fBXDG_DATA_HOME\fR
-is set to
-${HOME}/\&.local/share
-and
-\fBXDG_CONFIG_HOME\fR
-to
-${HOME}/\&.config\&.
-.br
-You may override them using command line option
-\fB\-\-var\-dir\fR
-and
-\fB\-\-config\fR
-(cf\&.
-\fBmpd-sima\fR(1))
-.SH "ENVIRONMENT"
-.PP
-\fBMPD_HOST\fR, \fBMPD_PORT\fR
-.RS 4
-mpd\-sima will look for
-\fBMPD_HOST\fR
-and
-\fBMPD_PORT\fR
-to override built\-in configuration (set to "localhost:6600")\&.
-.sp
-mpd\-sima expects
-\fBMPD_HOST\fR
-syntax as documented in mpc manual, cf\&.
-\fBmpc\fR(1)\&.
-
-.br
-To use a password, provide a value of the form "password@host"\&.
-.RE
-.PP
-\fBHTTP_PROXY\fR, \fBHTTPS_PROXY\fR
-.RS 4
-mpd\-sima honors
-\fBHTTP_PROXY\fR
-environment variables\&.
-.RE
-.SH "CONFIGURATION"
-.PP
-mpd_sima\&.cfg
-.RS 4
-mpd_sima\&.cfg
-is read if present\&. Otherwise built\-in defaults are used\&. An example should be provided in the tarball within
-doc/examples/\&. On Debian system please look in
-/usr/share/doc/mpd_sima\&.
-.RE
-.PP
-DEFAULTS
-.RS 4
-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\&.
-.sp
-The get the defaults as detected by mpd\-sima on your system you can run mpd\-sima to print the config:
-.sp
-\fBmpd_sima generate\-config\fR
-.RE
-.PP
-For details about mpd_sima\&.cfg refer to the manual
-\fBmpd_sima.cfg\fR(5)
-.SH "FEEDBACK/BUGS"
-.PP
-The maintainer would be more than happy to ear from you, don\*(Aqt hesitate to send feedback,
-\m[blue]\fB\%https://kaliko.me/contact/\fR\m[]\&.
-.PP
-XMPP
-users are welcome to join the dedicated chat room at
-\m[blue]\fBkaliko\&.me@conf\&.azylum\&.org\fR\m[]\&.
-.SH "SEE ALSO"
-.PP
-\fBmpc\fR(1),
-\fBmpd\fR(1)
-.PP
-/usr/share/doc/mpd\-sima/
-.SH "AUTHOR"
-.PP
-\fBkaliko\fR <\&kaliko@azylum\&.org\&>
-.RS 4
-Wrote this man page and is currently leading MPD_sima project\&.
-.RE
-.SH "COPYRIGHT"
-.br
-Copyright \(co 2009-2021 kaliko
-.br
-.PP
-This manual page was written for the Debian system (and may be used by others)\&.
-.PP
-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\&.
-.PP
-On Debian systems, the complete text of the GNU General Public License can be found in
-/usr/share/common\-licenses/GPL\&.
-.sp
+++ /dev/null
-<?xml version='1.0' encoding='UTF-8'?>
-<!--
-
-`xsltproc -''-nonet \
- -''-param man.charmap.use.subset "0" \
- -''-param make.year.ranges "1" \
- -''-param make.single.year.ranges "1" \
- /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl \
- manpage.xml'
-
-A manual page <package>.<section> will be generated. You may view the
-manual page with: nroff -man <package>.<section> | less'. A typical entry
-in a Makefile or Makefile.am is:
-
-DB2MAN = /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/manpages/docbook.xsl
-XP = xsltproc -''-nonet -''-param man.charmap.use.subset "0"
-
-manpage.1: manpage.xml
- $(XP) $(DB2MAN) $<
-
-The xsltproc binary is found in the xsltproc package. The XSL files are in
-docbook-xsl. A description of the parameters you can use can be found in the
-docbook-xsl-doc-* packages. Please remember that if you create the nroff
-version in one of the debian/rules file targets (such as build), you will need
-to include xsltproc and docbook-xsl in your Build-Depends control field.
-Alternatively use the xmlto command/package. That will also automatically
-pull in xsltproc and docbook-xsl.
-
-Notes for using docbook2x: docbook2x-man does not automatically create the
-AUTHOR(S) and COPYRIGHT sections. In this case, please add them manually as
-<refsect1> ... </refsect1>.
-
-To disable the automatic creation of the AUTHOR(S) and COPYRIGHT sections
-read /usr/share/doc/docbook-xsl/doc/manpages/authors.html. This file can be
-found in the docbook-xsl-doc-html package.
-
-Validation can be done using: `xmllint -''-noout -''-valid manpage.xml`
-
-General documentation about man-pages and man-page-formatting:
-man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
-
--->
-<!DOCTYPE refentry [
-
- <!ENTITY dhsection "1">
- <!ENTITY dhpackage "mpd_sima">
- <!ENTITY dhutils "mpd-sima">
-
-]>
-
-<refentry xmlns="http://docbook.org/ns/docbook"
- xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
- <xi:include href="info.xml" />
- <refmeta>
- <refentrytitle>&dhutils;</refentrytitle>
- <manvolnum>&dhsection;</manvolnum>
- </refmeta>
- <refnamediv>
- <refname>&dhutils;</refname>
- <refpurpose>&dhutils; will try to maintain some titles ahead in the queue following different policies.</refpurpose>
- </refnamediv>
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>&dhutils;</command>
- <arg choice="opt"><option>--daemon</option></arg>
- <arg choice="opt"><option>--config=</option><replaceable class="option">conf_file</replaceable></arg>
- <arg choice="opt"><option>--var-dir=</option><replaceable class="option">var_directory</replaceable></arg>
- <arg choice="opt"><option>--pid=</option><replaceable class="option">pid_file</replaceable></arg>
- <arg choice="opt"><option>--log=</option><replaceable class="option">log_file</replaceable></arg>
- <arg choice="opt"><option>--log-level=</option><replaceable class="option">log_level</replaceable></arg>
- <arg choice="opt"><option>--host=</option><replaceable class="option">mpd_host</replaceable></arg>
- <arg choice="opt"><option>--mpd_port=</option><replaceable class="option">mpd_port</replaceable></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>&dhutils;</command>
- <!-- Normally the help and version options make the programs stop
- right after outputting the requested information. -->
- <group choice="plain">
- <arg choice="req">
- <group choice="req">
- <arg choice="plain"><option>-h</option></arg>
- <arg choice="plain"><option>--help</option></arg>
- </group>
- <arg choice="plain"><option>--version</option></arg>
- </arg>
- </group>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>&dhutils;</command>
- <arg choice="plain">config-test</arg>
- <arg choice="opt"><option>--config=</option><replaceable class="option">conf_file</replaceable></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>&dhutils;</command>
- <arg choice="plain">create-db</arg>
- <arg choice="opt"><option>--var-dir=</option><replaceable class="option">var_directory</replaceable></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>&dhutils;</command>
- <arg choice="plain">generate-config</arg>
- <arg choice="opt"><option>…</option></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>&dhutils;</command>
- <arg choice="plain">purge-history</arg>
- <arg choice="opt"><option>--var-dir=</option><replaceable class="option">var_directory</replaceable></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>&dhutils;</command>
- <arg choice="plain">bl-view</arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>&dhutils;</command>
- <arg choice="plain">bl-add-artist</arg>
- <arg choice="opt"><option>artist</option></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>&dhutils;</command>
- <arg choice="plain">bl-add-album</arg>
- <arg choice="opt"><option>album</option></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>&dhutils;</command>
- <arg choice="plain">bl-add-track</arg>
- <arg choice="opt"><option>track</option></arg>
- </cmdsynopsis>
- <cmdsynopsis>
- <command>&dhutils;</command>
- <arg choice="plain">bl-delete</arg>
- <arg choice="plain"><option>id</option></arg>
- </cmdsynopsis>
- </refsynopsisdiv>
- <refsect1 id="description">
- <title>DESCRIPTION</title>
- <para>This manual page documents briefly the
- <command>&dhutils;</command> commands.</para>
- <para>At start up default configuration is first overridden by user
- configuration in mpd_sima.cfg (see <xref linkend="files"/>) and finally
- command lines options are honored. For instance you can override
- default MPD host (localhost) in your configuration
- file or with <command>-S my_mpd_server</command> option. For default
- configuration see <xref linkend="configuration"/>. See also environment
- variables special case for MPD host and port in <xref linkend="environment"/>.
- </para>
- </refsect1>
- <refsect1 id="example">
- <title>EXAMPLE</title>
- <refsect2 id="daemon">
- <title>Launch as a system service (dæmon).</title>
- <para>Here follows an example on how to launch &dhutils; as a service on your system, not attach to regular user configuration/database.</para>
- <para><command>&dhutils; --daemon --conf=/etc/mpd_sima.cfg --var-dir=/var/cache/mpd-sima/ --pid=/run/mpd-sima.pid --log=/var/log/mpd-sima.log</command></para>
- </refsect2>
- <refsect2 id="user_land">
- <title>Launch in user land</title>
- <para>Launching &dhutils; from/whithin your user account is easy, you can simply call <command>&dhutils;</command> from your shell or one of the following command:</para>
- <para>Background execution (dæmonise), log in the specified file, save pid:</para>
- <para><command>&dhutils; --daemon --pid=$HOME/var/run/mpd-sima.pid --log=$HOME/var/log/mpd-sima.log</command></para>
- <para>Foreground execution, connect <emphasis>my.mpd.server.org</emphasis>, log to std(out|err):</para>
- <para><command>&dhutils; --host=my.mpd.server.org</command></para>
- </refsect2>
- </refsect1>
- <refsect1 id="options">
- <title>OPTIONS</title>
- <para>The program follows the usual GNU command line syntax,
- with long options starting with two dashes (`-'). A summary of
- options is included below.</para>
- <variablelist>
- <!-- Use the variablelist.term.separator and the
- variablelist.term.break.after parameters to
- control the term elements. -->
- <varlistentry> <!-- help -->
- <term><option>-h</option></term>
- <term><option>--help</option></term>
- <listitem>
- <para>Print help and exit.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- version -->
- <term><option>--version</option></term>
- <listitem>
- <para>Print version and exit.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- daemon -->
- <term><option>--daemon</option></term>
- <listitem>
- <para>Start as a daemon. Log redirected to /dev/null, usually setting <option>--log</option> and <option>--pid</option> options in daemon mode are a good idea to monitor/stop the process.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- pid_file -->
- <term><option>-p <replaceable class="parameter">pid_file</replaceable></option></term>
- <term><option>--pid=<replaceable class="parameter">pid_file</replaceable></option></term>
- <listitem>
- <para>Use the specific file <replaceable>pid_file</replaceable> to store pid to.<sbr />Default is not to store pid info.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- log -->
- <term><option>-l <replaceable class="parameter">log_file</replaceable></option></term>
- <term><option>--log=<replaceable class="parameter">log_file</replaceable></option></term>
- <listitem>
- <para>Use the specific file <replaceable>log_file</replaceable> to log messages to.<sbr />Default is to log to stdout/stderr.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- log-level -->
- <term><option>-v <replaceable class="parameter">log_level</replaceable></option></term>
- <term><option>--log-level=<replaceable class="parameter">log_level</replaceable></option></term>
- <listitem>
- <para>Verbosity in [debug,info,warning,error].<sbr />Default is to log info messages.</para>
- </listitem>
- </varlistentry>
- <varlistentry><!-- config -->
- <term><option>-c <replaceable class="parameter">conf_file</replaceable></option></term>
- <term><option>--config=<replaceable class="parameter">conf_file</replaceable></option></term>
- <listitem>
- <para>Use the specific file <replaceable>conf_file</replaceable> to set up
- configuration instead of looking for the default user
- configuration file.<sbr />Default is to look for
- <envar>$XDG_CONFIG_HOME/mpd_sima/mpd_sima.cfg</envar>.<sbr />
- CLI option overrides any equivalent mentioned in configuration file, ie. launching &dhutils; with '<option>--port</option>' CLI option will ignore port setting in configuration file.<sbr />
- For more details on configuration file cf.
- <citerefentry><refentrytitle>mpd_sima.cfg</refentrytitle>
- <manvolnum>5</manvolnum></citerefentry>, see also <xref linkend="files"/>.<sbr />
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- var-dir -->
- <term><option>--var-dir=<replaceable class="parameter">var_directory</replaceable></option></term>
- <listitem>
- <para>Use the specific path <replaceable>var_directory</replaceable> to look for (or create) var files (ie. database) instead of looking at the default user data location.<sbr />Default is to look in <envar>$XDG_DATA_HOME/mpd_sima/</envar>. Concerning <envar>$XDG_DATA_HOME</envar> see also <xref linkend="files"/>.</para>
- </listitem>
- </varlistentry>
- <varlistentry><!-- host -->
- <term><option>-S <replaceable class="parameter">mpd_host</replaceable></option></term>
- <term><option>--host=<replaceable class="parameter">mpd_host</replaceable></option></term>
- <listitem>
- <para>Use the specific host <replaceable>mpd_host</replaceable> as MPD server.<sbr /><replaceable>mpd_host</replaceable> can be an <acronym>IP</acronym> or a fully qualified domain name as long as your system can resolve it. This overrides <envar>MPD_HOST</envar> environment variable.<sbr />Default is <emphasis>localhost</emphasis>.</para>
- <para>See also <xref linkend="environment"/>.</para>
- </listitem>
- </varlistentry>
- <varlistentry><!-- port -->
- <term><option>-P <replaceable class="parameter">mpd_port</replaceable></option></term>
- <term><option>--port=<replaceable class="parameter">mpd_port</replaceable></option></term>
- <listitem>
- <para>Use the specific port number <replaceable>mpd_port</replaceable> on MPD server. This overrides <envar>MPD_PORT</envar> environment variable.<sbr />Default is <emphasis>6600</emphasis>.</para>
- <para>See also <xref linkend="environment"/></para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- config-test -->
- <term><option>config-test</option></term>
- <listitem>
- <para>Test configuration file and exit. Uses the configuration file specified with <option>--config</option> or default location.<sbr />Default is to use <envar>$XDG_CONFIG_HOME/mpd_sima/mpd_sima.cfg</envar> (see <xref linkend="files"/> for more).</para>
- <para>config-test tests MPD connection and Tags plugin configuration.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- create-db -->
- <term><option>create-db</option></term>
- <listitem>
- <para>Create the database and exit. Uses folder specified with <option>--var-dir</option> or default directory.<sbr />Default is to use <envar>$XDG_DATA_HOME/mpd_sima/</envar> (see <xref linkend="files"/> for more).</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- generate-config -->
- <term><option>generate-config</option></term>
- <listitem>
- <para>Generate a sample configuration file according to the current CLI options and env. var.. The configuration is written on stdout.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- purge-history -->
- <term><option>purge-history</option></term>
- <listitem>
- <para>Purge play history in the database and exit. Uses folder specified with <option>--var-dir</option> or default directory.<sbr />Default is to use <envar>$XDG_DATA_HOME/mpd_sima/</envar> (see <xref linkend="files"/> for more).</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- bl-view -->
- <term><option>bl-view</option></term>
- <listitem>
- <para>View blocklist, useful to get entry IDs to remove with delete command.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- bl-add-artist -->
- <term><option>bl-add-artist <replaceable class="parameter">artist</replaceable></option></term>
- <listitem>
- <para>Add artist to the blocklist. If
- <replaceable class="parameter">artist</replaceable>
- is not provided, try to get the currently playing artist.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- bl-add-album -->
- <term><option>bl-add-album <replaceable class="parameter">album</replaceable></option></term>
- <listitem>
- <para>Add album to the blocklist. If
- <replaceable class="parameter">album</replaceable>
- is not provided, try to get the currently playing album.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- bl-add-track -->
- <term><option>bl-add-track <replaceable class="parameter">track</replaceable></option></term>
- <listitem>
- <para>Add track to the blocklist. If
- <replaceable class="parameter">track</replaceable>
- is not provided, try to get the currently playing track.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- bl-delete -->
- <term><option>bl-delete <replaceable class="parameter">id</replaceable></option></term>
- <listitem>
- <para>Remove blocklist entry referenced by its
- <replaceable class="parameter">id</replaceable>. Use bloclist view command to get the id.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <xi:include href="files.xml" />
- <refsect1 id="environment">
- <title>ENVIRONMENT</title>
- <variablelist>
- <varlistentry>
- <term><envar>MPD_HOST</envar>, <envar>MPD_PORT</envar></term>
- <listitem>
- <para>&dhutils; will look for <envar>MPD_HOST</envar> and
- <envar>MPD_PORT</envar> to override built-in configuration
- (set to "localhost:6600").</para>
- <para>&dhutils; expects <envar>MPD_HOST</envar> syntax as documented in mpc manual,
- cf. <citerefentry><refentrytitle>mpc</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
- <sbr/>To use a password, provide a value of the form "password@host".
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><envar>HTTP_PROXY</envar>, <envar>HTTPS_PROXY</envar></term>
- <listitem>
- <para>&dhutils; honors <envar>HTTP_PROXY</envar> environment variables.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <refsect1 id="configuration">
- <title>CONFIGURATION</title>
- <variablelist>
- <varlistentry>
- <term><filename>mpd_sima.cfg</filename></term>
- <listitem>
- <para><filename>mpd_sima.cfg</filename> is read if present.
- Otherwise built-in defaults are used. An example should be
- provided in the tarball within
- <filename>doc/examples/</filename>. On Debian
- system please look in
- <filename>/usr/share/doc/&dhpackage;</filename>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>DEFAULTS</term>
- <listitem>
- <para>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.</para>
- <para>The get the defaults as detected by &dhutils; on your system you can run &dhutils; to print the config:</para>
- <para><command>&dhpackage; generate-config</command></para>
- </listitem>
- </varlistentry>
- </variablelist>
- <para>For details about mpd_sima.cfg refer to the manual
- <citerefentry>
- <refentrytitle>mpd_sima.cfg</refentrytitle>
- <manvolnum>5</manvolnum>
- </citerefentry>
- </para>
- </refsect1>
- <xi:include href="feedback.xml" />
- <xi:include href="seealso.xml" />
-</refentry>
+++ /dev/null
-'\" t
-.\" Title: mpd_sima.cfg
-.\" Author: kaliko <kaliko@azylum.org>
-.\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
-.\" Date: 11/16/2021
-.\" Manual: mpd-sima 0.18.0 User Manual
-.\" Source: mpd-sima
-.\" Language: English
-.\"
-.TH "MPD_SIMA\&.CFG" "5" "11/16/2021" "mpd-sima" "mpd-sima 0.18.0 User Manual"
-.\" -----------------------------------------------------------------
-.\" * Define some portability stuff
-.\" -----------------------------------------------------------------
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.\" http://bugs.debian.org/507673
-.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.ie \n(.g .ds Aq \(aq
-.el .ds Aq '
-.\" -----------------------------------------------------------------
-.\" * set default formatting
-.\" -----------------------------------------------------------------
-.\" disable hyphenation
-.nh
-.\" disable justification (adjust text to left margin only)
-.ad l
-.\" -----------------------------------------------------------------
-.\" * MAIN CONTENT STARTS HERE *
-.\" -----------------------------------------------------------------
-.SH "NAME"
-mpd_sima.cfg \- mpd\-sima will try to maintain some titles ahead in the queue following different policies\&. This manual document the configuration file for mpd\-sima\&.
-.SH "DESCRIPTION"
-.PP
-This manual page documents briefly
-\fBmpd\-sima\fR
-configuration options available in user configuration file (see
-the section called \(lqFILES\(rq)\&.
-.SH "EXAMPLES"
-.SS "File tags queue mode (offline mode)\&."
-.PP
-Here is an example of autoqueue using file tags only\&.
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-[MPD]
-host=example\&.org
-port=6601
-
-[sima]
-# Setup internal plugins
-internal = Tags, Crop
-history_duration=48 # 2 days
-queue_length=2
-
-[tags]
-# Look for files with tagged with genre "electonica" OR "IDM" OR "glitch"
-genre = electonica, IDM, glitch
-
-[crop]
-# keep 30 played tracks in playlist
-consume=30
-
-
-.fi
-.if n \{\
-.RE
-.\}
-.SS "Album queue mode using last\&.fm recommendations (online mode)\&."
-.PP
-Here is an example of album queue configuration using online recommendations system\&.
-.sp
-.if n \{\
-.RS 4
-.\}
-.nf
-[MPD]
-host=example\&.org
-port=8000
-
-[sima]
-history_duration=48 # 2 days
-queue_length=5
-
-[lastfm]
-queue_mode=album
-album_to_add=2
-
-[crop]
-# keep 30 played tracks in playlist
-consume=30
-
-
-.fi
-.if n \{\
-.RE
-.\}
-.SH "CONFIGURATION FILE"
-.PP
-The configuration file consists of sections, led by a
-\fB[section]\fR
-header and followed by
-\fBname:\ \&value\fR
-entries, with continuations in the style of RFC 822 (see section 3\&.1\&.1, \(lqLONG HEADER FIELDS\(rq);
-\fBname=value\fR
-is also accepted\&. Lines beginning with
-\fI\*(Aq#\*(Aq\fR
-or
-\fI\*(Aq;\*(Aq\fR
-are ignored and may be used to provide comments (\fINota Bene:\fR
-inline comment are possible using
-\fI\*(Aq#\*(Aq\fR)\&.
-.PP
-The default values are used in the options lists below\&.
-.SS "MPD section"
-.PP
-This section is meant to configure MPD access, MPD host address / port and password if necessary\&.
-.PP
-\fB[MPD]\fR
-.RS 4
-.RE
-.PP
-\fBhost=\fR\fIlocalhost\fR
-.RS 4
-Set MPD host\&. Use IP or FQDN\&.
-.RE
-.PP
-\fBport=\fR\fI6600\fR
-.RS 4
-Set host port to access MPD to\&.
-.RE
-.PP
-\fBpassword=\fR\fIs3cr3t\fR
-.RS 4
-Set MPD password to use\&. Do not use this option if you don\*(Aqt have enabled password protected access on your MPD server\&.
-.RE
-.SS "log section"
-.PP
-Configure logging\&.
-.PP
-\fB[log]\fR
-.RS 4
-.RE
-.PP
-\fBlogfile=\fR
-.RS 4
-File to log to, usually in d\(aemon mode\&.
-.br
-Default (empty or unset) is to log to stdin/stdout\&.
-.RE
-.PP
-\fBverbosity=\fR\fIinfo\fR
-.RS 4
-Logging verbosity among
-\fIdebug\fR,
-\fIinfo\fR,
-\fIwarning\fR,
-\fIerror\fR\&.
-.RE
-.SS "Process daemonization"
-.PP
-Configure process daemon\&.
-.PP
-\fB[daemon]\fR
-.RS 4
-.RE
-.PP
-\fBdaemon=false\fR
-.RS 4
-whether to daemonize process or not\&.
-.RE
-.PP
-\fBpidfile=\fR
-.RS 4
-Where to store process ID\&.
-.RE
-.SS "sima section"
-.PP
-Core mpd_sima\&.cfg configuration\&.
-.PP
-\fB[sima]\fR
-.RS 4
-.RE
-.PP
-\fBcontrib=\fR
-.RS 4
-.RE
-.PP
-\fBinternal=\fR\fILastfm, Random, Crop\fR
-.RS 4
-mpd\-sima\*(Aqs plugin management for internal source plugin and contrib (ie\&. external plugins)\&.
-.br
-
-Plugins list is a comma separated string list\&.
-.br
-
-Optional plugin\*(Aqs configuration lays in its own section\&.
-.br
-For instance a "AwesomePlugin" declared here gets its configuration from the corresponding section "[awesomeplugin]"\&.
-.sp
-The default list of plugins to load at startup:
-\fBLastfm\fR,\fBRandom\fR,\fBCrop\fR\&.
-.br
-
-\fBCrop\fR
-is an utility plugin, it does not queue any tracks (cf\&. below)\&.
-.br
-
-\fBRandom\fR
-will queue a track at random if other plugins did not return any tracks\&.
-.br
-
-.sp
-You can add, combine here as many plugins you want\&.
-.br
-
-The priority may be used to order them\&.
-.RE
-.PP
-\fBhistory_duration=\fR\fI8\fR
-.RS 4
-How far to look back in history to avoid to play twice the same track/title (duration in hours)\&.
-.br
-
-The
-\fBhistory_duration\fR
-is also used to give priority to not recently played artists\&.
-.RE
-.PP
-\fBqueue_length=\fR\fI2\fR
-.RS 4
-Threshold value triggering queue process\&.
-.RE
-.PP
-\fBmusicbrainzid=\fR\fItrue\fR
-.RS 4
-Use MusicBrainzIdentifier to search music (mainly for artists)\&. Default is True, switch to False if you don\*(Aqt have MusicBrainzIdentifier set for at least 80% of you music library\&.
-.br
-
-Consider using these metadata as it enhances a lot artist/album/tracks identification\&. Use Picard to tag your file:
-\m[blue]\fB\%https://picard.musicbrainz.org/\fR\m[]\&.
-.RE
-.PP
-\fBrepeat_disable_queue=\fR\fItrue\fR
-.RS 4
-Prevent disabling queuing in repeat play mode\&.
-.RE
-.PP
-\fBsingle_disable_queue=\fR\fItrue\fR
-.RS 4
-Prevent disabling queuing in single play mode\&.
-.RE
-.SS "Crop section"
-.PP
-crop plugin\*(Aqs configuration:
-.PP
-\fB[crop]\fR
-.RS 4
-.RE
-.PP
-\fBconsume=\fR\fI10\fR
-.RS 4
-How many played tracks to keep in the queue\&. Allows you to maintain a fixed length queue\&. Set to some negative integer to keep all played tracks\&.
-.RE
-.PP
-\fBpriority=\fR\fI10\fR
-.RS 4
-Plugin priority
-.RE
-.SS "Random section"
-.PP
-When no similar tracks are found, falling back to random queuing\&.
-.PP
-Random plugin\*(Aqs configuration:
-.PP
-\fB[random]\fR
-.RS 4
-.RE
-.PP
-\fBtrack_to_add=\fR\fI1\fR
-.RS 4
-How many track(s) to add\&.
-.RE
-.PP
-\fBflavour=\fR\fIsensible\fR
-.RS 4
-Different mode, aka random flavour, are available:
-\fIpure\fR,
-\fIsensible\fR,
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-\fIpure\fR, pure random choice, even among recently played track\&.
-.RE
-.sp
-.RS 4
-.ie n \{\
-\h'-04'\(bu\h'+03'\c
-.\}
-.el \{\
-.sp -1
-.IP \(bu 2.3
-.\}
-\fIsensible\fR, use play history to filter chosen tracks\&.
-.RE
-.sp
-.RE
-.PP
-\fBpriority=\fR\fI50\fR
-.RS 4
-Plugin priority
-.RE
-.SS "LastFm section"
-.PP
-LastFM plugin\*(Aqs configuration\&.
-.PP
-\fB[lastfm]\fR
-.RS 4
-.RE
-.PP
-\fBqueue_mode=\fR\fItrack\fR
-.RS 4
-Queue mode to use among
-\fItrack\fR,
-\fItop\fR
-and
-\fIalbum\fR
-(see
-the section called \(lqQUEUE MODES\(rq
-for info about queue modes)\&.
-.RE
-.PP
-\fBmax_art=\fR\fI10\fR
-.RS 4
-Maximum number of similar artist to retrieve from local media library\&.
-.br
-When set to something superior to zero, it tries to get as much similar artists from media library\&.
-.RE
-.PP
-\fBdepth=\fR\fI1\fR
-.RS 4
-How many artists to base on similar artists search\&.
-.br
-
-The first is the last played artist and so on back in the history\&. Highter depth generates wider suggestions, it might help to reduce looping over same artists\&.
-.RE
-.PP
-\fBsingle_album=\fR\fIfalse\fR
-.RS 4
-Prevent from queueing a track from the same album (it often happens with OST)\&.
-.br
-
-Only relevant in "track" queue mode\&.
-.RE
-.PP
-\fBtrack_to_add=\fR\fI1\fR
-.RS 4
-How many track(s) to add\&. Only relevant in
-\fBtop\fR
-and
-\fBtrack\fR
-queue modes\&. This is actually an upper limit, min(\fBmax_art\fR,
-\fBtrack_to_add\fR) will be used\&.
-.RE
-.PP
-\fBalbum_to_add=\fR\fI1\fR
-.RS 4
-How many album(s) to add\&. Only relevant in
-\fBalbum\fR
-queue modes\&.
-.RE
-.PP
-\fBtrack_to_add_from_album=\fR\fI0\fR
-.RS 4
-How many track(s) to add from each selected albums\&. Only relevant in
-\fBalbum\fR
-queue modes\&. When set to 0 or lower the whole album is queued\&.
-.RE
-.PP
-\fBcache=\fR\fITrue\fR
-.RS 4
-Whether or not to use on\-disk persistent http cache\&.
-.br
-When set to "true", sima will use a persistent cache for its http client\&. The cache is written along with the dbfile in:
-.br
-
-$XDG_DATA_HOME/mpd_sima/http/WEB_SERVICE\&.
-.br
-
-If set to "false", caching is still done but in memory\&.
-.RE
-.PP
-\fBpriority=\fR\fI100\fR
-.RS 4
-Plugin priority
-.RE
-.SS "Genre section"
-.PP
-Genre plugin\*(Aqs configuration\&.
-.PP
-This plugin permits offline autoqueuing based on files genre tag only\&.
-.PP
-it will try to queue tracks base on genre tags of tracks in the queue\&.
-.PP
-\fB[genre]\fR
-.RS 4
-.RE
-.PP
-\fBqueue_mode=\fR\fItrack\fR
-.RS 4
-Queue mode to use among
-\fItrack\fR,
-\fIalbum\fR
-(see
-the section called \(lqQUEUE MODES\(rq
-for info about queue modes)\&.
-.RE
-.PP
-\fBsingle_album=\fR\fIfalse\fR
-.RS 4
-Prevent from queueing a track from the same album (it often happens with OST)\&.
-.br
-
-Only relevant in "track" queue mode\&.
-.RE
-.PP
-\fBpriority=\fR\fI80\fR
-.RS 4
-Plugin priority
-.RE
-.PP
-\fBtrack_to_add=\fR\fI1\fR
-.RS 4
-How many track(s) to add\&.
-.RE
-.PP
-\fBalbum_to_add=\fR\fI1\fR
-.RS 4
-How many album(s) to add\&. Only relevant in
-\fBalbum\fR
-queue mode\&.
-.RE
-.SS "Tags section"
-.PP
-Tags plugin\*(Aqs configuration\&. There is no default configuration for this plugin, it does not work out of the box\&.
-.PP
-This plugin permits offline autoqueuing based on files tags only\&. Supported tags are
-\fB\*(Aqcomment\*(Aq\fR,
-\fB\*(Aqdate\*(Aq\fR,
-\fB\*(Aqgenre\*(Aq\fR,
-\fB\*(Aqlabel\*(Aq\fR
-and
-\fB\*(Aqoriginaldate\*(Aq\fR\&.
-.PP
-In addition to supported tags above you can use an MPD filter\&. Please refer to MPD protocol documentation for more\&.
-.PP
-All tag entries in this section are ANDed as a single MPD filter to look for titles in the library\&. Moreover, for each tags, comma separated values are also ORed\&.
-.br
-
-For instance setting "\fBgenre=rock\fR" and "\fBdate=1982,1983,1984,1985,1986,1987,1988,1989\fR" will end up looking for track tagged with genre
-\fBrock\fR
-and date within 1982 through 1989\&.
-.br
-
-Using an MPD filter to replace
-\fBdate\fR
-you can achieve the same with the following setting: "\fBgenre=rock\fR" and "\fBfilter=(date =~ \*(Aq198[2\-9]+\*(Aq)\fR" (provided your MPD server was compiled with libpcre)\&.
-.PP
-\fB[tags]\fR
-.RS 4
-.RE
-.PP
-\fBqueue_mode=\fR\fItrack\fR
-.RS 4
-Queue mode to use among
-\fItrack\fR,
-\fIalbum\fR
-(see
-the section called \(lqQUEUE MODES\(rq
-for info about queue modes)\&.
-.RE
-.PP
-\fBsingle_album=\fR\fIfalse\fR
-.RS 4
-Prevent from queueing a track from the same album (it often happens with OST)\&.
-.br
-
-Only relevant in "track" queue mode\&.
-.RE
-.PP
-\fBfilter=\fR
-.RS 4
-You can use here any valid MPD filter as defined in MPD protocol documentation\&.
-.RE
-.PP
-\fBcomment=\fR
-.RS 4
-.RE
-.PP
-\fBdate=\fR
-.RS 4
-.RE
-.PP
-\fBgenre=\fR
-.RS 4
-.RE
-.PP
-\fBlabel=\fR
-.RS 4
-.RE
-.PP
-\fBoriginaldate=\fR
-.RS 4
-.RE
-.PP
-\fBpriority=\fR\fI80\fR
-.RS 4
-Plugin priority
-.RE
-.PP
-\fBtrack_to_add=\fR\fI1\fR
-.RS 4
-How many track(s) to add\&.
-.RE
-.PP
-\fBalbum_to_add=\fR\fI1\fR
-.RS 4
-How many album(s) to add\&. Only relevant in
-\fBalbum\fR
-queue mode\&.
-.RE
-.SH "QUEUE MODES"
-.PP
-Different queue modes are available with some plugins (check for
-\fBqueue_mode\fR
-presence in plugin config)\&.
-.PP
-mpd\-sima tries preferably to chose among unplayed artists or at least not recently played artist\&.
-.PP
-\fBtrack\fR
-.RS 4
-Queue a similar track chosen at random from a similar artist\&.
-.RE
-.PP
-\fBtop\fR
-.RS 4
-Queue a track from a similar artist, chosen among "top tracks" according to last\&.fm data mining\&.
-.RE
-.PP
-\fBalbum\fR
-.RS 4
-Queue a whole album chosen at random from a similar artist\&.
-.sp
-\fINota Bene:\fR
-.br
-
-Due to the track point of view of database build upon tracks tags an album lookup for a specific artist will return albums as soon as this artist appears in a single track of the album\&.
-.br
-
-For instance looking for album from "The Velvet Underground" will fetch "Last Days" and "Juno" OSTs because the band appears on the soundtrack of these two movies\&.
-.br
-
-A solution is for you to set AlbumArtists tag to something different than the actual artist of the track\&. For compilations, OSTs etc\&. a strong convention is to use "Various Artists" for this tag\&.
-.sp
-mpd\-sima is currently looking for AlbumArtists tags and avoid album where this tag is set with "Various Artists"\&. If a single track within an album is found with AlbumArtists:"Various Artists" the complete album is skipped and won\*(Aqt be queued\&.
-.RE
-.SH "FILES"
-.PP
-${XDG_CONFIG_HOME}/mpd_sima/mpd_sima\&.cfg
-.RS 4
-Configuration file\&.
-.RE
-.PP
-${XDG_DATA_HOME}/mpd_sima/sima\&.db
-.RS 4
-SQLite DB file\&.
-.RE
-.PP
-${XDG_DATA_HOME}/mpd_sima/WEB_SERVICE/
-.RS 4
-Persistent http cache\&.
-.RE
-.PP
-Usually
-\fBXDG_DATA_HOME\fR
-is set to
-${HOME}/\&.local/share
-and
-\fBXDG_CONFIG_HOME\fR
-to
-${HOME}/\&.config\&.
-.br
-You may override them using command line option
-\fB\-\-var\-dir\fR
-and
-\fB\-\-config\fR
-(cf\&.
-\fBmpd-sima\fR(1))
-.SH "FEEDBACK/BUGS"
-.PP
-The maintainer would be more than happy to ear from you, don\*(Aqt hesitate to send feedback,
-\m[blue]\fB\%https://kaliko.me/contact/\fR\m[]\&.
-.PP
-XMPP
-users are welcome to join the dedicated chat room at
-\m[blue]\fBkaliko\&.me@conf\&.azylum\&.org\fR\m[]\&.
-.SH "SEE ALSO"
-.PP
-\fBmpc\fR(1),
-\fBmpd\fR(1)
-.PP
-/usr/share/doc/mpd\-sima/
-.SH "AUTHOR"
-.PP
-\fBkaliko\fR <\&kaliko@azylum\&.org\&>
-.RS 4
-Wrote this man page and is currently leading MPD_sima project\&.
-.RE
-.SH "COPYRIGHT"
-.br
-Copyright \(co 2009-2021 kaliko
-.br
-.PP
-This manual page was written for the Debian system (and may be used by others)\&.
-.PP
-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\&.
-.PP
-On Debian systems, the complete text of the GNU General Public License can be found in
-/usr/share/common\-licenses/GPL\&.
-.sp
+++ /dev/null
-<?xml version='1.0' encoding='UTF-8'?>
-<!--
-
-`xsltproc -''-nonet \
- -''-param man.charmap.use.subset "0" \
- -''-param make.year.ranges "1" \
- -''-param make.single.year.ranges "1" \
- /usr/share/xml/docbook/stylesheet/nwalsh/manpages/docbook.xsl \
- manpage.xml'
-
-A manual page <package>.<section> will be generated. You may view the
-manual page with: nroff -man <package>.<section> | less'. A typical entry
-in a Makefile or Makefile.am is:
-
-DB2MAN = /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/manpages/docbook.xsl
-XP = xsltproc -''-nonet -''-param man.charmap.use.subset "0"
-
-manpage.1: manpage.xml
- $(XP) $(DB2MAN) $<
-
-The xsltproc binary is found in the xsltproc package. The XSL files are in
-docbook-xsl. A description of the parameters you can use can be found in the
-docbook-xsl-doc-* packages. Please remember that if you create the nroff
-version in one of the debian/rules file targets (such as build), you will need
-to include xsltproc and docbook-xsl in your Build-Depends control field.
-Alternatively use the xmlto command/package. That will also automatically
-pull in xsltproc and docbook-xsl.
-
-Notes for using docbook2x: docbook2x-man does not automatically create the
-AUTHOR(S) and COPYRIGHT sections. In this case, please add them manually as
-<refsect1> ... </refsect1>.
-
-To disable the automatic creation of the AUTHOR(S) and COPYRIGHT sections
-read /usr/share/doc/docbook-xsl/doc/manpages/authors.html. This file can be
-found in the docbook-xsl-doc-html package.
-
-Validation can be done using: `xmllint -''-noout -''-valid manpage.xml`
-
-General documentation about man-pages and man-page-formatting:
-man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
-
--->
-<!DOCTYPE refentry [
-
- <!ENTITY dhsection "5">
- <!ENTITY dhpackage "mpd-sima">
- <!ENTITY dhutils "mpd_sima.cfg">
-
-]>
-
-<refentry xmlns="http://docbook.org/ns/docbook"
- xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0">
- <xi:include href="info.xml" />
- <refmeta>
- <refentrytitle>&dhutils;</refentrytitle>
- <manvolnum>&dhsection;</manvolnum>
- </refmeta>
- <refnamediv>
- <refname>&dhutils;</refname>
- <refpurpose>&dhpackage; will try to maintain some titles ahead in the queue
- following different policies. This manual document the
- configuration file for &dhpackage;.</refpurpose>
- </refnamediv>
- <refsect1 id="description">
- <title>DESCRIPTION</title>
- <para>This manual page documents briefly <command>&dhpackage;</command>
- configuration options available in user configuration file
- (see <xref linkend="files"/>).</para>
- </refsect1>
- <refsect1 id="examples">
- <title>EXAMPLES</title>
- <!--
- <refsect2 id="track">
- <title>Default queue mode, similar artist.</title>
- <para></para>
- <para></para>
- </refsect2> -->
- <refsect2 id="tags">
- <title>File tags queue mode (offline mode).</title>
- <para>Here is an example of autoqueue using file tags only.</para>
- <programlisting><xi:include href="tags.cfg" parse="text" />
- </programlisting>
- </refsect2>
- <refsect2 id="album">
- <title>Album queue mode using last.fm recommendations (online mode).</title>
- <para>Here is an example of album queue configuration using online recommendations system.</para>
- <programlisting><xi:include href="album.cfg" parse="text" />
- </programlisting>
- </refsect2>
- </refsect1>
-
- <refsect1 id="options">
- <title>Configuration file</title>
- <para>The configuration file consists of sections, led by a
- <command>[section]</command> header and followed by <option>name: value</option>
- entries, with continuations in the style of RFC 822 (see section
- 3.1.1, “LONG HEADER FIELDS”); <option>name=value</option> is also accepted. Lines
- beginning with <parameter>'#'</parameter> or <parameter>';'</parameter>
- are ignored and may be used to provide comments (<emphasis>Nota
- Bene:</emphasis> inline comment are possible using <parameter>'#'</parameter>).</para>
- <title>OPTIONS</title>
- <para>The default values are used in the options lists below.</para>
- <refsect2 id="MPD">
- <title>MPD section</title>
- <para>This section is meant to configure MPD access, MPD host
- address / port and password if necessary.</para>
- <variablelist>
- <!-- Use the variablelist.term.separator and the
- variablelist.term.break.after parameters to
- control the term elements. -->
- <varlistentry> <!-- MPD -->
- <term><option>[MPD]</option></term>
- <listitem></listitem>
- </varlistentry>
- <varlistentry> <!-- MPD.host -->
- <term><option>host=</option><replaceable>localhost</replaceable></term>
- <listitem>
- <para>Set MPD host. Use IP or FQDN.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- MPD.port -->
- <term><option>port=</option><replaceable>6600</replaceable></term>
- <listitem>
- <para>Set host port to access MPD to.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- MPD.password -->
- <term><option>password=</option><replaceable>s3cr3t</replaceable></term>
- <listitem>
- <para>Set MPD password to use. Do not use this option
- if you don't have enabled password protected access
- on your MPD server.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
- <refsect2 id="log">
- <title>log section</title>
- <para>Configure logging.</para>
- <variablelist>
- <varlistentry> <!-- LOG -->
- <term><option>[log]</option></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry> <!-- log.logfile -->
- <term><option>logfile=</option></term>
- <listitem>
- <para>File to log to, usually in dæmon mode.<sbr />Default
- (empty or unset) is to log to stdin/stdout.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- log.verbosity -->
- <term><option>verbosity=</option><replaceable>info</replaceable></term>
- <listitem>
- <para>Logging verbosity among
- <replaceable>debug</replaceable>,
- <replaceable>info</replaceable>,
- <replaceable>warning</replaceable>,
- <replaceable>error</replaceable>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
- <refsect2 id="daemon">
- <title>Process daemonization</title>
- <para>Configure process daemon.</para>
- <variablelist>
- <varlistentry> <!-- DAEMON -->
- <term><option>[daemon]</option></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <varlistentry> <!-- daemon.daemon -->
- <term><option>daemon=false</option></term>
- <listitem>
- <para>whether to daemonize process or not.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- daemon.pidfile -->
- <term><option>pidfile=</option></term>
- <listitem>
- <para>Where to store process ID.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
- <refsect2 id="sima">
- <title>sima section</title>
- <para>Core &dhutils; configuration.</para>
- <variablelist>
- <varlistentry> <!-- SIMA -->
- <term><option>[sima]</option></term>
- <listitem><para></para></listitem>
- </varlistentry>
- <variablelist>
- <varlistentry> <!-- sima.contrib -->
- <term><option>contrib=</option><replaceable></replaceable></term>
- <listitem>
- <para></para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- sima.internal -->
- <term><option>internal=</option><replaceable>Lastfm, Random, Crop</replaceable></term>
- <listitem>
- <para>&dhpackage;'s plugin management for internal source plugin
- and contrib (ie. external plugins).<sbr /> Plugins list is a
- comma separated string list.<sbr /> Optional plugin's
- configuration lays in its own section.<sbr />For instance a
- "AwesomePlugin" declared here gets its configuration from the
- corresponding section "[awesomeplugin]".
- </para>
- <para>The default list of plugins to load at startup: <option>Lastfm</option>,<option>Random</option>,<option>Crop</option>.<sbr />
- <option>Crop</option> is an utility plugin, it does not queue any tracks (cf. below).<sbr />
- <option>Random</option> will queue a track at random if other plugins did not return any tracks.<sbr />
- </para>
- <para>You can add, combine here as many plugins you want.<sbr />
- The priority may be used to order them.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- sima.history_duration -->
- <term><option>history_duration=</option><replaceable>8</replaceable></term>
- <listitem>
- <para>How far to look back in history to avoid to play
- twice the same track/title (duration in
- hours).<sbr />
- The <option>history_duration</option> is also used to give priority to not recently played artists.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- sima.queue_length -->
- <term><option>queue_length=</option><replaceable>2</replaceable></term>
- <listitem>
- <para>Threshold value triggering queue process.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- sima.musicbrainzid -->
- <term><option>musicbrainzid=</option><replaceable>true</replaceable></term>
- <listitem>
- <para>Use MusicBrainzIdentifier to search music (mainly
- for artists).
- Default is True, switch to False if you don't have
- MusicBrainzIdentifier set for at least 80% of you
- music library.<sbr /> Consider using these metadata as it
- enhances a lot artist/album/tracks identification.
- Use Picard to tag your file: <ulink url="https://picard.musicbrainz.org/"/>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- sima.repeat_disable_queue -->
- <term><option>repeat_disable_queue=</option><replaceable>true</replaceable></term>
- <listitem>
- <para>Prevent disabling queuing in repeat play mode.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- sima.single_disable_queue -->
- <term><option>single_disable_queue=</option><replaceable>true</replaceable></term>
- <listitem>
- <para>Prevent disabling queuing in single play mode.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </variablelist>
- </refsect2>
- <refsect2 id="crop">
- <title>Crop section</title>
- <para>crop plugin's configuration:</para>
- <varlistentry> <!-- crop -->
- <term><option>[crop]</option></term>
- </varlistentry>
- <varlistentry> <!-- crop.consume -->
- <term><option>consume=</option><replaceable>10</replaceable></term>
- <listitem>
- <para>How many played tracks to keep in the queue.
- Allows you to maintain a fixed length queue.
- Set to some negative integer to keep all played tracks.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- crop.priority -->
- <term><option>priority=</option><replaceable>10</replaceable></term>
- <listitem>
- <para>
- Plugin priority
- </para>
- </listitem>
- </varlistentry>
- </refsect2>
- <refsect2 id="random">
- <title>Random section</title>
- <para>When no similar tracks are found, falling back to random queuing.</para>
- <para>Random plugin's configuration:</para>
- <varlistentry> <!-- random -->
- <term><option>[random]</option></term>
- </varlistentry>
- <varlistentry> <!-- random.track_to_add -->
- <term><option>track_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many track(s) to add.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- random.flavour -->
- <term><option>flavour=</option><replaceable>sensible</replaceable></term>
- <listitem>
- <para>Different mode, aka random flavour,
- are available:
- <replaceable>pure</replaceable>,
- <replaceable>sensible</replaceable>,
- <itemizedlist mark='bullet'>
- <listitem>
- <para><replaceable>pure</replaceable>, pure random choice, even among recently played track.
- </para>
- </listitem>
- <listitem >
- <para><replaceable>sensible</replaceable>, use play history to filter chosen tracks.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- random.priority -->
- <term><option>priority=</option><replaceable>50</replaceable></term>
- <listitem>
- <para>
- Plugin priority
- </para>
- </listitem>
- </varlistentry>
- </refsect2>
- <refsect2 id="lastfm">
- <title>LastFm section</title>
- <para>LastFM plugin's configuration.</para>
- <variablelist>
- <varlistentry> <!-- lastfm -->
- <term><option>[lastfm]</option></term>
- </varlistentry>
- <varlistentry> <!-- lastfm.queue_mode -->
- <term><option>queue_mode=</option><replaceable>track</replaceable></term>
- <listitem>
- <para>Queue mode to use among
- <replaceable>track</replaceable>,
- <replaceable>top</replaceable> and
- <replaceable>album</replaceable> (see <xref linkend="queue_mode"/> for info about queue modes).</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.max_art -->
- <term><option>max_art=</option><replaceable>10</replaceable></term>
- <listitem>
- <para>Maximum number of similar artist to retrieve from local
- media library.<sbr />When set to something superior
- to zero, it tries to get as much similar artists
- from media library.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.depth -->
- <term><option>depth=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many artists to base on similar artists
- search.<sbr /> The first is the last played artist
- and so on back in the history. Highter depth
- generates wider suggestions, it might help to
- reduce looping over same artists.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.single_album -->
- <term><option>single_album=</option><replaceable>false</replaceable></term>
- <listitem>
- <para>Prevent from queueing a track from the same album
- (it often happens with OST).<sbr />
- Only relevant in "track" queue mode.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.track_to_add -->
- <term><option>track_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many track(s) to add. Only relevant in
- <option>top</option> and <option>track</option>
- queue modes. This is actually an upper limit,
- min(<option>max_art</option>,
- <option>track_to_add</option>) will be used.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.album_to_add -->
- <term><option>album_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many album(s) to add. Only relevant in
- <option>album</option> queue modes.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.track_to_add_from_album -->
- <term><option>track_to_add_from_album=</option><replaceable>0</replaceable></term>
- <listitem>
- <para>How many track(s) to add from each selected albums. Only relevant in
- <option>album</option> queue modes. When set to 0 or lower the whole album is queued.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.cache -->
- <term><option>cache=</option><replaceable>True</replaceable></term>
- <listitem>
- <para>Whether or not to use on-disk persistent http
- cache.<sbr />When set to "true", sima will use a
- persistent cache for its http client. The cache is
- written along with the dbfile in:<sbr />
- <filename>$XDG_DATA_HOME/mpd_sima/http/WEB_SERVICE</filename>.<sbr/>
- If set to "false", caching is still done but in memory.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- lastfm.priority -->
- <term><option>priority=</option><replaceable>100</replaceable></term>
- <listitem>
- <para>
- Plugin priority
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect2>
- <refsect2 id="genre">
- <title>Genre section</title>
- <para>Genre plugin's configuration.</para>
- <para>This plugin permits offline autoqueuing based on files genre tag only.</para>
- <para>It will try to queue tracks with similar genres (track's genre being read from tags).</para>
- <varlistentry> <!-- genre -->
- <term><option>[genre]</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.queue_mode -->
- <term><option>queue_mode=</option><replaceable>track</replaceable></term>
- <listitem>
- <para>Queue mode to use among
- <replaceable>track</replaceable>,
- <replaceable>album</replaceable> (see <xref linkend="queue_mode"/> for info about queue modes).</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- genre.single_album -->
- <term><option>single_album=</option><replaceable>false</replaceable></term>
- <listitem>
- <para>Prevent from queueing a track from the same album
- (it often happens with OST).<sbr />
- Only relevant in "track" queue mode.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- genre.priority -->
- <term><option>priority=</option><replaceable>80</replaceable></term>
- <listitem>
- <para>
- Plugin priority
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- genre.track_to_add -->
- <term><option>track_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many track(s) to add.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- genre.album_to_add -->
- <term><option>album_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many album(s) to add. Only relevant in
- <option>album</option> queue mode.</para>
- </listitem>
- </varlistentry>
- </refsect2>
- <refsect2 id="tags">
- <title>Tags section</title>
- <para>Tags plugin's configuration. There is no default configuration for this plugin,
- it does not work out of the box.</para>
- <para>This plugin permits offline autoqueuing based on files tags only. Supported tags are
- <option>'comment'</option>, <option>'date'</option>, <option>'genre'</option>,
- <option>'label'</option> and <option>'originaldate'</option>.</para>
- <para>In addition to supported tags above you can use an MPD filter. Please refer to
- MPD protocol documentation for more.</para>
- <para>All tag entries in this section are ANDed as a single MPD filter to look for titles
- in the library. Moreover, for each tags, comma separated values are also ORed.<sbr />
- For instance setting "<option>genre=rock</option>" and
- "<option>date=1982,1983,1984,1985,1986,1987,1988,1989</option>"
- will end up looking for track tagged with genre <option>rock</option>
- and date within 1982 through 1989.<sbr />
- Using an MPD filter to replace <option>date</option> you can achieve
- the same with the following setting: "<option>genre=rock</option>" and
- "<option>filter=(date =~ '198[2-9]+')</option>" (provided your MPD server
- was compiled with libpcre).
- </para>
- <varlistentry> <!-- tags -->
- <term><option>[tags]</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.queue_mode -->
- <term><option>queue_mode=</option><replaceable>track</replaceable></term>
- <listitem>
- <para>Queue mode to use among
- <replaceable>track</replaceable>,
- <replaceable>album</replaceable> (see <xref linkend="queue_mode"/> for info about queue modes).</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- tags.single_album -->
- <term><option>single_album=</option><replaceable>false</replaceable></term>
- <listitem>
- <para>Prevent from queueing a track from the same album
- (it often happens with OST).<sbr />
- Only relevant in "track" queue mode.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- tags.filter -->
- <term><option>filter=</option></term>
- <listitem>
- <para>You can use here any valid MPD filter as defined in MPD protocol documentation.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- tags.comment -->
- <term><option>comment=</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.date -->
- <term><option>date=</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.genre -->
- <term><option>genre=</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.label -->
- <term><option>label=</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.originaldate -->
- <term><option>originaldate=</option></term>
- </varlistentry>
- <varlistentry> <!-- tags.priority -->
- <term><option>priority=</option><replaceable>80</replaceable></term>
- <listitem>
- <para>
- Plugin priority
- </para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- tags.track_to_add -->
- <term><option>track_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many track(s) to add.</para>
- </listitem>
- </varlistentry>
- <varlistentry> <!-- tags.album_to_add -->
- <term><option>album_to_add=</option><replaceable>1</replaceable></term>
- <listitem>
- <para>How many album(s) to add. Only relevant in
- <option>album</option> queue mode.</para>
- </listitem>
- </varlistentry>
- </refsect2>
- </refsect1>
- <refsect1 id="queue_mode">
- <title>QUEUE MODES</title>
- <para>Different queue modes are available with some plugins (check for
- <option>queue_mode</option> presence in plugin config).
- </para>
- <para>&dhpackage; tries preferably to chose among unplayed artists or
- at least not recently played artist.</para>
- <variablelist>
- <varlistentry>
- <term><option>track</option></term>
- <listitem>
- <para>Queue a similar track chosen at random from a similar artist.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>top</option></term>
- <listitem>
- <para>Queue a track from a similar artist, chosen among
- "top tracks" according to last.fm data mining.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><option>album</option></term>
- <listitem>
- <para>Queue a whole album chosen at random from a similar artist.</para>
- <para><emphasis>Nota Bene:</emphasis><sbr /> Due to the
- track point of view of database build upon tracks tags
- an album lookup for a specific artist will return
- albums as soon as this artist appears in a single track
- of the album.<sbr />
- For instance looking for album from "The Velvet
- Underground" will fetch "Last Days" and "Juno" OSTs
- because the band appears on the soundtrack of these two
- movies.<sbr />
- A solution is for you to set AlbumArtists tag to
- something different than the actual artist of the
- track. For compilations, OSTs etc. a strong convention
- is to use "Various Artists" for this tag.</para>
- <para>&dhpackage; is currently looking for AlbumArtists tags
- and avoid album where this tag is set with "Various
- Artists". If a single track within an album is found
- with AlbumArtists:"Various Artists" the complete album
- is skipped and won't be queued.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
- <xi:include href="files.xml" />
- <xi:include href="feedback.xml" />
- <xi:include href="seealso.xml" />
-</refentry>
-<!-- vim: tabstop=4 softtabstop=4 shiftwidth=4 :
--->
+++ /dev/null
-<?xml version='1.0' encoding='UTF-8'?>
-<refsect1 id="see_also">
- <title>SEE ALSO</title>
- <!-- In alpabetical order. -->
- <para><citerefentry>
- <refentrytitle>mpc</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry>, <citerefentry>
- <refentrytitle>mpd</refentrytitle>
- <manvolnum>1</manvolnum>
- </citerefentry></para>
- <para>
- <filename>/usr/share/doc/mpd-sima/</filename>
- </para>
-</refsect1>
-<!-- vim:filetype=docbk
--->
+++ /dev/null
-[MPD]
-host=example.org
-port=6601
-
-[sima]
-# Setup internal plugins
-internal = Tags, Crop
-history_duration=48 # 2 days
-queue_length=2
-
-[tags]
-# Look for files with tagged with genre "electonica" OR "IDM" OR "glitch"
-genre = electonica, IDM, glitch
-
-[crop]
-# keep 30 played tracks in playlist
-consume=30
MPD_sima v0.18.1.dev0
* Remove bad heuristic to infer artist aliases
+ * Add shpinx documentation
+ * Merge unix manuals in sphinx reStructuredText
+ Call "setup.py build_sphinx" to build troff manuals
-- kaliko <kaliko@azylum.org> Thu, 18 Nov 2021 13:55:12 +0100
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
-sys.path.insert(0, os.path.abspath('../../'))
-from sima.info import __version__, __author__
+from sima.info import __author__
# -- General configuration ------------------------------------------------
# built documents.
#
# The short X.Y version.
-version = __version__
+#version =
# The full version, including alpha/beta/rc tags.
-release = __version__
+#release =
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
- (master_doc, 'mpd_sima', 'MPD_sima Documentation',
- [author], 1)
+ ('man/mpd-sima.1', 'mpd-sima',
+ 'mpd-sima will try to maintain some titles ahead in the queue following different policies.',
+ [author], 1),
+ ('man/mpd_sima.cfg.5', 'mpd_sima.cfg',
+ 'mpd-sima configuration.',
+ [author], 5),
]
# If true, show URL addresses after external links.
The default setting for MPD_sima is to queue similar artists thanks to last.fm_
suggestions but there are other possibilities.
-**To queue tracks from similar artists, start playing a track in MPD then launch MPD_sima:**
+**To queue tracks from similar artists:**
+ - start playing a track in MPD
+ - launch MPD_sima
.. code-block:: sh
# runs against a specific MPD server
mpd-sima --host mpd.example.org
+
#####################
User's documentation
#####################
user/*
+############
+Unix Manuals
+############
+
+These manual pages were written for the Debian system (and may be used by others).
+
+.. toctree::
+ :maxdepth: 2
+ :titlesonly:
+
+ man/mpd-sima.1.rst
+ man/mpd_sima.cfg.5.rst
+
+
##########################
Development documentation
##########################
dev/simadb
-###################
+##################
Indices and tables
-###################
+##################
* :ref:`genindex`
* :ref:`modindex`
--- /dev/null
+FILES
+-----
+
+:file:`${{XDG_CONFIG_HOME}}/mpd_sima/mpd_sima.cfg`
+ Configuration file.
+
+:file:`${{XDG_DATA_HOME}}/mpd_sima/sima.db`
+ SQLite internal DB file. Stores play history and blocklists.
+
+:file:`${{XDG_DATA_HOME}}/mpd_sima/WEB_SERVICE/`
+ HTTP cache.
+
+.. only:: format_man
+
+ Usually :envvar:`XDG_DATA_HOME` is set to :file:`${{HOME}}/.local/share` and
+ :envvar:`XDG_CONFIG_HOME` to :file:`${{HOME}}/.config` (for regular users).
+ You may override them using command line option ``--var-dir`` and ``--config``
+ (cf. :manpage:`mpd-sima(1)`)
+
+.. only:: format_html
+
+ Usually :envvar:`XDG_DATA_HOME` is set to :file:`${{HOME}}/.local/share` and
+ :envvar:`XDG_CONFIG_HOME` to :file:`${{HOME}}/.config` (for regular users).
+ You may override them using command line option ``--var-dir`` and ``--config``
+ (cf. :doc:`mpd-sima.1`)
--- /dev/null
+FEEDBACK/BUGS
+-------------
+
+The maintainer would be more than happy to ear from you, don't hesitate to send feedback, https://kaliko.me/contact/
+
+XMPP users are welcome to join the dedicated chat room at kaliko.me@conf.azylum.org
--- /dev/null
+========
+mpd-sima
+========
+
+SYNOPSYS
+--------
+
+``mpd-sima [--daemon] [--config=conf_file] [--var-dir=var_directory] [--pid=pid_file] [--log=log_file] [--log-level=log_level] [--host=mpd_host] [--mpd_port=mpd_port]``
+
+``mpd-sima {{-h | --help} --version}``
+
+``mpd-sima [--config=conf_file] config-test``
+
+``mpd-sima [--var-dir=var_directory] create-db``
+
+``mpd-sima […] generate-config``
+
+``mpd-sima [--var-dir=var_directory] purge-history``
+
+``mpd-sima bl-view``
+
+``mpd-sima bl-add-artist [artist]``
+
+``mpd-sima bl-add-album [album]``
+
+``mpd-sima bl-add-track [track]``
+
+``mpd-sima bl-delete id``
+
+
+DESCRIPTION
+-----------
+
+This manual page documents briefly the ``mpd-sima`` commands.
+
+At start up default configuration is first overridden by user configuration in
+mpd_sima.cfg (see FILES_) and finally command lines options are honored. For
+instance you can override default MPD host (localhost) in your configuration
+file or with ``-S my_mpd_server.local`` option. For default configuration see
+CONFIGURATION_. See also environment variables special case for MPD host and
+port in ENVIRONMENT_.
+
+
+OPTIONS
+-------
+
+The program follows the usual GNU command line syntax, with long options
+starting with two dashes ('-'). A summary of options is included below.
+
+``-h``; ``--help``
+ Print help and exit.
+
+``--version``
+ Print version and exit.
+
+``--daemon``
+ Start as a daemon. Log redirected to :file:`/dev/null`, usually setting
+ ``--log`` and ``--pid`` options in daemon mode are a good idea to
+ monitor/stop the process.
+
+``-p pid_file``; ``--pid=pid_file``
+ Use the specific file pid_file to store pid to.
+
+ Default is not to store pid info.
+
+``-l log_file``; ``--log=log_file``
+ Use the specific file log_file to log messages to.
+
+ Default is to log to stdout/stderr.
+
+``-v log_level``; ``--log-level=log_level``
+ Verbosity in [debug,info,warning,error].
+
+ Default is to log info messages.
+
+``-c conf_file``; ``--config=conf_file``
+ Use the specific file conf_file to set up configuration instead of
+ looking for the default user configuration file.
+
+ Default is to look for :file:`${{XDG_CONFIG_HOME}}/mpd_sima/mpd_sima.cfg`.
+ CLI option overrides any equivalent mentioned in configuration file, ie.
+ launching mpd-sima with ``--port`` CLI option will ignore port setting in
+ configuration file.
+
+ For more details on configuration file see also `FILES <#files>`__ and `CONFIGURATION <#configuration>`__ sections.
+
+``--var-dir=var_directory``
+ Use the specific path var_directory to look for (or create) var files
+ (ie. database) instead of looking at the default user data
+ location.
+
+ Default is to look in :file:`${{XDG_DATA_HOME}}/mpd_sima/`. Concerning
+ :envvar:`XDG_DATA_HOME` see also `FILES section <#files>`__.
+
+``-S mpd_host``; ``--host=mpd_host``
+ Use the specific host mpd_host as MPD server.mpd_host can be an IP or
+ a fully qualified domain name as long as your system can resolve it.
+ This overrides MPD_HOST environment variable.
+ Default is *localhost*.
+
+ See also `ENVIRONMENT section <#environment>`__.
+
+``-P mpd_port``; ``--port=mpd_port``
+ Use the specific port number mpd_port on MPD server. This overrides
+ MPD_PORT environment variable.Default is *6600*.
+
+ See also `ENVIRONMENT section <#environment>`__
+
+Command arguments
+-----------------
+
+``config-test``
+ Test configuration file and exit. Uses the configuration file
+ specified with ``--config`` or default location.
+ Default is to use $XDG_CONFIG_HOME/mpd_sima/mpd_sima.cfg.
+
+ config-test tests MPD connection and Tags plugin configuration.
+
+``create-db``
+ Create the database and exit. Uses folder specified with
+ ``--var-dir`` or default directory.
+
+ Default is to use :file:`${{XDG_DATA_HOME}}/mpd_sima/` (see `CONFIGURATION
+ section <#configuration>`__ for more).
+
+``generate-config``
+ Generate a sample configuration file according to the current CLI
+ options and environment variables. The configuration is written on stdout.
+
+``purge-history``
+ Purge play history in the database and exit. Uses folder specified
+ with ``--var-dir`` or default directory.
+
+ Default is to use :file:`${{XDG_DATA_HOME}}/mpd_sima/` (see `FILES section
+ <#files>`__ for more).
+
+``bl-view``
+ View blocklist, useful to get entry IDs to remove with delete
+ command.
+
+``bl-add-artist artist``
+ Add artist to the blocklist. If artist is not provided, try to get
+ the currently playing artist.
+
+``bl-add-album album``
+ Add album to the blocklist. If album is not provided, try to get the
+ currently playing album.
+
+``bl-add-track track``
+ Add track to the blocklist. If track is not provided, try to get the
+ currently playing track.
+
+``bl-delete id``
+ Remove blocklist entry referenced by its id. Use bloclist view
+ command to get the id.
+
+ENVIRONMENT
+-----------
+
+:envvar:`MPD_HOST`, :envvar:`MPD_PORT`
+ mpd-sima will look for MPD_HOST and MPD_PORT to override built-in
+ configuration (set to "localhost:6600").
+
+ mpd-sima expects MPD_HOST syntax as documented in mpc manual, cf.
+ :manpage:`mpc(1)`. To use a password, provide a value of the form **password@host**.
+
+:envvar:`HTTP_PROXY`, :envvar:`HTTPS_PROXY`
+ mpd-sima honors HTTP_PROXY environment variables.
+
+
+CONFIGURATION
+-------------
+
+:file:`mpd_sima.cfg`
+ :file:`mpd_sima.cfg` is read if present. Otherwise built-in defaults are
+ used. An example should be provided in the tarball within ``doc/examples/``.
+ On Debian system please look in :file:`/usr/share/doc/mpd-sima`.
+
+**DEFAULTS**
+
+ Default is to look for MPD server at localhost:6600 (or
+ :envvar:`MPD_HOST`/:envvar:`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.
+
+ The get the defaults as detected by mpd-sima on your system you can
+ run mpd-sima to print the config:
+
+ ``mpd-sima generate-config``
+
+.. only:: format_man
+
+ For details about mpd_sima.cfg refer to the manual :manpage:`mpd_sima.cfg(5)`
+
+.. only:: format_html
+
+ For details about mpd_sima.cfg refer to the manual :doc:`mpd_sima.cfg.5`
+
+.. include:: files.rst
+.. include:: seealso.rst
+.. include:: info.rst
--- /dev/null
+============
+mpd_sima.cfg
+============
+
+DESCRIPTION
+-----------
+
+This manual page documents briefly ``mpd-sima`` configuration options available
+in user configuration file (see `FILES <#files>`__).
+
+EXAMPLES
+--------
+
+File tags queue mode (offline mode).
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here is an example of autoqueue using file tags only.
+
+::
+
+ [MPD]
+ # Uses defaults for MPD connection
+ #host = localhost
+ #port = 6600
+ #password = s3cr3t
+
+ [sima] # Setup internal plugins
+ # Tags plugin falls back to Random if nothing is found then Crop the queue
+ internal = Tags, Random, Crop
+ history_duration=48 # 48h / 24 = 2 days
+ queue_length=2 # triggers autoqueue when 2 tracks remains to play
+
+ [tags]
+ # Look for files with tagged with genre "electronica" OR "IDM" OR "glitch"
+ genre = electronica, IDM, glitch
+
+ [crop]
+ # keep 30 played tracks in playlist
+ consume=30
+
+
+Album queue mode using last.fm recommendations (online mode).
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here is an example of album queue configuration using online
+recommendations system.
+
+::
+
+ [sima]
+ history_duration = 96 # 4 days in hours, get a larger history for album mode
+ queue_length = 5
+
+ [crop]
+ consume = 20
+
+ [lastfm]
+ queue_mode = album
+ album_to_add = 1
+
+.. _options:
+
+Configuration file
+------------------
+
+The configuration file consists of sections, led by a ``[section]``
+header and followed by ``name: value`` entries, with continuations in
+the style of :rfc:`822` (see section 3.1.1, “LONG HEADER FIELDS”);
+``name=value`` is also accepted. Lines beginning with ``'#'`` or ``';'``
+are ignored and may be used to provide comments (*Nota Bene:* inline
+comment are possible using ``'#'``).
+
+The default values are used in the options lists below.
+
+.. _MPD:
+
+MPD section
+^^^^^^^^^^^
+
+This section is meant to configure MPD access, MPD host address / port
+and password if necessary.
+
+**[MPD]**
+
+**host=localhost**
+ Set MPD host. Use IP or FQDN.
+
+**port=6600**
+ Set host port to access MPD to.
+
+**password=s3cr3t**
+ Set MPD password to use. Do not use this option if you don't have
+ enabled password protected access on your MPD server.
+
+.. _log:
+
+log section
+^^^^^^^^^^^
+
+Configure logging.
+
+**[log]**
+
+**logfile=**
+ File to log to, usually in dæmon mode.Default (empty or unset) is to
+ log to stdin/stdout.
+
+**verbosity=info**
+ Logging verbosity among debug, info, warning, error.
+
+.. _daemon:
+
+Process daemonization
+^^^^^^^^^^^^^^^^^^^^^
+
+Configure process daemon.
+
+**[daemon]**
+
+**daemon=false**
+ whether to daemonize process or not.
+
+**pidfile=**
+ Where to store process ID.
+
+.. _sima:
+
+sima section
+^^^^^^^^^^^^
+
+Core mpd-sima configuration.
+
+**[sima]**
+
+
+**internal=Lastfm, Random, Crop**
+ mpd-sima's plugin management for internal source plugin and contrib (ie. external plugins).
+
+ Plugins list is a comma separated string list.
+
+ Optional plugin's configuration lays in its own section.
+ For instance a "AwesomePlugin" declared here gets its configuration from the corresponding section "[awesomeplugin]".
+
+ The default list of plugins to load at startup: Lastfm,Random,Crop.
+
+ Crop is an utility plugin, it does not queue any tracks (cf. below).
+
+ Random will queue a track at random if other plugins did not return any tracks.
+
+ You can add, combine here as many plugins you want.
+
+ The priority may be used to order them.
+
+**history_duration=8**
+ How far to look back in history to avoid to play twice the same track/title (duration in hours).
+
+ The history_duration is also used to give priority to not recently played artists. Artist/tracks not in the scope of history have higther priority.
+
+**queue_length=2**
+ Threshold value triggering queue process.
+
+**musicbrainzid=true**
+ Use MusicBrainzIdentifier to search music (mainly for artists). Default is True, switch to False if you don't have MusicBrainzIdentifier set for at least 80% of you music library.
+
+ Consider using these metadata as it enhances a lot artist/album/tracks identification. Use Picard to tag your file: https://picard.musicbrainz.org/.
+
+**repeat_disable_queue=true**
+ Prevent disabling queuing in repeat play mode.
+
+**single_disable_queue=true**
+ Prevent disabling queuing in single play mod
+
+
+.. _crop:
+
+Crop section
+^^^^^^^^^^^^
+
+crop plugin's configuration:
+
+**[crop]**
+
+**consume=10**
+ How many played tracks to keep in the queue. Allows you to maintain a
+ fixed length queue. Set to some negative integer to keep all played
+ tracks.
+
+**priority=10**
+ Plugin priority
+
+.. _random:
+
+Random section
+^^^^^^^^^^^^^^
+
+When no similar tracks are found, falling back to random queuing.
+
+Random plugin's configuration:
+
+**[random]**
+
+**track_to_add=1**
+ How many track(s) to add.
+
+**flavour=sensible**
+ Different mode, aka random flavour, are available: **pure**, **sensible**,
+
+ - **pure**: pure random choice, even among recently played track.
+
+ - **sensible**: use play history to filter chosen tracks.
+
+**priority=50**
+ Plugin priority
+
+.. _lastfm:
+
+LastFm section
+^^^^^^^^^^^^^^
+
+LastFM plugin's configuration.
+
+
+**[lastfm]**
+**queue_mode=track**
+
+ Queue mode to use among track, top and album (see `QUEUE MODE section
+ <#queue_mode>`__ for info about queue modes).
+
+**max_art=0**
+
+ Maximum number of similar artist to retrieve from local media
+ library. When set to something superior to zero, it tries to get as
+ much similar artists from media library.
+
+**depth=1**
+ How many artists to base on similar artists search. The first is the
+ last played artist and so on back in the history. Highter depth
+ generates wider suggestions, it might help to reduce looping over
+ same artists.
+
+**single_album=false**
+ Prevent from queueing a track from the same album (it often happens
+ with OST). Only relevant in "track" queue mode.
+
+**track_to_add=1**
+ How many track(s) to add. Only relevant in ``top`` and ``track``
+ queue modes. This is actually an upper limit, min(``max_art``,
+ ``track_to_add``) will be used.
+
+**album_to_add=1**
+ How many album(s) to add. Only relevant in ``album`` queue modes.
+
+**track_to_add_from_album=0**
+ How many track(s) to add from each selected albums. Only relevant in
+ ``album`` queue modes. When set to 0 or lower the whole album is
+ queued.
+
+**cache=True**
+ Whether or not to use on-disk persistent http cache.When set to
+ "true", sima will use a persistent cache for its http client. The
+ cache is written along with the dbfile in:
+ ``$XDG_DATA_HOME/mpd_sima/http/WEB_SERVICE``. If set to "false",
+ caching is still done but in memory.
+
+**priority=100**
+ Plugin priority
+
+.. _genre:
+
+Genre section
+^^^^^^^^^^^^^
+
+Genre plugin's configuration.
+
+This plugin permits offline autoqueuing based on files genre tag only.
+
+It will try to queue tracks with similar genres (track's genre being read from
+tags).
+
+
+**[genre]**
+
+**queue_mode=track**
+ Queue mode to use among track, album (see
+ `QUEUE MODE section <#queue_mode>`__ for more info).
+
+**single_album=false**
+ Prevent from queueing a track from the same album (it often happens with
+ OST). Only relevant in "track" queue mode.
+
+**priority=80**
+ Plugin priority
+
+**track_to_add=1**
+ How many track(s) to add.
+
+**album_to_add=1**
+ How many album(s) to add. Only relevant in ``album`` queue mode.
+
+.. _tags:
+
+Tags section
+^^^^^^^^^^^^
+
+Tags plugin's configuration. There is no default configuration for this
+plugin, it does not work out of the box.
+
+This plugin permits offline autoqueuing based on files tags only.
+Supported tags are ``'comment'``, ``'date'``, ``'genre'``, ``'label'``
+and ``'originaldate'``.
+
+In addition to supported tags above you can use an MPD filter. Please
+refer to MPD protocol documentation for more.
+
+All tag entries in this section are ANDed as a single MPD filter to look
+for titles in the library. Moreover, for each tags, comma separated
+values are also ORed. For instance setting "``genre=rock``" and
+"``date=1982,1983,1984,1985,1986,1987,1988,1989``" will end up looking
+for track tagged with genre ``rock`` and date within 1982 through 1989.
+Using an MPD filter to replace ``date`` you can achieve the same with
+the following setting: "``genre=rock``" and
+"``filter=(date =~ '198[2-9]+')``" (provided your MPD server was
+compiled with libpcre).
+
+**[tags]**
+
+**queue_mode=track**
+ Queue mode to use among track, album (see `QUEUE MODES section
+ <#queue_mode>`__ for info).
+
+**single_album=false**
+ Prevent from queueing a track from the same album (it often happens with
+ OST). Only relevant in "track" queue mode.
+
+**filter=**
+ You can use here any valid MPD filter as defined in MPD protocol
+ documentation.
+
+**comment=**
+
+**date=**
+
+**genre=**
+
+**label=**
+
+**originaldate=**
+
+**priority=80**
+ Plugin priority
+
+**track_to_add=1**
+ How many track(s) to add.
+
+**album_to_add=1**
+ How many album(s) to add. Only relevant in ``album`` queue mode.
+
+.. _queue_mode:
+
+QUEUE MODES
+-----------
+
+Different queue modes are available with some plugins (check for
+``queue_mode`` presence in plugin config).
+
+mpd-sima tries preferably to chose among unplayed artists or at least
+not recently played artist.
+
+``track``
+ Queue a similar track chosen at random from a similar artist.
+
+``top``
+ Queue a track from a similar artist, chosen among "top tracks"
+ according to last.fm data mining.
+
+``album``
+ Queue a whole album chosen at random from a similar artist.
+
+ *Nota Bene:* Due to the track point of view of database build upon
+ tracks tags an album lookup for a specific artist will return albums
+ as soon as this artist appears in a single track of the album. For
+ instance looking for album from "The Velvet Underground" will fetch
+ "Last Days" and "Juno" OSTs because the band appears on the
+ soundtrack of these two movies. A solution is for you to set
+ AlbumArtists tag to something different than the actual artist of the
+ track. For compilations, OSTs etc. a strong convention is to use
+ "Various Artists" for this tag.
+
+ mpd-sima is currently looking for AlbumArtists tags and avoid album
+ where this tag is set with "Various Artists". If a single track
+ within an album is found with AlbumArtists:"Various Artists" the
+ complete album is skipped and won't be queued.
+
+.. include:: files.rst
+.. include:: seealso.rst
+.. include:: info.rst
--- /dev/null
+SEE ALSO
+--------
+
+:envvar:`mpc(1)`, :envvar:`mpd(1)`
from sima.info import __doc__ as DESCRIPTION, __email__ as EMAIL
data_files = [
- ('share/man/man1', ['data/man/mpd-sima.1']),
- ('share/man/man5', ['data/man/mpd_sima.cfg.5']),
('share/doc/mpd-sima/examples/', glob.glob('doc/examples/*')),
('share/doc/mpd-sima/', [fi for fi in listdir('doc') if isfile(fi)]),
]
]
},
test_suite="tests",
+ command_options={
+ 'build_sphinx': {
+ 'version': ('setup.py', VERSION),
+ 'release': ('setup.py', VERSION),
+ 'builder': ('setup.py', 'html,man'),
+ }
+ }
)
# VIM MODLINE
home / dev / repositories / mpd-sima.git / commitdiff