mpris-webhook - Man Page
Bridge local media playback to ListenBrainz scrobbling
Synopsis
mpris-webhook
Description
mpris-webhook is an optional service that connects your local media playback, specifically from mpris-enabled players, with your MusicBrainz scrobbling via ListenBrainz. It sends scrobbles to a Beetbrainz instance, which enriches the data before submitting it to ListenBrainz. This program is designed for use with content residing in your local Beets database.
Requirements
To use mpris-webhook, the following are required:
- mpris-enabled players: Such as qmmp or Elisa.
- Beetbrainz: Essential for enriching scrobbles before submission to ListenBrainz.
Configuration
mpris-webhook is primarily configured through environment variables. These are typically set within its systemd service unit file or through user overrides.
- MPRIS_WEBHOOK_URL
The URL where mpris-webhook sends its data. This should point to your Beetbrainz instance's mpris webhook endpoint. Default: http://localhost:5000/mpris Example: MPRIS_WEBHOOK_URL="http://localhost:5000/mpris"
- MPRIS_WEBHOOK_LOG_LEVEL
Controls the verbosity of the mpris-webhook logs. Default: info Example: MPRIS_WEBHOOK_LOG_LEVEL="info"
- MPRIS_ALLOWLIST
A comma-separated list of mpris player names from which mpris-webhook will accept events. Default: qmmp,elisa Example: MPRIS_ALLOWLIST="qmmp,elisa"
- MPRIS_DEFAULT_USER
The default user associated with the scrobbles. %u will resolve to the username of the user running the service. Default: %u Example: MPRIS_DEFAULT_USER="%u"
Under normal circumstances, no additional user configuration is required. The default settings in mpris-webhook.service should suffice. Override configurations can be made via systemctl --user edit mpris-webhook.service.
Installation
mpris-webhook is currently available in the copr gbcox/dogfood repository.
1. Activate the COPR repository:
sudo dnf copr enable gbcox/dogfood
2. Install the mpris-webhook package:
sudo dnf5 install mpris-webhook
This command will also ensure that beetbrainz is installed as a dependency.
3. To disable the repository (optional):
sudo dnf copr disable gbcox/dogfood
Enabling and Customizing the Systemd User Service
The mpris-webhook service unit is designed for user-specific execution, allowing it to run as the currently logged-in user for interaction with mpris-enabled players.
End users can make overrides to this service, primarily for setting environment variables or for debugging, using systemctl --user edit mpris-webhook.service.
Understanding User Service Locations
- /usr/lib/systemd/user/mpris-webhook.service: The main service file installed by the package.
- ~/.config/systemd/user/mpris-webhook.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 Overrides
To set any 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:
systemctl --user edit mpris-webhook.service
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 desired variables.
Example: Setting MPRIS_WEBHOOK_LOG_LEVEL to debug:
# ~/.config/systemd/user/mpris-webhook.service.d/override.conf [Service] Environment="MPRIS_WEBHOOK_LOG_LEVEL=debug"
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:
systemctl --user enable mpris-webhook.service systemctl --user start mpris-webhook.service
5. Check the service status (optional): You can verify that the service is running correctly:
systemctl --user status mpris-webhook.service
See Also
beetbrainz(1), beets(1), qmmp(1), elisa(1), systemctl(1)
Authors
The mpris-webhook project is maintained by gbcox.
Online documentation: <https://codeberg.org/gbcox/mpris-webhook/>