MPD_SIMA.CFG(5)

📦
version 0.18.2 · 7 versions
, in debian bookworm, ubuntu noble

💖 MPD_SIMA.CFG(5) — the mpd-sima config manual, part one 💖

okay bestie, welcome to the mpd-sima configuration page ✨ this is the MPD_sima config file docs and we're gonna go through every single option together, no skips, no shortcuts, because you deserve to actually understand your daemon 🫶

🌸 NAME 🌸

mpd_sima.cfg — mpd-sima configuration. that's it, that's the name, short and iconic 💅

🌈 DESCRIPTION 🌈

this manual page documents, briefly, the config options you can use in your user configuration file (peep the FILES section for where that lives, iykyk). lowkey everything you can tweak lives in here ✨

🎀 EXAMPLES 🎀

🦋 File tags queue mode (offline mode) 🦋

here's a whole example of autoqueue using file tags only. no internet required, we're going fully offline and it's giving self-sufficient queen 👑

[MPD]
# Uses defaults for MPD connection
#host = localhost
#port = 6600
#password = s3cr3t

[sima] # Setup internal plugins
# Tags plugin falls back to Random if nothing is found then Crop the queue
internal = Tags, Random, Crop
history_duration = 48  # 48h / 24 = 2 days
queue_length = 2       # triggers autoqueue when 2 tracks remains to play

[tags]
# Look for files with tagged with genre "electronica" OR "IDM" OR "glitch"
genre = electronica, IDM, glitch

[crop]
# keep 30 played tracks in playlist
consume = 30

see how it all fits together?? the tags plugin looks for your genres, random catches whatever's left, and crop keeps the queue from becoming a whole mess 💖

💜 Album queue mode using last.fm recommendations (online mode) 💜

and here's the album queue version, using the online recommendations system. this one's for when you want full albums, not just lil singles ✨

[sima]
history_duration = 96  # 4 days in hours, get a larger history for album mode
queue_length = 5

[crop]
consume = 20

[lastfm]
queue_mode = album
album_to_add = 1

notice the history_duration is way bigger here because album mode wants a bigger history to work with. more context, better picks, periodt 🌸

👑 CONFIGURATION FILE 👑

so the config file is made of sections, each one led by a [section] header, and then followed by name: value entries. continuations work in the classic RFC 822 style (go look at section 3.1.1, "LONG HEADER FIELDS", if you wanna be thorough). name=value also works, so pick your fave, no judgement 🫶

lines that start with # or ; get ignored and are perfect for comments. Nota Bene: inline comments are possible using # too, so you can gossip right next to your settings 💅

the default values are the ones shown in the option lists below. if you don't set anything, that's what you get ✨

🍓 MPD section 🍓

this section is for configuring how mpd-sima talks to MPD: the host address, the port, and the password if you need one.

[MPD]

  • host=localhost — set the MPD host. use an IP or an FQDN, whatever you got 💖
  • port=6600 — set the host port to access MPD on.
  • password=s3cr3t — set the MPD password to use. do NOT use this option if you haven't enabled password protected access on your MPD server, bestie, it's not gonna do anything good for you 😭

🌸 log section 🌸

configuring the logging, because we love receipts 📝

[log]

  • logfile= — file to log to, usually in dæmon mode. the default (empty or unset) is to log to stdin/stdout.
  • verbosity=info — logging verbosity. your choices are debug, info, warning, error.

🧚 Process daemonization 🧚

configuring the process daemon, aka how this thing runs in the background being mysterious ✨

[daemon]

  • daemon=false — whether to daemonize the process or not. false means no, true means yes go be a background queen 👑
  • pidfile= — where to store the process ID.

💅 sima section 💅

this is the core mpd-sima configuration. the main character section, honestly.

[sima]

  • internal=Lastfm, Random, Crop — mpd-sima's plugin management for internal source plugins and contrib (aka external plugins).

the plugins list is a comma separated string list.

optional plugin configuration lives in its own section. for instance, an "AwesomePlugin" declared here gets its config from the corresponding section "[awesomeplugin]".

the default list of plugins to load at startup is: Lastfm,Random,Crop.

Crop is a utility plugin, it does not queue any tracks (see below for the details).

Random will queue a track at random if other plugins did not return any tracks.

you can add and combine as many plugins here as you want, go off 💖

the priority may be used to order them.

  • history_duration=8 — how far to look back in history to avoid playing the same track/title twice. duration is in hours.

the history_duration is also used to give priority to artists you haven't played recently. artists/tracks that aren't in the scope of history have higher priority ✨

  • queue_length=2 — threshold value that triggers the queue process.
  • musicbrainzid=true — use MusicBrainzIdentifier to search music (mainly for artists). default is True. switch to False if you don't have MusicBrainzIdentifier set for at least 80% of your music library.

consider using these metadata because it enhances artist/album/track identification a lot. use Picard to tag your files: https://picard.musicbrainz.org/.

  • repeat_disable_queue=true — prevent disabling queuing in repeat play mode.
  • single_disable_queue=true — prevent disabling queuing in single play mod. (yes, that's exactly how it's written, we keep it verbatim bestie 🙈)

🌿 Crop section 🌿

the crop plugin's configuration:

[crop]

  • consume=10 — how many played tracks to keep in the queue. lets you maintain a fixed length queue. set it to some negative integer to keep all played tracks.
  • priority=10 — plugin priority.

🎲 Random section 🎲

when no similar tracks are found, it falls back to random queuing. iconic backup plan honestly 💅

the Random plugin's configuration:

[random]

  • track_to_add=1 — how many track(s) to add.
  • flavour=sensible — different modes, aka random flavours, are available: pure, sensible.
    • pure: pure random choice, even among recently played tracks.
    • sensible: use play history to filter the chosen tracks.
  • priority=50 — plugin priority.

💖 LastFm section 💖

the LastFM plugin's configuration:

[lastfm]

  • queue_mode=track — queue mode to use, among track, top and album (peep the QUEUE MODE section for info about queue modes).
  • max_art=20 — maximum number of similar artists to retrieve from your local media library. when set to something superior to zero, it tries to get as many similar artists from your media library as it can.
  • depth=1 — how many artists to base the similar artists search on. the first is the last played artist, and so on back in the history. higher depth generates wider suggestions, and it might help reduce looping over the same artists.
  • single_album=false — prevent queueing a track from the same album (it often happens with OSTs). only relevant in "track" queue mode.
  • track_to_add=1 — how many track(s) to add. only relevant in top and track queue modes. this is actually an upper limit, so min(max_art, track_to_add) will be used.
  • album_to_add=1 — how many album(s) to add. only relevant in album queue modes.
  • track_to_add_from_album=0 — how many track(s) to add from each selected album. only relevant in album queue modes. when set to 0 or lower, the whole album is queued.
  • cache=True — whether or not to use the on-disk persistent http cache. when set to "true", sima will use a persistent cache for its http client. the cache is written along with the dbfile in: $XDG_DATA_HOME/mpd_sima/http/WEB_SERVICE. if set to "false", caching is still done, but in memory.
  • priority=100 — plugin priority.

🌈 Genre section 🌈

the Genre plugin's configuration.

this plugin lets you do offline autoqueuing based only on the files' genre tag.

it will try to queue tracks with similar genres (the track's genre being read from tags).

[genre]

  • queue_mode=track — queue mode to use, among track, album (see the QUEUE MODE section for more info).
  • single_album=false — prevent queueing a track from the same album (it often happens with OSTs). only relevant in "track" queue mode.
  • priority=80 — plugin priority.
  • track_to_add=1 — how many track(s) to add.
  • album_to_add=1 — how many album(s) to add. only relevant in album queue mode.

🦋 Tags section 🦋

the Tags plugin's configuration. there is no default configuration for this plugin — it does not work out of the box, you have to set it up yourself bestie 😭

this plugin lets you do offline autoqueuing based only on file tags. the supported tags are 'comment', 'date', 'genre', 'label' and 'originaldate'.

on top of those supported tags, you can also use an MPD filter. please refer to the MPD protocol documentation for more on that.

all tag entries in this section are ANDed as a single MPD filter to look for titles in the library. and on top of that, for each tag, comma separated values are also ORed. for instance, setting "genre=rock" and "date=1982,1983,1984,1985,1986,1987,1988,1989" will end up looking for tracks tagged with genre rock and date within 1982 through 1989. using an MPD filter to replace date you can achieve the same thing with the following setting: "genre=rock" and "filter=(date =~ '198[2-9]+')" — provided your MPD server was compiled with libpcre ✨

[tags]

  • queue_mode=track — queue mode to use, among track, album (see the QUEUE MODES section for info).
  • single_album=false — prevent queueing a track from the same album (it often happens with OSTs). only relevant in "track" queue mode.
  • filter= — you can use any valid MPD filter here, as defined in the MPD protocol documentation.
  • comment=
  • date=
  • genre=
  • label=
  • originaldate=
  • priority=80 — plugin priority.
  • track_to_add=1 — how many track(s) to add.
  • album_to_add=1 — how many album(s) to add. only relevant in album queue mode.

👑 QUEUE MODES 👑

different queue modes are available with some plugins (check for queue_mode presence in the plugin config, bestie 🔍).

mpd-sima tries preferably to choose among unplayed artists, or at least artists that haven't been played recently. we love a considerate queen 💅

  • track — queue a similar track chosen at random from a similar artist.
  • top — queue a track from a similar artist, chosen among "top tracks" according to last.fm data mining.
  • album — queue a whole album chosen at random from a similar artist.
Nota Bene: due to the track point of view of the database build upon track tags, an album lookup for a specific artist will return albums as soon as this artist appears in a single track of the album. for instance, looking for an album from "The Velvet Underground" will fetch "Last Days" and "Juno" OSTs, because the band appears on the soundtrack of these two movies. a solution is for you to set the 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.
mpd-sima is currently looking for AlbumArtists tags and avoids albums 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't be queued. 🙈

🗂️ FILES (where ur stuff lives) 🗂️

ok so here's the lil map of everywhere sima keeps its things, bestie. bookmark this fr.

  • ${XDG_CONFIG_HOME}/mpd_sima/mpd_sima.cfg — the configuration file itself. the whole vibe lives here 💅
  • ${XDG_DATA_HOME}/mpd_sima/sima.db — the SQLite internal DB file. it stores ur play history and ur blocklists, so don't go deleting it unless u want amnesia 🧠💀
  • ${XDG_DATA_HOME}/mpd_sima/WEB_SERVICE/ — the HTTP cache. just cache things, minding its own business 🎀

quick heads up about those env vars: usually XDG_DATA_HOME is set to ${HOME}/.local/share and XDG_CONFIG_HOME is set to ${HOME}/.config (for regular users, anyway). u can totally override them with the command line options --var-dir and --config — cf. mpd-sima(1) if u wanna peek at those ✨

👀 SEE ALSO 👀

💌 FEEDBACK/BUGS 💌

bestie the maintainer would be more than happy to hear from u (they wrote "ear" but we know what they meant 😭🫶). do not hesitate to send feedback, ok? like genuinely, slide into the inbox:

and for my XMPP girlies — ur so welcome to join the dedicated chat room at:

  • kaliko.me@conf.azylum.org

it's giving community, it's giving support group for people who love auto-queueing bangers 🦋

👑 AUTHOR 👑

kaliko — that's the icon, that's the moment, that's the main character who wrote all this 🌈

2009-2022, kaliko — respect the OGs, periodt 💖

and that's the whole page babes 💅 this was MPD_SIMA.CFG(5) — no version number beyond that, dated Nov 04, 2022, and now u know everything about it. go queue something iconic 🔥🎀

📦 where this page comes from