MPDStats Plugin

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 play_count and skip_count.

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 work.

Installing Dependencies

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

Add the mpdstats plugin to your configuration (see Using Plugins).

Usage

Use the mpdstats command to fire it up:

$ beet mpdstats

Configuration

To configure the plugin, make an mpd: section in your configuration file. The available options are:

  • host: The MPD server hostname. Default: The $MPD_HOST environment variable if set, falling back to localhost otherwise.

  • port: The MPD server port. Default: The $MPD_PORT environment 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. Default: yes.

  • 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.

Warning

This has only been tested with MPD versions >= 0.16. It may not work on older versions. If that is the case, please report an issue.