cliamp-listenbrainz

A cliamp plugin that scrobbles everything you play to ListenBrainz — the free, open-source scrobbling service powered by MusicBrainz.

Works with local files, radio, Spotify, Plex, Navidrome and any other provider cliamp plays. Modeled on the excellent cliamp-lastfm plugin, but for ListenBrainz's simpler token-based API — no API key, no secret, no session key.

Why ListenBrainz?

• One token, done. Authenticate once with a personal API token — no app registration, no OAuth dance.
• Your data is yours. ListenBrainz is open source and your listen history is freely downloadable (ListenBrainz API).
• Pinning. Pin a track to your profile — a feature Last.fm doesn't have.

Quickstart

Requires cliamp ≥ v1.63 and a ListenBrainz account.

1. Install the plugin

cliamp plugins install geokkjer/cliamp-plugin-listenbrainz
cliamp plugins trust listenbrainz

The plugin installs as listenbrainz (the cliamp-plugin- prefix is stripped). cliamp plugins trust asks you to review the source and its permissions before it runs — that's cliamp's normal approval flow.

2. Allow curl (one line in the config)

The plugin runs all ListenBrainz HTTP through curl subprocesses (via cliamp's exec permission) so a slow or unreachable ListenBrainz can never stall playback or trip cliamp's 5-second plugin deadline. Allow curl in ~/.config/cliamp/config.toml:

[plugins]
allowed_binaries = "curl"

(./setup.sh does this for you.)

3. Get your API token

Open https://listenbrainz.org/settings/, log in, and copy the API Token.

4. Configure

The easiest way is the setup script — it opens the settings page for you and writes the config:

./setup.sh

Or edit ~/.config/cliamp/config.toml by hand:

[plugins.listenbrainz]
token    = "YOUR-API-TOKEN"      # required — from listenbrainz.org/settings
username = "your-lb-username"    # optional — enables stats + pinning

5. Restart cliamp and verify

cliamp plugins call listenbrainz test

With a valid token and a track playing, this prints OK: playing_now accepted by ListenBrainz. Play a track past the halfway point and you'll see Scrobble Sent: Artist - Title in the status bar.

Usage

Keybindings

Key	Action
*	Love / unlove the current track
#	Pin / unpin the current track (requires username)
&	Cycle mode: normal → silent → off

Bindings only fire in the main view, and are listed in the Ctrl+K keymap overlay under "— plugins —".

Commands

Run from a shell while cliamp is running:

cliamp plugins call listenbrainz status   # mode, config state, queue size, current track
cliamp plugins call listenbrainz test     # verify token by submitting a "now playing"

Modes

	normal	silent	off
Scrobbling	✓	✓	✗
Now playing	✓	✓	✗
Love / Pin	✓	✓	✗
UI messages	✓	✗	✗

How it works

• Buffered, never blocking. Event hooks (play, pause, stop, scrobble) never touch the network. They write intents — scrobbles and now-playing — to the plugin's persistent store (~/.local/share/cliamp/plugins/listenbrainz/store.json), and a background worker flushes them. Every request runs in a curl subprocess via cliamp's exec API (bounded by --max-time 15), whose completion callbacks are not subject to cliamp's 5-second plugin deadline — so even a completely hung ListenBrainz can never abort a hook, stall playback, or lose a scrobble.
• Scrobbling. cliamp fires a track.scrobble event once a track is ≥ 50 % played or ≥ 4 minutes in — exactly ListenBrainz's listen criteria. The plugin queues a single listen with listened_at set to when the track actually started.
• Now playing. On play, the plugin queues a playing_now listen so your profile shows what you're listening to, and clears it when playback stops. Pausing keeps the badge (the listen is still current). It requests return_msid=true, which also gives us the recording_msid used for love feedback and pinning.
• Love / pin. Uses the cached recording_msid from the now-playing submission, falling back to a metadata/lookup by artist + track name.
• Retry & backoff. The worker runs every minute, sends scrobbles in batches of up to 20, and backs off exponentially on failures (rate limits, outages, hangs) — nothing is lost, and it all catches up when the API recovers. The next flush is always scheduled first, so even a killed callback can't stop the chain.
• Privacy. Your token never leaves the machine — it lives only in ~/.config/cliamp/config.toml, is sent only to api.listenbrainz.org, and the plugin makes no other network calls.

Troubleshooting

Symptom	Cause / fix
[ListenBrainz] Not configured on startup	No token in [plugins.listenbrainz]. Run ./setup.sh.
curl unavailable via cliamp.exec in plugins.log	The plugin needs curl allowed: add allowed_binaries = "curl" under [plugins] in config.toml, then restart. Scrobbles buffer until then.
test command prints FAILED	Check the token, then look at ~/.config/cliamp/plugins.log for the HTTP status. 401 = wrong token.
Scrobble shows "queued for retry"	Network hiccup or rate limit. The queue flushes automatically; no action needed.
* / # say "no MBID match"	ListenBrainz couldn't match the track to MusicBrainz by name. Love/pin need a match; scrobbling still works.
# says "Set username"	Pinning needs username in the config (it queries your profile).

Development

lua5.1 test/harness.lua   # runs the logic test suite (71 checks, no network)

The harness stubs the cliamp API, records every HTTP call the plugin makes, and asserts the exact payloads sent to ListenBrainz — scrobble shape, now playing, love/pin flows, rate-limit queueing and mode gating.

Credits

• Adapted from cliamp-lastfm by tetsuo76, licensed CC0.
• API details cross-checked against the ListenBrainz API docs and web-scrobbler's ListenBrainz connector.

License

MIT