From: kaliko <kaliko@azylum.org>
Date: Sun, 8 Feb 2015 15:30:37 +0000 (+0100)
Subject: Update manuals
X-Git-Tag: 0.14.0~21
X-Git-Url: https://git.kaliko.me/?a=commitdiff_plain;h=0bca6ee3dd5a5426c985e85e0e50fac77e4ec8f1;p=mpd-sima.git

Update manuals
---

diff --git a/data/man/files.xml b/data/man/files.xml
index 381b223..806d5de 100644
--- a/data/man/files.xml
+++ b/data/man/files.xml
@@ -25,7 +25,7 @@
             <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>
+            <citerefentry><refentrytitle>mpd-sima</refentrytitle>
                 <manvolnum>1</manvolnum></citerefentry>)</para>
     </refsect1>
 <!-- vim:filetype=docbk
diff --git a/data/man/mpd-sima.1 b/data/man/mpd-sima.1
index 3739b64..2aa20a9 100644
--- a/data/man/mpd-sima.1
+++ b/data/man/mpd-sima.1
@@ -2,12 +2,12 @@
 .\"     Title: mpd-sima
 .\"    Author: Jack Kaliko <kaliko@azylum.org>
 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 01/28/2015
-.\"    Manual: mpd-sima 0.13.1 User Manual
+.\"      Date: 02/08/2015
+.\"    Manual: mpd-sima 0.14.0 User Manual
 .\"    Source: mpd-sima
 .\"  Language: English
 .\"
-.TH "MPD\-SIMA" "1" "01/28/2015" "mpd-sima" "mpd-sima 0.13.1 User Manual"
+.TH "MPD\-SIMA" "1" "02/08/2015" "mpd-sima" "mpd-sima 0.14.0 User Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -225,7 +225,7 @@ ${HOME}/\&.config\&.
 You may override them using command line option
 \fB\-\-var_dir\fR
 (cf\&.
-\fBmpd_sima\fR(1))
+\fBmpd-sima\fR(1))
 .SH "ENVIRONMENT"
 .PP
 \fBMPD_HOST\fR, \fBMPD_PORT\fR
diff --git a/data/man/mpd_sima.cfg.5 b/data/man/mpd_sima.cfg.5
index aad901f..faf4003 100644
--- a/data/man/mpd_sima.cfg.5
+++ b/data/man/mpd_sima.cfg.5
@@ -2,12 +2,12 @@
 .\"     Title: mpd_sima.cfg
 .\"    Author: Jack Kaliko <kaliko@azylum.org>
 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 01/28/2015
-.\"    Manual: mpd-sima 0.13.1 User Manual
+.\"      Date: 02/08/2015
+.\"    Manual: mpd-sima 0.14.0 User Manual
 .\"    Source: mpd-sima
 .\"  Language: English
 .\"
-.TH "MPD_SIMA\&.CFG" "5" "01/28/2015" "mpd-sima" "mpd-sima 0.13.1 User Manual"
+.TH "MPD_SIMA\&.CFG" "5" "02/08/2015" "mpd-sima" "mpd-sima 0.14.0 User Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -152,28 +152,12 @@ Core mpd_sima\&.cfg configuration\&.
 .RS 4
 .RE
 .PP
-\fBhistory_duration=\fR\fI8\fR
+\fBcontrib=\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
+\fBinternal=\fR\fILastfm, Random, Crop\fR
 .RS 4
-This value triggers queue process if the queue length is less than specified queue_length\&.
-.RE
-.PP
-\fBmusicbrainzid=\fR\fItrue\fR
-.RS 4
-Use MusicBrainzIdentifier to search music (mainly for artists)\&. Consider using these metadata as it enhances a lot artist/album/tracks identification\&.
-.br
-
-Default is True, switch to False if you don\*(Aqt have MusicBrainzIdentifier set for at least 80% of you music library\&.
-.br
-
-Use Picard to tag your file:
-\m[blue]\fB\%https://picard.musicbrainz.org/\fR\m[]\&.
-.RE
-.PP
 mpd\-sima\*(Aqs plugin management for internal source plugin and contrib (ie\&. external plugins)\&.
 .br
 
@@ -183,28 +167,50 @@ Plugins list is a comma separated string list\&.
 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
-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\&.
+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
 
-Another queue plugin is available as a "techno preview", it relies on EchoNest web services, replace
-\fBLastFm\fR
-with
+.sp
+You can add here as many plugins you want, currently shipping
+\fBLastfm\fR
+and
 \fBEchoNest\fR
-to try\&.
+only\&.
+.br
+
+The priority may be used to order them\&.
 .RE
 .PP
-\fBcontrib=\fR
+\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
 .SS "Crop section"
 .PP
@@ -218,11 +224,16 @@ crop plugin\*(Aqs configuration:
 .RS 4
 How many played tracks to keep in the queue\&. Allows you to maintain a fixed length queue\&. Set to 0 to keep all played tracks\&.
 .RE
-.SS "RandomFallback section"
 .PP
-RandomFallback plugin\*(Aqs configuration:
+\fBpriority=\fR\fI10\fR
+.RS 4
+Plugin priority
+.RE
+.SS "Random section"
 .PP
-\fB[randomfallback]\fR
+Random plugin\*(Aqs configuration:
+.PP
+\fB[random]\fR
 .RS 4
 .RE
 .PP
@@ -267,6 +278,11 @@ When no similar tracks are found, falling back to random queuing\&. Different mo
 .RE
 .sp
 .RE
+.PP
+\fBpriority=\fR\fI50\fR
+.RS 4
+Plugin priority
+.RE
 .SS "LastFm section"
 .PP
 LastFM plugin\*(Aqs configuration\&.
@@ -337,6 +353,48 @@ $XDG_CONFIG_HOME/mpd_sima/http/WEB_SERVICE\&.
 
 If set to "false", caching is still done but in memory\&.
 .RE
+.PP
+\fBpriority=\fR\fI100\fR
+.RS 4
+Plugin priority
+.RE
+.SS "EchoNest section"
+.PP
+EchoNest plugin\*(Aqs configuration\&.
+.PP
+Options for EchoNest are exactly the same as LastFm (same default as well), except for cache plugin which is always needed to limit number of requests to the service\&.
+.PP
+\fB[echonest]\fR
+.RS 4
+.RE
+.PP
+\fBqueue_mode=\fR\fItrack\fR
+.RS 4
+.RE
+.PP
+\fBmax_art=\fR\fI10\fR
+.RS 4
+.RE
+.PP
+\fBdepth=\fR\fI1\fR
+.RS 4
+.RE
+.PP
+\fBsingle_album=\fR\fIfalse\fR
+.RS 4
+.RE
+.PP
+\fBtrack_to_add=\fR\fI1\fR
+.RS 4
+.RE
+.PP
+\fBalbum_to_add=\fR\fI1\fR
+.RS 4
+.RE
+.PP
+\fBpriority=\fR\fI100\fR
+.RS 4
+.RE
 .SH "QUEUE MODES"
 .PP
 mpd\-sima offers different queue modes\&. All of them pick up tracks from artists similar to the last track in the queue\&.
@@ -369,9 +427,6 @@ For instance looking for album from "The Velvet Underground" will fetch "Last Da
 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
@@ -402,7 +457,7 @@ ${HOME}/\&.config\&.
 You may override them using command line option
 \fB\-\-var_dir\fR
 (cf\&.
-\fBmpd_sima\fR(1))
+\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,
diff --git a/data/man/mpd_sima.cfg.5.xml b/data/man/mpd_sima.cfg.5.xml
index b6bd123..71189d4 100644
--- a/data/man/mpd_sima.cfg.5.xml
+++ b/data/man/mpd_sima.cfg.5.xml
@@ -185,62 +185,64 @@ man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
                     <term><option>[sima]</option></term>
                     <listitem><para></para></listitem>
                 </varlistentry>
+            <variablelist>
+                <varlistentry> <!-- sima.contrib -->
+                    <term><option>contrib=</option><replaceable></replaceable></term>
+                    <listitem>
+                        <para></para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry> <!-- sima.internal -->
+                    <term><option>internal=</option><replaceable>Lastfm, Random, Crop</replaceable></term>
+                    <listitem>
+                        <para>&dhpackage;'s plugin management for internal source plugin
+                            and contrib (ie. external plugins).<sbr /> Plugins list is a
+                            comma separated string list.<sbr /> Optional plugin's
+                            configuration lays in its own section.<sbr />For instance a
+                            "AwesomePlugin" declared here gets its configuration from the
+                            corresponding section "[awesomeplugin]".
+                        </para>
+                        <para>The default list of plugins to load at startup: <option>Lastfm</option>,<option>Random</option>,<option>Crop</option>.<sbr />
+                            <option>Crop</option> is an utility plugin, it does not queue any tracks (cf. below).<sbr />
+                            <option>Random</option> will queue a track at random if other plugins did not return any tracks.<sbr />
+                        </para>
+                        <para>You can add here as many plugins you want,
+                            currently shipping <option>Lastfm</option> and
+                            <option>EchoNest</option> only.<sbr />
+                            The priority may be used to order them.
+                        </para>
+                    </listitem>
+                </varlistentry>
                 <varlistentry> <!-- sima.history_duration -->
                     <term><option>history_duration=</option><replaceable>8</replaceable></term>
                     <listitem>
                         <para>How far to look back in history to avoid to play
                             twice the same track/title (duration in
-                            hours).</para>
+                            hours).<sbr />
+                            The <option>history_duration</option> is also used to give priority to not recently played artists.
+                        </para>
                     </listitem>
                 </varlistentry>
                 <varlistentry> <!-- sima.queue_length -->
-                    <term><option>queue_length=</option><replaceable>1</replaceable></term>
+                    <term><option>queue_length=</option><replaceable>2</replaceable></term>
                     <listitem>
-                        <para>This value triggers queue process if the queue
-                            length is less than specified
-                            queue_length.</para>
+                        <para>Threshold value triggering queue process.</para>
                     </listitem>
                 </varlistentry>
                 <varlistentry> <!-- sima.musicbrainzid -->
                     <term><option>musicbrainzid=</option><replaceable>true</replaceable></term>
                     <listitem>
                         <para>Use MusicBrainzIdentifier to search music (mainly
-                            for artists). Consider using these metadata as it
-                            enhances a lot artist/album/tracks identification.<sbr />
+                            for artists).
                             Default is True, switch to False if you don't have
                             MusicBrainzIdentifier set for at least 80% of you
-                            music library.<sbr />
+                            music library.<sbr /> Consider using these metadata as it
+                            enhances a lot artist/album/tracks identification.
                             Use Picard to tag your file: <ulink url="https://picard.musicbrainz.org/"/>.
                         </para>
                     </listitem>
                 </varlistentry>
             </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
-                plugin, ie.  Random → random.
-            </para>
-            <variablelist>
-                <varlistentry> <!-- sima.internal -->
-                    <term><option>internal=</option><replaceable>Crop, Random, Lastfm</replaceable></term>
-                    <listitem>
-                        <para><option>Crop</option> and <option>Random</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">
@@ -258,6 +260,14 @@ man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
                         </para>
                     </listitem>
                 </varlistentry>
+                <varlistentry> <!-- crop.priority -->
+                    <term><option>priority=</option><replaceable>10</replaceable></term>
+                    <listitem>
+                        <para>
+                            Plugin priority
+                        </para>
+                    </listitem>
+                </varlistentry>
         </refsect2>
         <refsect2 id="random">
             <title>Random section</title>
@@ -291,6 +301,14 @@ man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
                         </para>
                     </listitem>
                 </varlistentry>
+                <varlistentry> <!-- random.priority -->
+                    <term><option>priority=</option><replaceable>50</replaceable></term>
+                    <listitem>
+                        <para>
+                            Plugin priority
+                        </para>
+                    </listitem>
+                </varlistentry>
         </refsect2>
         <refsect2 id="lastfm">
             <title>LastFm section</title>
@@ -363,6 +381,47 @@ man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
                         </para>
                     </listitem>
                 </varlistentry>
+                <varlistentry> <!-- lastfm.priority -->
+                    <term><option>priority=</option><replaceable>100</replaceable></term>
+                    <listitem>
+                        <para>
+                            Plugin priority
+                        </para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+        </refsect2>
+        <refsect2 id="echonest">
+            <title>EchoNest section</title>
+            <para>EchoNest plugin's configuration.</para>
+            <para>Options for EchoNest are exactly the same as LastFm (same
+                default as well), except for cache plugin which is always
+                needed to limit number of requests to the service.</para>
+            <variablelist>
+                <varlistentry> <!-- echonest -->
+                    <term><option>[echonest]</option></term>
+                </varlistentry>
+                <varlistentry> <!-- echonest.queue_mode -->
+                    <term><option>queue_mode=</option><replaceable>track</replaceable></term>
+                </varlistentry>
+                <varlistentry> <!-- echonest.max_art -->
+                    <term><option>max_art=</option><replaceable>10</replaceable></term>
+                </varlistentry>
+                <varlistentry> <!-- echonest.depth -->
+                    <term><option>depth=</option><replaceable>1</replaceable></term>
+                </varlistentry>
+                <varlistentry> <!-- echonest.single_album -->
+                    <term><option>single_album=</option><replaceable>false</replaceable></term>
+                </varlistentry>
+                <varlistentry> <!-- echonest.track_to_add -->
+                    <term><option>track_to_add=</option><replaceable>1</replaceable></term>
+                </varlistentry>
+                <varlistentry> <!-- echonest.album_to_add -->
+                    <term><option>album_to_add=</option><replaceable>1</replaceable></term>
+                </varlistentry>
+                <varlistentry> <!-- echonest.priority -->
+                    <term><option>priority=</option><replaceable>100</replaceable></term>
+                </varlistentry>
             </variablelist>
         </refsect2>
     </refsect1>
@@ -409,10 +468,7 @@ man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
                         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>
+                        is skipped and won't be queued.</para>
                 </listitem>
             </varlistentry>
         </variablelist>
diff --git a/data/man/simadb_cli.1 b/data/man/simadb_cli.1
index c2c5172..19a4fe9 100644
--- a/data/man/simadb_cli.1
+++ b/data/man/simadb_cli.1
@@ -2,12 +2,12 @@
 .\"     Title: simadb_cli
 .\"    Author: Jack Kaliko <kaliko@azylum.org>
 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
-.\"      Date: 01/28/2015
-.\"    Manual: mpd-sima 0.13.1 User Manual
+.\"      Date: 02/08/2015
+.\"    Manual: mpd-sima 0.14.0 User Manual
 .\"    Source: mpd-sima
 .\"  Language: English
 .\"
-.TH "SIMADB_CLI" "1" "01/28/2015" "mpd-sima" "mpd-sima 0.13.1 User Manual"
+.TH "SIMADB_CLI" "1" "02/08/2015" "mpd-sima" "mpd-sima 0.14.0 User Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
diff --git a/doc/examples/all_settings.cfg b/doc/examples/all_settings.cfg
index 4778e1a..ca8e9e6 100644
--- a/doc/examples/all_settings.cfg
+++ b/doc/examples/all_settings.cfg
@@ -65,7 +65,7 @@ verbosity = info
 #                contrib = Scrobble, AwesomePlugin,
 #                          ExperimentalTest, AnotherTest
 # default:
-#          internal = "Crop, Lastfm, Random"
+#          internal = "Lastfm, Random, Crop"
 #          contrib =
 # description: Plugins list declaration.
 #     Optional plugin's configuration lays in its own section.
@@ -73,11 +73,11 @@ verbosity = info
 #     gets its configuration from the corresponding section:
 #     "[awesomeplugin]"
 #     internal plugins will look for a section named after the lower-cased name
-#     of the pluglin, ie. Random → random.
+#     of the plugin, ie. AwesomePlugin → awesomeplugin.
 #
 #     Two plugins sources are available, internal and contrib
 #
-internal = Crop, Lastfm, Random
+internal = Lastfm, Random, Crop
 #contrib =
 
 ## HISTORY_DURATION
@@ -97,9 +97,9 @@ user_db = false
 
 ## QUEUE_LENGTH
 # type: integer
-# default: 1
-# description: Queue length triggering tracks addition
-queue_length = 1
+# default: 2
+# description: Queue length threshold triggering tracks addition
+queue_length = 2
 
 ## MUSICBRAINZID
 # type: boolean
diff --git a/sima/utils/config.py b/sima/utils/config.py
index d3bcbe2..f7ec982 100644
--- a/sima/utils/config.py
+++ b/sima/utils/config.py
@@ -46,7 +46,7 @@ DEFAULT_CONF = {
             'port': 6600,
             },
         'sima': {
-            'internal': "Crop, Lastfm, RandomFallBack",
+            'internal': "Crop, Lastfm, Random",
             'contrib': "",
             'user_db': "false",
             'history_duration': 8,
@@ -64,6 +64,7 @@ DEFAULT_CONF = {
             },
         'crop': {
             'consume': 10,
+            'priority': 0,
             },
         'echonest': {
             'queue_mode': "track", #TODO control values