doc/source/user/01_configurations.rst

   1 Configuration examples
   2 ======================
   3
   4 Configuration location is ``${XDG_CONFIG_HOME}/mpd_sima/mpd_sima.cfg`` usually ``${XDG_CONFIG_HOME}``  is in ``${HOME}/.config/``.
   5
   6
   7 Default configuration
   8 ---------------------
   9
  10 MPD_sima runs without explicit configuration as long as your MPD server is easy
  11 to discover (``localhost:6600`` or exposed via environment variables ``MPD_HOST``/``MPD_PORT``).
  12
  13 The default configuration is to run in *track mode* with suggestions from
  14 last.fm. In addition to `Lastfm` plugin set in **[sima]** section (within *internal*
  15 option) there is a `Crop` plugin (keeps 10 tracks behind the currently playing
  16 track) and a `Random` plugin (acting as a fallback if `Lastfm` did not find any
  17 track to queue).
  18
  19 .. code:: ini
  20
  21     [MPD]
  22     # Change MPD server here
  23     #host = mpdserver.example.org
  24     #port = 6600
  25
  26     [sima]
  27     internal = Crop, Lastfm, Random
  28     history_duration = 8
  29     queue_length = 2
  30
  31     [crop]
  32     consume = 10
  33
  34     [lastfm]
  35     queue_mode = track
  36     single_album = False
  37     track_to_add = 1
  38
  39 Album mode
  40 ^^^^^^^^^^
  41
  42 One of the first request added to MPD_sima was album mode. It allows to queue whole album instead of single tracks.
  43
  44 Here the configuration keeps the queue plugin *Lastfm* but configure it to queue albums (``queue_mode = album``) and ask for 2 albums to be add.
  45
  46 The configuration of MPD_sima in ``sima`` section is also modified for ``queue_length``. The value of 10 is to trigger album queueing when there are 10 tracks or less in the queue.
  47
  48 .. code:: ini
  49
  50     [sima]
  51     internal = Crop, Lastfm, Random
  52     history_duration = 24
  53     queue_length = 10
  54
  55     [crop]
  56     consume = 10
  57
  58     [lastfm]
  59     queue_mode = album
  60     album_to_add = 2
  61
  62
  63 Offline auto-queuing
  64 --------------------
  65
  66 In addition to LastFm there are other *plugins* you can mix together or use alone to have a specific queue mode.
  67
  68 Genre auto-queuing
  69 ^^^^^^^^^^^^^^^^^^
  70 With this mode MPD_sima is trying to queue tracks with genre tag similar to previously played tracks.
  71
  72 .. code:: ini
  73
  74     [sima]
  75     internal = Crop, Genre, Random
  76     history_duration = 8
  77
  78     [genre]
  79     queue_mode = track
  80     track_to_add = 1
  81
  82
  83 Random queuing
  84 ^^^^^^^^^^^^^^
  85 This mode allows random queuing with different flavour **pure** (total
  86 randomness) or **sensible** (use play history to filter chosen tracks).
  87 The **sensible** flavour will then tend to play track not in recently played.
  88
  89 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.
  90
  91 .. code:: ini
  92
  93     [sima]
  94     internal = Crop, Random
  95     history_duration = 168
  96
  97     [random]
  98     flavour = sensible
  99
 100 Tag queuing
 101 ^^^^^^^^^^^
 102
 103 This is the most complex and versatile offline mode. "Tags" plugin allows to queue track based on actual tags value.
 104
 105 Here is an example to have MPD_sima to queue only electronic music tagged with genres **electonica** or **IDM** or **glitch**:
 106
 107 .. code:: ini
 108
 109     [sima]
 110     internal = Crop, Tags
 111
 112     [tags]
 113     # Look for files with tagged with genre "electonica" OR "IDM" OR "glitch"
 114     genre = electonica, IDM, glitch
 115
 116 There are other supported tags, mainly **date**, **originaldate** or
 117 **comment** (cf manual for the exact list). You can use more than one, entries
 118 in tags sections are ANDed within a single MPD filter to look for titles.
 119
 120 For instance setting "genre=rock" and
 121 "date=1982,1983,1984,1985,1986,1987,1988,1989" will end up looking for track
 122 tagged with genre rock and date within 1982 through 1989:
 123
 124 .. code:: ini
 125
 126     [sima]
 127     internal = Crop, Tags
 128
 129     [tags]
 130     genre = rock
 131     date = 1982,1983,1984,1985,1986,1987,1988,1989
 132
 133 In case you want to make complex search in MPD library you can provide an `MPD
 134 filter`_. This is a powerful feature, it comes at the cost of a different syntax, some might find it more readable some wont :D
 135
 136 For instance in the previous example you can simply replace **date** with the
 137 current filter "`(date =~ '198[2-9]+')`":
 138
 139 .. code:: ini
 140
 141     [sima]
 142     internal = Crop, Tags
 143
 144     [tags]
 145     genre = rock
 146     filter = (date =~ '198[2-9]+')
 147
 148 And even go further and merge genre in the filter using "`((genre == 'rock') AND
 149 (date =~ '198[2-9]+'))`".
 150
 151 .. code:: ini
 152
 153     [sima]
 154     internal = Crop, Tags
 155
 156     [tags]
 157     filter = (genre == 'rock' ) AND (date =~ '198[2-9]+'))
 158
 159
 160 Since the setup for the filter can be tricky and it can be useful to validate
 161 the syntax and have a look at what kind of artists the filter would return.
 162
 163 You can call MPD_sima to controls the configuration file. For instance with a config in `sima.cfg` run:
 164
 165 .. code:: bash
 166
 167     ./mpd-sima --log-level info --config sima.cfg config-test
 168
 169
 170 .. include:: ../links.rst
 171
 172 .. vim: spell spelllang=en