YAMS (Yet Another MPD Scrobbler)

features

yams is just another Last.FM scrobbler but its cooler

• authenticate with the new Last.FM [scrobbling api v2.0](https://www.last.fm/api/scrobbling) - without the need to input/store your username/password locally.
• Update your profile’s “Now Playing” track via Last.FM’s “Now Playing” [API](https://www.last.fm/api/show/track.updateNowPlaying)
• save failed scrobbles to a disk and upload them at a later date.
• timing configuration (e.g. scrobble percentage, real world timing values for scrobbling, etc.).
• prevent accidental duplicate scrobbles on rewind/playback restart/etc.
• automatic daemonization and config file generation.

requirements

• python3
• PyYAML
• psutil
• python-mpd2

installation

via pipx:

pipx install git+https://github.com/shadowash8/yams.git

setup

yams uses $MPD_HOST and $MPD_PORT to connect to mpd. run yams and follow the prompts to authenticate with last.fm.

configuration files

if missing, yams automatically generates default files based on your platform’s directories (via platformdirs):

yams.yml

primary config (usually $XDG_CONFIG_HOME)

yams.pid

daemon process id (usually $XDG_RUNTIME_DIR)

yams.log

log file (usually $XDG_STATE_HOME)

.lastfm_session

session data (usually $XDG_STATE_HOME)

scrobbles.cache

failed scrobbles cache (usually $XDG_CACHE_HOME)

help

run yams --help for the full option list. key arguments include:

-m, --mpd-host / -p, --mpd-port

set mpd connection details

-t, --scrobble-threshold

minimum percentage before scrobbling (default: 50)

-g, --generate-config

save current cli flags directly into your config file

-N, --no-daemon

run in the foreground instead of daemonizing

-k, --kill-daemon

kill a running yams daemon instance

-a, --attach

run tail -F on the active log file

contributing

• pull requests are welcome.
• code is formatted using black.
• scripts are heavily commented and entry-level friendly.

other information

• error handling: failed scrobbles retry every minute during playback or on the next scrobble. “now playing” failures are not retried.
• mpd polling: waits on mpd’s idle() when playback is stopped. use update_interval in your config to set active polling frequency.
• reconnects: if the mpd connection drops, yams attempts a lightweight reconnect every 10 seconds without crashing.
• compatibility: developed on python 3.7. tested on linux and macos; windows support is not guaranteed.
• libre.fm support: set base_url to https://libre.fm/2.0/, clear your old session files, and swap last.fm for libre.fm in the generated authentication url.