]> kaliko git repositories - mpd-sima.git/blob - doc/source/user/01_configurations.rst
Add positional argument random, a random mode shortcut
[mpd-sima.git] / 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