Automatic MPD "smart playlist" creator with minimal but hackable setup.

Project maintained by uriel1998 Hosted on GitHub Pages — Theme by mattgraham


Automatic MPD playlist or party mode creator to provide complexity and randomness while autoqueuing MPD without relying on external services.

mpdq logo

mpdq in action


  1. About
  2. License
  3. Prerequisites
  4. Installation
  5. Setup
  6. Usage
  7. TODO

1. About

mpdq is a auto-queing system for MPD to create a flexible and configurable “party mode” effect with randomization and (re)discovery of your own music. Inspired by the eclectic soundtracks of Letterkenny, High Fidelity, Doom Patrol, and many more. (More explanation for why is at my blog.

mpdq will autoqueue random tracks from your existing music library, with (very) configurable weighting by genre and simple defaults.

Because it uses mpd’s own data, new tracks and changes to your music library will be incorporated when mpd is updated.

If you are looking for the older, heaver, and BPM-using version of mpdq, those files are in the bpm_version directory of this repository.

2. License

This project is licensed under the MIT License. For the full license, see LICENSE.

3. Prerequisites

These are probably already installed or are easily available from your distro on linux-like distros:

4. Installation

This file (example provided) contains only the following lines:


The last two manage the size of queue that mpdq maintains and how many hours after playing a song that mpdq will not play it again. Defaults are:

(no password)

See below under Setup for the difference in “modes”.

5. Setup

The behavior of mpdq is governed by simple instruction files, as many (or few) as you desire. The location of the instruction file does not matter, and must be specified on the command line. Without an instruction file, mpdq will just shuffle through your entire library with an equal weight to each genre.

Each instruction file is a series of lines in the format genre=weight like so:


Rather than go through all the genres and subgenres of your music library and explicitly defining each one, the Default line assigns a weight to all genres not otherwise explictly named. Genres with higher number values will show up more often. In the example above, all genres have a weight of “1” except for Rock and Classical. Rock will show up more often, while Classical will not appear at all with a value of “0”.

This allows for both very eclectic selections (as with the example above) or very focused selections, such as with the example below:


Capitalization Matters Here

mpdq can also create an example instruction file with all genres listed so that you can check your genre names properly. It won’t hurt to have all the genres listed, but it is totally unneeded.

The instruction file should end in a newline. If it does not, mpdq will add one automatically.


There are three possible weighting modes for mpdq:

If you do not have mode defined, it defaults to simple.

6. Usage

mpdq [-d #][-c /path/to/file][-khe]

mpdq has the following command line switches:

mpdq will automatically pause if MPD is not set to:

So if you want to have “default” behavior back from MPD without interference from mpdq, but want to leave the process running, just toggle any of those values for MPD.

mpdq is meant to be run in the background. Because you define the hostname, it does not have to be on the same machine running MPD.

mpdq logs what songs it has played, and will not repeat the same song during the time specified in mpdq.ini.

systemd unit

If you wish to use mpdq as a systemd unit, this template works for me (obviously change the home directory and user as appropriate, named mpdq.service:

Description=Start mpdq service

ExecStart=/home/steven/apps/mpdq/mpdq -c /home/steven/.config/mpdq/example_instruction_file
ExecStop=/home/steven/apps/mpdq/mpdq -k


Adjusting to changes

If mpdq is running for any length of time, there will be library changes. I realized this after adding a bunch of standup albums with the new genre “Standup” and suddenly had Steven Wright talking after “Love Will Tear Us Apart”. To fix this possible problem, you first have to set Default=0 in the instruction file loaded by systemd. Then you have to have mpdq get restarted whenever the MPD database changes. You can either use monit or fswatch to make this happen.

Reloading using monit

If you have mpdq set up as a systemd unit, reloading it if there’s a change to the MPD database is pretty easy with this configuration (again, changing path names as appropriate:

(The “every 2 cycles” is because of the delay as mpdq starts up.)

check process mpdq with pidfile /tmp/
  every 2 cycles
  start program "/bin/systemctl start mpdq.service"
  stop program "/bin/systemctl stop mpdq.service"
  depends on mpd_db

check file mpd_db with path /home/steven/.mpd/tag_cache
   if changed timestamp then restart

using fswatch

If you would rather use the fswatch utility to achive the same end, have cron call this script at a regular interval:

/usr/local/bin/fswatch /home/steven/.mpd/tag_cache | sudo /bin/systemctl stop mpdq.service && sudo /bin/systemctl start mpdq.service


Steven Saus injects people with radioactivity for his day job, but only to serve the forces of good.