2 .\" Title: mpd_sima.cfg
3 .\" Author: kaliko <kaliko@azylum.org>
4 .\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
6 .\" Manual: mpd-sima 0.16.1 User Manual
10 .TH "MPD_SIMA\&.CFG" "5" "12/17/2020" "mpd-sima" "mpd-sima 0.16.1 User Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
25 .\" disable justification (adjust text to left margin only)
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
31 mpd_sima.cfg \- mpd\-sima will try to maintain some titles ahead in the queue following different policies\&. This manual document the configuration file for mpd\-sima\&.
34 This manual page documents briefly
36 configuration options available in user configuration file (see
37 the section called \(lqFILES\(rq)\&.
39 .SS "File tags queue mode (offline mode)\&."
41 Here is an example of autoqueue using file tags only\&.
52 # Setup internal plugins
54 history_duration=48 # 2 days
58 # Look for files with tagged with genre "electonica" OR "IDM" OR "glitch"
59 genre = electonica, IDM, glitch
62 # keep 30 played tracks in playlist
70 .SS "Album queue mode using last\&.fm recommendations (online mode)\&."
72 Here is an example of album queue configuration using online recommendations system\&.
83 history_duration=48 # 2 days
91 # keep 30 played tracks in playlist
99 .SH "CONFIGURATION FILE"
101 The configuration file consists of sections, led by a
103 header and followed by
105 entries, with continuations in the style of RFC 822 (see section 3\&.1\&.1, \(lqLONG HEADER FIELDS\(rq);
107 is also accepted\&. Lines beginning with
111 are ignored and may be used to provide comments (\fINota Bene:\fR
112 inline comment are possible using
113 \fI\*(Aq#\*(Aq\fR)\&.
115 The default values are used in the options lists below\&.
118 This section is meant to configure MPD access, MPD host address / port and password if necessary\&.
124 \fBhost=\fR\fIlocalhost\fR
126 Set MPD host\&. Use IP or FQDN\&.
129 \fBport=\fR\fI6600\fR
131 Set host port to access MPD to\&.
134 \fBpassword=\fR\fIs3cr3t\fR
136 Set MPD password to use\&. Do not use this option if you don\*(Aqt have enabled password protected access on your MPD server\&.
148 File to log to, usually in d\(aemon mode\&.
150 Default (empty or unset) is to log to stdin/stdout\&.
153 \fBverbosity=\fR\fIinfo\fR
155 Logging verbosity among
161 .SS "Process daemonization"
163 Configure process daemon\&.
171 whether to daemonize process or not\&.
176 Where to store process ID\&.
180 Core mpd_sima\&.cfg configuration\&.
190 \fBinternal=\fR\fILastfm, Random, Crop\fR
192 mpd\-sima\*(Aqs plugin management for internal source plugin and contrib (ie\&. external plugins)\&.
195 Plugins list is a comma separated string list\&.
198 Optional plugin\*(Aqs configuration lays in its own section\&.
200 For instance a "AwesomePlugin" declared here gets its configuration from the corresponding section "[awesomeplugin]"\&.
202 The default list of plugins to load at startup:
203 \fBLastfm\fR,\fBRandom\fR,\fBCrop\fR\&.
207 is an utility plugin, it does not queue any tracks (cf\&. below)\&.
211 will queue a track at random if other plugins did not return any tracks\&.
215 You can add, combine here as many plugins you want\&.
218 The priority may be used to order them\&.
221 \fBhistory_duration=\fR\fI8\fR
223 How far to look back in history to avoid to play twice the same track/title (duration in hours)\&.
227 \fBhistory_duration\fR
228 is also used to give priority to not recently played artists\&.
231 \fBqueue_length=\fR\fI2\fR
233 Threshold value triggering queue process\&.
236 \fBmusicbrainzid=\fR\fItrue\fR
238 Use MusicBrainzIdentifier to search music (mainly for artists)\&. Default is True, switch to False if you don\*(Aqt have MusicBrainzIdentifier set for at least 80% of you music library\&.
241 Consider using these metadata as it enhances a lot artist/album/tracks identification\&. Use Picard to tag your file:
242 \m[blue]\fB\%https://picard.musicbrainz.org/\fR\m[]\&.
245 \fBrepeat_disable_queue=\fR\fItrue\fR
247 Prevent disabling queuing in repeat play mode\&.
250 \fBsingle_disable_queue=\fR\fItrue\fR
252 Prevent disabling queuing in single play mode\&.
256 crop plugin\*(Aqs configuration:
262 \fBconsume=\fR\fI10\fR
264 How many played tracks to keep in the queue\&. Allows you to maintain a fixed length queue\&. Set to some negative integer to keep all played tracks\&.
267 \fBpriority=\fR\fI10\fR
273 Random plugin\*(Aqs configuration:
279 \fBtrack_to_add=\fR\fI1\fR
281 How many track(s) to add\&.
284 \fBflavour=\fR\fIsensible\fR
286 When no similar tracks are found, falling back to random queuing\&. Different mode, aka random flavour, are available:
299 \fIpure\fR, pure random choice, even among recently played track\&.
310 \fIsensible\fR, use play history to filter chosen tracks\&.
321 \fIgenre\fR, Not implemented yet\&.
326 \fBpriority=\fR\fI50\fR
332 LastFM plugin\*(Aqs configuration\&.
338 \fBqueue_mode=\fR\fItrack\fR
340 Queue mode to use among
346 the section called \(lqQUEUE MODES\(rq
347 for info about queue modes)\&.
350 \fBmax_art=\fR\fI10\fR
352 Maximum number of similar artist to retrieve from local media library\&.
354 When set to something superior to zero, it tries to get as much similar artists from media library\&.
359 How many artists to base on similar artists search\&.
362 The first is the last played artist and so on back in the history\&. Highter depth generates wider suggestions, it might help to reduce looping over same artists\&.
365 \fBsingle_album=\fR\fIfalse\fR
367 Prevent from queueing a track from the same album (it often happens with OST)\&.
370 Only relevant in "track" queue mode\&.
373 \fBtrack_to_add=\fR\fI1\fR
375 How many track(s) to add\&. Only relevant in
379 queue modes\&. This is actually an upper limit, min(\fBmax_art\fR,
380 \fBtrack_to_add\fR) will be used\&.
383 \fBalbum_to_add=\fR\fI1\fR
385 How many album(s) to add\&. Only relevant in
390 \fBtrack_to_add_from_album=\fR\fI0\fR
392 How many track(s) to add from each selected albums\&. Only relevant in
394 queue modes\&. When set to 0 or lower the whole album is queued\&.
397 \fBcache=\fR\fITrue\fR
399 Whether or not to use on\-disk persistent http cache\&.
401 When set to "true", sima will use a persistent cache for its http client\&. The cache is written along with the dbfile in:
404 $XDG_CONFIG_HOME/mpd_sima/http/WEB_SERVICE\&.
407 If set to "false", caching is still done but in memory\&.
410 \fBpriority=\fR\fI100\fR
416 Tags plugin\*(Aqs configuration\&. There is no default configuration for this plugin, it does not work out of the box\&.
418 This plugin permits offline autoqueuing based on files tags only\&. Supported tags are
419 \fB\*(Aqcomment\*(Aq\fR,
420 \fB\*(Aqdate\*(Aq\fR,
421 \fB\*(Aqgenre\*(Aq\fR,
422 \fB\*(Aqlabel\*(Aq\fR
424 \fB\*(Aqoriginaldate\*(Aq\fR\&. It currently supports single track queuing only, no album mode for this plugin\&.
426 In addition to supported tags above you can use an MPD filter\&. Please refer to MPD protocol documentation for more\&.
428 All entries in this section are ANDed as a single MPD filter to look for titles in the library\&. Moreover, with tags, comma separated values are also ORed\&.
431 For instance setting "\fBgenre=rock\fR" and "\fBdate=1982,1983,1984,1985,1986,1987,1988,1989\fR" will end up looking for track tagged with genre
433 and date within 1985 through 1990\&.
436 Using an MPD filter to replace
438 you can achieve the same with the following setting: "\fBgenre=rock\fR" and "\fBfilter=(date =~ \*(Aq198[2\-9]+\*(Aq)\fR" (provided your MPD server was compiled with libpcre)\&.
444 \fBqueue_mode=\fR\fItrack\fR
446 Queue mode to use among
450 the section called \(lqQUEUE MODES\(rq
451 for info about queue modes)\&.
456 You can use here any valid MPD filter as defined in MPD protocol documentation\&.
475 \fBpriority=\fR\fI80\fR
480 \fBtrack_to_add=\fR\fI1\fR
482 How many track(s) to add\&.
485 \fBalbum_to_add=\fR\fI1\fR
487 How many album(s) to add\&. Only relevant in
493 Different queue modes are available with some plugins (check for
495 presence in plugin config)\&.
497 mpd\-sima tries preferably to chose among unplayed artists or at least not recently played artist\&.
501 Queue a similar track chosen at random from a similar artist\&.
506 Queue a track from a similar artist, chosen among "top tracks" according to last\&.fm data mining\&.
511 Queue a whole album chosen at random from a similar artist\&.
516 Due to the track point of view of database build upon tracks tags an album lookup for a specific artist will return albums as soon as this artist appears in a single track of the album\&.
519 For instance looking for album from "The Velvet Underground" will fetch "Last Days" and "Juno" OSTs because the band appears on the soundtrack of these two movies\&.
522 A solution is for you to set AlbumArtists tag to something different than the actual artist of the track\&. For compilations, OSTs etc\&. a strong convention is to use "Various Artists" for this tag\&.
524 mpd\-sima is currently looking for AlbumArtists tags and avoid album where this tag is set with "Various Artists"\&. If a single track within an album is found with AlbumArtists:"Various Artists" the complete album is skipped and won\*(Aqt be queued\&.
528 ${XDG_CONFIG_HOME}/mpd_sima/mpd_sima\&.cfg
530 Configuration file\&.
533 ${XDG_DATA_HOME}/mpd_sima/sima\&.db
538 ${XDG_DATA_HOME}/mpd_sima/WEB_SERVICE/
540 Persistent http cache\&.
546 ${HOME}/\&.local/share
548 \fBXDG_CONFIG_HOME\fR
552 You may override them using command line option
560 The maintainer would be more than happy to ear from you, don\*(Aqt hesitate to send feedback,
561 \m[blue]\fB\%https://kaliko.me/contact/\fR\m[]\&.
564 users are welcome to join the dedicated chat room at
565 \m[blue]\fBkaliko\&.me@conf\&.azylum\&.org\fR\m[]\&.
571 /usr/share/doc/mpd\-sima/
574 \fBkaliko\fR <\&kaliko@azylum\&.org\&>
576 Wrote this man page and is currently leading MPD_sima project\&.
580 Copyright \(co 2009-2020 kaliko
583 This manual page was written for the Debian system (and may be used by others)\&.
585 Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 3 published by the Free Software Foundation\&.
587 On Debian systems, the complete text of the GNU General Public License can be found in
588 /usr/share/common\-licenses/GPL\&.