# Table of Contents
1. [Introduction](#org66b2e8c)
2. [What Can You Do With It?](#org60b8c21)
3. [Prerequisites](#orgf282ba3)
4. [Installing](#installing)
1. [Use the pre-built binaries](#org93d1cca)
2. [Crates.io](#org96a340c)
3. [Use the Debian package](#org9c57fcd)
4. [Use the Arch package](#org5c824eb)
5. [Autotools source distributions](#orgdf3af24)
6. [Building from source](#org45e7dda)
5. [Getting Started](#getting_started)
1. [Program Structure](#orgc702029)
2. [Getting Set-up](#org39ef940)
1. [MPD](#org5103582)
2. [mppopmd](#org646d89e)
3. [mppopm](#orgc4621fc)
6. [Status & Roadmap](#org6debec4)
<a id="org66b2e8c"></a>
# Introduction
[mpdpopm](https://github.com/sp1ff/mpdpopm) provides a companion daemon to [MPD](https://www.musicpd.org/) for maintaining play counts, ratings and last-played timestamps, along with an associated CLI for talking to the companion daemon. Similar to [mpdfav](https://github.com/vincent-petithory/mpdfav), but written in Rust (which I prefer to Go), it will maintain this information in your sticker database. Along the lines of [mpdcron](https://alip.github.io/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](https://github.com/sp1ff/mpdpopm); the user manual is distributed with the package in [Texinfo](https://www.gnu.org/software/texinfo/) format. The HTML version of the user manual is hosted on my personal [site](https://www.unwoundstack.com/doc/mpdpopm/curr).
<a id="org60b8c21"></a>
# What Can You Do With It?
Once you've [installed](#installing) & [started](#getting_started) [mpdpopm](https://github.com/sp1ff/mpdpopm), its daemon (`mppopmd`) will sit in the background noting the songs you play and updating play counts & last played timestamps in your [MPD](https://www.musicpd.org/) 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 <= \"2020-03-27\")"
to add all songs that haven't been played in the last year.
<a id="orgf282ba3"></a>
# Prerequisites
[Music Player Daemon](https://www.musicpd.org/): "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](https://github.com/sp1ff/mpdpopm/releases)), that's all you'll need– you can jump ahead to the section entitled [Installing](#getting_started), below.
If you would prefer to download [mpdpopm](https://github.com/sp1ff/mpdpopm) from [crates.io](https://crates.io/crates/mpdpopm), you'll need need the [Rust](https://www.rust-lang.org/tools/install) 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](https://github.com/sp1ff/mpdpopm) is also available as an Autotools source distribution (also under [releases](https://github.com/sp1ff/mpdpopm/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](https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html) 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.
<a id="installing"></a>
# Installing
As mentioned above, you can install [mpdpopm](https://github.com/sp1ff/mpdpopm) in a few different ways. In increasing order of complexity:
<a id="org93d1cca"></a>
## Use the pre-built binaries
Thanks to a suggestion by [m040601](https://github.com/m040601), you can download pre-built binaries for each [release](https://github.com/sp1ff/mpdpopm/releases). At the time of this writing, only Linux & MacOS are supported, and only on x86<sub>64</sub> at that. If that works for you, you can do something like:
cd /tmp
curl -L --output mpdpopm-0.3.0.tar.gz https://github.com/sp1ff/mpdpopm/releases/download/0.3.0/mpdpopm-0.3.0-x86_64-unknown-linux.tar.gz
tar xf mpdpopm-0.3.0.tar.gz
tree mpdpopm-0.3.0-x86_64-unknown-linux/
mpdpopm-0.3.0-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](#getting_started), below.
<a id="org96a340c"></a>
## 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](#getting_started), below.
<a id="org9c57fcd"></a>
## Use the Debian package
If you're running on a Debian-based Linux distribution, and you're on an x86<sub>64</sub> processor, I've begun providing a Debian binary package, courtesy of the very cool [cargo-deb](https://github.com/mmstick/cargo-deb) Cargo helper command. Just do:
cd /tmp
curl -L -O https://github.com/sp1ff/mpdpopm/releases/download/0.3.0/mpdpopm_0.3.0_amd64.deb
sudo dpkg -i mpdpopm_0.3.0_amd64.deb
The binaries will be placed in `/usr/local/bin`, and you can proceed to [Getting Started](#getting_started), below.
<a id="org5c824eb"></a>
## Use the Arch package
If you're running on an Arch-based Linux distribution, and you're on an x86<sub>64</sub> processor, I've begun providing a Arch binary package. Just do:
cd /tmp
curl -L -O https://github.com/sp1ff/mpdpopm/releases/download/0.3.0/mpdpopm_0.3.0-1-x86_64.pkg.tar.zst
sudo pacman -U mpdpopm_0.3.0-1-x86_64.pkg.tar.zst
The binaries will be placed in `/usr/local/bin`, and you can proceed to [Getting Started](#getting_started), below.
<a id="orgdf3af24"></a>
## 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.0/mpdpopm-0.3.0.tar.xz
tar xf mpdpopm-0.3.0.tar.xz
cd mpdpopm-0.3.0
./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.
<a id="org45e7dda"></a>
## 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.
<a id="getting_started"></a>
# Getting Started
This README provides a "quick-start" guide to getting mpdpopm up & running. For detailed user docs, refer to the [manual](https://www.unwoundstack.com/doc/mpdpopm/curr).
<a id="orgc702029"></a>
## Program Structure
[mpdpopm](https://github.com/sp1ff/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](https://www.musicpd.org/doc/html/protocol.html#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](https://github.com/sp1ff/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.
<a id="org39ef940"></a>
## Getting Set-up
<a id="org5103582"></a>
### 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](https://github.com/m040601), however: as mentioned above, [mpdpopm](https://github.com/sp1ff/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](https://github.com/sp1ff/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.
<a id="org646d89e"></a>
### 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](https://www.unwoundstack.com/doc/mpdpopm/curr#mppopmd-Configuration) 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](https://www.unwoundstack.com/doc/mpdopmd/curr#mppopmd-as-a-Daemon) 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](https://github.com/tanshoku).
[tanshoku](https://github.com/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.
<a id="orgc4621fc"></a>
### mppopm
At this point, [mpdpopm](https://github.com/sp1ff/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](https://github.com/sp1ff/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 somethings 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.
<a id="org6debec4"></a>
# Status & Roadmap
I am currently using [mpdpopm](https://github.com/sp1ff/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 <span class="underline">do</span> 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](https://github.com/sp1ff/mpdpopm) manages– so you can now, for instance, say:
mppopm findadd "(artist =~ \"foo\") and (rating > 175)"
MPD will handle the "artist =~" clause & [mpdpopm](https://github.com/sp1ff/mpdpopm) the "rating >" clause, as well as combining the results.
This will hopefully be a start to making [mpdpopm](https://github.com/sp1ff/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.
Suggestions, bug reports & PRs welcome!