BEETBRAINZ(1)

💖 BEETBRAINZ 💖

okay bestie, sit down, hydrate, because we're about to talk about beetbrainz — a lightweight webhook listener for ListenBrainz scrobbling, and honestly? she's iconic. it's a page in the User Commands manual and she is serving.

---

✨ SYNOPSIS ✨

beetbrainz

that's it. that's the whole vibe. no flags, no drama, just run her. 💅

---

🌸 DESCRIPTION 🌸

Beetbrainz is a Go-based webhook listener that bridges media server playback events with scrobbling to ListenBrainz. like a lil matchmaker for your music and your stats. no cap.

She processes playback events from:

• Emby
• Jellyfin
• Plex (standalone or with Tautulli)
• Local MPRIS-enabled players or MPD servers (via Beetpost)

When a playback event shows up, 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. it's giving thorough. 🎀

If Beets integration is unavailable, Beetbrainz will submit basic metadata directly from the webhook payload. she's flexible like that fr fr.

---

🫶 REQUIREMENTS 🫶

For Beetbrainz to function correctly, she requires:

• Beets with the web plugin installed, enabled, and running.
• One supported media server (Emby, Jellyfin, Plex, etc.).

that's the whole shopping list bestie, don't overthink it 💖

---

🎀 INSTALLATION 🎀

This section focuses on systemd user installations. yes, user installations. keep that in mind.

Fedora

Beetbrainz is available in the official Fedora repositories. slay ✨

Install with:

sudo dnf5 install golang-codeberg-gbcox-beetbrainz

This will also install Beets if necessary. two birds, one command, we love efficiency 💅

After installation, configure the service before starting it. like, actually configure it first. don't rawdog the start.

---

🦋 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.yaml and library.db.

that last one is the one people mess up, bestie. same user. same vibes. periodt.

---

💜 RELIABILITY AND SPOOLING 💜

Beetbrainz is designed as a durable background service. she does not simply evaporate when things go sideways.

If ListenBrainz is temporarily unavailable, scrobbles are written to a local spool directory instead of being discarded. no silent loss, no ghosting your own listening history 😭

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_at timestamps
• Deletes spool files only after successful submission
• Safe to run multiple times

If ListenBrainz remains unavailable during replay, files are left intact. she's not gonna nuke your backlog out of spite, she's a professional 🫶

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. set it and forget it energy ✨

If user lingering is enabled:

loginctl enable-linger <username>

the replay timer will continue running even when logged out. logged out but still scrobbling? that's main character behavior 👑

---

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

no token, no scrobbles bestie. USER_TOKENS is the whole personality of this setup 💅

---

⭐ SERVICE MANAGEMENT ⭐

After configuration:

systemctl --user enable beetbrainz.service
systemctl --user start beetbrainz.service

Check status with:

systemctl --user status beetbrainz.service

look at her go. so productive. so stable. we're obsessed 🥹💖

---

👀 SEE ALSO 👀

beetbrainz-replay(1), beets(1), systemd(1), systemctl(1)

go read those too, iykyk 📚

---

💀 AUTHORS 💀

gbcox

---

that's the whole page bestie, you ate that 🎀✨

and for the cute sign-off: this lil masterpiece is part of the Beetbrainz Documentation, dated March 3, 2026. screenshot it, frame it, put it on the fridge. 💖🦋🌸