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.

Secrets Interpolation​

When using File or AIO Configuration, Multi-Scrobbler can interpolate Environmental Variables into your json files. This can be used, for example, to keep sensitive data (like Last.fm Client/Secret) out of your configuration files so that they can be committed to git.

Multi-scrobbler will look for patterns in text fields within all of your json files:

  • Some part of the text field matches: [[MY_ENV]]
  • Is replaced by the value of the Environmental Variable named MY_ENV
Example

Given this Last.fm File config:

lastfm.json
[
  {
    "name": "myLastFmClient",
    "configureAs": "client",
    "data": {
      "apiKey": "[[MY_APIKEY]]",
      "secret": "[[MY_SECRET]]",
      "redirectUri": "http://localhost:9078/lastfm/callback"
    }
  }
]

And these environmental variables, in this scenario set through environment in the docker compose installation:

MY_APIKEY=a89cba1569901a0671d5a9875fed4be1
MY_SECRET=ec42e09d5ae0ee0f0816ca151008412a

The resulting json multi-scrobbler would use:

lastfm.json
[
  {
    "name": "myLastFmClient",
    "configureAs": "client",
    "data": {
      "apiKey": "a89cba1569901a0671d5a9875fed4be1",
      "secret": "ec42e09d5ae0ee0f0816ca151008412a",
      "redirectUri": "http://localhost:9078/lastfm/callback"
    }
  }
]
Caveats
  • ENV variable names/interpolation keys are case-insensitive
  • Interpolation only works for string values within json. This cannot be used for numbers, booleans, objects, etc...
Missing ENVS

Multi-scrobbler will not throw an error if the environmental value is not found. Instead, it will leave the string as-is and log a warning (WARN level) with the names of the missing environmental variable names like so:

WARN : [App] [Sources] [spotify Secrets] Matched: None | Unmatched: SPOTIFY_SECRET
ENV Name Collisions

Verify that interpolation keys/environmental variable names you will use do not collide with existing ENV names used by multi-scrobbler. Use the docs search to verify the name you want to use is not already used elsewhere by multi-scrobbler.

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 caches some activities to persist important data across restarts, reduce external API calls, and make some actions faster.

All of the activities below are always cached in-memory with an optional, configurable secondary store for persistence.

Queued and Failed Scrobbles are cached so that any un-scrobbled data you have is persisted across restarts of multi-scrobbler.

tip

By default, this data use a Secondary File store, configured for you automatically.

If you have configured a persisted volume/bind mount for configuration (/config is mounted in docker compose) then you are already done. If you are not persisting this directory then you should consider setting up Valkey Cache for this.

Configuration​

Use any Secondary Cache, the config examples below show the default values:

Environmental VariableRequired?DefaultDescription
CACHE_SCROBBLENofileThe cache type to use
CACHE_SCROBBLE_CONNNo/config

Secondary Caching Configuration​

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

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

Example

Environmental VariableRequired?DefaultDescription
CACHE_SCROBBLENofileThe cache type to use
CACHE_SCROBBLE_CONNNo/configThe 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