ListenBrainz plugin for Jellyfin

This plugin allows you to record your music activity directly from Jellyfin server to ListenBrainz.

Visualize and share your music listening history

ListenBrainz keeps track of music you listen to and provides you with insights into your listening habits. We're completely open-source and publish our data as open data.

— ListenBrainz

Features

• Send listens of tracks you've listened to
• Send 'now playing' listens
• Submit optional MusicBrainz metadata (requires track MBID)
• Mark favorite tracks in Jellyfin as loved listens in ListenBrainz
• Sync loved listens in ListenBrainz as favorite tracks in Jellyfin (requires track MBID)
• Sync playlists from ListenBrainz to Jellyfin (weekly jams, top discoveries, etc.)
• Cache listens when ListenBrainz server cannot be reached
• Back up listens

...and probably some more to come.

More details about the plugin features and how the plugin works can be found in the documentation.

Installation

The plugin can be installed either via repository or manually. Additionally, all plugin releases are available on the releases page.

Install via repository

There are two repositories available for the plugin - stable and unstable. It is recommended to only use the stable repository.

Plugin build type	Repo URL
Stable	https://repo.xkrivo.net/jellyfin/manifest.json
Unstable/development	https://repo.xkrivo.net/jellyfin-dev/manifest.json

Unstable repository contains development versions of the plugin, which may not work correctly or be straight up broken. It should not be used, unless:

1. You are fine with all the risks of running unstable releases of software
2. Or you have been explicitly asked to use it

Adding the repository

Head over to Repositories tab in Jellyfin server settings > Plugins (advanced section), and add the repository there, using one the URLs above. Repository name does not matter, it has only an informational purpose for the server admin.

After you add the repository, you should be able to see ListenBrainz plugin in the catalog under General category. Select the version you want to install and restart the server as asked. Continue with plugin configuration.

A major plugin version is always compatible with latest minor Jellyfin version, unless in some exceptional situations. Since Jellyfin treats semver minor version as a major one, the mapping between plugin versions and Jellyfin versions is as follows:

Plugin	Jellyfin
1.x.y.z	10.7.a
2.x.y.z	10.8.a
3.x.y.z	10.8.a
4.x.y.z	10.9.a
5.x.y.z	10.10.a
6.x.y.z	10.11.a

Configuration

The complete configuration documentation is available here.

Quickstart

For plugin to be able to send listens, it needs user API token to be able to authenticate. Unfortunately, the server admin must configure the plugin for all users as there's no way to make user-configurable plugin. So the admin has an access to the ListenBrainz API tokens of all users on their server.

Minimal user configuration:

1. Open plugin settings
2. Select the user you want to configure
3. Paste the token to the API token field (you can get it from the profile page)
4. (Optional) Click on Verify to check the validity of the API token
5. Check Enable submitting listens
6. Save configuration

Debug logging

Please always make sure to provide debug logs when reporting a plugin issue. To set up debug logging, you need to modify the logging configuration of the Jellyfin server. In addition to changing the logging level, it is also necessary to update the log template, to properly display logged data.

To set up debug logging:

First, follow the steps described here to enable debug logging. Then, in the same file, you will see two log templates (outputTemplate). One template is for a console output, the other one is for a file output. If you are using the Jellyfin UI to collect the logs, then modify the File template by adding {EventId} , {ClientRequestId} and {HttpRequestId} fields.

• EventId identifies the event which is being processed (playback start/stop, user data save)
• ClientRequestId identifies a ListenBrainz API request being processed
• HttpRequestId identifies a specific HTTP request being processed

The modified template should look like this:

- "[{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz}] [{Level:u3}] [{ThreadId}] {SourceContext}: {Message}{NewLine}{Exception}"
+ "[{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz}] [{Level:u3}] [{ThreadId}] {SourceContext} {EventId} {ClientRequestId} {HttpRequestId}: {Message}{NewLine}{Exception}"

After modifying the template, restart Jellyfin server, and you should see extra whitespace (before the :) in the log like this: ... [INF] [1] Main   : Jellyfin version: "10.8.13" This is expected, as the three new fields you added earlier are only defined in this plugin, while the template affects all log messages. Unfortunately, Jellyfin does not seem to be using a logging extension which allows dynamic log templates.

Do not forget to revert these changes after you are done with capturing the logs. You can keep the template if you don't mind the additional IDs, but make sure you change the log level back to Information as debug logging can in general have an impact on the application performance.

Development

This should be somewhat similar to standard .NET project development. So, clone the repo, open it in your favorite editor, restore dependencies, and you should be good to go. Debugging setup is documented in the jellyfin plugin template.

The plugin pages are written in TypeScript, bundled with esbuild and embedded in the plugin DLL. Code quality is enforced with ESLint and Prettier (npm run lint, npm run format:check).

Manual build and installation

.NET 9.0 and Node.js are required to build the plugin. To install the .NET SDK, check out the .NET download page. To install Node.js, check out the Node.js download page.

Once the SDKs are installed, install the TypeScript dependencies first:

npm ci

Then you should be able to compile the plugin in either debug or release configuration:

dotnet publish -c Debug

dotnet publish -c Release

The npm build is automatically run before the .NET build, it is not necessary to run it manually.

Once the build is completed, the compiled DLLs should be available at: src/Jellyfin.Plugin.Listenbrainz/bin/<Debug|Release>/net9.0/

To install the plugin for the first time, copy all DLL files starting with Jellyfin.Plugin.ListenBrainz to the plugin directory in your Jellyfin config directory (${CONFIG_DIR}/plugins/ListenBrainz_1.0.0.0). Create the plugin directory if it does not exist, and make sure Jellyfin has correct permissions to access it.

Then copy all the DLL files and restart the Jellyfin server. After restarting Jellyfin, the plugin should be recognized and activated. If you forgot any of these files, then the plugin will crash during initialization and in the log, you should see which DLL is missing.

It is not necessary to copy all the files every time. For subsequent builds of the plugin it is enough to copy only the recompiled files.

Making a plugin release

1. Make sure you have updated build file
2. Create a new release in the repository
3. Check that the new version is available in the repository

Jellyfin?

This repository only contains the source code for the ListenBrainz plugin for Jellyfin Media Server. If you somehow arrived here without knowing what Jellyfin is, check out the project website.

License

TL;DR: MIT + GPLv3.

This plugin began its life as a reimplementation of the LastFM plugin. While that one does not have a license, the plugin has been now completely rewritten to the point that I believe it can be no longer considered as a derivative work. As such, I decided to license the plugin code (except some parts as described below) under the MIT license.

However, if I understand correctly, the code which depends on Jellyfin libraries, which are licenced under GPLv3, must be also licenced under GPLv3 license. And so this plugin is also licensed under the GPLv3 license.