Skip to main content

Overview

tip

Check the FAQ if you have any issues after configuration!

Configuration Types​

Sources and Clients are configured using:

  • environmental (ENV) variables
  • client/source specific json config files
  • an all-in-one json config file

MS will parse configuration from all configuration types. You can mix and match configurations but it is generally better to stick to one or the other.

MS will parse environmental variables present in the OS/container when it is run. This method means MS does not require files to run.

Use ENV-based configuration if...
  • You are the only person for whom MS is scrobbling for
  • You have a very simple setup for MS such as one scrobble Client and one Source IE Plex -> Maloja
Config Example

For Docker container...

docker run -e "SPOTIFY_CLIENT_ID=yourId" -e "SPOTIFY_CLIENT_SECRET=yourSecret" ...

For Docker Compose

docker-compose.yml
services:
    multi-scrobbler:
        image: foxxmd/multi-scrobbler
        environment:
            - SPOTIFY_CLIENT_ID=yourId
            - SPOTIFY_CLIENT_SECRET=yourSecret
            - MALOJA_URL=http://domain.tld:42010
            - MALOJA_API_KEY=1234
            # ...
        # ...

For a local/node installation export variables before running...

SPOTIFY_CLIENT_ID=yourId SPOTIFY_CLIENT_SECRET=yourSecret npm run start

Setup Sources and Clients​

See the Configuration Types above for your options for creating Source and Client configurations.

Each entry for a Source/Client includes a Configuration section that describes how to configure it using a configuration type.

Application Options​

These options affect multi-scrobbler's behavior and are not specific to any source/client.

Base URL​

Defines the URL that is used to generate default redirect URLs for authentication on spotify and lastfm -- as well as some logging hints.

  • Default => http://localhost:9078
  • Set with ENV BASE_URL or baseUrl all-in-one configuration
  • If protocol is http or no protocol is specified MS will try to use port 9078 -- to override this explicitly set the port or use https

Useful when running with docker so that you do not need to specify redirect URLs for each configuration.

Example

EX Lastfm Redirect Url is BASE_URL:PORT/lastfm/callback (when no other redirectUri is specified for lastfm configuration)

BASE_URLRedirect URL
192.168.0.101http://192.168.0.101:9078/lastfm/callback
http://my.domain.localhttp://my.domain.local:9078/lastfm/callback
http://192.168.0.101/my/subfolderhttp://192.168.0.101:9078/my/subfolder/lastfm/callback
BASE_URLRedirect URL
my.domain.local:80http://192.168.0.101:80/lastfm/callback
my.domain.local:9000http://my.domain.local:9000/lastfm/callback
192.168.0.101:4000/my/subfolderhttp://192.168.0.101:4000/my/subfolder/lastfm/callback
https://192.168.0.101https://192.168.0.101:443/lastfm/callback

Caching​

Multi-scrobbler can cache some of its data for the purpose of persisting queued and dead scrobbles after restarting.

It supports caching using either:

  • File cache stored in the CONFIG_DIR directory (next to your File/AIO file)
  • Valkey, an open-source fork of Redis.

File caching is enabled by default when no other configuration is present.

The type of cache used, and it's connection properties, can be configured through ENV or AIO config.

Caching Configuration​

File cache is stored in the CONFIG_DIR directory using the pre-defined file name ms-scrobble.cache.

It is enabled by default if CACHE_SCROBBLE, or the respective AIO configuration, is not defined.

Environmental VariableRequired?DefaultDescription
CACHE_SCROBBLENofileThe cache type to use
CACHE_SCROBBLE_CONNNoThe config directoryThe directory, within the container, to store the cache file

Debug Mode​

Turning on Debug Mode will

  • override and enable all optional "debugging" options found in configuration
  • set log output to DEBUG

Use this as a shortcut for enabling output that can be used for troubleshooting and issue reporting. Be aware that logs will likely be VERY noisy while Debug Mode is on. You should only have this mode on while gathering logs for troubleshooting and then turn it off afterwards.

To set debug mode either add it to AIO config.json

config.json
{
    "debugMode": true,
    "sources": [...],
    // ...
}

or set the ENV DEBUG_MODE=true

Disable Web​

If you do not need the dashboard and/or ingress sources, or have security concerns about ingress and cannot control your hosting environment, the web server and API can be disabled.

warning

Any ingress-based sources will be unusable (Webscrobbler, etc...) if this is disabled.

Disable using either:

  • ENV DISABLE_WEB=true
  • In All-in-One File use the top-level property "disableWeb": true

Monitoring​

Multi-scrobbler supports some common webhooks and a healthcheck endpoint in order to monitor Sources and Clients for errors.

Webhook Configurations​

Webhooks will push a notification to your configured servers on these events:

  • Source polling started
  • Source polling retry
  • Source polling stopped on error
  • Scrobble client scrobble failure

Webhooks are configured in the AIO config.json file under the webhook top-level property. Multiple webhooks may be configured for each webhook type.

Example
config.json
{
  "sources": [
    //...
  ],
  "clients": [
    //...
  ],
  "webhooks": [
    {
      "name": "FirstGotifyServer",
      "type": "gotify",
      "url": "http://192.168.0.100:8070",
      "token": "abcd"
    },
    {
      "name": "SecondGotifyServer",
      "type": "gotify",
      //...
    },
    {
      "name": "NtfyServerOne",
      "type": "ntfy",
      //...
    },
    //...
  ]
}

Gotify​

Refer to the config schema for GotifyConfig

multi-scrobbler optionally supports setting message notification priority via info warn and error mappings.

Example
config.json
{
  "type": "gotify",
  "name": "MyGotifyFriendlyNameForLogs",
  "url": "http://192.168.0.100:8070",
  "token": "AQZI58fA.rfSZbm",
  "priorities": {
    "info": 5,
    "warn": 7,
    "error": 10
  }
}

Ntfy​

Refer to the config schema for NtfyConfig

multi-scrobbler optionally supports setting message notification priority via info warn and error mappings.

Example
config.json
{
  "type": "ntfy",
  "name": "MyNtfyFriendlyNameForLogs",
  "url": "http://192.168.0.100:9991",
  "topic": "RvOwKJ1XtIVMXGLR",
  "username": "Optional",
  "password": "Optional",
  "priorities": {
    "info": 3,
    "warn": 4,
    "error": 5
  }
}

Apprise​

Refer to the config schema for AppriseConfig

multi-scrobbler supports stateless and persistent storage endpoints as well as tags/

Example
config.json
{
  "type": "apprise",
  "name": "MyAppriseFriendlyNameForLogs",
  "host": "http://192.168.0.100:8080",
  "urls": ["gotify://192.168.0.101:8070/MyToken"], // stateless endpoints
  "keys": ["e90b20526808373353afad7fb98a201198c0c3e0555bea19f182df3388af7b17"], //persistent storage endpoints
  "tags": ["my","optional","tags"]
}

Health Endpoint​

An endpoint for monitoring the health of sources/clients is available at GET http://YourMultiScrobblerDomain/health

  • Returns 200 OK when everything is working or 500 Internal Server Error if anything is not
  • The plain url (/health) aggregates status of all clients/sources -- so any failing client/source will make status return 500
    • Use query params type or name to restrict client/sources aggregated IE /health?type=spotify or /health?name=MyMaloja
  • On 500 the response returns a JSON payload with messages array that describes any issues
    • For any clients/sources that require authentication /health will return 500 if they are not authenticated
    • For sources that poll (spotify, yt music, subsonic) /health will 500 if they are not polling