all: man
simadb_cli: simadb_cli.1.xml
- $(XP) $(OPTIONS) $(XSL) $<
+ xmllint --xinclude --nowarning --noent $< | $(XP) $(OPTIONS) $(XSL) -
mpd_sima: mpd_sima.1.xml
xmllint --xinclude --nowarning --noent $< | $(XP) $(OPTIONS) $(XSL) -
clean_mpd_sima:
rm -rf mpd-sima.1 mpd_sima.1.html
-clean: clean_mpd_sima
+clean_simadb_cli:
+ rm -rf simadb_cli.1 simadb_cli.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="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>Persistant 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> (cf.
+ <citerefentry><refentrytitle>mpd_sima</refentrytitle>
+ <manvolnum>1</manvolnum></citerefentry>)</para>
+ </refsect1>
+<!-- vim:filetype=docbk
+-->
.\" Title: mpd-sima
.\" Author: Jack Kaliko <kaliko@azylum.org>
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\" Date: 01/25/2014
+.\" Date: 06/10/2014
.\" Manual: mpd-sima 0.12.0 User Manual
.\" Source: mpd-sima
.\" Language: English
.\"
-.TH "MPD\-SIMA" "1" "01/25/2014" "mpd-sima" "mpd-sima 0.12.0 User Manual"
+.TH "MPD\-SIMA" "1" "06/10/2014" "mpd-sima" "mpd-sima 0.12.0 User Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.PP
${XDG_CONFIG_HOME}/mpd_sima/mpd_sima\&.cfg
.RS 4
-The per\-user configuration file\&. Usually
-\fBXDG_CONFIG_HOME\fR
-is set to
-${HOME}/\&.config\&.
+Configuration file\&.
.RE
.PP
${XDG_DATA_HOME}/mpd_sima/sima\&.db
.RS 4
-SQLite database\&. Usually
+SQLite DB file\&.
+.RE
+.PP
+${XDG_DATA_HOME}/mpd_sima/WEB_SERVICE/
+.RS 4
+Persistant http cache\&.
+.RE
+.PP
+Usually
\fBXDG_DATA_HOME\fR
is set to
-${HOME}/\&.local/share\&.
-.RE
+${HOME}/\&.local/share
+and
+\fBXDG_CONFIG_HOME\fR
+to
+${HOME}/\&.config\&.
+.br
+You may override them using command line option
+\fB\-\-var_dir\fR
+(cf\&.
+\fBmpd_sima\fR(1))
.SH "ENVIRONMENT"
.PP
\fBMPD_HOST\fR, \fBMPD_PORT\fR
.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/mpd_sima\&.cfg\&. On Debian system please look in
+doc/examples/\&. On Debian system please look in
/usr/share/doc/mpd\-sima\&.
.RE
.PP
To change these defaults, use the configuration file
mpd_sima\&.cfg
.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,
.SH "SEE ALSO"
.PP
\fBmpc\fR(1),
-\fBmpd\fR(1),
-\fBmpd-sima.cfg\fR(5)
+\fBmpd\fR(1)
.PP
/usr/share/doc/mpd\-sima/
.SH "AUTHOR"
</varlistentry>
</variablelist>
</refsect1>
- <refsect1 id="files">
- <title>FILES</title>
- <variablelist>
- <varlistentry>
- <term><filename>${XDG_CONFIG_HOME}/mpd_sima/mpd_sima.cfg</filename></term>
- <!--
- <listitem>
- </listitem>
- <term><filename>${HOME}/.config/mpd_sima/mpd_sima.cfg</filename></term>
- -->
- <listitem>
- <para>The per-user configuration file. Usually <envar>XDG_CONFIG_HOME</envar> is set to <filename>${HOME}/.config</filename>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><filename>${XDG_DATA_HOME}/mpd_sima/sima.db</filename></term>
- <!--
- <listitem>
- </listitem>
- <term><filename>${HOME}/.local/share/mpd_sima/history.pkl</filename></term>
- -->
- <listitem>
- <para>SQLite database. Usually <envar>XDG_DATA_HOME</envar> is set to <filename>${HOME}/.local/share</filename>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
+ <xi:include href="files.xml" />
<refsect1 id="environment">
<title>ENVIRONMENT</title>
<variablelist>
<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/mpd_sima.cfg</filename>. On Debian
+ <filename>doc/examples/</filename>. On Debian
system please look in
<filename>/usr/share/doc/&dhpackage;</filename>.</para>
</listitem>
</listitem>
</varlistentry>
</variablelist>
- </refsect1>
- <xi:include href="feedback.xml" />
- <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>, <citerefentry>
- <refentrytitle>mpd-sima.cfg</refentrytitle>
- <manvolnum>5</manvolnum>
- </citerefentry>
- </para>
- <para>
- <filename>/usr/share/doc/mpd-sima/</filename>
+ <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: Jack Kaliko <kaliko@azylum.org>
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\" Date: 06/10/2014
+.\" Manual: mpd-sima 0.12.0 User Manual
+.\" Source: mpd-sima
+.\" Language: English
+.\"
+.TH "MPD_SIMA\&.CFG" "5" "06/10/2014" "mpd-sima" "mpd-sima 0.12.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 your play list 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 "Album queue mode\&."
+.PP
+Here is an example of album queue configuration\&.
+.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
+Defaut (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 "sima section"
+.PP
+This section allows you to tweak core mpd_sima\&.cfg configuration\&.
+.PP
+\fB[sima]\fR
+.RS 4
+.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)\&.
+.RE
+.PP
+\fBqueue_length=\fR\fI1\fR
+.RS 4
+This value triggers queue process if the play list length is less than specified queue_length\&.
+.RE
+.PP
+\fBuser_db=\fR\fIfalse\fR
+.RS 4
+Temporarily removed feature
+.RE
+.PP
+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]"\&.
+.br
+internal plugins will look for a section named after the lower\-cased name of the pluglin, ie\&. RandomFallBack\ \&\(-> randomfallback\&.
+.PP
+\fBinternal=\fR\fICrop, RandomFallBack, Lastfm\fR
+.RS 4
+\fBCrop\fR
+and
+\fBRandomFallback\fR
+are utilities plugins while
+\fBLastfm\fR
+is the actual queue plugin\&.
+.br
+
+Another queue plugin is available as a "techno preview", it relies on EchoNest web services, replace
+\fBLastFm\fR
+with
+\fBEchoNest\fR
+to try\&.
+.RE
+.PP
+\fBcontrib=\fR
+.RS 4
+.RE
+.SS "Crop section"
+.PP
+crop plugin\*(Aqs configuration:
+.PP
+\fB[crop]\fR
+.RS 4
+.RE
+.PP
+\fBconsume=\fR\fI0\fR
+.RS 4
+How many played tracks to keep in the play list\&. Allow to maintain a fixed length play list\&. Set to 0 to keep all played tracks\&.
+.RE
+.SS "RandomFallback section"
+.PP
+RandomFallback plugin\*(Aqs configuration:
+.PP
+\fB[randomfallback]\fR
+.RS 4
+.RE
+.PP
+\fBflavour=\fR\fIsensible\fR
+.RS 4
+When no similar tracks are found, falling back to random queuing\&. Different mode, aka random flavour, are available:
+\fIpure\fR,
+\fIsensible\fR,
+\fIgenre\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
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\fIgenre\fR, Not implemented yet\&.
+.RE
+.sp
+.RE
+.SS "LastFm section"
+.PP
+This section allows you to tweak 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
+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 allows to get 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\&.
+.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
+\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_CONFIG_HOME/mpd_sima/http/WEB_SERVICE\&.
+.br
+
+If set to "false", caching is still done but in memory\&.
+.RE
+.SH "QUEUE MODES"
+.PP
+mpd\-sima offers different queue modes\&. All of them pick up tracks from artists similar to the one currently played\&.
+.PP
+mpd\-sima tries preferably to chose among unplayed artists or at least not recently played artist\&. Concerning track and album queue modes titles are chosen purely at random among unplayed tracks\&.
+.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\&.
+.br
+
+It is planned to allow users to set the values of AlbumArtists tag triggering this behaviour\&. cf\&. feature request #2085 on the tracker\&.
+.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
+Persistant 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
+(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\%http://kaliko.me/id/\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
+\fBJack Kaliko\fR <\&kaliko@azylum\&.org\&>
+.RS 4
+Wrote this man page and is currently leading MPD_sima project\&.
+.RE
+.SH "COPYRIGHT"
+.br
+Copyright \(co 2009-2014 Jack 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 your play
+ list 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="album">
+ <title>Album queue mode.</title>
+ <para>Here is an example of album queue configuration.</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">
+ <para>Configure logging.</para>
+ <title>log section</title>
+ <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 />Defaut
+ (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="sima">
+ <title>sima section</title>
+ <para>This section allows you to tweak core &dhutils; configuration.</para>
+ <variablelist>
+ <varlistentry> <!-- SIMA -->
+ <term><option>[sima]</option></term>
+ <listitem><para></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).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- sima.queue_length -->
+ <term><option>queue_length=</option><replaceable>1</replaceable></term>
+ <listitem>
+ <para>This value triggers queue process if the play
+ list length is less than specified
+ queue_length.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- sima.user_db -->
+ <term><option>user_db=</option><replaceable>false</replaceable></term>
+ <listitem>
+ <para>Temporarily removed feature</para>
+ <!--<para>Look for user defined similarities in user data base.</para>-->
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <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]".<sbr />internal plugins
+ will look for a section named after the lower-cased name of the
+ pluglin, ie. RandomFallBack → randomfallback.
+ </para>
+ <variablelist>
+ <varlistentry> <!-- sima.internal -->
+ <term><option>internal=</option><replaceable>Crop, RandomFallBack, Lastfm</replaceable></term>
+ <listitem>
+ <para><option>Crop</option> and <option>RandomFallback</option>
+ are utilities plugins while <option>Lastfm</option> is the
+ actual queue plugin.<sbr /> Another queue plugin is available as
+ a "techno preview", it relies on EchoNest web services, replace
+ <option>LastFm</option> with <option>EchoNest</option> to try.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- sima.contrib -->
+ <term><option>contrib=</option><replaceable></replaceable></term>
+ <listitem>
+ <para></para>
+ </listitem>
+ </varlistentry>
+ </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>0</replaceable></term>
+ <listitem>
+ <para>How many played tracks to keep in the play list.
+ Allow to maintain a fixed length play list.
+ Set to 0 to keep all played tracks.
+ </para>
+ </listitem>
+ </varlistentry>
+ </refsect2>
+ <refsect2 id="randomfallback">
+ <title>RandomFallback section</title>
+ <para>RandomFallback plugin's configuration:</para>
+ <varlistentry> <!-- randomfallback -->
+ <term><option>[randomfallback]</option></term>
+ </varlistentry>
+ <varlistentry> <!-- randomfallback.flavour -->
+ <term><option>flavour=</option><replaceable>sensible</replaceable></term>
+ <listitem>
+ <para>When no similar tracks are found, falling back to
+ random queuing. Different mode, aka random flavour,
+ are available:
+ <replaceable>pure</replaceable>,
+ <replaceable>sensible</replaceable>,
+ <replaceable>genre</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>
+ <listitem>
+ <para><replaceable>genre</replaceable>, Not implemented yet.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </refsect2>
+ <refsect2 id="lastfm">
+ <title>LastFm section</title>
+ <para>This section allows you to tweak 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>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
+ allows to get 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.</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.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_CONFIG_HOME/mpd_sima/http/WEB_SERVICE</filename>.<sbr/>
+ If set to "false", caching is still done but in memory.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+ </refsect1>
+ <refsect1 id="queue_mode">
+ <title>QUEUE MODES</title>
+ <para>&dhpackage; offers different queue modes. All of them pick up
+ tracks from artists similar to the one currently played.</para>
+ <para>&dhpackage; tries preferably to chose among unplayed artists or
+ at least not recently played artist. Concerning track and album
+ queue modes titles are chosen purely at random among unplayed
+ tracks.</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.<sbr />
+ It is planned to allow users to set the values of
+ AlbumArtists tag triggering this behaviour. cf.
+ feature request #2085 on the tracker.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <xi:include href="files.xml" />
+ <xi:include href="feedback.xml" />
+ <xi:include href="seealso.xml" />
+</refentry>
--- /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
+'\" t
+.\" Title: simadb_cli
+.\" Author: Jack Kaliko <kaliko@azylum.org>
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\" Date: 06/10/2014
+.\" Manual: mpd-sima 0.12.0 User Manual
+.\" Source: mpd-sima
+.\" Language: English
+.\"
+.TH "SIMADB_CLI" "1" "06/10/2014" "mpd-sima" "mpd-sima 0.12.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"
+simadb_cli \- simadb_cli is a command line interface editor for the sima user DB\&.
+.SH "SYNOPSIS"
+.HP \w'\fBsimadb_cli\fR\ 'u
+\fBsimadb_cli\fR \fB\-\-add_similarity=\fR\fIsimilarity_string\fR [\fB\-\-check_names\fR] [\fB\-\-dbfile=\fR\fIdb_file\fR] [\fB\-\-reciprocal\fR] [\fB\-\-host=\fR\fImpd_host\fR] [\fB\-\-port=\fR\fImpd_port\fR]
+.HP \w'\fBsimadb_cli\fR\ 'u
+\fBsimadb_cli\fR \fB\-\-remove_artist=\fR\fIartist\fR [\fB\-\-dbfile=\fR\fIdb_file\fR] [\fB\-\-reciprocal\fR]
+.HP \w'\fBsimadb_cli\fR\ 'u
+\fBsimadb_cli\fR \fB\-\-remove_similarity=\fR\fI"main\ artist,similar\ artist"\fR [\fB\-\-dbfile=\fR\fIdb_file\fR] [\fB\-\-reciprocal\fR]
+.HP \w'\fBsimadb_cli\fR\ 'u
+\fBsimadb_cli\fR \fB\-\-purge_hist\fR [\fB\-\-dbfile=\fR\fIdb_file\fR]
+.HP \w'\fBsimadb_cli\fR\ 'u
+\fBsimadb_cli\fR \fB\-\-view_artist=\fR\fB\fI"artist\ name"\fR\fR [\fB\-\-dbfile=\fR\fIdb_file\fR]
+.HP \w'\fBsimadb_cli\fR\ 'u
+\fBsimadb_cli\fR \fB\-\-view_all\fR [\fB\-\-dbfile=\fR\fIdb_file\fR]
+.HP \w'\fBsimadb_cli\fR\ 'u
+\fBsimadb_cli\fR {\fB\-\-bl_curr_trk\fR | \fB\-\-bl_curr_art\fR | \fB\-\-bl_curr_alb\fR | \fB\-\-bl_art=\fR\fIartist_name\fR} [\fB\-\-dbfile=\fR\fIdb_file\fR] [\fB\-\-host=\fR\fImpd_host\fR] [\fB\-\-port=\fR\fImpd_port\fR]
+.HP \w'\fBsimadb_cli\fR\ 'u
+\fBsimadb_cli\fR \fB\-\-remove_bl=\fR\fIrow_id\fR [\fB\-\-dbfile=\fR\fIdb_file\fR]
+.HP \w'\fBsimadb_cli\fR\ 'u
+\fBsimadb_cli\fR \fB\-\-view_bl\fR [\fB\-\-dbfile=\fR\fIdb_file\fR]
+.HP \w'\fBsimadb_cli\fR\ 'u
+\fBsimadb_cli\fR {{\fB\-h\fR\ |\ \fB\-\-help\fR} | \fB\-\-version\fR}
+.SH "DESCRIPTION"
+.PP
+This manual page documents briefly the
+\fBsimadb_cli\fR
+commands\&.
+.PP
+simadb_cli is a command line interface to get and edit users similarities and blacklist database used with MPD_sima\&. The default database file (see
+the section called \(lqFILES\(rq) can be overridden if you want\&.
+.PP
+Consider reading
+the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq
+to understand the structure and relation of similarities within the database\&.
+.SH "EXAMPLE"
+.SS "Similarity edition"
+.PP
+Here follows some simple examples on how to deal with similarity database\&.
+.PP
+Pay attention, the following examples set one\-way similarities in the DB! Read more about it in
+the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq\&.
+.PP
+\fIAdding a similarity between two artists\&.\fR
+In the following example "Pelican" will point to "Russian Circles" with a match score of 88% (ie\&. "Russian Circles" 88% similar to Pelican, not reciprocal), it will also check against MPD the presence of both artists in the music library\&.
+.PP
+\fBsimadb_cli \-\-add "Pelican,Russian Circles:80" \-\-check_names\fR
+.PP
+Similarity string use comma "," as artists separator and semi colon ":" for artist/similarity score separator, cf\&.
+the section called \(lqSIMILARITY FORMAT\(rq\&.
+.PP
+\fIAdding a similarity between multiple artists\&.\fR
+In the following example "Rage Against The Machine" will point to "Tool" and "Audioslave" as similar artists and controls artists names are actually in MPD music library\&.
+.PP
+\fBsimadb_cli \-\-add "Rage Against The Machine,Tool:70,Audiosalve:80" \-\-check_names\fR
+.PP
+\fIViewing similarit(y|ies) for an artist\&.\fR
+In the following example we are looking for entries for "Rage Against The Machine"
+.PP
+\fBsimadb_cli \-\-view_artist "Rage Against The Machine"\fR
+.SS "Black list edition"
+.PP
+\fIAdding to black list\&.\fR
+You can add a single track, an album or an artist to the black list\&. The element to black list is chosen from the currently playing track\&. Use
+\fB\-\-bl_curr_trk\fR
+to prevent simadb_cli to queue this track,
+\fB\-\-bl_curr_alb\fR
+or
+\fB\-\-bl_curr_art\fR
+respectively for the album and the artist\&.
+.PP
+Remember you need access to your MPD server to retrieve information to black list\&. Defaults are localhost:6600 or found in environment variables but you may set it up from command line:
+.PP
+\fBsimadb_cli \-\-bl_curr_art \-S mympd\&.example\&.org\fR
+.PP
+\fITo black list a specific artist\fR
+(not currently playing) you can use
+\fB\-\-bl_ar="Artist name to black list"\fR\&.
+.SH "OPTIONS"
+.PP
+The program follows the usual GNU command line syntax, with long options starting with two dashes ("\-")\&. 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\-a \fR\fB\fIsimilarity_string\fR\fR, \fB\-\-add_similarity=\fR\fB\fIsimilarity_string\fR\fR
+.RS 4
+Add similarity to the database\&.
+.br
+For more details about the
+\fIsimilarity_string\fR
+see
+the section called \(lqSIMILARITY FORMAT\(rq\&.
+.RE
+.PP
+\fB\-c\fR, \fB\-\-check_names\fR
+.RS 4
+Use with
+\fB\-\-add_similarity\fR
+in order to check artists names used in
+\fIsimilarity_string\fR\&. simadb_cli will control presence of artists names in MPD library\&. Default is to look for MPD server on localhost:6600 or environment variables
+\fBMPD_HOST\fR
+and
+\fBMPD_PORT\fR
+if set\&.
+.br
+You can as well give simadb_cli host/port on the command line using respectively
+\fB\-S\fR
+and
+\fB\-P\fR\&.
+.RE
+.PP
+\fB\-\-bl_art=\fR\fB\fIartist_name\fR\fR
+.RS 4
+Use to black list
+\fIartist_name\fR\&. simadb_cli is checking
+\fIartist_name\fR
+is actually in MPD music library (cf
+\fB\-S\fR
+and
+\fB\-P\fR
+options to set MPD host/address if necessary)\&.
+.sp
+If
+\fIartist_name\fR
+is not found the script print out a list of matching artists\&.
+.RE
+.PP
+\fB\-\-bl_curr_trk\fR | \fB\-\-bl_curr_art\fR | \fB\-\-bl_curr_alb\fR
+.RS 4
+Use to black list the currently playing track|artist|album\&. You need access to your MPD server, use
+\fB\-S\fR
+and
+\fB\-P\fR
+to set MPD host/address if necessary\&.
+.RE
+.PP
+\fB\-d \fR\fB\fIdb_file\fR\fR, \fB\-\-dbfile=\fR\fB\fIdb_file\fR\fR
+.RS 4
+Use the specific file
+\fIdb_file\fR
+as database\&.
+.br
+Default is too use
+\fBXDG_DATA_HOME\fR
+(see
+the section called \(lqFILES\(rq)\&.
+.RE
+.PP
+\fB\-\-purge_hist\fR
+.RS 4
+Purge history, you may supply an alternative DB file with \-\-dbfile option\&.
+.RE
+.PP
+\fB\-r\fR, \fB\-\-reciprocal\fR
+.RS 4
+Use with an editing options in order to edit reciprocal similarity as well\&.
+\fB\-\-add_similarity\fR
+and
+\fB\-\-remove_{artist|similarity}\fR
+are supporting reciprocal edition\&.
+.sp
+\fIN\&.B\fR: this option has to appear after the editing option on the command line\&.
+.sp
+See
+the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq
+for further information about reciprocity notion\&.
+.RE
+.PP
+\fB\-\-remove_artist=\fR\fB\fIartist\fR\fR
+.RS 4
+Use to remove an artist entry (as main artist) with its associated similarities\&. To remove artist where it appears as a similar artist use the
+\fB\-\-reciprocal\fR
+option\&.
+.RE
+.PP
+\fB\-\-remove_bl=\fR\fB\fIrow_id\fR\fR
+.RS 4
+Use to remove a black list entry\&. To get the row_id to suppress use
+\fB\-\-view_bl\fR
+option\&.
+.RE
+.PP
+\fB\-\-remove_similarity=\fR\fB\fI"main artist,similar artist"\fR\fR
+.RS 4
+Use to remove a single similarity between a main artist and an associated similarity\&. Give the main artist first, use comma (",") to separate it from similar artist\&.
+.br
+Use of
+\fB\-\-reciprocal\fR
+is possible here, see
+the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq\&.
+.sp
+This option is useful in case you want to remove only a specific similarity between two artists, to remove completely an artist use
+\fB\-\-remove_artist\fR
+instead\&.
+.RE
+.PP
+\fB\-v \fR\fB\fI"artist name"\fR\fR, \fB\-\-view_artist=\fR\fB\fI"artist name"\fR\fR
+.RS 4
+Get entries for
+\fI"artist name"\fR
+in the data base (print to stdout)\&.
+.RE
+.PP
+\fB\-\-view_bl\fR
+.RS 4
+Get all entries in the black list\&.
+.RE
+.PP
+\fB\-\-view_all\fR
+.RS 4
+Get all entries in the data base (print to stdout)\&.
+.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\&.
+.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\&.
+.RE
+.SH "FILES"
+.PP
+${XDG_DATA_HOME}/mpd_sima/sima\&.db
+.RS 4
+SQLite DB file\&. Usually
+\fBXDG_DATA_HOME\fR
+is set to
+${HOME}/\&.local/share\&.
+.RE
+.SH "SIMILARITY FORMAT"
+.PP
+The
+\fIsimilarity_string\fR
+has to be formatted following a special pattern in order for simadb_cli to extract similarity relations between artists names\&. Usually a similarity entry is defined as a main artist, lets say
+\fImain_art\fR, followed by a list of similar artists which you want to be related to that
+\fImain_art\fR, each artist of that list with a specific similarity value, a match score, quantifying the similarity relation with the
+\fImain_art\fR\&. The match score value is an integer in [0 ,100] with 100 corresponding to a perfect match\&.
+.PP
+\fIsimilarity_string\fR
+is then to be formatted as follow:
+.PP
+\fBmain_art,first artist:<score>,second artist:<score>\fR
+.PP
+Each artist group are separated with commas (",") and inside each group the artist name and the match score is colon (":") separated\&. Obviously the first artist group, as the main artist, does not have a match score\&.
+.PP
+Lets see how it works with an example\&. I consider "Led Zeppelin" to be similar to "Tool" with a match score of 25, I also want to have "Audioslave" related to "Led Zeppelin" with a score of 20\&. Then the
+\fIsimilarity_string\fR
+will be the following:
+.PP
+\fBLed Zeppelin,Tool:25,Audiosalve:20\fR
+.PP
+See
+the section called \(lqA WORD ABOUT SIMA DATA BASE\(rq
+for more details about how similarities are handled
+.SH "A WORD ABOUT SIMA DATA BASE"
+.PP
+The similarity database is defined from the point of view of a
+\fImain artist\fR
+which is declared related to a list of
+\fIsimilar artists\fR\&. That means when you define
+\fImain_art\fR
+to be similar to
+\fIsim_art A\fR
+and
+\fIsim_art B\fR
+the reciprocal won\*(Aqt be true,
+\fIsim_art A\fR
+and
+\fIsim_art B\fR
+are not similar to
+\fImain_art\fR\&. At least this is the default behavior when you edit entries with simadb_cli, this is also the way last\&.fm is working concerning similar artists\&. This documentation is using that particular terminology to specify which kind of artist we are dealing with : "main artist" or "similar artist"\&.
+.br
+The
+\fB\-\-reciprocal\fR
+option allows one to add reciprocal relation where
+\fIsim_art A\fR
+and
+\fIsim_art B\fR
+become respectively the
+\fImain_art\fR\&. Using
+\fB\-\-reciprocal\fR
+you will then edit two more entries in the database\&. To summarize here is what you\*(Aqll end up with in your data base adding similarity with this string
+\fBmain_art,sim_art A:34,sim_art B:45\fR\&.
+.PP
+\fBsimadb_cli \-\-reciprocal \-\-add_similarity=main_art,sim_art A:34,sim_art B:45\fR
+.PP
+main_art similar to sim_art A:34 and sim_art B:45
+.br
+sim_art A similar to main_art:34
+.br
+sim_art B similar to main_art:45
+.PP
+Without the reciprocal option you would have add only the first similarity\&. Usually using the reciprocal option is the desired behavior, at least what users have in mind when thinking of similarity relation between to artists but keep in mind that it may lead to have MPD_sima more sensible to loop over the same two artist (ASSERTION TO BE CONFIRMED)\&.
+.SH "FEEDBACK/BUGS"
+.PP
+The maintainer would be more than happy to ear from you, don\*(Aqt hesitate to send feedback,
+\m[blue]\fB\%http://kaliko.me/id/\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
+\fBJack Kaliko\fR <\&kaliko@azylum\&.org\&>
+.RS 4
+Wrote this man page and is currently leading MPD_sima project\&.
+.RE
+.SH "COPYRIGHT"
+.br
+Copyright \(co 2009-2014 Jack 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 "simadb_cli">
+
+]>
+
+<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; is a command line interface editor for the sima user DB.</refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <cmdsynopsis><!-- REGULAR EDIT (ADD) OPTIONS -->
+ <command>&dhutils;</command>
+ <arg choice="plain"><option>--add_similarity=</option><replaceable class="option">similarity_string</replaceable></arg>
+ <arg choice="opt">
+ <option>--check_names</option>
+ </arg>
+ <arg choice="opt">
+ <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
+ </arg>
+ <arg choice="opt">
+ <option>--reciprocal</option>
+ </arg>
+ <arg choice="opt">
+ <option>--host=</option><replaceable class="option">mpd_host</replaceable>
+ </arg>
+ <arg choice="opt">
+ <option>--port=</option><replaceable class="option">mpd_port</replaceable>
+ </arg>
+ </cmdsynopsis>
+ <cmdsynopsis><!-- EDIT (RM ARTIST) OPTIONS -->
+ <command>&dhutils;</command>
+ <arg choice="plain"><option>--remove_artist=</option><replaceable class="parameter">artist</replaceable></arg>
+ <arg choice="opt">
+ <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
+ </arg>
+ <arg choice="opt">
+ <option>--reciprocal</option>
+ </arg>
+ </cmdsynopsis>
+ <cmdsynopsis><!-- EDIT (RM SIM) OPTIONS -->
+ <command>&dhutils;</command>
+ <arg choice="plain"><option>--remove_similarity=</option><replaceable class="parameter">"main artist,similar artist"</replaceable></arg>
+ <arg choice="opt">
+ <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
+ </arg>
+ <arg choice="opt">
+ <option>--reciprocal</option>
+ </arg>
+ </cmdsynopsis>
+ <cmdsynopsis><!-- EDIT (PURGE HIST) OPTIONS -->
+ <command>&dhutils;</command>
+ <arg choice="plain"><option>--purge_hist</option></arg>
+ <arg choice="opt">
+ <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
+ </arg>
+ </cmdsynopsis>
+ <cmdsynopsis><!-- REGULAR VIEW OPTIONS -->
+ <command>&dhutils;</command>
+ <arg choice="plain"><option>--view_artist=<replaceable class="parameter">"artist name"</replaceable></option></arg>
+ <arg choice="opt">
+ <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
+ </arg>
+ </cmdsynopsis>
+ <cmdsynopsis><!-- VIEW ALL ENTRIES OPTIONS -->
+ <command>&dhutils;</command>
+ <arg choice="plain"><option>--view_all</option></arg>
+ <arg choice="opt">
+ <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
+ </arg>
+ </cmdsynopsis>
+ <cmdsynopsis><!-- EDIT (BLACK LIST) OPTIONS -->
+ <command>&dhutils;</command>
+ <group choice="req">
+ <arg choice="plain"><option>--bl_curr_trk</option></arg>
+ <arg choice="plain"><option>--bl_curr_art</option></arg>
+ <arg choice="plain"><option>--bl_curr_alb</option></arg>
+ <arg choice="plain"><option>--bl_art=</option><replaceable class="parameter">artist_name</replaceable></arg>
+ </group>
+ <arg choice="opt">
+ <arg choice="plain"><option>--dbfile=</option><replaceable class="parameter">db_file</replaceable></arg>
+ </arg>
+ <arg choice="opt">
+ <arg choice="plain"><option>--host=</option><replaceable class="option">mpd_host</replaceable></arg>
+ </arg>
+ <arg choice="opt">
+ <arg choice="plain"><option>--port=</option><replaceable class="option">mpd_port</replaceable></arg>
+ </arg>
+ </cmdsynopsis>
+ <cmdsynopsis><!-- EDIT (RM BL) OPTIONS -->
+ <command>&dhutils;</command>
+ <arg choice="plain"><option>--remove_bl=</option><replaceable class="parameter">row_id</replaceable></arg>
+ <arg choice="opt">
+ <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
+ </arg>
+ </cmdsynopsis>
+ <cmdsynopsis><!-- VIEW BL OPTIONS -->
+ <command>&dhutils;</command>
+ <arg choice="plain"><option>--view_bl</option></arg>
+ <arg choice="opt">
+ <option>--dbfile=</option><replaceable class="option">db_file</replaceable>
+ </arg>
+ </cmdsynopsis>
+ <cmdsynopsis><!-- HELP/VERSION -->
+ <command>&dhutils;</command>
+ <!-- Normally the help and version options make the programs stop
+ right after outputting the requested information. -->
+ <group choice="req">
+ <arg choice="plain">
+ <group choice="req">
+ <arg choice="plain"><option>-h</option></arg>
+ <arg choice="plain"><option>--help</option></arg>
+ </group>
+ </arg>
+ <arg choice="plain"><option>--version</option></arg>
+ </group>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+ <refsect1 id="description">
+ <title>DESCRIPTION</title>
+ <para>This manual page documents briefly the
+ <command>&dhutils;</command> commands.</para>
+ <para>simadb_cli is a command line interface to get and edit users
+ similarities and blacklist database used with MPD_sima. The default
+ database file (see <xref linkend="files"/>) can be overridden if
+ you want.</para>
+ <para>Consider reading <xref linkend="simadb" /> to understand the
+ structure and relation of similarities within the database.</para>
+ </refsect1>
+ <refsect1 id="example">
+ <title>EXAMPLE</title>
+ <refsect2 id="similarity">
+ <title>Similarity edition</title>
+ <para>Here follows some simple examples on how to deal with similarity database.</para>
+ <para>Pay attention, the following examples set one-way similarities in the DB! Read more about it in <xref linkend="simadb" />.</para>
+ <para><emphasis>Adding a similarity between two artists.</emphasis> In the following example "Pelican" will point
+ to "Russian Circles" with a match score of 88% (ie. "Russian Circles"
+ 88% similar to Pelican, not reciprocal), it will also check against MPD
+ the presence of both artists in the music library.</para>
+ <para><command>&dhutils; --add "Pelican,Russian Circles:80" --check_names</command></para>
+ <para>Similarity string use comma "," as artists separator and semi colon ":" for
+ artist/similarity score separator, cf. <xref linkend="simiformat"/>.</para>
+ <para><emphasis>Adding a similarity between multiple artists.</emphasis> In the following example "Rage
+ Against The Machine" will point to "Tool" and "Audioslave" as similar
+ artists and controls artists names are actually in MPD music library.</para>
+ <para><command>&dhutils; --add "Rage Against The Machine,Tool:70,Audiosalve:80" --check_names</command></para>
+ <para><emphasis>Viewing similarit(y|ies) for an artist.</emphasis> In the
+ following example we are looking for entries for "Rage Against The Machine"</para>
+ <para><command>&dhutils; --view_artist "Rage Against The Machine"</command></para>
+ </refsect2>
+ <refsect2 id="blacklist">
+ <title>Black list edition</title>
+ <para><emphasis>Adding to black list.</emphasis> You can add a single
+ track, an album or an artist to the black list. The element to
+ black list is chosen from the currently playing track. Use
+ <option>--bl_curr_trk</option> to prevent &dhutils; to queue this
+ track, <option>--bl_curr_alb</option> or <option>--bl_curr_art</option> respectively for the album and the
+ artist.
+ </para>
+ <para>Remember you need access to your MPD server to retrieve
+ information to black list. Defaults are localhost:6600 or found in
+ environment variables but you may set it up from command
+ line:
+ </para>
+ <para><command>&dhutils; --bl_curr_art -S mympd.example.org</command></para>
+ <para>
+ <emphasis>To black list a specific artist</emphasis> (not
+ currently playing) you can use <option>--bl_ar="Artist name to black list"</option>.
+ </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> <!-- add similarity -->
+ <term><option>-a <replaceable class="parameter">similarity_string</replaceable></option></term>
+ <term><option>--add_similarity=<replaceable class="parameter">similarity_string</replaceable></option></term>
+ <listitem>
+ <para>Add similarity to the database.<sbr />For more details about the <replaceable class="option">similarity_string</replaceable> see <xref linkend="simiformat"/>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- check_names -->
+ <term><option>-c</option></term>
+ <term><option>--check_names</option></term>
+ <listitem>
+ <para>Use with <option>--add_similarity</option> in order to check artists names used in <replaceable class="parameter">similarity_string</replaceable>. &dhutils; will control presence of artists names in MPD library. Default is to look for MPD server on localhost:6600 or environment variables <envar>MPD_HOST</envar> and <envar>MPD_PORT</envar> if set.<sbr />You can as well give &dhutils; host/port on the command line using respectively <option>-S</option> and <option>-P</option>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- black list artist -->
+ <term><option>--bl_art=<replaceable class="parameter">artist_name</replaceable></option></term>
+ <listitem>
+ <para>Use to black list <replaceable class="parameter">artist_name</replaceable>. &dhutils; is checking <replaceable class="parameter">artist_name</replaceable> is actually in MPD music library (cf <option>-S</option> and <option>-P</option> options to set MPD host/address if necessary).</para>
+ <para>If <replaceable class="parameter">artist_name</replaceable> is not found the script print out a list of matching artists.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- black list -->
+ <term><option>--bl_curr_trk</option> | <option>--bl_curr_art</option> | <option>--bl_curr_alb</option></term>
+ <listitem>
+ <para>Use to black list the currently playing track|artist|album. You need access to your MPD server, use <option>-S</option> and <option>-P</option> to set MPD host/address if necessary.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- dbfile -->
+ <term><option>-d <replaceable class="parameter">db_file</replaceable></option></term>
+ <term><option>--dbfile=<replaceable class="parameter">db_file</replaceable></option></term>
+ <listitem>
+ <para>Use the specific file <replaceable>db_file</replaceable> as database.<sbr />Default is too use <envar>XDG_DATA_HOME</envar> (see <xref linkend="files"/>).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- purge history -->
+ <term><option>--purge_hist</option></term>
+ <listitem>
+ <para>Purge history, you may supply an alternative DB file with --dbfile option.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- reciprocal -->
+ <term><option>-r</option></term>
+ <term><option>--reciprocal</option></term>
+ <listitem>
+ <para>Use with an editing options in order to edit reciprocal similarity as well. <option>--add_similarity</option> and <option>--remove_{artist|similarity}</option> are supporting reciprocal edition.</para>
+ <para><emphasis>N.B</emphasis>: this option has to appear after the editing option on the command line.</para>
+ <para>See <xref linkend="simadb"/> for further information about reciprocity notion.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- remove artist -->
+ <term><option>--remove_artist=<replaceable class="parameter">artist</replaceable></option></term>
+ <listitem>
+ <para>Use to remove an artist entry (as main artist) with its associated similarities. To remove artist where it appears as a similar artist use the <option>--reciprocal</option> option.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- remove bl id -->
+ <term><option>--remove_bl=<replaceable class="parameter">row_id</replaceable></option></term>
+ <listitem>
+ <para>Use to remove a black list entry. To get the row_id to suppress use <option>--view_bl</option> option.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- remove similarity -->
+ <term><option>--remove_similarity=<replaceable class="parameter">"main artist,similar artist"</replaceable></option></term>
+ <listitem>
+ <para>Use to remove a single similarity between a main artist and an associated similarity. Give the main artist first, use comma (",") to separate it from similar artist.<sbr />Use of <option>--reciprocal</option> is possible here, see <xref linkend="simadb" />.</para>
+ <para>This option is useful in case you want to remove only a specific similarity between two artists, to remove completely an artist use <option>--remove_artist</option> instead.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- view artist -->
+ <term><option>-v <replaceable class="parameter">"artist name"</replaceable></option></term>
+ <term><option>--view_artist=<replaceable class="parameter">"artist name"</replaceable></option></term>
+ <listitem>
+ <para>Get entries for <replaceable class="parameter">"artist name"</replaceable> in the data base (print to stdout).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- view bl -->
+ <term><option>--view_bl</option></term>
+ <listitem>
+ <para>Get all entries in the black list.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry> <!-- view all -->
+ <term><option>--view_all</option></term>
+ <listitem>
+ <para>Get all entries in the data base (print to stdout).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <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>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <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>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1 id="files">
+ <title>FILES</title>
+ <variablelist>
+ <varlistentry>
+ <term><filename>${XDG_DATA_HOME}/mpd_sima/sima.db</filename></term>
+ <listitem>
+ <para>SQLite DB file. Usually <envar>XDG_DATA_HOME</envar> is set to <filename>${HOME}/.local/share</filename>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1 id="simiformat">
+ <title>SIMILARITY FORMAT</title>
+ <para>The <replaceable class="parameter">similarity_string</replaceable> has to be formatted following a special pattern in order for simadb_cli to extract similarity relations between artists names. Usually a similarity entry is defined as a main artist, lets say <emphasis>main_art</emphasis>, followed by a list of similar artists which you want to be related to that <emphasis>main_art</emphasis>, each artist of that list with a specific similarity value, a match score, quantifying the similarity relation with the <emphasis>main_art</emphasis>. The match score value is an integer in [0 ,100] with 100 corresponding to a perfect match.</para>
+ <para><replaceable class="parameter">similarity_string</replaceable> is then to be formatted as follow:</para>
+ <para><command>main_art,first artist:<score>,second artist:<score></command></para>
+ <para>Each artist group are separated with commas (",") and inside each group the artist name and the match score is colon (":") separated. Obviously the first artist group, as the main artist, does not have a match score.</para>
+ <para>Lets see how it works with an example. I consider "Led Zeppelin" to be similar to "Tool" with a match score of 25, I also want to have "Audioslave" related to "Led Zeppelin" with a score of 20. Then the <replaceable class="parameter">similarity_string</replaceable> will be the following:</para>
+ <para><command>Led Zeppelin,Tool:25,Audiosalve:20</command></para>
+ <para>See <xref linkend="simadb" /> for more details about how similarities are handled</para>
+ </refsect1>
+ <refsect1 id="simadb">
+ <title>A WORD ABOUT SIMA DATA BASE</title>
+ <para>The similarity database is defined from the point of view of a <emphasis>main artist</emphasis> which is declared related to a list of <emphasis>similar artists</emphasis>. That means when you define <emphasis>main_art</emphasis> to be similar to <emphasis>sim_art A</emphasis> and <emphasis>sim_art B</emphasis> the reciprocal won't be true, <emphasis>sim_art A</emphasis> and <emphasis>sim_art B</emphasis> are not similar to <emphasis>main_art</emphasis>. At least this is the default behavior when you edit entries with simadb_cli, this is also the way last.fm is working concerning similar artists. This documentation is using that particular terminology to specify which kind of artist we are dealing with : "main artist" or "similar artist".<sbr />The <option>--reciprocal</option> option allows one to add reciprocal relation where <emphasis>sim_art A</emphasis> and <emphasis>sim_art B</emphasis> become respectively the <emphasis>main_art</emphasis>. Using <option>--reciprocal</option> you will then edit two more entries in the database. To summarize here is what you'll end up with in your data base adding similarity with this string <command>main_art,sim_art A:34,sim_art B:45</command>.</para>
+ <para><command>simadb_cli --reciprocal --add_similarity=main_art,sim_art A:34,sim_art B:45</command></para>
+ <para>main_art similar to sim_art A:34 and sim_art B:45<sbr />sim_art A similar to main_art:34<sbr />sim_art B similar to main_art:45</para>
+ <para>Without the reciprocal option you would have add only the first similarity. Usually using the reciprocal option is the desired behavior, at least what users have in mind when thinking of similarity relation between to artists but keep in mind that it may lead to have MPD_sima more sensible to loop over the same two artist (ASSERTION TO BE CONFIRMED).</para>
+ </refsect1>
+ <!--
+ <refsect1 id="diagnostics">
+ <title>DIAGNOSTICS</title>
+ <para>The following diagnostics may be issued
+ on <filename class="devicefile">stderr</filename>:</para>
+ <variablelist>
+ <varlistentry>
+ <term><errortext>Bad configuration file. Exiting.</errortext></term>
+ <listitem>
+ <para>The configuration file seems to contain a broken configuration
+ line. Use the <option>-''-verbose</option> option, to get more info.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para><command>&dhpackage;</command> provides some return codes, that can
+ be used in scripts:</para>
+ <segmentedlist>
+ <segtitle>Code</segtitle>
+ <segtitle>Diagnostic</segtitle>
+ <seglistitem>
+ <seg><errorcode>0</errorcode></seg>
+ <seg>Program exited successfully.</seg>
+ </seglistitem>
+ <seglistitem>
+ <seg><errorcode>1</errorcode></seg>
+ <seg>The configuration file seems to be broken.</seg>
+ </seglistitem>
+ </segmentedlist>
+ </refsect1>
+ -->
+ <xi:include href="feedback.xml" />
+ <xi:include href="seealso.xml" />
+</refentry>
home / dev / repositories / mpd-sima.git / commitdiff