Skip to main content

# Listenbrainz (Endpoint)

This Source enables multi-scrobbler to accept scrobbles from outside applications as if it was a Listenbrainz server.

If your service/player has a "Scrobble to Listenbrainz" feature and there is an option to set the Listenbrainz URL then multi-scrobbler can accept scrobbles from that service/player by imitating a real Listenbrainz server.

Other Uses

- To scrobble to Listenbrainz, create a Listenbrainz (Client)
- To monitor and re-scrobble activity from your Listenbrainz account, create a Listenbrainz (Source)

## Setup​

Scenario Picker

Use one of the scenarios below based on how on your service(s) (things "scrobbling" to Multi-Scrobbler using this Source) will need to interact with MS.

- One Service
- Many Services, Same User
- Many Services, Many Users, Can use Tokens
- Many Services, Many Users, Cannot use Tokens
- Service cannot use standard URL

> You have one service, like Navidrome, that will scrobble to Multi-Scrobbler.

Configure one Listenbrainz Endpoint Source. Use the standard base URL to configure your service and set a Token, if necessary. Use the same Token in MS as you do in your service.

> You may have more than one service that will scrobble to Multi-Scrobbler, like Navidrome and Panoscrobbler.

> All of these services will scrobble for the same user (you) and all of the scrobbles should go to the same Clients.

Configure one Listenbrainz Endpoint Source. Use the standard base URL to configure your service and configure a Token in MS, if necessary. Use the same token for all your services as you configure in MS.

> You have more than one service that will scrobble to Multi-Scrobbler, like Navidrome and Panoscrobbler.

> Some of these services should scrobble for different users, scrobble to different Clients, or generally be treated differently (such as for transforms).

> All of these services can accept a Token to authenticate a Listenbrainz user/account.

Configure one Listenbrainz Endpoint Sources per service that should be treated differently. That is, if multiple services are all "the same user" then you only need one Source for that entire group of services.

For each Listenbrainz Endpoint Source, configure a different Token. Use that same token when configuring Listenbrainz for the associated service.

All Listenbrainz Endpoint Sources should use the same standard base URL.

> You have more than one service that will scrobble to Multi-Scrobbler, like Navidrome and Panoscrobbler.

> Some of these services should scrobble for different users, scrobble to different Clients, or generally be treated differently (such as for transforms).

> All, or some, of these services cannot accept a Token to authenticate a Listenbrainz user/account.

This is not a common scenario but if it fits your usecase then use these guidelines to differentiate your services:

Configure one Listenbrainz Endpoint Sources per service that should be treated differently. That is, if multiple services are all "the same user" then you only need one Source for that entire group of services.

- For any groups of services that can accept a token, use the instructions for Many Services, Many Users, Can use Tokens
- For any groups of services that cannot accept a token...
  - You can still configure a Source without a Token. Any services not using a token will use this "default" Source.
  - If multiple groups cannot use a token, or the groups cannot use the standard base URL, then use different base url Slugs.

> You have one service, like Navidrome, that will scrobble to Multi-Scrobbler.

> You have already tried the One Service scenario with both standard base URL and neither is working.

This is not a common scenario. Check the Troubleshooting URL section before trying this.

At this point, you can try to use a different base url Slug. Your service must be able to set a "fully custom" URL for Listenbrainz IE it must allow you to set more than just a domain/host.

### Standard Base URL​

In most scenarios you should use one of the following as the base URL when configuring your service to scrobble to multi-scrobbler:

- `http://myMultiScrobblerIP:9078`
- `http://myMultiScrobblerIP:9078/1/`

Default Scrobble Submit URL

Multi-scrobbler will accept Listenbrainz scrobbles at

    http://myMultiScrobblerIP:9078/1/submit-listens

which is the standard Listenbrainz server path for scrobbling.

### Token​

Most Listenbrainz clients require an Authentication Token to be provided during setup. This value can be anything you want but ensure you use the same value for `token` (ENV `LZE_TOKEN`) in your configuration for this Listenbrainz Endpoint Source.

If your service does not require a token, or does not let you set one, then do not configure it for this Source either.

### Multiple Sources​

If you need configure more than one Listenbrainz Endpoint Source then MS can differentiate scrobbles based on Token so that you can use the same, standard base URL for many users.

However, if you cannot configure multiple tokens for your scenario you may also use a URL Slug to tell MS which Source belongs to a specific user. This is not a common scenario and should only be used if Token configuration is not sufficient or not possible.

Different URL Base (Slug)

When a slug is defined in ENV/File config MS will listen for listenbrainz `submit-listens` requests using the slug as the base route path. Example:

    LZE_SLUG=foobar

MS will accept requests for `submit-listens` (scrobble submissions and now playing) at

    http://myMultiScrobblerIP:9078/api/listenbrainz/foobar
    http://myMultiScrobblerIP:9078/api/listenbrainz/foobar/submit-listens

## Setup for Popular Apps​

### Navidrome​

Details

Set the ListenBrainz.BaseURL (env `ND_LISTENBRAINZ_BASEURL`) to `http://myMultiScrobblerIP:9078/1/`

### Music Assistant​

Details

Music Assistant Docs

- In your Music Assistant UI navigate to Settings -> Plugins
- Click Add a plugin
  - Add ListenBrainz Scrobbler
- In the ListenBrainz Scrobbler configuration screen:
  - User Token is the Token you configured
  - Toggle Show advanced settings
    - Base URL is the URL you can configured, or the equivalent of `http://myMultiScrobblerIP:9078` for your MS instance
- Save the configuration and you are ready to scrobble

To troubleshoot any errors, and assuming you are using Home Assistant, view the Logs in the Music Assistant Add-ons. Please include these logs in any reported issue.

## Troubleshooting URL​

If you think your service should be able to use the standard base URL but it is not working follow these steps before trying the the base URL Slug.

#### Verify URL Format​

Some service may require `http/https` in the URL format (`http://myMSDomainOrIp:9078`) while others may not (`myDomainOrIp:9078`). Check the docs for your service to see if they specify this or have an example. Try both versions, if possible, to see if one works.

Some Services Require HTTPS

Some services that can scrobble to a custom Listenbrainz URL may require the URL to have a real domain (`example.com`) and/or use SSL (`https://`). In this case you should setup multi-scrobbler behind a reverse proxy to support this functionality.

#### Is MS is Reachable?​

Verify that MS can be accessed by your service, or from the same host as the service is running. See the FAQ for guidance on troubleshooting ingress connection issues.

#### Service Logging​

If you service has accessible logging, check to see if it outputs the URL it is trying to reach when authenticating the Listenbrainz account/user, or trying to make a scrobble request.

If you decide to report this issue, please include this logging in your issue.

## Configuration​

- ENV
- File
- AIO

Configuration Type

This is configuration for the ENV Config Type.

Environmental Variable | Type | Default | Description
--- | --- | --- | ---
`LZE_ID` | string |  | A globally unique ID EX `myComponentId`
`LZE_NAME` | string | Value of `LZE_ID` | A vanity name EX `My Cool Component`
`LZE_ENABLE` | boolean | true | Should this component be used?
`LZE_SLUG` | string |  | When using multiple sources without tokens, or not using a standard base URL, this is the URL base path that should be used to identify scrobbles for this source
`LZE_TOKEN` | string |  | If an LZ submission request contains this token in the Authorization Header it will be used to match the submission with this Source
`LZE_USERNAME` | string |  | The listenbrainz "username" to associate with this Source

Bold/Italic = Required

Config Structure

This displays the structure of the File Configuration for a endpointlz type Source with all possible properties, their shape, and descriptions/types. Use this to understand how to write a valid config.

Loading ...
Config Example

This displays an example config file of a endpointlz Source File Configuration that adheres to the shown Config Structure.

- text mode lets you edit the JSON directly.
- tree mode gives you a guided point-and-click editing experience that always keeps the JSON syntax valid.

Both modes validate that the configuration is correct. Any errors show up as squiggly lines.

important

Only source endpointlz configs will validate correctly in the editor but both source and client endpointlz configs are allowed in the real `CONFIG/endpointlz.json`

After you finish editing, switch to text and then copy all text to get a completed config.

Config Example Mobile Experience

This displays an example config file of a endpointlz Source File Configuration that adheres to the shown Config Structure.

The example config file editor is meant for a larger screen experience so only the read-only example is shown. Please use this site on a tablet/laptop/desktop to enable file editor features.

CONFIG/endpointlz.json

    [
      {
        "name": "LZ for Navidrome",
        "id": "myLzNavidrome",
        "enable": true,
        "data": {
          "token": "myToken"
        }
      }
    ]

Config Structure

This displays the structure of the all-in-one (`config.json`) configuration with all possible properties, their shape, and descriptions/types. Use this to understand how to write a valid config.

Select the endpointlz type from the respective `sources` node below, then expand it.

Loading ...
Config Example

This displays an example config file of a all-in-one (`config.json`) configuration that includes a endpointlz Source that adheres to the shown Config Structure.

- text mode lets you edit the JSON directly.
- tree mode gives you a guided point-and-click editing experience that always keeps the JSON syntax valid.

Both modes validate that the configuraion is correct. Any errors show up as squiggly lines.

After you finish editing, switch to text and then copy all text to get a completed config.

Config Example Mobile Experience

This displays an example config file of a all-in-one (`config.json`) configuration that includes a endpointlz Source that adheres to the shown Config Structure.

The example config file editor is meant for a larger screen experience so only the read-only example is shown. Please use this site on a tablet/laptop/desktop to enable file editor features.

CONFIG/config.json

    {
      "sources": [
        {
          "name": "LZ for Navidrome",
          "id": "myLzNavidrome",
          "enable": true,
          "data": {
            "token": "myToken"
          },
          "type": "endpointlz"
        }
      ]
    }