Skip to main content

Configuration

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.

This is done by passing environmental variables and so does not require any files to run MS.

  • Using a docker container EX docker run -e "SPOTIFY_CLIENT_ID=yourId" -e "SPOTIFY_CLIENT_SECRET=yourSecret" ...
  • Using a local installations by exporting variables before running MS EX SPOTIFY_CLIENT_ID=yourId SPOTIFY_CLIENT_SECRET=yourSecret node index.js

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

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

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 (Plex, Tautulli, etc...) if this is disabled.

Disable using either:

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

Source Configurations​

Spotify​

To access your Spotify history you must register an application to get a Client ID/Secret. Make sure to also whitelist your redirect URI in the application settings.

note

If your Spotify player has Automix enabled and Spotify uses it for your playlist/queue then MS cannot accurately determine when a track will end. This is because the track is "mixed" in your queue with a shorter play time than its actual length and Spotify does not report this modified play time in its API. This does not affect MS's ability to scrobble from Spotify but it will affect the accuracy of the duration MS reports was played.

Configuration​

Environmental VariableRequired?DefaultDescription
SPOTIFY_CLIENT_IDYes
SPOTIFY_CLIENT_SECRETYes
SPOTIFY_REDIRECT_URINohttp://localhost:9078/callbackURI must end in callback

Plex​

Find your Plex Token and make note of the URL and Port used to connect to your Plex instance.

Allowed Users and Defaults

Multi-scrobbler will automatically scrobble for these users by default:

  • The User authenticated with the Plex Token
  • and the Local User

The Local User (PLEX_LOCAL_USER) is how Plex identifies anyone directly accessing the Plex UI from a local IP (who does not need to login).

To allow MS to scrobble for other users use usersAllow or PLEX_USERS_ALLOW (env) from the below configuration docs. However, because you are overriding the default settings you must also explicitly list the authenticated user and the Local User if you want them to also be able to scrobble.

Examples
Defaults​

If usersallow and PLEX_USERS_ALLOW are not defined then the Plex Token authenticated User and Local User will be scrobbled for.

Only A Specific User​
  • "usersallow": ["SomeUser"] or
  • PLEX_USERS_ALLOW: SomeUser

Only the Plex user SomeUser will be scrobbled for. The Plex Token authenticated user and the Local User will not be scrobbled for.

A Specific User + Defaults​

(Assuming the plex authenticated user is FoxxMD)

  • "usersallow": ["FoxxMD", "PLEX_LOCAL_USER", "SomeUser"] or
  • PLEX_USERS_ALLOW: FoxxMD,PLEX_LOCAL_USER,SomeUser

The Plex user SomeUser, the Plex Token authenticated user (FoxxMD) and the Local User will be scrobbled for.

Allowed Libraries and Defaults

By default multi-scrobbler will only scrobble media found in Plex libraries that are labelled as Music.

  • librariesAllow or PLEX_LIBRARIES_ALLOW will override this

Configuration​

Environmental VariableRequired?DefaultDescription
PLEX_URLYesThe URL of the Plex server IE http://localhost:32400
PLEX_TOKENYesThe Plex Token to use with the API
PLEX_USERS_ALLOWNoComma-separated list of usernames (from Plex) to scrobble for
PLEX_USERS_BLOCKNoComma-separated list of usernames (from Plex) to disallow scrobble for
PLEX_DEVICES_ALLOWNoComma-separated list of devices to scrobble from
PLEX_DEVICES_BLOCKNoComma-separated list of devices to disallow scrobbles from
PLEX_LIBRARIES_ALLOWNoComma-separated list of libraries to allow scrobbles from
PLEX_LIBRARIES_BLOCKNoComma-separated list of libraries to disallow scrobbles from

Tautulli​

Potentially Deprecated

Multi-scrobbler >= 0.8.8 supports a Plex Source that directly uses the API and removes the need to use Tautulli since it does not require Plex Pass.

Please see this issue for discussion on deprecating Tautulli and provide your input.

Check the instructions on how to setup a notification agent.

Configuration​

Environmental VariableRequiredDefaultDescription
TAUTULLI_USERNoThe a comma-delimited list of usernames to scrobble tracks for. No usernames specified means all tracks by all users will be scrobbled.

Subsonic​

Can use this source for any application that implements the Subsonic API and supports the getNowPlaying endpoint (such as Airsonic and Navidrome)

Known Issues
  • Multiple artists are reported as one value and cannot be separated
  • If using Airsonic Advanced the password used (under Credentials) must be Decodable

Configuration​

Environmental VariableRequired?DefaultDescription
SUBSONIC_USERYes
SUBSONIC_PASSWORDYes
SUBSONIC_URLYesBase url of your subsonic-api server

Jellyfin​

Migrating from Webhook (multi-scrobbler below v0.8.4) to API

In multi-scrobbler below v0.9.0 communication with Jellyfin was done using Jellyfin's Webhook plugin. This has been deprecated in favor of directly using Jeyllfin's API for a better experience in multi-scrobbler.

To Migrate:​

  • Remove the Webhook plugin (if not using it for anything else)
  • Follow the new instructions below (outside this section) to setup API usage
  • The servers (JELLYFIN_SERVERS) setting is no longer available as MS only scrobbles from the server using the API anyways.
    • If you need to scrobble for multiple servers set up each server as a separate Jellyfin source
  • The users (JELLYFIN_USER) setting has been renamed usersAllow (JELLYFIN_USERS_ALLOWED)
    • If you were using this filter to ensure only scrobbles from yourself were registered then you no longer need this setting -- by default MS will only scrobble for the user authenticated with Jellyfin's API.

Must be using Jellyfin 10.7 or greater

  • Create an API Key for multi-scrobbler
    • In the Jellyfin desktop web UI Navigate to -> Administration -> Dashboard -> API Keys (http://YOUR_JELLYIN_URL/web/index.html#!/apikeys.html)
    • Click + button and create a new key with App name multi-scrobbler
    • Copy the created API Key value for use in configuration below

It is recommended to use API Key + username but if you are not an admin for your Jellyfin instance you can also authenticate with your Jellyfin username and password.

Important Defaults

By default...

  • multi-scrobbler will only scrobbling for the user authenticated with the API.
    • Allowed Users (usersAllow or JELLYFIN_USERS_ALLOW) are only necessary if you want to scrobble for additional users.
  • multi-scrobbler will only scrobble media found in Jellyfin libraries that were labelled as Music.
    • librariesAllow or JELLYFIN_LIBRARIES_ALLOW will override this
    • OR use additionalAllowedLibraryTypes to allow more types (like mixed or book for audiobooks)
  • multi-scrobbler will only scrobble media Jellyfin detects as Audio.
    • To force multi-scrobbler to scrobble when media is detected as Unknown use "allowUnknown": true in file/aio configuration.

Configuration​

Environmental VariableRequired?DefaultDescription
JELLYFIN_URLYesThe URL of the Jellyfin server IE http://localhost:8096
JELLYFIN_USERYesThe user to authenticate with the API
JELLYFIN_APIKEYNoThe API Key to use for authentication (Must provide either apikey or password)
JELLYFIN_PASSWORDNoThe password of the user to authenticate for. (Must provide either apikey or password)
JELLYFIN_USERS_ALLOWNoComma-separated list of usernames (from Jellyfin) to scrobble for
JELLYFIN_USERS_BLOCKNoComma-separated list of usernames (from Jellyfin) to disallow scrobble for
JELLYFIN_DEVICES_ALLOWNoComma-separated list of devices to scrobble from
JELLYFIN_DEVICES_BLOCKNoComma-separated list of devices to disallow scrobbles from
JELLYFIN_LIBRARIES_ALLOWNoComma-separated list of libraries to allow scrobbles from
JELLYFIN_LIBRARIES_BLOCKNoComma-separated list of libraries to disallow scrobbles from

Last.fm (Source)​

See the Last.fm (Client) setup for registration instructions.

Configuration​

No support for ENV based for Last.fm as a client (only source)

Listenbrainz (Source)​

You will need to run your own Listenbrainz server or have an account on the official instance

On your profile page find your User Token to use in the configuration.

Configuration​

note

You cannot use ENV variables shown in the Listenbrainz Client config -- multi-scrobbler assumes Listenbrainz ENVs are always used for the client configuration. You must use the file-based config from below to setup Listenbrainz as a Source.

Deezer​

warning

This Source is DEPRECATED because Deezer has dropped official API support. This Source will not be removed but no further support or fixes will be given.

Users cannot create new applications on Deezer Developers and there is no guarantee existing applications will continue to work.

As a workaround consider integrating Deezer with last.fm and then using last.fm as a Source.

Users with existing Deezer applications in use with multi-scrobbler should consider this change as well to avoid future breaking issues with the unsupported API.

See this issue for more discussion.

Create a new application at Deezer Developers

  • Application Domain must be the same as your multi-scrobbler domain. Default is localhost:9078
  • Redirect URL must end in deezer/callback
    • Default would be http://localhost:9078/deezer/callback

After application creation you should have credentials displayed in the "My Apps" dashboard. You will need:

  • Application ID
  • Secret Key
  • Redirect URL (if not the default)

If no access token is provided...

After starting multi-scrobbler with credentials in-place open the dashboard (http://localhost:9078) and find your Deezer source. Click (Re)authenticate and (re)start polling to start the login process. After login is complete polling will begin automatically.

Configuration​

Environmental VariableRequired?DefaultDescription
DEEZER_CLIENT_IDYesYour Application ID
DEEZER_CLIENT_SECRETYesYour Secret Key
DEEZER_REDIRECT_URINohttp://localhost:9078/deezer/callbackURI must end in deezer/callback

Youtube Music​

note
  • YT Music authentication is "browser based" which means your credentials may expire after a (long?) period of time OR if you log out of https://music.youtube.com. In the event this happens just repeat the steps below to get new credentials. See the FAQ for a more detailed explanation.
  • Communication to YT Music is unofficial and not supported or endorsed by Google. This means that this integration may stop working at any time if Google decides to change how YT Music works in the browser.
    • Due to this scrobble history from YTM is often inconsistent and can cause missed scrobbles. See the FAQ for a more detailed explanation.

Credentials for YT Music are obtained from a browser request to https://music.youtube.com once you are logged in. Specific requirements are here and summarized below:

  • Open a new tab
  • Open the developer tools (Ctrl-Shift-I) and select the “Network” tab
  • Go to https://music.youtube.com and ensure you are logged in

Then...

  1. Find and select an authenticated POST request. The simplest way is to filter by /browse using the search bar of the developer tools. If you don’t see the request, try scrolling down a bit or clicking on the library button in the top bar.
  2. **Make sure Headers pane is selected and open
  3. In the Request Headers section find and copy the entire value found after Cookie: and use this as the cookie value in your multi-scrobbler config
  4. If present, in the Request Headers section find and copy the number found in X-google-AuthUser and use this as the value for authUser in your multi-scrobbler config

Google Headers

Configuration​

No ENV support

MPRIS​

MPRIS is a standard interface for communicating with Music Players on linux operating systems.

If you run Linux and have a notification tray that shows what media you are listening to, you likely have access to MPRIS.

Notification Tray

multi-scrobbler can listen to this interface and scrobble tracks played by any media player that communicates to the operating system with MPRIS.

note

multi-scrobbler needs to be running as a Local Installation in order to use MPRIS. This cannot be used from docker.

Configuration​

Environmental VariableRequired?DefaultDescription
MPRIS_ENABLENoUse MPRIS as a Source (useful when you don't need any other options)
MPRIS_BLACKLISTNoComma-delimited list of player names not to scrobble from
MPRIS_WHITELISTNoComma-delimited list of players names to ONLY scrobble from. Overrides blacklist

Mopidy​

Mopidy is a headless music server that supports playing music from many standard and non-standard sources such as Pandora, Bandcamp, and Tunein.

multi-scrobbler can scrobble tracks played from any Mopidy backend source, regardless of where you listen to them.

note

You must have Mopidy-HTTP extension enabled for this integration to work.

Configuration​

No ENV support

Configuration Options​

URL​

The URL used to connect to the Mopidy server, set in your file config as url. The URL used to connect ultimately must be formed like this:

Syntax  => [protocol]://[hostname]:[port]/[path]
Default =>         ws://localhost:6680/mopidy/ws

If any part of this URL is missing multi-scrobbler will use a default value. This also means that if any part of your URL is not standard you must explicitly define it.

Mopidy Configuration

Make sure the hostname and port number match what is found in the Mopidy configuration file mopidy.conf:

[http]
hostname = localhost
port = 6680
URL Transform Examples

Examples of a given url in your file config and the final URL multi-scrobbler will use to connect to Mopidy:

urlTransformed URL
(none set)ws://localhost:6680/mopidy/ws
mopidy.mydomain.comws://mopidy.mydomain.com:6680/mopidy/ws/
192.168.0.101:3456ws://192.168.0.101:3456/mopidy/ws/
mopidy.mydomain.com:80/MOPWSws://mopidy.mydomain.com:80/MOPWS
URI Blacklist/Whitelist​

If you wish to disallow or only allow scrobbling from some sources played through Mopidy you can specify these using uriBlacklist or uriWhitelist in your config. multi-scrobbler will check the list to see if any string matches the START of the uri on a track. If whitelist is used then blacklist is ignored. All strings are case-insensitive.

Example
{
    "uriBlacklist": ["soundcloud"]
}

Will prevent multi-scrobbler from scrobbling any Mopidy track that start with a uri like soundcloud:song:MySong-1234

Album Blacklist​

For certain sources (Soundcloud) Mopidy does not have all track info (Album) and will instead use "Soundcloud" as the Album name. You can prevent multi-scrobbler from using this bad Album data by adding the fake Album name to this list. Multi-scrobbler will still scrobble the track, just without the bad data. All strings are case-insensitive.

Example
{
    "albumBlacklist": ["SoundCloud", "Mixcloud"]
}

If a track would be scrobbled like

Album: Soundcloud, Track: My Cool Track, Artist: A Cool Artist

then multi-scrobbler will instead scrobble

Track: My Cool Track, Artist: A Cool Artist

JRiver​

In order for multi-scrobbler to communicate with JRiver you must have Web Server Interface enabled. This can can be in the JRiver GUI:

  • Tools -> Options -> Media Network
    • Check Use Media Network to share this library...
    • If you have Authentication checked you will need to provide the Username and Password in the ENV/File configuration below.

Configuration​

Environmental VariableRequiredDefaultDescription
JRIVER_URLYeshttp://localhost:52199/MCWS/v1/The URL of the JRiver server
JRIVER_USERNAMENoIf authentication is enabled, the username set
JRIVER_PASSWORDNoIf authenticated is enabled, the password set
URL​

The URL used to connect to JRiver, set in your file config as url. The URL used to connect ultimately must be formed like this:

Syntax  => [protocol]://[hostname]:[port]/[path]
Default =>       http://localhost:52199/MCWS/v1/

If any part of this URL is missing multi-scrobbler will use a default value. This also means that if any part of your URL is not standard you must explicitly define it.

Jriver Settings
  • Make sure the port number matches what is found in Advanced section in the Media Network options.
  • If your installation is on the same machine but you cannot connect using localhost try 0.0.0.0 instead.
URL Transform Examples

Examples of a given url in your file config and the final URL multi-scrobbler will use to connect to JRiver:

urlTransformed URL
(none set)http://localhost:52199/MCWS/v1/
jriver.mydomain.comhttp://jriver.mydomain.com:52199/MCWS/v1/
192.168.0.101:3456http://192.168.0.101:3456/MCWS/v1/
mydomain.com:80/jriverReverse/MCWS/v1/mydomain.com:80/jriverReverse/MCWS/v1/

Kodi​

In order for multi-scrobbler to communicate with Kodi you must have the Web Interface enabled. This can be done in the Kodi GUI:

  • Settings -> Services -> Control
    • Check Allow remote control via HTTP
    • Ensure you have a Username and Password set, you will need to provide them in the ENV/File configuration below.

Configuration​

Environmental VariableRequiredDefaultDescription
KODI_URLYeshttp://localhost:8080/jsonrpcThe URL of the Kodi server
KODI_USERNAMENoThe username set
KODI_PASSWORDNoThe password set
URL​

The URL used to connect to Kodi, set in your file config as url. The URL used to connect ultimately must be formed like this:

Syntax  => [protocol]://[hostname]:[port]/[path]
Default =>       http://localhost:8080/jsonrpc

If any part of this URL is missing multi-scrobbler will use a default value. This also means that if any part of your URL is not standard you must explicitly define it.

Kodi Settings
  • Make sure the port number matches what is found in Port in the Control section mentioned above.
  • If your installation is on the same machine but you cannot connect using localhost try 0.0.0.0 instead.
URL Transform Examples

Examples of a given url in your file config and the final URL multi-scrobbler will use to connect to Kodi:

urlTransformed URL
(none set)http://localhost:8080/jsonrpc
kodi.mydomain.comhttp://kodi.mydomain.com:8080/jsonrpc
192.168.0.101:3456http://192.168.0.101:3456/jsonprc
mydomain.com:80/kodiReverse/jsonrpchttp://mydomain.com:80/kodiReverse/jsonrpc

WebScrobbler​

After installing the extension open the preferences/settings for it:

  • Under Accounts
    • Add Webhook
      • API URL: [YourMultiScrobblerInstance]/api/webscrobbler EX http://localhost:9078/api/webscrobbler
      • Application name: (whatever you want)

Reload the extension after adding the webhook.

note
  • On Firefox - Only FQNs (domain.tld), localhost, and 127.0.0.1 are supported for API URL due to firefox requiring https
  • On Chromium-based Browsers - Any domain will work for API URL
  • All other browsers are untested
warning

Multi-scrobbler is not designed to be publicly accessible from the internet. To use Webscrobbler outside your local network you should be accessing MS through a VPN or through a reverse proxy with some kind of authentication (though this is still not recommended).

Configuration​

Environmental VariableRequired?DefaultDescription
WS_ENABLENoSet to 'true' to enable WS without needing to define other ENVs
WS_WHITELISTNoOnly scrobble from these WebScrobbler Connectors. Comma-delimited list
WS_BLACKLISTNoDo not scrobble from these WebScrobbler Connectors. Comma-delimited list
Multiple Users​

If you would like use multiple WebScrobbler sources they can be matched using a slug at the end of the API URL. This requires using a file-based config.

Example
webscrobbler.json
[
  {
    "name": "aUserWS",
    "clients": [
      "client1Maloja"
    ],
    "data": {
      "slug": "usera"
    }
  },
  {
    "name": "bUserWS",
    "clients": [
      "client2Maloja"
    ],
    "data": {
      "slug": "userb"
    }
  }
]
  • To use aUserWS source set API URL to http://localhost:9078/api/webscrobbler/usera
  • To use bUserWS source set API URL to http://localhost:9078/api/webscrobbler/userb
tip

http://localhost:9078/api/webscrobbler is matched with the first source that that does not have a slug defined.

Connectors Black/Whitelist​

MS can be configured to only scrobble, or NOT scrobble, from some WS connectors. Use the name of the website from the supported websites or from the Connectors tab in the extension.

note

This affects only MS's behavior and does not affect the general connector behavior you have configured within the WebScrobbler extension.

Google Cast (Chromecast)​

If your media device can be Cast to using this button Chromecast Icon on your phone/computer then multi-scrobbler can monitor it in order to scrobble music you play.

note

Google Cast support is experimental. You may experience crashes and errors while using this Source. Please open an issue if you experience problems and include all information detailed in the issue template to help debug your issue.

note

This source relies on common, basic music data provided by the cast device which will always be less exhaustive than data parsed from full source integrations. If there is an existing Source it is recommended to configure for it and blacklist the app on Google Cast, rather than relying solely on Google Cast for scrobbling.

Configuration​

note

Manually configuring cast device connections is only available through file-based config.

Environmental VariableRequired?DefaultDescription
CC_ENABLENoSet to 'true' to enable Cast monitoring without needing to define other ENVs
CC_WHITELIST_DEVICESNoOnly scrobble from these Cast devices. Comma-delimited list. EX mini-home, family-tv
CC_BLACKLIST_DEVICESNoDo not scrobble from these Cast devices. Comma-delimited list
CC_WHITELIST_APPSNoOnly scrobble from these casted Apps. Comma-delimited list. EX spotify, pandora
CC_BLACKLIST_APPSNoDo not scrobble from these casted Apps. Comma-delimited list

Connecting Devices​

Cast devices can be manually configured using file-based configuration OR automatically discovered using mDNS.

mDNS Discovery​

The host machine running multi-scrobbler must be configured to allow mDNS traffic on port 5353/UDP.

OS Specific Instructions

Docker

The host machine must have avahi-daemon running to circumvent limitations with DNS resolution due to musl in Alpine. Most major linux distributions package avahi and many have it built-in. Once avahi is running you must pass D-Bus and the avahi daemon socket to your container like so:

docker run ... -v /var/run/dbus:/var/run/dbus -v  	/var/run/avahi-daemon/socket:/var/run/avahi-daemon/socket ... foxxmd/multi-scrobbler

Flatpak/Nodejs

No additional steps are required.

What Media Does MS Scrobble?​

Cast devices report what type of media the current activity is (see metadata property here). The reported type is dependent on the application playing the media to correctly report it, the cast device does not magically know what the media is. If an application does not report a type it is always classified as unknown.

By default, MS will only track media that is reported as MusicTrack.

Allow Unknown Media Type​

Media with an Unknown (Generic) media type can be explicitly allowed by setting "allowUnknownMedia": true in the file-based configuration. This can also be configured to only allow unknown media types for specific applications by using a list of application names.

Example
chromecast.json
[
  {
    "name": "MyCast",
    "type": "chromecast",
    "data": {
      // only allow unknown if app name contains any of these phrases
      "allowUnknownMedia": ["smarttube", "default media receiver"]
    },
  }
]
Forcing Media Tracking​

MS can be forced to track media from an application regardless of media type. This is useful if an application incorrectly reports a media type you are sure should be music. Set "forceMediaRecognitionOn" in the file-based configuration to a list of application names that should always be tracked.

Example
chromecast.json
[
  {
    "name": "MyCast",
    "type": "chromecast",
    "data": {
      // media from applications that contains these phrases will always be tracked, regardless of media type reported
      "forceMediaRecognitionOn": ["smarttube", "default media receiver"]
    },
  }
]

Cast Troubleshooting​

Please include any/all logs with raw output if there are any errors encountered as this is critical to diagnosing issues.

To diagnose bad/incomplete track information or strange MS player behavior please turn on payload logging and include log output of the source running to help diagnose this issue.

Example
chromecast.json
[
  {
    "name": "MyCast",
    "type": "chromecast",
    "data": {
      //...
    },
    "options": {
      "logPayload": true
    }
  }
]

Musikcube​

In order to use Musikcube configure it to accept websocket connections in server setup:

  • Enable the Metadata Server
  • Set a Password

Both of these settings are found in Musikcube -> (s)ettings -> server setup

Server Setup

The URL used by MS has the syntax:

[ws|wss]://HOST:[PORT]

The port is the same as shown in the server setup screenshot from above, under metadata server enabled. If no port is provided to MS it will default to 7905.

If no URL is provided to MS it will try to use ws://localhost:7905

Configuration​

Environmental VariableRequired?DefaultDescription
MC_URLNows://localhost:7905Use port set for metadata server
MC_PASSWORDYes

MPD (Music Player Daemon)​

MS communicates with MPD using the TCP client connection.

You should uncomment/create the following settings in your mpd config:

bind_to_address	"any"   # or a specific ipv4/v6 address
port            "6600"

Configuration​

Environmental VariableRequired?DefaultDescription
MPD_URLNolocalhost:6600
MPD_PASSWORDNo

VLC​

MS communicates with VLC using the Web (http) interface module

Enable HTTP Interface​

Open VLC:

  • Tools Menu -> Preferences
    • In the bottom left change Show Settings from Simple to All
    • In the updated window select Interface -> Main interfaces
      • In the Extra interface modules section enable Web and verify that http is shown in the textbox
    • Select Interface -> Main interfaces -> Lua
      • In Lua HTTP -> Password -> set a password in this box
    • Click Save at the bottom to persist your changes
  • Restart VLC
  • Verify the HTTP interface is accessible by navigating to http://localhost:8080 in your browser

If the interface is accessible, after typing in your password, VLC is now ready to be used by MS.

Setting VLC Interface and Port​

These can be set by starting VLC from command line with specific options:

  • vlc --http-host yourHostIp:yourPort or
  • vlc --http-port yourPort or
  • modify the configuration file for VLC by editing keys with the same values as from the command line (http-host and http-port)

Configuration​

Environmental VariableRequired?DefaultDescription
VLC_URLNolocalhost:8080
VLC_PASSWORDYes

Filename Parsing​

If the file being played in VLC does not have ID3 tags/metadata information multi-scrobbler can attempt to extract artist, title, and album information from the raw filename using regular expressions. Mutli-scrobbler will only do this if there is no other information reported by VLC about these fields.

To extract this information use named capture groups in your expression matching the field that should be extracted: artist title and/or album. MS accepts multiple expressions, the first one that matches a filename will be used.

Example usage in a file-based config:

config/vlc.json
[
  {
    "name": "MyVlc",
    "enable": true,
    "data": {
      // ...
    },
    "options": {
      "filenamePatterns": [
          // Extracts artist and title from filenames that look like:
          // My Artist - My Cool title.mp4
          "/^\\s*(?<artist>.+?) - (?<title>.+?)\\.\\w+$/i"
        ],
      // logs to DEBUG when MS tries to extract data from a filename
      "logFilenamePatterns": true,
    }
  }
]

Vlc Information Reporting​

If you find that VLC is incorrectly reporting track information (in its interface) but multi-scrobbler is not parsing it correctly it may be due to the name of the fields VLC is reporting. mutli-scrobbler uses the most common field name but does not cover all use cases. Before reporting an issue please turn on metadata logging and include output from your logs while it is turned on:

config/vlc.json
    [
      {
        "name": "MyVlc",
        "enable": true,
        "data": {
          // ...
        },
        "options": {
          "dumpVlcMetadata": true
        }
      }
    ]

Client Configurations​

Maloja​

Configuration​

Environmental VariableRequired?DefaultDescription
MALOJA_URLYesBase URL of your installation
MALOJA_API_KEYYesApi Key

Last.fm​

Register for an API account here.

The Callback URL is actually specified by multi-scrobbler but to keep things consistent you should use

http://localhost:9078/lastfm/callback

or replace localhost:9078 with your own base URL

Configuration​

Environmental VariableRequired?DefaultDescription
LASTFM_API_KEYYesApi Key from your API Account
LASTFM_SECRETYesShared secret from your API Account
LASTFM_REDIRECT_URINohttp://localhost:9078/lastfm/callbackUrl to use for authentication. Must include lastfm/callback somewhere in it
LASTFM_SESSIONNoSession id. Will be generated by authentication flow if not provided.

Listenbrainz​

You will need to run your own Listenbrainz server or have an account on the official instance

On your profile page find your User Token to use in the configuration.

Configuration​

Environmental VariableRequired?DefaultDescription
LZ_TOKENYesUser token from your LZ profile
LZ_USERYesYour LZ username
LZ_URLNohttps://api.listenbrainz.org/The base URL for the LZ server

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