From < 0.14.0

Source/Client IDs

MS 0.14.0 introduces a database for persisting Plays/Scrobbles, queues, and other data associated with a Source/Client.

To make this association atomic a Source/Client ID is now configurable. This ID is what MS will use to identify the Source/Client in your config with the Source/Client in the database.

This ID needs to be unique to the client or source type it is used on IE:

• two Koito Clients cannot both have the ID myKoitoID
• it is recommended that the ID be globally unique among all sources/clients, but it’s not required

Configuring IDs

ENV

For each Source/Client in your environmental variables, add a key with the suffix _ID and the ID value. EX

compose.yaml

services:
  multi-scrobbler:
  # ...
  environment:
    - KOITO_TOKEN=...
    # ...more koito config
    - KOITO_ID=myKoitoID

    - JELLYFIN_URL=...
    # ...more jellyin config
    - JELLYFIN_ID=myJellyfinID

File

Add an id to the top-level for each Source/Client configuration, next to data:

koito.json

[
  {
    "name": "koito-source",
    "configureAs": "source",
    "id": "myKoitoID",
    "data": {
      "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
      "username": "admin",
      "url": "http://192.168.0.100:4110"
    }
  }
]

AIO

Add an id to the top-level for each Source/Client configuration, next to data:

config.json

{
  "sources": [
    {
      "name": "koito-source",
      "configureAs": "source",
      "type": "koito",
      "id": "myKoitoID",
      "data": {
        "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
        "username": "admin",
        "url": "http://192.168.0.100:4110"
      }
    }
  ]
}

Default ID

In 0.14.0, If you do not add an ID then Multi-Scrobbler will automatically use the name of the Source/Client as the ID. The name is shown in the Dashboard.

If you decide to add an ID later, you must use the Source/Client name as the ID in order to keep Plays/Scobbles associated with the same config.

In 0.16.0+ you are required to have an ID or a configuration error is thrown.

Cached Scrobble Migration

Tip

Before upgrading, if your MS dashboard shows 0 queued/failed for all Scrobble Clients then you can ignore this section.

Important

The cached scrobbles for a Client/Source were based on its name. If you plan on changing the name of a Client/Source with this upgrade you should do it after this migration has run or else MS will not be able to find any associated cached scrobbles.

MS 0.14.0 introduces a database for persisting Plays/Scrobbles, queues, and other data. Prior to 0.14.0, queued/failed scrobbles were stored in a cache file inside your CONFIG_DIR named ms-scrobble.cache.

When a Client is created and enabled in 0.14.0 it will attempt to automatically migrate scrobbles from this cache into the database.

• You can see progress/results for this process by filtering logs for [Cached Scrobble Migration]
• If the process fails MS will attempt to migrate failed scrobbles, again, the next time it is started
• Your cached scrobbles are not deleted in either the success or failure outcome
  • If the process succeeds then MS knows to ignore the cache on subsequent startups

Note

This process only occurs for Clients that are enabled.

• If you are using ENV for config then your Clients are automatically enabled
• If you are using File/AIO make sure that the enable property is either true or not present in your Client configs

Even if your Client does not start successfully (EX due to authentication) you should still enable and start all Clients in order to get all scrobbled migrated.

Cache Configuration

In 0.14.0 Cache has been simplified with much of the required configuration being removed.

Tip

This only applies to users who have cache in their AIO Config config.json or are using CACHE_* ENV Config

If you do not have any of the above Cache configuration defined then you can ignore this section.

Scrobble Caching Removed

Scrobble caching has removed and replaced by the new database.

• Remove any ENV Config starting with CACHE_SCROBBLE
• Remove cache.scrobble from the AIO Config

Metadata Config Simplified

Metadata caching remains the same but the config has been simplified. If you were using Valkey for caching update your config:

ENV

• Remove CACHE_METADATA
• Rename CACHE_METADATA_CONN to CACHE_VALKEY

AIO

Remove cache.metadata and add a new string key valkey to the cache object, containing your valkey connection string:

config.json

"cache": {
   "valkey": "redis://valkey:6379"
   "metadata": {
     "provider": "valkey",
     "connection": "redis://valkey:6379"
   }
}

Auth Config Simplified

Auth caching remains the same but the config has been simplified. The connection option for Auth is no longer configurable. You may specify provider as either file (default, uses CONFIG_DIR) or valkey. If you want to use Valkey for auth it will use the same config as Metadata.

ENV

• Remove CACHE_AUTH_CONN
• Add CACHE_VALKEY (if using valkey)

AIO

Remove the connection property from the auth object. If using file the entire auth object can be removed.

config.json

"cache": {
  "valkey": "redis://valkey:6379",
  "auth": {
    "provider": "valkey",
    "connection": "redis://valkey:6379"
  }
}

Renamed ENV Keys

In an effort to standard ENV prefixes some ENV keys have been renamed:

• LZENDPOINT_ENABLE => LZE_ENABLE
• LFMENDPOINT_ENABLE => LFM_ENABLE

(Optional) ENV Client/Source Names

In the MS Dashboard, prior to 0.14.0, UI Client/Sources configured with ENV Config always had generated names like unnamed-koito.

ENV Config Clients/Sources can now be configured with a name by using the _NAME suffix, example:

compose.yaml

services:
  multi-scrobbler:
  # ...
  environment:
    - KOITO_TOKEN=...
    # ...
    - KOITO_ID=myKoitoID
    - KOITO_NAME=Koito A

    - JELLYFIN_URL=...
    # ..
    - JELLYFIN_ID=myJellyfinID
    - JELLYFIN_NAME=Foxx Jelly

Important

If you have cached scrobbles make sure to upgrade and run Cached Scrobble Migration before adding names to Client/Sources.