jellyfin-plugin-listenbrainz - GitLite

KO | EN

gitlite — search

#react #ai #golang #android #deep-learning #docker #nodejs #macos #awesome #cli #vue #pytorch #ios #mcp

jellyfin-plugin-listenbrainz

(★ 214)

ListenBrainz plugin for Jellyfin.

File Explorer

Download Latest Version (.zip)

- - bug_report.yml
  - config.yml
  - feature_request.yml
- - build-upload-publish-dev.yml
  - build-upload-publish.yml
  - build.yml
  - publish.yml
  - upload-repo.yml
  - upload.yml
- configuration.md
- how-it-works.md
- - ListenBrainz_logo.svg
  - README.md
- - Jellyfin.Plugin.ListenBrainz.csproj
  - Plugin.cs
  - PluginEventHandlerService.cs
  - PluginServiceRegistrator.cs
- - BaseApiClient.cs
  - HttpClientWrapper.cs
  - Jellyfin.Plugin.ListenBrainz.Api.csproj
  - ListenBrainzApiClient.cs
- - DateUtils.cs
  - Jellyfin.Plugin.ListenBrainz.Common.csproj
  - Utils.cs
- - HttpClient.cs
  - Jellyfin.Plugin.ListenBrainz.Http.csproj
  - Utils.cs
- - BaseClient.cs
  - Jellyfin.Plugin.ListenBrainz.MusicBrainzApi.csproj
  - MusicBrainzApiClient.cs
- - BaseApiClientTests.cs
  - Jellyfin.Plugin.ListenBrainz.Api.Tests.csproj
  - JsonEncodeTests.cs
  - LimitsTests.cs
- - EnumerableExtensionsTests.cs
  - GlobalUsings.cs
  - Jellyfin.Plugin.ListenBrainz.Common.Tests.csproj
  - StringExtensionsTests.cs
- - ClientTests.cs
  - Jellyfin.Plugin.ListenBrainz.Http.Tests.csproj
  - UtilsTests.cs
- - Jellyfin.Plugin.ListenBrainz.MusicBrainzApi.Tests.csproj
- - AudioItemMetadataTests.cs
  - Jellyfin.Plugin.ListenBrainz.Tests.csproj
  - MockPlugin.cs
- jellyfin.d.ts
.editorconfig
.gitignore
.prettierrc
build.yaml
code.ruleset
esbuild.config.mjs
eslint.config.mjs
global.json
Jellyfin.Plugin.ListenBrainz.sln
Jellyfin.Plugin.ListenBrainz.sln.DotSettings
LICENSE
package-lock.json
package.json
README.md
tsconfig.json

# Installation Guide

1. Get the code

git clone https://github.com/lyarenei/jellyfin-plugin-listenbrainz

Downloads the entire project code from GitHub to your computer.

cd jellyfin-plugin-listenbrainz

Moves into the project folder you just downloaded.

2. .NET

Medium Recommended

Prerequisites

Git Needed to download the project code from GitHub.
.NET SDK The SDK required for the dotnet command.

dotnet publish -c Debug

Type this command into your terminal and run it.

dotnet publish -c Release

Type this command into your terminal and run it.

✅ After dotnet run, check the message or address shown in the terminal.

Pulled directly from this repo's README.

3. Node.js

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm ci

Type this command into your terminal and run it.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align=center>
    <h1>ListenBrainz plugin for Jellyfin</h1>
    <image
        src="res/listenbrainz/ListenBrainz_logo.svg"
        alt="Image for ListenBrainz plugin for Jellyfin"
        width=500
        height="300"
        align=center
    />
<p>This plugin sends the music activity on your Jellyfin server to ListenBrainz.</p>
</div>

> 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.

&mdash; <cite>[ListenBrainz][LISTENBRAINZ]</cite>

---

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](doc/how-it-works.md).

# Installation

You can install the plugin from a repository or [build it yourself](#manual-build-and-installation). Every release
is also available on the [releases page][RELEASES].

## Install from a repository

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

| Plugin build type    | Repository 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

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](doc/configuration.md).

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

| 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](doc/configuration.md).

### 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](https://listenbrainz.org/profile/).
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][JELLYFIN_DEBUG]. 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:

```diff
- "[{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
<code>... &#91;INF] &#91;1] Main&nbsp;&nbsp;&nbsp;: Jellyfin version: "10.11.0"</code> — 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][PLUGIN_DEBUGGING].

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](https://dotnet.microsoft.com/download) and the [Node.js download page](https://nodejs.org)
if you need to install them.

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

```shell
npm ci
```

Then build in either configuration:

```shell
dotnet publish -c Debug
```

```shell
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](build.yaml) 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](https://jellyfin.org).

# License

TL;DR: MIT + GPLv3.

This plugin began its life as a reimplementation of
the [LastFM plugin](https://github.com/jesseward/jellyfin-plugin-lastfm).
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.

[LISTENBRAINZ]: https://listenbrainz.org

[RELEASES]: https://github.com/lyarenei/jellyfin-plugin-listenbrainz/releases

[JELLYFIN_DEBUG]: https://jellyfin.org/docs/general/administration/troubleshooting/#debug-logging

[PLUGIN_DEBUGGING]: https://github.com/jellyfin/jellyfin-plugin-template#6-set-up-debugging