Document new offline autoqueue plugin based on file tags only

diff --git a/data/man/mpd_sima.cfg.5 b/data/man/mpd_sima.cfg.5
index 7fb9853605aee7b2351d5d12b26e967d38a89d9a..345864f59509a56f2e0c8afb9f560b8418c21e7e 100644 (file)
--- a/data/man/mpd_sima.cfg.5
+++ b/data/man/mpd_sima.cfg.5
@@ -2,12 +2,12 @@
 .\"     Title: mpd_sima.cfg
 .\"    Author: kaliko <kaliko@azylum.org>
 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
-.\"      Date: 05/11/2020
+.\"      Date: 12/14/2020
 .\"    Manual: mpd-sima 0.16.0 User Manual
 .\"    Source: mpd-sima
 .\"  Language: English
 .\"
-.TH "MPD_SIMA\&.CFG" "5" "05/11/2020" "mpd-sima" "mpd-sima 0.16.0 User Manual"
+.TH "MPD_SIMA\&.CFG" "5" "12/14/2020" "mpd-sima" "mpd-sima 0.16.0 User Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -36,9 +36,40 @@ This manual page documents briefly
 configuration options available in user configuration file (see
 the section called \(lqFILES\(rq)\&.
 .SH "EXAMPLES"
-.SS "Album queue mode\&."
+.SS "File tags queue mode (offline mode)\&."
 .PP
-Here is an example of album queue configuration\&.
+Here is an example of autoqueue using file tags only\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+[MPD]
+host=example\&.org
+port=6601
+
+[sima]
+# Setup internal plugins
+internal = Tags, Crop
+history_duration=48  # 2 days
+queue_length=2
+
+[tags]
+# Look for files with tagged with genre "electonica" OR "IDM" OR "glitch"
+genre = electonica, IDM, glitch
+
+[crop]
+# keep 30 played tracks in playlist
+consume=30
+
+            
+.fi
+.if n \{\
+.RE
+.\}
+.SS "Album queue mode using last\&.fm recommendations (online mode)\&."
+.PP
+Here is an example of album queue configuration using online recommendations system\&.
 .sp
 .if n \{\
 .RS 4
@@ -181,9 +212,7 @@ will queue a track at random if other plugins did not return any tracks\&.
 .br
 
 .sp
-You can add here as many plugins you want, currently shipping
-\fBLastfm\fR
-only\&.
+You can add, combine here as many plugins you want\&.
 .br
 
 The priority may be used to order them\&.
@@ -377,9 +406,64 @@ If set to "false", caching is still done but in memory\&.
 .RS 4
 Plugin priority
 .RE
+.SS "Tags section"
+.PP
+Tags plugin\*(Aqs configuration\&. There is no default configuration for this plugin, it does not work out of the box\&.
+.PP
+This plugin permits offline autoqueuing based on files tags only\&. Supported tags are
+\fB\*(Aqcomment\*(Aq\fR,
+\fB\*(Aqdate\*(Aq\fR,
+\fB\*(Aqgenre\*(Aq\fR,
+\fB\*(Aqlabel\*(Aq\fR
+and
+\fB\*(Aqoriginaldate\*(Aq\fR\&. It currently supports single track queuing only, no album mode for this plugin\&.
+.PP
+In addition to supported tags above you can use an MPD filter\&. Please refer to MPD protocol documentation for more\&.
+.PP
+All entries in this section are ANDed as a single MPD filter to look for titles in the library\&. Moreover, with tags, comma separated values are also ANDed\&.
+.br
+
+For instance setting "\fBgenre=rock\fR" and "\fBdate=1982,1983,1984,1985,1986,1987,1988,1989\fR" will end up looking for track tagged with genre
+\fBrock\fR
+and date within 1985 through 1990\&.
+.br
+
+Using an MPD filter to replace
+\fBdate\fR
+you can achieve the same with the following setting: "\fBgenre=rock\fR" and "\fBfilter=(date =~ \*(Aq198[2\-9]\*(Aq)\fR" (provided your MPD server was compiled with libpcre)\&.
+.PP
+\fB[tags]\fR
+.RS 4
+.RE
+.PP
+\fBfilter=\fR
+.RS 4
+You can use here any valid MPD filter as defined in MPD protocol documentation\&.
+.RE
+.PP
+\fBcomment=\fR
+.RS 4
+.RE
+.PP
+\fBdate=\fR
+.RS 4
+.RE
+.PP
+\fBgenre=\fR
+.RS 4
+.RE
+.PP
+\fBlabel=\fR
+.RS 4
+.RE
+.PP
+\fBpriority=\fR\fI80\fR
+.RS 4
+Plugin priority
+.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\&.
+mpd\-sima offers different queue modes with lastfm plugin\&. All of them pick up tracks from artists similar to the last track in the queue\&.
 .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

diff --git a/data/man/mpd_sima.cfg.5.xml b/data/man/mpd_sima.cfg.5.xml
index 678e4de0d39389fa89b8c1c4b28f7161b64f1167..8ff9db0312e88f00c1a559bfede3aceaac08d719 100644 (file)
--- a/data/man/mpd_sima.cfg.5.xml
+++ b/data/man/mpd_sima.cfg.5.xml
@@ -75,9 +75,15 @@ man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
             <para></para>
             <para></para>
         </refsect2> -->
+        <refsect2 id="tags">
+            <title>File tags queue mode (offline mode).</title>
+            <para>Here is an example of autoqueue using file tags only.</para>
+            <programlisting><xi:include href="tags.cfg" parse="text" />
+            </programlisting>
+        </refsect2>
         <refsect2 id="album">
-            <title>Album queue mode.</title>
-            <para>Here is an example of album queue configuration.</para>
+            <title>Album queue mode using last.fm recommendations (online mode).</title>
+            <para>Here is an example of album queue configuration using online recommendations system.</para>
             <programlisting><xi:include href="album.cfg" parse="text" />
             </programlisting>
         </refsect2>
@@ -206,8 +212,7 @@ man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
                                 <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> only.<sbr />
+                            <para>You can add, combine here as many plugins you want.<sbr />
                                 The priority may be used to order them.
                             </para>
                         </listitem>
@@ -414,10 +419,63 @@ man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
                 </varlistentry>
             </variablelist>
         </refsect2>
+        <refsect2 id="tags">
+            <title>Tags section</title>
+              <para>Tags plugin's configuration. There is no default configuration for this plugin, it does not work out of the box.</para>
+              <para>
+                This plugin permits offline autoqueuing based on files tags only. Supported tags are
+              <option>'comment'</option>, <option>'date'</option>, <option>'genre'</option>, <option>'label'</option> and
+              <option>'originaldate'</option>. It currently supports single track queuing only, no album mode for this plugin.
+              </para>
+            <para>
+              In addition to supported tags above you can use an MPD filter. Please refer to MPD protocol documentation for more.
+            </para>
+            <para>
+              All entries in this section are ANDed as a single MPD filter to look for titles
+              in the library. Moreover, with tags, comma separated values are also ANDed.<sbr />
+              For instance setting "<option>genre=rock</option>" and
+              "<option>date=1982,1983,1984,1985,1986,1987,1988,1989</option>"
+              will end up looking for track tagged with genre <option>rock</option>
+              and date within 1985 through 1990.<sbr />
+              Using an MPD filter to replace <option>date</option> you can achieve
+              the same with the following setting: "<option>genre=rock</option>" and
+              "<option>filter=(date =~ '198[2-9]')</option>" (provided your MPD server
+              was compiled with libpcre).
+            </para>
+                <varlistentry> <!-- tags -->
+                   <term><option>[tags]</option></term>
+                </varlistentry>
+                <varlistentry> <!-- tags.filter -->
+                    <term><option>filter=</option></term>
+                    <listitem>
+                        <para>You can use here any valid MPD filter as defined in MPD protocol documentation.</para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry> <!-- tags.comment -->
+                    <term><option>comment=</option></term>
+                </varlistentry>
+                <varlistentry> <!-- tags.date -->
+                    <term><option>date=</option></term>
+                </varlistentry>
+                <varlistentry> <!-- tags.genre -->
+                    <term><option>genre=</option></term>
+                </varlistentry>
+                <varlistentry> <!-- tags.label -->
+                    <term><option>label=</option></term>
+                </varlistentry>
+                <varlistentry> <!-- tags.priority -->
+                    <term><option>priority=</option><replaceable>80</replaceable></term>
+                    <listitem>
+                        <para>
+                            Plugin priority
+                        </para>
+                    </listitem>
+                </varlistentry>
+        </refsect2>
     </refsect1>
     <refsect1 id="queue_mode">
         <title>QUEUE MODES</title>
-        <para>&dhpackage; offers different queue modes. All of them pick up
+        <para>&dhpackage; offers different queue modes with lastfm plugin. All of them pick up
             tracks from artists similar to the last track in the queue.</para>
         <para>&dhpackage; tries preferably to chose among unplayed artists or
             at least not recently played artist. Concerning track and album
@@ -467,3 +525,5 @@ man(1), man(7), http://www.tldp.org/HOWTO/Man-Page/
   <xi:include href="feedback.xml" />
   <xi:include href="seealso.xml" />
 </refentry>
+<!-- vim: tabstop=4 softtabstop=4 shiftwidth=4 :
+-->

diff --git a/doc/Changelog b/doc/Changelog
index 3504aa366817130dfbf1de89d7b141b362c2989c..f4aaa7dcee4beb4a2227f6f9ad2b39016c601f47 100644 (file)
--- a/doc/Changelog
+++ b/doc/Changelog
@@ -1,5 +1,6 @@
 MPD_sima v0.16.0
 
+ * New offline autoqueue plugin based on file tags only
  * Update vinstall.py (closes #34)
  * Fixed bug when http client fetches a corrupted cached entry (closes #35)
  * Need at least python 3.6

diff --git a/doc/examples/all_settings.cfg b/doc/examples/all_settings.cfg
index 2551f34dd5573db344a214e7d3b432aab30605cf..7b8e68511fc83c17590c28062a0eef34188ed75c 100644 (file)
--- a/doc/examples/all_settings.cfg
+++ b/doc/examples/all_settings.cfg
@@ -120,6 +120,26 @@ single_disable_queue  = True
 
 ######################### PLUGINS #####################################
 
+[tags]
+## Offline tags queing
+# This plugin has no defaults set
+
+# TAGS, any of the supported tags below
+# type: string
+# default: not set
+# description: 
+comment=
+date=
+genre=
+label=
+originaldate=
+
+# FILTER
+# type: string
+# default: not set
+# description: Forge your own MPD filter (cf MPD protocol documentation)
+filter=
+
 [crop]
 ## CONSUME
 # type: integer

diff --git a/sima/utils/config.py b/sima/utils/config.py
index c9240ea1c8a094d9b244c4708f5cf6588196d2c6..20356a153492d8675531d1cd814f97ff90ebaf14 100644 (file)
--- a/sima/utils/config.py
+++ b/sima/utils/config.py
@@ -87,6 +87,14 @@ DEFAULT_CONF = {
             'track_to_add': 1,
             'priority': 50,
             },
+        'tags': {
+            'comment': "",
+            'date': "",
+            'genre': "",
+            'label': "",
+            'originaldate': "",
+            'priority': 80,
+            }
         }
 #