A simple, cross-platform music scrobbler daemon. Inspired by audio software like PulseAudio and PipeWire, it can be configured to connect different sources (e.g., media players) and sinks (e.g., last.fm).
Warning
This project is still beta software. Features may break without warning (especially on macOS), scrobbling may be unreliable, and the config file format is subject to change. Use at your own risk.
Note: This README refers to the main branch. To view the README for a specific version, check out the corresponding tagged commit.
curl https://raw.githubusercontent.com/p-mng/goscrobble/refs/heads/main/scripts/install.sh | bashThis will install the latest tagged version. Set GOSCROBBLE_VERSION to a branch or tag name to install a specific version (e.g., export GOSCROBBLE_VERSION=dev).
On macOS, media-control and julienXX/terminal-notifier are required:
brew install media-control terminal-notifiergoscrobble is available on the Arch User Repository.
A configuration file is created automatically in your config directory (usually $HOME/.config/goscrobble/config.toml). See https://toml.io/en/ for TOML syntax.
Example configuration file
# track position update frequency in seconds
poll_rate = 2
# minimum playback duration in seconds
min_playback_duration = 240
# minimum playback percentage
min_playback_percent = 50
# send a desktop notification when a scrobble is saved
notify_on_scrobble = false
# send a desktop notification when a scrobble cannot be saved
notify_on_error = true
# player blacklist
blacklist = ["chromium", "firefox"]
# regex match/replace
[[regexes]]
match = " - [0-9]+ Remaster(ed)?"
replace = ""
artist = false
track = true
album = true
[[regexes]]
match = " - Radio Edit"
replace = " (Radio Edit)"
track = true
# MPRIS2 dbus interface
# https://specifications.freedesktop.org/mpris/latest/
[sources.dbus]
# dbus address: if empty, connect to the session bus
address = ""
# ungive/media-control
# https://github.com/ungive/media-control
[sources.media-control]
# path to the "media-control" binary
command = "media-control"
# media-control arguments, if empty use the following default value
arguments = ["get", "--now"]
[sinks.lastfm.default]
# replace this for sites that support the Audioscrobbler v2.0 API
# if empty, use last.fm API
base_url = "https://ws.audioscrobbler.com/2.0/"
# last.fm API key
key = "replace with last.fm API key"
# last.fm API shared secret
secret = "replace with last.fm API secret"
# last.fm session key, automatically set by "goscrobble lastfm-auth"
session_key = ""
# last.fm username, automatically set by "goscrobble lastfm-auth"
username = ""
[sinks.csv.default]
# filename to write scrobbles to, defaults to $HOME/scrobbles.csv
filename = "/home/username/scrobbles.csv"
[sinks.csv.network]
# you can define sinks multiple times using different keys
# this example defines two CSV sinks: "default" and "network"
filename = "/network/data/scrobbles.csv"You can blacklist players using Go regular expressions. Players are identified by their D-Bus service name on Linux or the bundle identifier on macOS.
The example above will block org.mpris.MediaPlayer2.chromium.instance10670 and org.mpris.MediaPlayer2.firefox.instance_1_84 on Linux and org.mozilla.firefox on macOS.
- Create an API account. Description, callback URL, and application homepage are not required.
- Open the config file and insert the newly generated API key and shared secret.
- Run
goscrobble lastfm-auth, and authenticate the application in your browser. - Return to your terminal and confirm the prompt. The session key and last.fm username will be automatically written to your config file.
tidal-hifi exposes two MPRIS media players (tidal-hifi and chromium). Right now, you should add tidal-hifi to your blacklist, as the album name is incorrectly reported (see tidal-hifi issue 505).
- FoxxMD/multi-scrobbler: scrobbler for multiple sources and clients (written in TypeScript)
- mariusor/mpris-scrobbler: MPRIS scrobbler (written in C)
- InputUsername/rescrobbled: MPRIS scrobbler (written in Rust)
- hrfee/go-scrobble: "ugly last.fm scrobbler" (written in Go)
- web-scrobbler/web-scrobbler: scrobbling browser extension (written in TypeScript)