Table of Contents

1. Introduction
2. What Can You Do With It?
3. Licsense
4. Prerequisites
5. Installing
   1. Use the pre-built binaries
   2. Crates.io
   3. Use the Debian package
   4. Use the Arch package
   5. Autotools source distributions
   6. Building from source
6. Getting Started
   1. Program Structure
   2. Getting Set-up
      1. MPD
      2. mppopmd
      3. mppopm
7. Status & Roadmap

Introduction

mpdpopm provides a companion daemon to MPD for maintaining play counts, ratings and last-played timestamps, along with an associated CLI for talking to the companion daemon. Similar to mpdfav, but written in Rust (which I prefer to Go), it will maintain this information in your sticker database. Along the lines of mpdcron, it will also allow you to keep that information up-to-date in your tags by invoking external (user-provided & -configured) commands.

This README focuses on obtaining & installing mpdpopm; the user manual is distributed with the package in Texinfo format. The HTML version of the user manual is hosted on my personal site.

What Can You Do With It?

Once you've installed & started mpdpopm, its daemon (mppopmd) will sit in the background noting the songs you play and updating play counts & last played timestamps in your MPD sticker database. If you'd like to rate a song, you can send mppopmd a message using your favorte MPD client, or with the mppopm CLI that comes along with this package; mppopmd will note the rating, as well.

If you'd like to make use of this information in your song selection, you can ask mppopmd to queue-up songs on this basis by saying things like:

mppopm findadd "(rating > 128)"

to add all songs with a rating greater than 128 to the play queue, or

mppopm findadd "(lastplayed <= \"2022-12-28\")"

to add all songs that haven't been played in the last year.

Licsense

mpdpopm is GPL v3 software.

Prerequisites

Music Player Daemon: "Music Player Daemon (MPD) is a flexible, powerful, server-side application for playing music. Through plugins and libraries it can play a variety of sound files while being controlled by its network protocol." If you're reading this, I assume you're already running MPD, so this document won't have much to say on installing & configuring it other than that you do need to setup the sticker database by setting sticker_file in your configuration.

If you choose to use the pre-built binaries or the Debian or Arch packages (available under releases), that's all you'll need– you can jump ahead to the section entitled Installing, below.

If you would prefer to download mpdpopm from crates.io, you'll need need the Rust toolchain ("Rust is a memory- & thread-safe language with no runtime or garbage collector"). Installing the toolchain is easy:

curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

mpdpopm is also available as an Autotools source distribution (also under releases), and of course you can just clone the repo & build the project from source. In either of those two cases you'll need the Gnu Autotools installed in addition to Rust. In the former case, grab the tarball in the format of your choice & perform the usual "./configure && make && make install" incantation. In the latter, you'll need to invoke "./bootstrap" after you clone the repo. Again, if you're considering that route, I assume you're familiar with the Autotools & won't say much about them here.

Installing

As mentioned above, you can install mpdpopm in a few different ways. In increasing order of complexity:

Use the pre-built binaries

Thanks to a suggestion by m040601, you can download pre-built binaries for each release. At the time of this writing, only Linux & MacOS are supported, and only on x86₆₄ at that. If that works for you, you can do something like:

cd /tmp
curl -L --output mpdpopm-0.3.3.tar.gz https://github.com/sp1ff/mpdpopm/releases/download/0.3.3/mpdpopm-0.3.3-x86_64-unknown-linux.tar.gz
tar xf mpdpopm-0.3.3.tar.gz
tree mpdpopm-0.3.3-x86_64-unknown-linux/
mpdpopm-0.3.3-x86_64-unknown-linux/
├── bin
│   ├── mppopm
│   └── mppopmd
└── doc
    ├── AUTHORS
    ├── ChangeLog
    ├── COPYING
    ├── NEWS
    ├── README.org
    ├── THANKS
    ├── mppopmd.conf
    ├── mppopmd.info
    └── mppopmd.service

2 directories, 10 files

Copy the binaries mppopmd (the daemon) and mppopm (the CLI) to a convenient place (e.g. /usr/local/bin or $HOME/.local/bin) and proceed to Getting Started, below.

Crates.io

If you've got the Rust toolchain installed, just say cargo install mpdpopm. The binaries will now be in $HOME/.cargo/bin, and you can proceed to Getting Started, below.

Use the Debian package

If you're running on a Debian-based Linux distribution, and you're on an x86₆₄ processor, I've begun providing a Debian binary package, courtesy of the very cool cargo-deb Cargo helper command. Just do:

cd /tmp
curl -L -O https://github.com/sp1ff/mpdpopm/releases/download/0.3.3/mpdpopm_0.3.3_amd64.deb
sudo dpkg -i mpdpopm_0.3.3_amd64.deb

The binaries will be placed in /usr/local/bin, and you can proceed to Getting Started, below.

Use the Arch package

If you're running on an Arch-based Linux distribution, I'm in the process of submitting packages to the AUR.

Autotools source distributions

If you've got the Rust toolchain as well as Autotools installed, you can build from source via Autotools:

cd /tmp
curl -L -O https://github.com/sp1ff/mpdpopm/releases/download/0.3.3/mpdpopm-0.3.3.tar.xz
tar xf mpdpopm-0.3.3.tar.xz
cd mpdpopm-0.3.3
./configure
make
make check
sudo make install

All the usual configure options apply (--prefix, e.g.) In particular, you can say --enable-debug to produce debug builds.

Building from source

Finally, and again if you have the build toolchain (Rust & Autotools) installed, you can build from source:

git clone git@github.com:sp1ff/mpdpopm.git
cd mpdpopm
./bootstrap
./configure
make
make check
sudo make install

Notice the call to ./bootstrap, in this case.

Getting Started

This README provides a "quick-start" guide to getting mpdpopm up & running. For detailed user docs, refer to the manual.

Program Structure

mpdpopm provides two programs:

1. mppopmd is the companion daemon process
2. mppopm is the associated command-line interface to the daemon

mppopmd will monitor mpd for song playback & note when songs complete; this is how it knows to increment the playcount & update the last played timestamp for each song to which you listen. mppopmd records this information (i.e. play counts, last played and ratings) using mpd stickers. A sticker is a little bit of textual information which clients can attach to songs in the form of a name-value pair. mpdpopm defines a new sticker name for each of these items & udpates the values for each song when & as requested.

Of course, other mpd clients will not, in general, be aware of mppopmd or the stickers it sets: you the user will have to bridge that gap. You could of course just fire-up netcat & start sending commands over the MPD protocol using sendmessage, but that's not particularly convenient– that's where mppopm comes in. mppopm is the client interface; one can through it instruct mppopmd to set ratings, get & set the various stickers mpdpopm knows about, and even search for songs in terms of mpdpopm attributes & add them to the play queue.

Getting Set-up

MPD

If you're reading this, I assume you already have MPD up & running, so this section will be brief. One note, prompted by user m040601, however: as mentioned above, mpdpopm leverages the MPD sticker database. I was chagrined to find that if you do not configure MPD to maintain a sticker database, all sticker commands will simply be disabled. Therefore, before setting up mpdpopm, find your mpd configuration file and check to be sure you have a sticker_file entry; something like this:

sticker_file "/home/sp1ff/lib/mpd/sticker.sql"

Check also that the you have write access to the named file & its parent directory.

mppopmd

The daemon depends on a configuration file that you'll need to provide. Most mppopmd configuration items have sensible defaults, but there are a few that will need to be customized to your MPD setup. A sample configuration file is provided with all distributions; see also the user manual for detailed documentation.

You'll likely want to run the program in the foreground initially for ease of trouble-shooting, but after that you'll probably want to run it as a daemon. Again see the manual for detailed instructions.

Once you've got the daemon running to your satisfaction, if you're on a systemd-based Linux distribution, have a look at the sample systemd unit file thanks to tanshoku.

tanshoku was kind enough to contribute a systemd unit for this purpose. At present, the build does not install it, but provides it as an example and leaves it to the user to install should they desire (and after they have edited it to suit their configuration). You can find it in ${prefix}/share/mpdpopm/examples for the Autotools distribution, /usr/local/share/mpdpopm/examples for the Debian package, and in the doc folder for the pre-built binaries.

mppopm

At this point, mpdpopm will happily monitor your playback history & keep play counts & last played timestamps for you. If you would like to rate tracks, however, you will need to somehow induce your favorite mpd client to send a "rating" message to the mpdpopm commands channel ("unwoundstack.com:commands" by default). Since this is unlikely to be convenient, I wrote an mpd client for the purpose: a little CLI called mppopm. You can simply execute

mppopm set-rating '*****'

to set the current track's rating to five "stars" (say mppopm --help for an explanation of the rating system; in brief– it's Winamp's). NB. the set rating command by default produces no output; if you want confirmation that something's happening, use the -v flag.

The CLI offers "get" & "set" commands for play counts, last played timestamps & the rating. It also provides commands for searching your songs on the basis of play count, rating & last played times in addition to the usual artist, title &c. Say mppopm --help for a full list of options, including how to tell it where the mpd server can be found on your network.

Status & Roadmap

I am currently using mpdpopm day in & day out with my music collection, but it's early days; I have chosen the version number (0.n) in the hopes of indicating that. Right now, mpdpopm is the bare-bones of an app: it's plumbing, not the sink.

Heretofore, you could use the mppopm CLI to, say, rate the current song, but in order to actually do anything with that rating in the future, you'd have had to write some kind of mpd client for yourself. With the 0.2 release, I've added support for extended MPD filter syntax that allows queries that include the stickers that mpdpopm manages– so you can now, for instance, say:

mppopm findadd "(artist =~ \"foo\") and (rating > 175)"

MPD will handle the "artist =~" clause & mpdpopm the "rating >" clause, as well as combining the results.

This will hopefully be a start to making mpdpopm into a more of a user-facing application than a developer-facing utlity.

Windows support may be some time coming; the daemon depends on Unix signal handling, the MPD Unix socket, and the Unix daemon logic, especially fork & exec… if you'd like to run it on Windows, let me know– if there's enough interest, and I can get some kind of Windows VM setup, I'll look at a port.

Longer-term, I see mpdpopm as a "dual" to mpd– mpd commits to never altering your files. mpdpopm will take on that task in terms of tags, at least. To address the "plumbing, not the sink" problem, I'd like to author a client that will handle player control (of course), but also visualization & tag editing– a complete music library solution.

Suggestions, bug reports & PRs welcome!