mirror of
https://github.com/beetbox/beets.git
synced 2025-12-10 02:22:25 +01:00
aa31fea037
*All* URLs were checked manually, but only once per domain! I mostly concerned myself with URLs in documentation rather than source code because the latter may or may not have impactful changes, while the former should be straight forward. Changes in addition to simply adding an s: - changed pip and pypi references as their location has changed - MPoD (iOS app) url redirects to Regelian, so I replaced those - updated homebrew references Notable observations: - beets.io does have HTTPS set up properly (via gh-pages) - beatport.py uses the old HTTP url for beatport - as does lyrics.py for lyrics.wikia.com - https://tomahawk-player.org/ expired long ago, but the http page redirects to https regardless - none of the sourceforge subdomains have https (in 2019!)
100 lines
3.3 KiB
ReStructuredText
100 lines
3.3 KiB
ReStructuredText
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*.
|
|
|
|
.. _MPD: https://www.musicpd.org/
|
|
|
|
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 :ref:`using-plugins`).
|
|
|
|
.. _pip: https://pip.pypa.io
|
|
|
|
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.
|
|
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`_.
|
|
|
|
.. _issue: https://github.com/beetbox/beets/issues
|