beetbrainz - Man Page
Lightweight webhook listener for ListenBrainz scrobbling
Synopsis
beetbrainz
Description
Beetbrainz is a Go-based webhook listener that bridges media server playback events with scrobbling to ListenBrainz.
It processes playback events from:
- Emby
- Jellyfin
- Plex (standalone or with Tautulli)
- Local MPRIS-enabled players or MPD servers (via Beetpost)
When a playback event is received, Beetbrainz can cross-reference the played track with a local Beets database to gather enriched metadata. This may include album, year, track number, and MusicBrainz identifiers when available.
If Beets integration is unavailable, Beetbrainz will submit basic metadata directly from the webhook payload.
Requirements
To function correctly, Beetbrainz requires:
- Beets with the
webplugin installed, enabled, and running. - One supported media server (Emby, Jellyfin, Plex, etc.).
Installation
This section focuses on systemd user installations.
Fedora
Beetbrainz is available in the official Fedora repositories.
Install with:
sudo dnf5 install golang-codeberg-gbcox-beetbrainz
This will also install Beets if necessary.
After installation, configure the service before starting it.
Beets Setup
For metadata enrichment to work properly:
- Running: Start the Beets web plugin (e.g.,
beet web). - Accessible: Default address is
127.0.0.1:8337. - Correct user: The Beets web process must run as the user who owns
~/.config/beets/config.yamlandlibrary.db.
Reliability and Spooling
Beetbrainz is designed as a durable background service.
If ListenBrainz is temporarily unavailable, scrobbles are written to a local spool directory instead of being discarded.
Spool characteristics:
- Append-only JSON Lines format
- One file per day (e.g. scrobbles-YYYY-MM-DD.jsonl)
- Safe across restarts
- No silent data loss during outages
The spool directory is controlled by:
- BEETBRAINZ_SPOOL_DIR
Default:
~/.local/state/beetbrainz/spool
Replay
Queued scrobbles can be replayed manually using:
beetbrainz-replay
Replay behavior:
- Processes spool files in chronological order
- Preserves original
listened_attimestamps - Deletes spool files only after successful submission
- Safe to run multiple times
If ListenBrainz remains unavailable during replay, files are left intact.
Automatic Replay
A user-level replay service and timer are provided:
- beetbrainz-replay.service
- beetbrainz-replay.timer
Enable automatic replay:
systemctl --user enable --now beetbrainz-replay.timer
The timer runs periodically (typically hourly) and automatically drains backlog when ListenBrainz becomes reachable.
If user lingering is enabled:
loginctl enable-linger <username>
the replay timer will continue running even when logged out.
Configuration
Beetbrainz is configured via environment variables, typically set using:
systemctl --user edit beetbrainz.service
Common variables:
- USER_TOKENS
Format:
<username>:<token>
Required for authentication to ListenBrainz.- BEETS_IP
Default:
127.0.0.1- BEETS_PORT
Default:
8337- BEETBRAINZ_IP
Default:
0.0.0.0- BEETBRAINZ_PORT
Default:
5000- BEETBRAINZ_PLAYINFO
When set to
true, playback information is written back into the Beets library.
Service Management
After configuration:
systemctl --user enable beetbrainz.service
systemctl --user start beetbrainz.service
Check status with:
systemctl --user status beetbrainz.service
See Also
beetbrainz-replay(1), beets(1), systemd(1), systemctl(1)
Authors
gbcox