From dd2a18ade8d2cdbd3111c4eb01cf95f4a631f8a7 Mon Sep 17 00:00:00 2001 From: kaliko Date: Mon, 22 Nov 2021 16:02:54 +0100 Subject: [PATCH] doc: Merge manual in sphinx build --- .gitlab-ci.yml | 4 +- data/man/Makefile | 49 --- data/man/album.cfg | 15 - data/man/feedback.xml | 8 - data/man/files.xml | 32 -- data/man/info.xml | 51 --- data/man/mpd-sima.1 | 389 ------------------ data/man/mpd_sima.1.xml | 372 ----------------- data/man/mpd_sima.cfg.5 | 637 ------------------------------ data/man/mpd_sima.cfg.5.xml | 604 ---------------------------- data/man/seealso.xml | 17 - data/man/tags.cfg | 17 - doc/Changelog | 3 + doc/source/conf.py | 15 +- doc/source/index.rst | 23 +- doc/source/man/files.rst | 25 ++ doc/source/man/info.rst | 6 + doc/source/man/mpd-sima.1.rst | 202 ++++++++++ doc/source/man/mpd_sima.cfg.5.rst | 396 +++++++++++++++++++ doc/source/man/seealso.rst | 4 + setup.py | 9 +- 21 files changed, 675 insertions(+), 2203 deletions(-) delete mode 100644 data/man/Makefile delete mode 100644 data/man/album.cfg delete mode 100644 data/man/feedback.xml delete mode 100644 data/man/files.xml delete mode 100644 data/man/info.xml delete mode 100644 data/man/mpd-sima.1 delete mode 100644 data/man/mpd_sima.1.xml delete mode 100644 data/man/mpd_sima.cfg.5 delete mode 100644 data/man/mpd_sima.cfg.5.xml delete mode 100644 data/man/seealso.xml delete mode 100644 data/man/tags.cfg create mode 100644 doc/source/man/files.rst create mode 100644 doc/source/man/info.rst create mode 100644 doc/source/man/mpd-sima.1.rst create mode 100644 doc/source/man/mpd_sima.cfg.5.rst create mode 100644 doc/source/man/seealso.rst diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 228dcfb..8379c87 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -22,10 +22,12 @@ stages: 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 diff --git a/data/man/Makefile b/data/man/Makefile deleted file mode 100644 index ca85943..0000000 --- a/data/man/Makefile +++ /dev/null @@ -1,49 +0,0 @@ -# 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 diff --git a/data/man/album.cfg b/data/man/album.cfg deleted file mode 100644 index d21464f..0000000 --- a/data/man/album.cfg +++ /dev/null @@ -1,15 +0,0 @@ -[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 diff --git a/data/man/feedback.xml b/data/man/feedback.xml deleted file mode 100644 index ce2740c..0000000 --- a/data/man/feedback.xml +++ /dev/null @@ -1,8 +0,0 @@ - - - FEEDBACK/BUGS - The maintainer would be more than happy to ear from you, don't hesitate to send feedback, . - XMPP users are welcome to join the dedicated chat room at kaliko.me@conf.azylum.org. - - diff --git a/data/man/files.xml b/data/man/files.xml deleted file mode 100644 index 5743c5b..0000000 --- a/data/man/files.xml +++ /dev/null @@ -1,32 +0,0 @@ - - - FILES - - - ${XDG_CONFIG_HOME}/mpd_sima/mpd_sima.cfg - - Configuration file. - - - - ${XDG_DATA_HOME}/mpd_sima/sima.db - - SQLite DB file. - - - - ${XDG_DATA_HOME}/mpd_sima/WEB_SERVICE/ - - Persistent http cache. - - - - Usually XDG_DATA_HOME is set to - ${HOME}/.local/share and XDG_CONFIG_HOME to - ${HOME}/.config.You may override them using - command line option and (cf. - mpd-sima - 1) - - diff --git a/data/man/info.xml b/data/man/info.xml deleted file mode 100644 index 344b27f..0000000 --- a/data/man/info.xml +++ /dev/null @@ -1,51 +0,0 @@ - - - - - - - - - - ]> - - &dhtitle; - &dhpackage; - - - &dhsurname; - Wrote this man page and is currently leading MPD_sima project. -
- &dhemail; -
- - - - 2009 - 2010 - 2011 - 2012 - 2013 - 2014 - 2015 - 2016 - 2017 - 2018 - 2019 - 2020 - 2021 - &dhusername; - - - This manual page was written for the Debian system - (and may be used by others). - 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. - On Debian systems, the complete text of the GNU General Public - License can be found in - /usr/share/common-licenses/GPL. - - diff --git a/data/man/mpd-sima.1 b/data/man/mpd-sima.1 deleted file mode 100644 index 8e1b63d..0000000 --- a/data/man/mpd-sima.1 +++ /dev/null @@ -1,389 +0,0 @@ -'\" t -.\" Title: mpd-sima -.\" Author: kaliko -.\" Generator: DocBook XSL Stylesheets v1.79.2 -.\" 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 diff --git a/data/man/mpd_sima.1.xml b/data/man/mpd_sima.1.xml deleted file mode 100644 index 9873396..0000000 --- a/data/man/mpd_sima.1.xml +++ /dev/null @@ -1,372 +0,0 @@ - - - - - - -]> - - - - - &dhutils; - &dhsection; - - - &dhutils; - &dhutils; will try to maintain some titles ahead in the queue following different policies. - - - - &dhutils; - - conf_file - var_directory - pid_file - log_file - log_level - mpd_host - mpd_port - - - &dhutils; - - - - - - - - - - - - - &dhutils; - config-test - conf_file - - - &dhutils; - create-db - var_directory - - - &dhutils; - generate-config - - - - &dhutils; - purge-history - var_directory - - - &dhutils; - bl-view - - - &dhutils; - bl-add-artist - - - - &dhutils; - bl-add-album - - - - &dhutils; - bl-add-track - - - - &dhutils; - bl-delete - - - - - DESCRIPTION - This manual page documents briefly the - &dhutils; commands. - At start up default configuration is first overridden by user - configuration in mpd_sima.cfg (see ) 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 option. For default - configuration see . See also environment - variables special case for MPD host and port in . - - - - EXAMPLE - - Launch as a system service (dæmon). - Here follows an example on how to launch &dhutils; as a service on your system, not attach to regular user configuration/database. - &dhutils; --daemon --conf=/etc/mpd_sima.cfg --var-dir=/var/cache/mpd-sima/ --pid=/run/mpd-sima.pid --log=/var/log/mpd-sima.log - - - Launch in user land - Launching &dhutils; from/whithin your user account is easy, you can simply call &dhutils; from your shell or one of the following command: - Background execution (dæmonise), log in the specified file, save pid: - &dhutils; --daemon --pid=$HOME/var/run/mpd-sima.pid --log=$HOME/var/log/mpd-sima.log - Foreground execution, connect my.mpd.server.org, log to std(out|err): - &dhutils; --host=my.mpd.server.org - - - - OPTIONS - The program follows the usual GNU command line syntax, - with long options starting with two dashes (`-'). A summary of - options is included below. - - - - - - - Print help and exit. - - - - - - Print version and exit. - - - - - - Start as a daemon. Log redirected to /dev/null, usually setting and options in daemon mode are a good idea to monitor/stop the process. - - - - - - - Use the specific file pid_file to store pid to.Default is not to store pid info. - - - - - - - Use the specific file log_file to log messages to.Default is to log to stdout/stderr. - - - - - - - Verbosity in [debug,info,warning,error].Default is to log info messages. - - - - - - - Use the specific file conf_file to set up - configuration instead of looking for the default user - configuration file.Default is to look for - $XDG_CONFIG_HOME/mpd_sima/mpd_sima.cfg. - CLI option overrides any equivalent mentioned in configuration file, ie. launching &dhutils; with '' CLI option will ignore port setting in configuration file. - For more details on configuration file cf. - mpd_sima.cfg - 5, see also . - - - - - - - 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 $XDG_DATA_HOME/mpd_sima/. Concerning $XDG_DATA_HOME see also . - - - - - - - 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 . - - - - - - - Use the specific port number mpd_port on MPD server. This overrides MPD_PORT environment variable.Default is 6600. - See also - - - - - - Test configuration file and exit. Uses the configuration file specified with or default location.Default is to use $XDG_CONFIG_HOME/mpd_sima/mpd_sima.cfg (see for more). - config-test tests MPD connection and Tags plugin configuration. - - - - - - Create the database and exit. Uses folder specified with or default directory.Default is to use $XDG_DATA_HOME/mpd_sima/ (see for more). - - - - - - Generate a sample configuration file according to the current CLI options and env. var.. The configuration is written on stdout. - - - - - - Purge play history in the database and exit. Uses folder specified with or default directory.Default is to use $XDG_DATA_HOME/mpd_sima/ (see for more). - - - - - - View blocklist, useful to get entry IDs to remove with delete command. - - - - - - Add artist to the blocklist. If - artist - is not provided, try to get the currently playing artist. - - - - - - - Add album to the blocklist. If - album - is not provided, try to get the currently playing album. - - - - - - - Add track to the blocklist. If - track - is not provided, try to get the currently playing track. - - - - - - - Remove blocklist entry referenced by its - id. Use bloclist view command to get the id. - - - - - - - - ENVIRONMENT - - - MPD_HOST, MPD_PORT - - &dhutils; will look for MPD_HOST and - MPD_PORT to override built-in configuration - (set to "localhost:6600"). - &dhutils; expects MPD_HOST syntax as documented in mpc manual, - cf. mpc1. - To use a password, provide a value of the form "password@host". - - - - - HTTP_PROXY, HTTPS_PROXY - - &dhutils; honors HTTP_PROXY environment variables. - - - - - - CONFIGURATION - - - mpd_sima.cfg - - 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/&dhpackage;. - - - - DEFAULTS - - 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. - The get the defaults as detected by &dhutils; on your system you can run &dhutils; to print the config: - &dhpackage; generate-config - - - - For details about mpd_sima.cfg refer to the manual - - mpd_sima.cfg - 5 - - - - - - diff --git a/data/man/mpd_sima.cfg.5 b/data/man/mpd_sima.cfg.5 deleted file mode 100644 index 4816acd..0000000 --- a/data/man/mpd_sima.cfg.5 +++ /dev/null @@ -1,637 +0,0 @@ -'\" t -.\" Title: mpd_sima.cfg -.\" Author: kaliko -.\" Generator: DocBook XSL Stylesheets v1.79.2 -.\" 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 diff --git a/data/man/mpd_sima.cfg.5.xml b/data/man/mpd_sima.cfg.5.xml deleted file mode 100644 index c8efb96..0000000 --- a/data/man/mpd_sima.cfg.5.xml +++ /dev/null @@ -1,604 +0,0 @@ - - - - - - -]> - - - - - &dhutils; - &dhsection; - - - &dhutils; - &dhpackage; will try to maintain some titles ahead in the queue - following different policies. This manual document the - configuration file for &dhpackage;. - - - DESCRIPTION - This manual page documents briefly &dhpackage; - configuration options available in user configuration file - (see ). - - - EXAMPLES - - - File tags queue mode (offline mode). - Here is an example of autoqueue using file tags only. - - - - - Album queue mode using last.fm recommendations (online mode). - Here is an example of album queue configuration using online recommendations system. - - - - - - - Configuration file - The configuration file consists of sections, led by a - [section] header and followed by - entries, with continuations in the style of RFC 822 (see section - 3.1.1, “LONG HEADER FIELDS”); is also accepted. Lines - beginning with '#' or ';' - are ignored and may be used to provide comments (Nota - Bene: inline comment are possible using '#'). - OPTIONS - The default values are used in the options lists below. - - MPD section - This section is meant to configure MPD access, MPD host - address / port and password if necessary. - - - - - - - - localhost - - Set MPD host. Use IP or FQDN. - - - - 6600 - - Set host port to access MPD to. - - - - 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 section - Configure logging. - - - - - - - - - File to log to, usually in dæmon mode.Default - (empty or unset) is to log to stdin/stdout. - - - - info - - Logging verbosity among - debug, - info, - warning, - error. - - - - - - Process daemonization - Configure process daemon. - - - - - - - - - whether to daemonize process or not. - - - - - - Where to store process ID. - - - - - - sima section - Core &dhutils; configuration. - - - - - - - - - - - - - - Lastfm, Random, Crop - - &dhpackage;'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: ,,. - is an utility plugin, it does not queue any tracks (cf. below). - 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. - - - - - 8 - - How far to look back in history to avoid to play - twice the same track/title (duration in - hours). - The is also used to give priority to not recently played artists. - - - - - 2 - - Threshold value triggering queue process. - - - - 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: . - - - - - true - - Prevent disabling queuing in repeat play mode. - - - - - true - - Prevent disabling queuing in single play mode. - - - - - - - - Crop section - crop plugin's configuration: - - - - - 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. - - - - - 10 - - - Plugin priority - - - - - - Random section - When no similar tracks are found, falling back to random queuing. - Random plugin's configuration: - - - - - 1 - - How many track(s) to add. - - - - 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. - - - - - - - - 50 - - - Plugin priority - - - - - - LastFm section - LastFM plugin's configuration. - - - - - - track - - Queue mode to use among - track, - top and - album (see for info about queue modes). - - - - 10 - - 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. - - - - 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. - - - - - false - - Prevent from queueing a track from the same album - (it often happens with OST). - Only relevant in "track" queue mode. - - - - 1 - - How many track(s) to add. Only relevant in - and - queue modes. This is actually an upper limit, - min(, - ) will be used. - - - - 1 - - How many album(s) to add. Only relevant in - queue modes. - - - - 0 - - How many track(s) to add from each selected albums. Only relevant in - queue modes. When set to 0 or lower the whole album is queued. - - - - - 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. - - - - - 100 - - - Plugin priority - - - - - - - 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). - - - - - track - - Queue mode to use among - track, - album (see for info about queue modes). - - - - false - - Prevent from queueing a track from the same album - (it often happens with OST). - Only relevant in "track" queue mode. - - - - 80 - - - Plugin priority - - - - - 1 - - How many track(s) to add. - - - - 1 - - How many album(s) to add. Only relevant in - queue mode. - - - - - 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 - , , , - and . - 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 "" and - "" - will end up looking for track tagged with genre - and date within 1982 through 1989. - Using an MPD filter to replace you can achieve - the same with the following setting: "" and - "" (provided your MPD server - was compiled with libpcre). - - - - - - track - - Queue mode to use among - track, - album (see for info about queue modes). - - - - false - - Prevent from queueing a track from the same album - (it often happens with OST). - Only relevant in "track" queue mode. - - - - - - You can use here any valid MPD filter as defined in MPD protocol documentation. - - - - - - - - - - - - - - - - - - - 80 - - - Plugin priority - - - - - 1 - - How many track(s) to add. - - - - 1 - - How many album(s) to add. Only relevant in - queue mode. - - - - - - QUEUE MODES - Different queue modes are available with some plugins (check for - presence in plugin config). - - &dhpackage; tries preferably to chose among unplayed artists or - at least not recently played artist. - - - - - Queue a similar track chosen at random from a similar artist. - - - - - - Queue a track from a similar artist, chosen among - "top tracks" according to last.fm data mining. - - - - - - 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. - &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. - - - - - - - - - diff --git a/data/man/seealso.xml b/data/man/seealso.xml deleted file mode 100644 index 79415a1..0000000 --- a/data/man/seealso.xml +++ /dev/null @@ -1,17 +0,0 @@ - - - SEE ALSO - - - mpc - 1 - , - mpd - 1 - - - /usr/share/doc/mpd-sima/ - - - diff --git a/data/man/tags.cfg b/data/man/tags.cfg deleted file mode 100644 index c34cf52..0000000 --- a/data/man/tags.cfg +++ /dev/null @@ -1,17 +0,0 @@ -[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 diff --git a/doc/Changelog b/doc/Changelog index b4b755d..7e772a7 100644 --- a/doc/Changelog +++ b/doc/Changelog @@ -1,6 +1,9 @@ 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 Thu, 18 Nov 2021 13:55:12 +0100 diff --git a/doc/source/conf.py b/doc/source/conf.py index 7102970..2b847f1 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -21,8 +21,7 @@ import os # 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 ------------------------------------------------ @@ -63,9 +62,9 @@ author = __author__ # 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. @@ -264,8 +263,12 @@ latex_documents = [ # 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. diff --git a/doc/source/index.rst b/doc/source/index.rst index 3a1cb25..72b39ee 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -17,7 +17,9 @@ your library is correctly tagged (see :ref:`metadata-convention`). 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 @@ -27,6 +29,7 @@ suggestions but there are other possibilities. # runs against a specific MPD server mpd-sima --host mpd.example.org + ##################### User's documentation ##################### @@ -38,6 +41,20 @@ 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 ########################## @@ -53,9 +70,9 @@ Development documentation dev/simadb -################### +################## Indices and tables -################### +################## * :ref:`genindex` * :ref:`modindex` diff --git a/doc/source/man/files.rst b/doc/source/man/files.rst new file mode 100644 index 0000000..34299af --- /dev/null +++ b/doc/source/man/files.rst @@ -0,0 +1,25 @@ +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`) diff --git a/doc/source/man/info.rst b/doc/source/man/info.rst new file mode 100644 index 0000000..dc57c74 --- /dev/null +++ b/doc/source/man/info.rst @@ -0,0 +1,6 @@ +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 diff --git a/doc/source/man/mpd-sima.1.rst b/doc/source/man/mpd-sima.1.rst new file mode 100644 index 0000000..5877bde --- /dev/null +++ b/doc/source/man/mpd-sima.1.rst @@ -0,0 +1,202 @@ +======== +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 diff --git a/doc/source/man/mpd_sima.cfg.5.rst b/doc/source/man/mpd_sima.cfg.5.rst new file mode 100644 index 0000000..2503f95 --- /dev/null +++ b/doc/source/man/mpd_sima.cfg.5.rst @@ -0,0 +1,396 @@ +============ +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 diff --git a/doc/source/man/seealso.rst b/doc/source/man/seealso.rst new file mode 100644 index 0000000..3977bec --- /dev/null +++ b/doc/source/man/seealso.rst @@ -0,0 +1,4 @@ +SEE ALSO +-------- + +:envvar:`mpc(1)`, :envvar:`mpd(1)` diff --git a/setup.py b/setup.py index 8c86cc2..6e99e6c 100755 --- a/setup.py +++ b/setup.py @@ -11,8 +11,6 @@ from sima.info import __version__ as VERSION, __author__ as AUTHOR 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)]), ] @@ -52,6 +50,13 @@ setup(name='MPD_sima', ] }, test_suite="tests", + command_options={ + 'build_sphinx': { + 'version': ('setup.py', VERSION), + 'release': ('setup.py', VERSION), + 'builder': ('setup.py', 'html,man'), + } + } ) # VIM MODLINE -- 2.39.2