goscrobble

Description

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).

Features

• Lightweight and privacy-oriented
• Available on macOS and Linux
• Many supported media players ("sources")
  • all media players on Linux implementing MPRIS2 (e.g., mpv, VLC, Spotify, and many others)
  • all media players on macOS using ungive/media-control
  • Tidal using the tidal-hifi JSON API
  • Tidal using the TidaLuna EddyAPI
• Supports different "sinks"
  • last.fm
  • one or more local CSV files

Note

This project is still beta software. Features may break without warning, scrobbling may be unreliable, and the config file format is subject to change.

Note: This README refers to the main branch. To view the README for a specific version, check out the corresponding tagged commit.

Installation

macOS

1. Add the homebrew tap: brew tap p-mng/goscrobble.
2. Install the package using brew install goscrobble.
3. Generate the config file using goscrobble check-config (see below).
4. Enable the service using brew services start goscrobble.

Arch Linux

1. Install goscrobble from the Arch User Repository.
2. Generate the config file using goscrobble check-config (see below).
3. Enable the systemd user service using systemctl --user enable --now goscrobble.service.

Manual Installation (Linux/macOS)

Manual installation is only recommended for advanced users.

1. Install the binary using go install github.com/p-mng/goscrobble@latest.
2. Install the service file (goscrobble.service if on Linux¹, io.github.p-mng.goscrobble.plist if on macOS²); replace $GOSCROBBLE_PATH with the binary location from the previous step.
3. If on macOS, install media-control and terminal-notifier.
4. Enable and start the service/launch agent.

¹) Documentation for systemd/Linux: https://wiki.archlinux.org/title/Systemd/User#Basic_setup

²) Documentation for launchd/macOS: https://support.apple.com/guide/terminal/script-management-with-launchd-apdc6c1077b-5d5d-4d35-9c19-60f2397b2369/mac

Configuration

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 = ""

[sources.media-control]
# path to the "media-control" binary
command = "/opt/homebrew/bin/media-control"
# media-control arguments, if empty use the following default value
arguments = ["get", "--now"]

# https://github.com/Mastermindzh/tidal-hifi
# TIDAL Hi-Fi JSON API
[sources.tidal-hifi]
# endpoint to fetch data from
endpoint = "http://localhost:47836/current"

# https://github.com/espeon/luna-plugins
# EddyAPI plugin for TidaLuna
[sources.eddyapi]
endpoint = "http://localhost:3665/now-playing"
# include the version of the song when scrobbling (e.g., "Remastered")
include_version = false

[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.

Connect last.fm account

1. Create an API account. Description, callback URL, and application homepage are not required.
2. Open the config file and insert the newly generated API key and shared secret.
3. Run goscrobble lastfm-auth and authenticate the application in your browser.
4. Return to your terminal and confirm the prompt. The session key and last.fm username will be automatically written to your config file.

Known issues

Double scrobbles when using tidal-hifi

tidal-hifi exposes two MPRIS media players (tidal-hifi and chromium). You should add either tidal-hifi or chromium to your blacklist to prevent double scrobbling.

Similar projects

• 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)