beetbrainz - Man Page
A lightweight Go-based webhook listener for MusicBrainz scrobbling via ListenBrainz.
Synopsis
beetbrainz
Description
Beetbrainz is a Go-based webhook listener that bridges media server playback events with MusicBrainz scrobbling via ListenBrainz. It processes playback events from media servers such as Emby, Jellyfin, Plex, or Plex combined with Tautulli. It also accepts webhooks from Beetpost for tracks played on local MPRIS-enabled players or MPD servers.
Upon receiving a playback event, Beetbrainz cross-references the played track with a local Beets database to gather enriched, accurate metadata. This enriched data is then submitted as a scrobble to ListenBrainz, with submissions ideally linked to precise MusicBrainz database entries for unparalleled data accuracy and consistency.
The use of a Beets database is crucial for accurate scrobbles, allowing for the inclusion of album, year, track number, and MusicBrainz IDs. Without Beets integration, Beetbrainz will only submit basic, unvalidated metadata directly from the media server's webhook, which is highly discouraged.
Requirements
To function correctly, Beetbrainz requires the following:
- Beets: The `web` plugin must be installed, enabled, and actively running to allow Beetbrainz to interact with your music library.
Media Server: One of the following:
- Emby
- Jellyfin
- Plex (standalone or with Tautulli)
- Local MPRIS-enabled players or MPD servers (via Beetpost)
Installation
This section details installation on supported systems, with a focus on `systemd --user` installations.
Fedora
Beetbrainz is available in the official Fedora production repositories.
To install the Beetbrainz package:
sudo dnf5 install golang-codeberg-gbcox-beetbrainz
This command will also install Beets as a dependency.
After installation, it is critical to proceed to the "Beets Setup" and "Enabling and Customizing the Systemd User Service" sections for correct configuration.
Beets Setup
Beetbrainz relies on your existing Beets installation and its web plugin for metadata enrichment. For proper functionality, your Beets web plugin must be:
- Running: Ensure your Beets instance (with the web plugin enabled) is actively running (e.g., using `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 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 database (`library.db`).
Configuration
Beetbrainz is configured primarily through environment variables. For `systemd --user` services, these are typically set within the service unit file or via user overrides.
- USER_TOKENS
- Description: A single `<ListenBrainz_user>:<ListenBrainz token>` pair for authentication and submission. All scrobbles will be submitted to this ListenBrainz account.
- Format: `LISTENBRAINZ_USER:LISTENBRAINZ_TOKEN`
- Note: The `<ListenBrainz_user>` key must correspond to your actual ListenBrainz username. Only one ListenBrainz account is currently supported.
- Example: `USER_TOKENS="johndoe_lb:xyz123abc"`
- BEETS_IP
- Description: The IP address of your Beets web application, used by Beetbrainz to query your Beets database for metadata enrichment.
- Default: `127.0.0.1`
- Note: Crucial for Beets integration. Incorrect configuration will lead 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: 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.
- Default: `0.0.0.0` (listens on all available network interfaces)
- Note: Set to a specific IP 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`
- 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, allowing it to run as the currently logged-in user and access Beets configuration and database files in the user's home directory.
End users will typically make overrides to this service, mainly for `USER_TOKENS` and debugging, using `systemctl --user edit beetbrainz.service`.
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.
How to Configure User Tokens and Other Overrides
To set the `USER_TOKENS` environment variable and other overrides, use `systemctl --user edit`. This command creates the necessary drop-in directory and file if they don't exist.
1. .B Open the override file for editing:
systemctl --user edit beetbrainz.service
This will open an editor (e.g., `nano` or `vim`) with a new, empty file.
2. .B Add your customizations:
Inside the editor, add the `[Service]` section and the `Environment=` directive to set `USER_TOKENS`.
# ~/.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"
Replace `your_listenbrainz_username` with your actual ListenBrainz username and `your_listenbrainz_token` with your ListenBrainz API token.
3. .B Save and exit the editor.
4. .B Enable and start the user service:
After making changes, enable the service to start automatically on login and then start it manually:
systemctl --user enable beetbrainz.service systemctl --user start beetbrainz.service
5. .B Check the service status (optional):
Verify the service is running correctly:
systemctl --user status beetbrainz.service
See Also
beets(1), systemd(1), systemctl(1)
Authors
gbcox