beetbrainz - Man Page
A lightweight Go-based webhook listener for scrobbling media server playback to ListenBrainz via Beets.
Synopsis
beetbrainz
Description
Beetbrainz is a Go-based webhook listener that bridges playback events from various media servers to ListenBrainz for scrobbling. It supports popular media servers such as Emby, Jellyfin, Plex (with or without Tautulli), and also accepts webhooks from mpris-webhook for local mpris-enabled players.
The core functionality of Beetbrainz relies on cross-referencing played tracks with your local Beets database. This process enriches the playback data with more accurate metadata, including album, year, track number, and MusicBrainz IDs, before submitting it to ListenBrainz. This ensures higher data quality for personalized recommendations and a more comprehensive collective music database. Without Beets integration, Beetbrainz will only submit basic, unvalidated metadata directly from the media server's webhook, which is highly discouraged.
Requirements
To function as intended, Beetbrainz requires the following:
- Beets
The `web` plugin for Beets must be installed, enabled, and actively running for Beetbrainz to interact with your music library.
- Media Server
One of the following media servers is required:
Emby Jellyfin Plex Plex combined with Tautulli Local mpris-enabled players via mpris-webhook
Installation
Beetbrainz is available in the official Fedora production repositories.
To install on Fedora:
1. **Install the Beetbrainz package:**
.RS
.PP
.B sudo dnf5 install golang-codeberg-gbcox-beetbrainz
.RE
This command will also ensure that beets is installed as a dependency.
After installation, it is crucial to proceed to the "Beets Setup" and "Enabling and Customizing the Systemd User Service" sections for proper configuration.
Beets Setup
Beetbrainz relies on your existing Beets installation and its web plugin for metadata enrichment. For correct functionality, your Beets web plugin must meet the following criteria:
- Running
Ensure your Beets instance, with the web plugin enabled, is actively running (e.g., by running `beet web`).
- Accessible
The Beets web plugin must be configured to listen on an IP address and port that Beetbrainz can access. The default for both Beetbrainz and the Beets web plugin is `127.0.0.1:8337`.
- Running as the correct user
The `beet` process running the web plugin must be executed by the user who owns your Beets configuration files (`~/.config/beets/config.yaml`) and your Beets database (`library.db`).
Configuration
Beetbrainz is primarily configured through environment variables. For `systemd --user` services, these are typically set within the service unit file or through user overrides.
The following environment variables can be set:
- USER_TOKENS
- Description
A single `<ListenBrainz_user>:<ListenBrainz token>` pair for authentication and submission. This specifies the ListenBrainz account to which all scrobbles will be submitted. Only one ListenBrainz account is currently supported for scrobbling.
- Format
`LISTENBRAINZ_USER:LISTENBRAINZ_TOKEN`
- Example
`USER_TOKENS="johndoe_lb:xyz123abc"`
- BEETS_IP
- Description
The IP address of your Beets web application. This is the address Beetbrainz uses to query your Beets database for metadata enrichment.
- Default
`127.0.0.1`
- Note
Incorrect configuration of this variable will cause Beetbrainz to fail connection to Beets, leading to unvalidated metadata submissions and errors.
- Example
`BEETS_IP="127.0.0.1"`
- BEETS_PORT
- Description
The port number of your Beets web application.
- Default
`8337`
- Note
This setting has no effect if `BEETS_IP` is not configured.
- Example
`BEETS_PORT="8337"`
- BEETBRAINZ_IP
- Description
The IP address that Beetbrainz should bind to and listen for incoming webhooks from your media server.
- Default
`0.0.0.0` (listens on all available network interfaces)
- Note
Set this to a specific IP address if you want Beetbrainz to listen only on a particular network interface.
- Example
`BEETBRAINZ_IP="0.0.0.0"`
- BEETBRAINZ_PORT
- Description
The port number that Beetbrainz should listen on for incoming webhook data.
- Default
`5000` (a common port for webhook listeners)
- Example
`BEETBRAINZ_PORT="5000"`
Enabling and Customizing the Systemd User Service
The `beetbrainz` service unit is installed to `/usr/lib/systemd/user/beetbrainz.service` for user-specific execution. This allows Beetbrainz to run as the currently logged-in user, which is ideal for accessing your Beets configuration and database.
Users can make overrides to this service, primarily for setting `USER_TOKENS` and for debugging, using `systemctl --user edit beetbrainz.service`.
Understanding User Service Locations
- /usr/lib/systemd/user/beetbrainz.service
The main service file installed by the package.
- ~/.config/systemd/user/beetbrainz.service.d/
The primary location for local, custom drop-in files for your user service. Files here take precedence over those in `/usr/lib/systemd/user/`.
How to Configure User Tokens and Other Overrides
To set the `USER_TOKENS` environment variable and any other desired overrides, use `systemctl --user edit`. This command automatically creates the necessary drop-in directory and file if they don't exist.
1. **Open the override file for editing:**
.RS
.PP
.B systemctl --user edit beetbrainz.service
.RE
This will open an editor (usually `nano` or `vim`) with a new, empty file.
2. **Add your customizations:** Inside the editor, add the `[Service]` section and the `Environment=` directive to set your `USER_TOKENS`.
.RS
.PP
.B Example: Setting USER_TOKENS for your ListenBrainz account:
.PP
.nf
# ~/.config/systemd/user/beetbrainz.service.d/override.conf
[Service]
Environment="USER_TOKENS=your_listenbrainz_username:your_listenbrainz_token"
# Optional: If you need to override other settings, add them here.
# For example, to enable debug logging:
# Environment="BEETBRAINZ_LOG_LEVEL=debug"
.fi
.PP
*Replace `your_listenbrainz_username` with your actual ListenBrainz username and `your_listenbrainz_token` with your ListenBrainz API token.*
.RE
3. **Save and exit the editor.**
4. **Enable and start the user service:**
After making changes, enable the service to start automatically on login and then start it manually for the first time:
.RS
.PP
.B systemctl --user enable beetbrainz.service
.B systemctl --user start beetbrainz.service
.RE
5. **Check the service status (optional):**
You can verify that the service is running correctly:
.RS
.PP
.B systemctl --user status beetbrainz.service
.RE
See Also
beets(1), systemctl(1), dnf5(8)