mpdstats is a plugin for beets that collects statistics about your listening
habits from MPD. It collects the following information about tracks:
play_count: The number of times you fully listened to this track.
skip_count: The number of times you skipped this track.
last_played: UNIX timestamp when you last played this track.
rating: A rating based on
To gather these statistics it runs as an MPD client and watches the current state
of MPD. This means that
mpdstats needs to be running continuously for it to
This plugin requires the python-mpd2 library in order to talk to the MPD server.
Install the library from pip, like so:
$ pip install python-mpd2
mpdstats plugin to your configuration (see Using Plugins).
mpdstats command to fire it up:
$ beet mpdstats
To configure the plugin, make an
mpd: section in your
configuration file. The available options are:
- host: The MPD server hostname.
$MPD_HOSTenvironment variable if set, falling back to
- port: The MPD server port.
$MPD_PORTenvironment variable if set, falling back to 6600 otherwise.
- password: The MPD server password. Default: None.
- music_directory: If your MPD library is at a different location from the beets library (e.g., because one is mounted on a NFS share), specify the path here.
- strip_path: If your MPD library contains local path, specify the part to remove here. Combining this with music_directory you can mangle MPD path to match the beets library one. Default: The beets library directory.
- rating: Enable rating updates.
- rating_mix: Tune the way rating is calculated (see below). Default: 0.75.
A Word on Ratings¶
Ratings are calculated based on the play_count, skip_count and the last action (play or skip). It consists in one part of a stable_rating and in another part on a rolling_rating. The stable_rating is calculated like this:
stable_rating = (play_count + 1.0) / (play_count + skip_count + 2.0)
So if the play_count equals the skip_count, the stable_rating is always 0.5. More play_counts adjust the rating up to 1.0. More skip_counts adjust it down to 0.0. One of the disadvantages of this rating system, is that it doesn’t really cover recent developments. e.g. a song that you loved last year and played over 50 times will keep a high rating even if you skipped it the last 10 times. That’s were the rolling_rating comes in.
If a song has been fully played, the rolling_rating is calculated like this:
rolling_rating = old_rating + (1.0 - old_rating) / 2.0
If a song has been skipped, like this:
rolling_rating = old_rating - old_rating / 2.0
So rolling_rating adapts pretty fast to recent developments. But it’s too fast. Taking the example from above, your old favorite with 50 plays will get a negative rating (<0.5) the first time you skip it. Also not good.
To take the best of both worlds, we mix the ratings together with the
rating_mix factor. A
rating_mix of 0.0 means all
rolling and 1.0 means all stable. We found 0.75 to be a good compromise,
but fell free to play with that.