doc/source/user/01_configurations.rst

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