From: kaliko <kaliko@azylum.org>
Date: Sun, 14 Nov 2021 17:51:40 +0000 (+0100)
Subject: doc: Add queue plugins examples
X-Git-Tag: 0.18.1~18
X-Git-Url: https://git.kaliko.me/?a=commitdiff_plain;h=f22f69c4510ccb1d32d389597939ffbc140a4178;p=mpd-sima.git

doc: Add queue plugins examples
---

diff --git a/doc/source/links.rst b/doc/source/links.rst
index cd326df..8c70b4b 100644
--- a/doc/source/links.rst
+++ b/doc/source/links.rst
@@ -6,3 +6,4 @@
 .. _MusicBrainz: https://musicbrainz.org
 .. _`ID3 tags`: https://en.wikipedia.org/wiki/ID3
 .. _last.fm: https://www.last.fm/
+.. _`MPD filter`: https://mpd.readthedocs.io/en/latest/protocol.html#filter-syntax
diff --git a/doc/source/user/01_configurations.rst b/doc/source/user/01_configurations.rst
index a5c9ba8..6819adf 100644
--- a/doc/source/user/01_configurations.rst
+++ b/doc/source/user/01_configurations.rst
@@ -10,7 +10,11 @@ Default configuration
 MPD_sima runs without explicit configuration as long as your MPD server is easy
 to discover (``localhost:6600`` or exposed via environment variables ``MPD_HOST``/``MPD_PORT``).
 
-The default configuration is to run in *track mode* with suggestions from last.fm:
+The default configuration is to run in *track mode* with suggestions from
+last.fm. In addition to `Lastfm` plugin set in **[sima]** section (within *internal*
+option) there is a `Crop` plugin (keeps 10 tracks behind the currently playing
+track) and a `Random` plugin (acting as a fallback if `Lastfm` did not find any
+track to queue).
 
 .. code:: ini
 
@@ -43,14 +47,9 @@ The configuration of MPD_sima in ``sima`` section is also modified for ``queue_l
 
 .. code:: ini
 
-    [MPD]
-    # Change MPD server here
-    #host = mpdserver.example.org
-    #port = 6600
-
     [sima]
     internal = Crop, Lastfm, Random
-    history_duration = 8
+    history_duration = 24
     queue_length = 10
 
     [crop]
@@ -64,5 +63,110 @@ The configuration of MPD_sima in ``sima`` section is also modified for ``queue_l
 Offline auto-queuing
 --------------------
 
+In addition to LastFm there are other *plugins* you can mix together or use alone to have a specific queue mode.
+
+Genre auto-queuing
+^^^^^^^^^^^^^^^^^^
+With this mode MPD_sima is trying to queue tracks with genre tag similar to previously played tracks.
+
+.. code:: ini
+
+    [sima]
+    internal = Crop, Genre, Random
+    history_duration = 8
+
+    [genre]
+    queue_mode = track
+    track_to_add = 1
+
+
+Random queuing
+^^^^^^^^^^^^^^
+This mode allows random queuing with different flavour **pure** (total
+randomness) or **sensible** (use play history to filter chosen tracks).
+The **sensible** flavour will then tend to play track not in recently played.
+
+The history duration is important for this plugin when running in **sensible** flavour since you might exhaust possible tracks to queue if the **history_duration** is larger than the total play time you have in your music library.
+
+.. code:: ini
+
+    [sima]
+    internal = Crop, Random
+    history_duration = 168
+
+    [random]
+    flavour = sensible
+
+Tag queuing
+^^^^^^^^^^^
+
+This is the most complex and versatile offline mode. "Tags" plugin allows to queue track based on actual tags value.
+
+Here is an example to have MPD_sima to queue only electronic music tagged with genres **electonica** or **IDM** or **glitch**:
+
+.. code:: ini
+
+    [sima]
+    internal = Crop, Tags
+
+    [tags]
+    # Look for files with tagged with genre "electonica" OR "IDM" OR "glitch"
+    genre = electonica, IDM, glitch
+
+There are other supported tags, mainly **date**, **originaldate** or
+**comment** (cf manual for the exact list). You can use more than one, entries
+in tags sections are ANDed within a single MPD filter to look for titles.
+
+For instance setting "genre=rock" and
+"date=1982,1983,1984,1985,1986,1987,1988,1989" will end up looking for track
+tagged with genre rock and date within 1982 through 1989:
+
+.. code:: ini
+
+    [sima]
+    internal = Crop, Tags
+
+    [tags]
+    genre = rock
+    date = 1982,1983,1984,1985,1986,1987,1988,1989
+
+In case you want to make complex search in MPD library you can provide an `MPD
+filter`_. This is a powerful feature, it comes at the cost of a different syntax, some might find it more readable some wont :D
+
+For instance in the previous example you can simply replace **date** with the
+current filter "`(date =~ '198[2-9]+')`":
+
+.. code:: ini
+
+    [sima]
+    internal = Crop, Tags
+
+    [tags]
+    genre = rock
+    filter = (date =~ '198[2-9]+')
+
+And even go further and merge genre in the filter using "`((genre == 'rock') AND
+(date =~ '198[2-9]+'))`".
+
+.. code:: ini
+
+    [sima]
+    internal = Crop, Tags
+
+    [tags]
+    filter = (genre == 'rock' ) AND (date =~ '198[2-9]+'))
+
+
+Since the setup for the filter can be tricky and it can be useful to validate
+the syntax and have a look at what kind of artists the filter would return.
+
+You can call MPD_sima to controls the configuration file. For instance with a config in `sima.cfg` run:
+
+.. code:: bash
+
+    ./mpd-sima --log-level info --config sima.cfg config-test
+
+
+.. include:: ../links.rst
 
 .. vim: spell spelllang=en