]> kaliko git repositories - mpd-sima.git/blob - data/man/mpd_sima.cfg.5.html
Fixed code smell
[mpd-sima.git] / data / man / mpd_sima.cfg.5.html
1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>mpd_sima.cfg</title><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry"><a name="idm1"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>mpd_sima.cfg &#8212; mpd-sima will try to maintain some titles ahead in the queue
2             following different policies. This manual document the
3             configuration file for mpd-sima.</p></div><div class="refsect1"><a name="description"></a><h2>DESCRIPTION</h2><p>This manual page documents briefly <span class="command"><strong>mpd-sima</strong></span>
4             configuration options available in user configuration file
5             (see <a class="xref" href="#files" title="FILES">the section called &#8220;FILES&#8221;</a>).</p></div><div class="refsect1"><a name="examples"></a><h2>EXAMPLES</h2><div class="refsect2"><a name="album"></a><h3>Album queue mode.</h3><p>Here is an example of album queue configuration.</p><pre class="programlisting">[MPD]
6 host=example.org
7 port=8000
8
9 [sima]
10 history_duration=48  # 2 days
11 queue_length=5
12
13 [lastfm]
14 queue_mode=album
15 album_to_add=2
16
17 [crop]
18 # keep 30 played tracks in playlist
19 consume=30
20
21             </pre></div></div><div class="refsect1"><a name="options"></a><h2>Configuration file</h2><p>The configuration file consists of sections, led by a
22             <span class="command"><strong>[section]</strong></span> header and followed by <code class="option">name: value</code>
23             entries, with continuations in the style of RFC 822 (see section
24             3.1.1, &#8220;LONG HEADER FIELDS&#8221;); <code class="option">name=value</code> is also accepted. Lines
25             beginning with <em class="parameter"><code>'#'</code></em> or <em class="parameter"><code>';'</code></em>
26             are ignored and may be used to provide comments (<span class="emphasis"><em>Nota
27                 Bene:</em></span> inline comment are possible using <em class="parameter"><code>'#'</code></em>).</p><p>The default values are used in the options lists below.</p><div class="refsect2"><a name="MPD"></a><h3>MPD section</h3><p>This section is meant to configure MPD access, MPD host
28                 address / port and password if necessary.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">[MPD]</code></span></dt><dd></dd><dt><span class="term"><code class="option">host=</code><em class="replaceable"><code>localhost</code></em></span></dt><dd><p>Set MPD host. Use IP or FQDN.</p></dd><dt><span class="term"><code class="option">port=</code><em class="replaceable"><code>6600</code></em></span></dt><dd><p>Set host port to access MPD to.</p></dd><dt><span class="term"><code class="option">password=</code><em class="replaceable"><code>s3cr3t</code></em></span></dt><dd><p>Set MPD password to use. Do not use this option
29                             if you don't have enabled password protected access
30                             on your MPD server.</p></dd></dl></div></div><div class="refsect2"><a name="log"></a><h3>log section</h3><p>Configure logging.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">[log]</code></span></dt><dd><p></p></dd><dt><span class="term"><code class="option">logfile=</code></span></dt><dd><p>File to log to, usually in dæmon mode.<br>Default
31                             (empty or unset) is to log to stdin/stdout.</p></dd><dt><span class="term"><code class="option">verbosity=</code><em class="replaceable"><code>info</code></em></span></dt><dd><p>Logging verbosity among
32                             <em class="replaceable"><code>debug</code></em>,
33                             <em class="replaceable"><code>info</code></em>,
34                             <em class="replaceable"><code>warning</code></em>,
35                             <em class="replaceable"><code>error</code></em>.</p></dd></dl></div></div><div class="refsect2"><a name="daemon"></a><h3>Process daemonization</h3><p>Configure process daemon.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">[daemon]</code></span></dt><dd><p></p></dd><dt><span class="term"><code class="option">daemon=false</code></span></dt><dd><p>whether to daemonize process or not.</p></dd><dt><span class="term"><code class="option">pidfile=</code></span></dt><dd><p>Where to store process ID.</p></dd></dl></div></div><div class="refsect2"><a name="sima"></a><h3>sima section</h3><p>Core mpd_sima.cfg configuration.</p><div class="variablelist"><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">contrib=</code><em class="replaceable"><code></code></em></span></dt><dd><p></p></dd><dt><span class="term"><code class="option">internal=</code><em class="replaceable"><code>Lastfm, Random, Crop</code></em></span></dt><dd><p>mpd-sima's plugin management for internal source plugin
36                                 and contrib (ie. external plugins).<br> Plugins list is a
37                                 comma separated string list.<br> Optional plugin's
38                                 configuration lays in its own section.<br>For instance a
39                                 "AwesomePlugin" declared here gets its configuration from the
40                                 corresponding section "[awesomeplugin]".
41                             </p><p>The default list of plugins to load at startup: <code class="option">Lastfm</code>,<code class="option">Random</code>,<code class="option">Crop</code>.<br>
42                                 <code class="option">Crop</code> is an utility plugin, it does not queue any tracks (cf. below).<br>
43                                 <code class="option">Random</code> will queue a track at random if other plugins did not return any tracks.<br>
44                             </p><p>You can add here as many plugins you want,
45                                 currently shipping <code class="option">Lastfm</code> only.<br>
46                                 The priority may be used to order them.
47                             </p></dd><dt><span class="term"><code class="option">history_duration=</code><em class="replaceable"><code>8</code></em></span></dt><dd><p>How far to look back in history to avoid to play
48                                 twice the same track/title (duration in
49                                 hours).<br>
50                                 The <code class="option">history_duration</code> is also used to give priority to not recently played artists.
51                             </p></dd><dt><span class="term"><code class="option">queue_length=</code><em class="replaceable"><code>2</code></em></span></dt><dd><p>Threshold value triggering queue process.</p></dd><dt><span class="term"><code class="option">musicbrainzid=</code><em class="replaceable"><code>true</code></em></span></dt><dd><p>Use MusicBrainzIdentifier to search music (mainly
52                                 for artists).
53                                 Default is True, switch to False if you don't have
54                                 MusicBrainzIdentifier set for at least 80% of you
55                                 music library.<br> Consider using these metadata as it
56                                 enhances a lot artist/album/tracks identification.
57                                 Use Picard to tag your file: <a class="ulink" href="https://picard.musicbrainz.org/" target="_top">https://picard.musicbrainz.org/</a>.
58                             </p></dd><dt><span class="term"><code class="option">repeat_disable_queue=</code><em class="replaceable"><code>true</code></em></span></dt><dd><p>Prevent disabling queuing in repeat play mode.
59                             </p></dd><dt><span class="term"><code class="option">single_disable_queue=</code><em class="replaceable"><code>true</code></em></span></dt><dd><p>Prevent disabling queuing in single play mode.
60                             </p></dd></dl></div><dl class="variablelist"><dt><span class="term"><code class="option">[sima]</code></span></dt><dd><p></p></dd></dl></div></div><div class="refsect2"><a name="crop"></a><h3>Crop section</h3><p>crop plugin's configuration:</p><dt><span class="term"><code class="option">[crop]</code></span></dt><dd></dd><dt><span class="term"><code class="option">consume=</code><em class="replaceable"><code>10</code></em></span></dt><dd><p>How many played tracks to keep in the queue.
61                             Allows you to maintain a fixed length queue.
62                             Set to some negative integer to keep all played tracks.
63                         </p></dd><dt><span class="term"><code class="option">priority=</code><em class="replaceable"><code>10</code></em></span></dt><dd><p>
64                             Plugin priority
65                         </p></dd></div><div class="refsect2"><a name="random"></a><h3>Random section</h3><p>Random plugin's configuration:</p><dt><span class="term"><code class="option">[random]</code></span></dt><dd></dd><dt><span class="term"><code class="option">flavour=</code><em class="replaceable"><code>sensible</code></em></span></dt><dd><p>When no similar tracks are found, falling back to
66                             random queuing. Different mode, aka random flavour,
67                             are available:
68                             <em class="replaceable"><code>pure</code></em>,
69                             <em class="replaceable"><code>sensible</code></em>,
70                             <em class="replaceable"><code>genre</code></em>.
71                             </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: bullet; "><li class="listitem" style="list-style-type: disc"><p><em class="replaceable"><code>pure</code></em>, pure random choice, even among recently played track.
72                                     </p></li><li class="listitem" style="list-style-type: disc"><p><em class="replaceable"><code>sensible</code></em>, use play history to filter chosen tracks.
73                                     </p></li><li class="listitem" style="list-style-type: disc"><p><em class="replaceable"><code>genre</code></em>, Not implemented yet.
74                                     </p></li></ul></div><p>
75                         </p></dd><dt><span class="term"><code class="option">priority=</code><em class="replaceable"><code>50</code></em></span></dt><dd><p>
76                             Plugin priority
77                         </p></dd></div><div class="refsect2"><a name="lastfm"></a><h3>LastFm section</h3><p>LastFM plugin's configuration.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">[lastfm]</code></span></dt><dd></dd><dt><span class="term"><code class="option">queue_mode=</code><em class="replaceable"><code>track</code></em></span></dt><dd><p>Queue mode to use among
78                             <em class="replaceable"><code>track</code></em>,
79                             <em class="replaceable"><code>top</code></em> and
80                             <em class="replaceable"><code>album</code></em> (see <a class="xref" href="#queue_mode" title="QUEUE MODES">the section called &#8220;QUEUE MODES&#8221;</a> for info about queue modes).</p></dd><dt><span class="term"><code class="option">max_art=</code><em class="replaceable"><code>10</code></em></span></dt><dd><p>Maximum number of similar artist to retrieve from local
81                             media library.<br>When set to something superior
82                             to zero, it tries to get as much similar artists
83                             from media library.</p></dd><dt><span class="term"><code class="option">depth=</code><em class="replaceable"><code>1</code></em></span></dt><dd><p>How many artists to base on similar artists
84                             search.<br> The first is the last played artist
85                             and so on back in the history. Highter depth
86                             generates wider suggestions, it might help to
87                             reduce looping over same artists.
88                             </p></dd><dt><span class="term"><code class="option">single_album=</code><em class="replaceable"><code>false</code></em></span></dt><dd><p>Prevent from queueing a track from the same album
89                             (it often happens with OST).<br>
90                             Only relevant in "track" queue mode.</p></dd><dt><span class="term"><code class="option">track_to_add=</code><em class="replaceable"><code>1</code></em></span></dt><dd><p>How many track(s) to add. Only relevant in
91                             <code class="option">top</code> and <code class="option">track</code>
92                             queue modes. This is actually an upper limit,
93                             min(<code class="option">max_art</code>,
94                             <code class="option">track_to_add</code>) will be used, and
95                             <code class="option">max_art</code> might be inferior lower
96                             than value set in config.</p></dd><dt><span class="term"><code class="option">album_to_add=</code><em class="replaceable"><code>1</code></em></span></dt><dd><p>How many album(s) to add. Only relevant in
97                             <code class="option">album</code> queue modes.</p></dd><dt><span class="term"><code class="option">cache=</code><em class="replaceable"><code>True</code></em></span></dt><dd><p>Whether or not to use on-disk persistent http
98                             cache.<br>When set to "true", sima will use a
99                             persistent cache for its http client. The cache is
100                             written along with the dbfile in:<br>
101                             <code class="filename">$XDG_CONFIG_HOME/mpd_sima/http/WEB_SERVICE</code>.<br>
102                             If set to "false", caching is still done but in memory.
103                         </p></dd><dt><span class="term"><code class="option">priority=</code><em class="replaceable"><code>100</code></em></span></dt><dd><p>
104                             Plugin priority
105                         </p></dd></dl></div></div></div><div class="refsect1"><a name="queue_mode"></a><h2>QUEUE MODES</h2><p>mpd-sima offers different queue modes. All of them pick up
106             tracks from artists similar to the last track in the queue.</p><p>mpd-sima tries preferably to chose among unplayed artists or
107             at least not recently played artist. Concerning track and album
108             queue modes titles are chosen purely at random among unplayed
109             tracks.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">track</code></span></dt><dd><p>Queue a similar track chosen at random from a similar artist.</p></dd><dt><span class="term"><code class="option">top</code></span></dt><dd><p>Queue a track from a similar artist, chosen among
110                         "top tracks" according to last.fm data mining.</p></dd><dt><span class="term"><code class="option">album</code></span></dt><dd><p>Queue a whole album chosen at random from a similar artist.</p><p><span class="emphasis"><em>Nota Bene:</em></span><br> Due to the
111                         track point of view of database build upon tracks tags
112                         an album lookup for a specific artist will return
113                         albums as soon as this artist appears in a single track
114                         of the album.<br>
115                         For instance looking for album from "The Velvet
116                         Underground" will fetch "Last Days" and "Juno" OSTs
117                         because the band appears on the soundtrack of these two
118                         movies.<br>
119                         A solution is for you to set AlbumArtists tag to
120                         something different than the actual artist of the
121                         track. For compilations, OSTs etc. a strong convention
122                         is to use "Various Artists" for this tag.</p><p>mpd-sima is currently looking for AlbumArtists tags
123                         and avoid album where this tag is set with "Various
124                         Artists". If a single track within an album is found
125                         with AlbumArtists:"Various Artists" the complete album
126                         is skipped and won't be queued.</p></dd></dl></div></div><div class="refsect1"><a name="files"></a><h2>FILES</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">${XDG_CONFIG_HOME}/mpd_sima/mpd_sima.cfg</code></span></dt><dd><p>Configuration file.</p></dd><dt><span class="term"><code class="filename">${XDG_DATA_HOME}/mpd_sima/sima.db</code></span></dt><dd><p>SQLite DB file.</p></dd><dt><span class="term"><code class="filename">${XDG_DATA_HOME}/mpd_sima/WEB_SERVICE/</code></span></dt><dd><p>Persistent http cache.</p></dd></dl></div><p>Usually <code class="envar">XDG_DATA_HOME</code> is set to
127             <code class="filename">${HOME}/.local/share</code> and <code class="envar">XDG_CONFIG_HOME</code> to
128             <code class="filename">${HOME}/.config</code>.<br>You may override them using
129             command line option <code class="option">--var-dir</code> and <code class="option">--config</code> (cf.
130             <span class="citerefentry"><span class="refentrytitle">mpd-sima</span>(1)</span>)</p></div><div class="refsect1"><a name="feedback"></a><h2>FEEDBACK/BUGS</h2><p>The maintainer would be more than happy to ear from you, don't hesitate to send feedback, <a class="ulink" href="http://kaliko.me/id/" target="_top">http://kaliko.me/id/</a>.</p><p><acronym class="acronym">XMPP</acronym> users are welcome to join the dedicated chat room at <a class="ulink" href="kaliko.me@conf.azylum.org" target="_top">kaliko.me@conf.azylum.org</a>.</p></div><div class="refsect1"><a name="see_also"></a><h2>SEE ALSO</h2><p><span class="citerefentry"><span class="refentrytitle">mpc</span>(1)</span>, <span class="citerefentry"><span class="refentrytitle">mpd</span>(1)</span></p><p>
131         <code class="filename">/usr/share/doc/mpd-sima/</code>
132     </p></div></div></body></html>