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

---

Please note that this plugin is not affiliated with ListenBrainz or Jellyfin projects. It is independently maintained and all issues with this plugin should be reported here instead of the respective project's communication channels.

---

Features

• Send listens of the tracks you play
• Send 'now playing' listens
• Include optional MusicBrainz metadata (needs a recording/track MBID)
• Mark favorite Jellyfin tracks as loved recordings in ListenBrainz
• Mark loved ListenBrainz recordings as favorite Jellyfin tracks (needs a recording MBID)
• Sync playlists generated by ListenBrainz into Jellyfin (user-created ones not supported yet)
• Cache the listens while the ListenBrainz server is unreachable (and resend them later)
• Back up the listens to local files

...and probably some more to come.

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

Installation

You can install the plugin from a repository or build it yourself. Every release is also available on the releases page.

Install from a repository

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

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

In the Jellyfin server settings, open Plugins (advanced section) and then the Repositories tab, and add one of the URLs above. The name you give the repository is purely informational.

The ListenBrainz plugin then shows up in the catalog under the General category. Install the version you want, restart the server when asked, and continue with the configuration.

Each major plugin version targets one Jellyfin version. Jellyfin bumps its minor version for breaking changes, so the two line up like this:

Configuration

The complete configuration documentation is available here.

Quickstart

The plugin needs an API token before it can send anything. Since Jellyfin has no support for per-user plugin settings, the server administrator configures the plugin on behalf of every user.

To set up a user:

1. Open the plugin settings.
2. Select the user on the User Config tab.
3. Grab the API token from the ListenBrainz profile page.
4. Paste it into the ListenBrainz API token field.
5. (Optional) Click Check to verify the token.
6. Tick Enable submitting listens.
7. Save.

Debug logging

Please always attach debug logs when you report a plugin issue. Getting them means changing the logging configuration of the Jellyfin server: both the log level and the log template, since the default template hides some of the data the plugin logs.

Start by enabling debug logging as described here. The same file holds two outputTemplate entries, one for console output and one for file output. If you collect logs through the Jellyfin interface, add {EventId}, {ClientRequestId} and {HttpRequestId} to the file template:

• EventId identifies the event being processed (playback start, playback stop, user data save).
• ClientRequestId identifies the ListenBrainz API request being processed.
• HttpRequestId identifies the individual HTTP request.

The result 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}"

Restart the server afterwards. Other log lines will now have extra spaces before the :, like ... [INF] [1] Main   : Jellyfin version: "10.11.0" — that is expected, because only this plugin fills in the three new fields while the template applies to everything.

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 it is recommended to change the log level back to Information as debug logging can in general have an impact on the application performance.

Development

This is a fairly ordinary .NET project — clone it, open it in your editor of choice, restore the dependencies, and you are ready to go. For the debugging setup, see the Jellyfin plugin template.

The plugin pages are written in TypeScript, bundled with esbuild and embedded in the plugin DLL. ESLint and Prettier are used for static code analysis and formatting (npm run lint, npm run format:check).

Manual build and installation

Building the plugin requires .NET 9.0 and Node.js. See the .NET download page and the Node.js download page if you need to install them.

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

npm ci

Then build in either configuration:

dotnet publish -c Debug

dotnet publish -c Release

The npm build runs automatically as part of the .NET build, so there is no need to trigger it manually.

The compiled DLLs end up in 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 the build file is up to date.
2. Create a new release in the repository.
3. Check that the new version shows up in the repository.

Jellyfin?

This repository only contains the source code of the ListenBrainz plugin for the Jellyfin Media Server. If you somehow ended up here without knowing what Jellyfin is, have a look at 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.