From 0bca6ee3dd5a5426c985e85e0e50fac77e4ec8f1 Mon Sep 17 00:00:00 2001
From: kaliko <kaliko@azylum.org>
Date: Sun, 8 Feb 2015 16:30:37 +0100
Subject: [PATCH] Update manuals
---
data/man/files.xml | 2 +-
data/man/mpd-sima.1 | 8 +-
data/man/mpd_sima.cfg.5 | 139 ++++++++++++++++++++++++----------
data/man/mpd_sima.cfg.5.xml | 132 ++++++++++++++++++++++----------
data/man/simadb_cli.1 | 6 +-
doc/examples/all_settings.cfg | 12 +--
sima/utils/config.py | 3 +-
7 files changed, 207 insertions(+), 95 deletions(-)
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
--
2.39.5