chore(release): Bump version for release

docs(lastfm): Document 2 week scrobble window
#606
2026-09-03 05:10:00 +03:00 · 2026-05-28 13:05:12 +00:00 · 2026-05-28 12:31:28 +00:00 · 2026-05-27 20:43:01 -04:00 · 2026-05-27 20:30:25 -04:00 · 2026-05-27 18:04:29 -04:00
268 changed files with 15914 additions and 4596 deletions
@@ -30,7 +30,9 @@
 				"dbaeumer.vscode-eslint",
 				"unifiedjs.vscode-mdx",
 				"bradlc.vscode-tailwindcss",
-				"TakumiI.markdowntable"
+				"TakumiI.markdowntable",
+				"YoavBls.pretty-ts-errors",
+				"bowlerr.sqlite-intelliview-vscode"
 			]
 		}
 	},
@@ -1,6 +1,6 @@
 ## Checklist before requesting a review

- [ ] I have read the [contributing guidelines.](../CONTRIBUTING.md)
+- [ ] I have read the [contributing guidelines.](../blob/master/CONTRIBUTING.md)

 ## Type of change

@@ -38,6 +38,10 @@ jobs:
        run: npm run build
        working-directory: ./docsite

+      - name: Replace canonical
+        working-directory: ./docsite
+        run: node --experimental-strip-types canonical-replace.ts ./build
+
      # Popular action to deploy to GitHub Pages:
      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
      - name: Deploy to GitHub Pages
@@ -67,4 +71,10 @@ jobs:
              \"client_payload\": {
                \"commit\": \"${{ github.sha }}\"
              }
-            }"
+            }"
+      - name: Trigger CF Pages build
+        if: ${{ vars.CF_PAGES == 'true' }}
+        run: |
+          # trigger CF pages hook deployment
+          curl -d "" \
+            "${{ secrets.CF_PAGES_HOOK }}"
@@ -18,11 +18,16 @@ jobs:
    name: Tests / Build / Sanity Run
    runs-on: ubuntu-latest
    steps:
-      - name: Check out the repo
+      - name: Check out the repo (gha)
+        if: ${{ !env.ACT }}
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd #v6.0.2
        with:
          ref: ${{ inputs.ref }}
          persist-credentials: false
+
+      - name: Check out the repo (act)
+        if: ${{ env.ACT }}
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd #v6.0.2
      - name: Use Node.js
        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f #6.3.0
        with:
@@ -151,4 +151,10 @@ tmp-*

 *storybook.log
 storybook-static
-lib
+
+*.db
+*.db.*
+*.db-*lib
+*.db
+*.db.*
+*.db-*lib
@@ -0,0 +1,6 @@
+{
+    "recommendations": [
+        "sanjulaganepola.github-local-actions",
+        "github.vscode-github-actions"
+    ]
+}
@@ -1,6 +1,19 @@
 {
    "version": "0.2.0",
    "configurations": [
+        {
+            "name": "Run Canonical Replace",
+            "program": "${workspaceFolder}/docsite/canonical-replace.ts",
+            "runtimeArgs": ["--experimental-strip-types"],
+            "args": [
+                "${workspaceFolder}/docsite/build"
+            ],
+            "request": "launch",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "type": "node"
+        },
        {
            "name": "dev",
            "type": "node",
@@ -118,8 +118,6 @@ RUN npm ci --omit=dev --no-audit \
    && npm uninstall ts-json-schema-generator \
    && npm cache clean --force \
    && chown -R abc:abc node_modules \
-    # added superflously https://github.com/Borewit/rate-limit-threshold/issues/110
-    && rm -R node_modules/@biomejs \
    && npx @usex/prune-mod -w \
    && rm -rf /root/.cache

@@ -2,7 +2,8 @@
  {
    "type": "azuracast",
    "enable": true,
-    "name": "azura",
+    "name": "Cool Station",
+    "id": "myAzura",
    "data": {
      "url": "ws://192.168.0.101",
      "station": "my-station-name",
@@ -1,6 +1,7 @@
 [
  {
-    "name": "MyCast",
+    "name": "My Cast",
+    "id": "myCast",
    "data": {
      "blacklistedDevices": [],
      "whitelistedDevices": [],
@@ -1,6 +1,7 @@
 [
  {
-    "name": "DeezerARL",
+    "name": "Family Account",
+    "id": "myDeezerId",
    "enable": true,
    "clients": [],
    "data": {
@@ -1,7 +1,8 @@
 [
    {
-      "name": "MS",
+      "name": "Desktop",
      "enable": true,
+      "id": "myDiscordLocal",
      "data": {
        "applicationId": "8190211179716453570",
        "ipcLocations": ["192.168.0.105:6655"]
@@ -1,11 +1,11 @@
 [
-    {
-      "name": "MS",
-      "enable": true,
-      "data": {
-        "token": "Ma7XBvzRERK3gQdkX4dkb3OQ.6aaGmJ.rvFiiVrzG4VXHHL3LyhZYhpWdG3Ph_if9aKz5E",
-        "applicationId": "8190211179716453570"
-      }
+  {
+    "name": "Discord",
+    "enable": true,
+    "id": "myDiscordRemote",
+    "data": {
+      "token": "Ma7XBvzRERK3gQdkX4dkb3OQ.6aaGmJ.rvFiiVrzG4VXHHL3LyhZYhpWdG3Ph_if9aKz5E",
+      "applicationId": "8190211179716453570"
    }
-  ]
-  
+  }
+]
@@ -1,7 +1,8 @@
 [
  {
-    "name": "myLfm",
+    "name": "LFM For App",
    "enable": true,
+    "id": "myLfmApp",
    "data": {
      "slug": "mySlug"
    }
@@ -1,6 +1,7 @@
 [
  {
-    "name": "myLz",
+    "name": "LZ for Navidrome",
+    "id": "myLzNavidrome",
    "enable": true,
    "data": {
      "token": "myToken"
@@ -1,7 +1,8 @@
 [
    {
-      "name": "myIcy",
+      "name": "Station 1",
      "enable": true,
+      "id": "myIceStation1",
      "data": {
        "url": "http://myIcecast.com/radio"
      }
@@ -1,7 +1,8 @@
 [
  {
-    "name": "MyJellyfin",
+    "name": "Cool JF Server",
    "enable": true,
+    "id": "myJellyfin",
    "clients": [],
    "data": {
      "url": "http://localhost:8096",
@@ -1,6 +1,7 @@
 [
  {
-    "name": "MyJriver",
+    "name": "My JRiver Server",
+    "id": "myRiver",
    "enable": true,
    "data": {
      "url": "0.0.0.0",
@@ -1,6 +1,7 @@
 [
  {
-    "name": "MyKodi",
+    "name": "My Kodi Server",
+    "id": "myKodi",
    "enable": true,
    "data": {
      "url": "http://localhost:8080/jsonrpc",
@@ -1,6 +1,7 @@
 [
-      {
-    "name": "koito-client",
+  {
+    "name": "Koito Client A",
+    "id": "myKoitoClient",
    "configureAs": "client",
    "data": {
      "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
@@ -9,7 +10,8 @@
    }
  },
  {
-    "name": "koito-source",
+    "name": "Koito Source B",
+    "id": "myKoitoSource",
    "configureAs": "source",
    "data": {
      "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
@@ -1,6 +1,7 @@
 [
  {
-    "name": "myLastFmClient",
+    "name": "Foxx LFM Client",
+    "id": "myLastFmClient",
    "enable": true,
    "configureAs": "client",
    "data": {
@@ -10,7 +11,8 @@
    }
  },
  {
-    "name": "myLastFmSource",
+    "name": "Foxx LFM Source",
+    "id": "myLastFmSource",
    "enable": true,
    "configureAs": "source",
    "data": {
@@ -1,6 +1,7 @@
 [
  {
-    "name": "myLibreFmClient",
+    "name": "Foxx Libre Client",
+    "id": "myLibreFmClient",
    "enable": true,
    "configureAs": "client",
    "data": {
@@ -10,7 +11,8 @@
    }
  },
  {
-    "name": "myLibreFmSource",
+    "name": "Foxx Libre Source",
+    "id": "myLibreFmSource",
    "enable": true,
    "configureAs": "source",
    "data": {
@@ -1,6 +1,7 @@
 [
  {
-    "name": "brainzClient",
+    "name": "Foxx LZ Client",
+    "id": "brainzClient",
    "enable": true,
    "configureAs": "client",
    "data": {
@@ -10,7 +11,8 @@
    }
  },
  {
-    "name": "brainzSource",
+    "name": "Foxx LZ Source",
+    "id": "brainzSource",
    "enable": true,
    "configureAs": "source",
    "data": {
@@ -1,6 +1,7 @@
 [
  {
-    "name": "myMaloja-client",
+    "name": "Maloja Client",
+    "id": "myMalojaClient",
    "enable": true,
    "configureAs": "client",
    "data": {
@@ -9,7 +10,8 @@
    }
  },
    {
-    "name": "myMaloja-source",
+    "name": "Maloja Source",
+    "id": "myMalojaSource",
    "enable": true,
    "configureAs": "source",
    "data": {
@@ -1,6 +1,7 @@
 [
  {
-    "name": "MyMopidy",
+    "name": "Mopidy Desktop",
+    "id": "MyMopidy",
    "enable": true,
    "data": {
      "url": "localhost",
@@ -1,7 +1,8 @@
 [
  {
    "enable": true,
-    "name": "MyMPD",
+    "id": "myMPD",
+    "name": "Desktop",
    "data": {
      "url": "192.168.0.100:6600",
      "password": "MY_PASSWORD"
@@ -1,6 +1,7 @@
 [
  {
-    "name": "ubuntu",
+    "name": "Desktop",
+    "id": "myMprisUbuntu",
    "enable": true,
    "data": {
      "whitelist": ["vlc", "mpd"],
@@ -1,6 +1,7 @@
 [
  {
-    "name": "myYamaha",
+    "name": "Livingroom Reciever",
+    "id": "myYamaha",
    "enable": true,
    "data": {
      "url": "192.168.0.101"
@@ -2,7 +2,8 @@
  {
    "type": "musikcube",
    "enable": true,
-    "name": "musikcube",
+    "name": "Desktop",
+    "id": "myMusikcube",
    "data": {
      "url": "ws://localhost:7905",
      "password": "MY_PASSWORD"
@@ -1,6 +1,7 @@
 [
  {
-    "name": "MyPlexApi",
+    "name": "Foxx Plex",
+    "id": "MyPlexApi",
    "enable": true,
    "clients": [],
    "data": {
@@ -1,6 +1,7 @@
 [
    {
-    "name": "myRockskyClient",
+    "id": "myRockskyClient",
+    "name": "FoxxMD Rocksky Client",
    "configureAs": "client",
    "data": {
      "key": "7cdr86vis3mpq5b1pi01md0hkm7ykzzxjy81r",
@@ -8,7 +9,8 @@
    }
  },
  {
-    "name": "myRockskySource",
+    "id": "myRockskySource",
+    "name": "FoxxMD Rocksky Source",
    "configureAs": "source",
    "data": {
      "key": "e4xwktm7jxm607x8el1fcda30eu14dzb64h3j",
@@ -1,7 +1,8 @@
 [
  {
    "enable": true,
-    "name": "MySonos",
+    "id": "MySonos",
+    "name": "Boom 2",
    "data": {
      "host": "192.168.0.150",
      "devicesAllow": ["move","beam"],
@@ -1,6 +1,7 @@
 [
  {
-    "name": "MySpotify",
+    "id": "MySpotify",
+    "name": "Foxx Spotify",
    "enable": true,
    "clients": [],
    "data": {
@@ -1,6 +1,7 @@
 [
  {
-    "name": "MySubsonic",
+    "id": "mySubsonic",
+    "name": "Airsonic Server",
    "enable": true,
    "data": {
      "url": "http://localhost:4040/airsonic",
@@ -1,6 +1,7 @@
 [
    {
-        "name": "myTeal",
+        "id": "myTealClient",
+        "name": "Foxx Teal Client",
        "configureAs": "client",
        "data": {
            "identifier": "alice.bsky.social",
@@ -8,7 +9,8 @@
        }
    },
        {
-        "name": "myTealSource",
+        "id": "myTealSource",
+        "name": "Foxx Teal Source",
        "configureAs": "source",
        "data": {
            "identifier": "alice.bsky.social",
@@ -1,7 +1,8 @@
 [
  {
    "enable": true,
-    "name": "MyVlc",
+    "id": "myVlc",
+    "name": "Desktop",
    "data": {
      "url": "localhost:8080",
      "password": "changeme"
@@ -1,6 +1,7 @@
 [
  {
-    "name": "MyWebScrobbler",
+    "id": "MyWebScrobbler",
+    "name": "Firefox Laptop",
    "data": {
      "slug": "MyOptionalSlug",
      "whitelist": [],
@@ -1,5 +1,6 @@
 [
  {
+    "id": "myYandex",
    "name": "Yandex Music",
    "type": "ymbridge",
    "data": {
@@ -1,6 +1,7 @@
 [
  {
-    "name": "MyYTMusic",
+    "id": "myYtMusic",
+    "name": "Foxx YT Music",
    "enable": true,
    "clients": [],
    "data": {
@@ -18,3 +18,4 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+lib
@@ -0,0 +1,42 @@
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+var args = process.argv.slice(2);
+
+const linkRegex = new RegExp(/<link data-rh="true" rel="\w+"\shref="(https:\/\/foxxmd\.github\.io\/multi-scrobbler)/g,);
+const replacement = process.env.CANONICAL_HREF ?? 'https://docs.multi-scrobbler.app';
+
+/**
+ * Replace canonical and alternative <link> nodes with the "real" domain of the site
+ * so that SEO (google) chooses the correct domain when showing search results
+ * 
+ */
+
+(async function () {
+
+    if(replacement === undefined || replacement === '') {
+        console.warn('No replacement value found in process.env.CANONICAL_HREF');
+        return;
+    }
+
+    const buildDir = path.resolve(args[0]);
+    console.log(`Reading dir recursively ${buildDir}`);
+    const files = (await fs.readdir(buildDir, { recursive: true })).filter(x => x.includes('.html'));
+    console.log(`Found ${files.length} files with .html extensions`);
+    let modifications = 0;
+
+    await Promise.all(files.map(async (x) => {
+            const filePath = path.resolve(path.join(buildDir, x));
+            //console.log(`Replacing at ${filePath}`);
+            await fs.writeFile(filePath, (await fs.readFile(filePath)).toString().replace(linkRegex, (match, capture, offset, string, groups) => {
+                // this may not be fully accurate since we're mutating concurrently/async
+                // but its a good enough signal for logging to tell if replacements happened
+                modifications++;
+                return match.replace(capture, replacement);
+            }));
+    }));
+
+    console.log(`Done with ${modifications} replacements`);
+
+}());
@@ -114,6 +114,12 @@ It means the JSON in your configuration file is not valid. Copy and paste your c

 ## Scrobbling Issues

+### How do I prevent duplicate scrobbles?
+
+Multi-scrobbler has a [robust duplicate scrobble detection system](/configuration/duplicates#how-duplicates-are-detected) that should handle this for you in the majority of usecases. If you have a [simple setup without any circular dependencies](/configuration/duplicates#valid-configs) then you are already protected against duplicates.
+
+If your scenario is more complex or you have a service(s) acting as **both** a **Client** and **Source** you should refer to the [**Duplicate Scrobble Guidance**](/configuration/duplicates#valid-configs) page to determine if you can avoid a configuration that may result in duplicate scrobbles.
+
 ### Last.fm does not scrobble tracks with multiple artists correctly

 This is a limitation of the [Last.fm API](https://www.last.fm/api/show/track.scrobble) where the **artist** field is only one string and Last.fm does not recognize (play well) with "combined" artists.
@@ -0,0 +1,177 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs groupId="configType" queryString>
+<TabItem value="file" label="File">
+
+Using [File Config](/configuration/?configType=file#configuration-types)
+
+```json5 title="CONFIG_DIR/jellyin.json"
+[
+  {
+    "id": "fredJf",
+    "name": "Freds Jellyfin",
+    "clients": ["fredLFM"],
+    "data": {
+      "url": "https://jellyfin.fred.com",
+      "user": "Fred",
+      "apiKey": "c9fae8756fbf481ebd9c5bb56bd6540c"
+    }
+  },
+  {
+    "id": "maryJf",
+    "name": "Marys Jellyfin",
+    "clients": ["maryLFM"],
+    "data": {
+      "url": "https://jellyfin.mary.com",
+      "user": "Mary",
+      "apiKey": "26fe9c5dc6374542adc4f4d5e8352838"
+    }
+  }
+]
+```
+
+```json5 title="CONFIG_DIR/plex.json"
+[
+  {
+    "id": "foxxPlex",
+    "name": "Foxx Plex",
+    "clients": ["foxxKoi"],
+    "data": {
+      "token": "JtRnwQWD__XMJF8sT3jc",
+      "url": "192.168.0.233:32400"
+    }
+  }
+]
+```
+
+```json5 title="CONFIG_DIR/lastfm.json"
+[
+  {
+    "id": "maryLFM",
+    "name": "Marys Lastfm",
+    "configureAs": "client",
+    "data": {
+      "apiKey": "maryApiKey",
+      "secret": "marySecret",
+      "redirectUri": "http://localhost:9078/lastfm/callback"
+    }
+  },
+  {
+    "id": "fredLFM",
+    "name": "Freds Lastfm",
+    "configureAs": "client",
+    "data": {
+      "apiKey": "fredApiKey",
+      "secret": "fredSecret",
+      "redirectUri": "http://localhost:9078/lastfm/callback"
+    }
+  }
+]
+```
+
+```json5 title="CONFIG_DIR/koito.json"
+[
+  {
+    "id": "foxxKoi",
+    "name": "Foxx Koito",
+    "configureAs": "client",
+    "data": {
+      "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
+      "username": "admin",
+      "url": "http://192.168.0.100:4110"
+    }
+  }
+]
+```
+
+</TabItem>
+
+<TabItem value="aio" label="AIO">
+
+Using [AIO Config](/configuration/?configType=aio#configuration-types)
+
+```json5 title="CONFIG_DIR/config.json"
+{
+  "sources": [
+    {
+      "type": "jellyfin",
+      "id": "fredJf",
+      "name": "Freds Jellyfin",
+      "clients": [
+        "fredLFM"
+      ],
+      "data": {
+        "url": "https://jellyfin.fred.com",
+        "user": "Fred",
+        "apiKey": "c9fae8756fbf481ebd9c5bb56bd6540c"
+      }
+    },
+    {
+      "type": "jellyfin",
+      "id": "maryJf",
+      "name": "Marys Jellyfin",
+      "clients": [
+        "maryLFM"
+      ],
+      "data": {
+        "url": "https://jellyfin.mary.com",
+        "user": "Mary",
+        "apiKey": "26fe9c5dc6374542adc4f4d5e8352838"
+      }
+    },
+    {
+      "type": "plex",
+      "id": "foxxPlex",
+      "name": "Foxx Plex",
+      "clients": [
+        "foxxKoi"
+      ],
+      "data": {
+        "token": "JtRnwQWD__XMJF8sT3jc",
+        "url": "192.168.0.233:32400",
+        "usersallow": [
+          "foxx"
+        ]
+      }
+    }
+  ],
+  "clients": [
+    {
+      "type": "lastfm",
+      "id": "maryLFM",
+      "name": "Marys Lastfm",
+      "configureAs": "client",
+      "data": {
+        "apiKey": "maryApiKey",
+        "secret": "marySecret",
+        "redirectUri": "http://localhost:9078/lastfm/callback"
+      }
+    },
+    {
+      "type": "lastfm",
+      "id": "fredLFM",
+      "name": "Freds Lastfm",
+      "configureAs": "client",
+      "data": {
+        "apiKey": "fredApiKey",
+        "secret": "fredSecret",
+        "redirectUri": "http://localhost:9078/lastfm/callback"
+      }
+    },
+    {
+      "type": "koito",
+      "id": "foxxKoi",
+      "name": "Foxx Koito",
+      "configureAs": "client",
+      "data": {
+        "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
+        "username": "admin",
+        "url": "http://192.168.0.100:4110"
+      }
+    }
+  ]
+}
+```
+</TabItem>
+</Tabs>
@@ -0,0 +1,196 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs groupId="configType" queryString>
+<TabItem value="env" label="ENV">
+
+Using [ENV Config](/configuration/?configType=env#configuration-types)
+
+```yaml title="compose.yaml"
+services:
+  multi-scrobbler:
+    image: foxxmd/multi-scrobbler
+    container_name: multi-scrobbler
+    environment:
+      - TZ=Etc/GMT # Specify timezone from TZ Database name found here https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+      # spotify
+      - SPOTIFY_ID=foxxSpotify
+      - SPOTIFY_CLIENT_ID=H2UvGv8okrFlv2OUoc1lAtK7Xe5EGDgs
+      - SPOTIFY_CLIENT_SECRET=HvoFE5Ce2hdblNE6vaFBEx6dRVcDdo43
+      - SPOTIFY_REDIRECT_URI=https://multiscrobbler.example.com/callback
+
+      # navidrome listenbrainz endpoint
+      - LZE_ID=myLzNavidrome
+      - LZE_TOKEN=myToken
+
+      # plex
+      - PLEX_ID=foxxPlex
+      - PLEX_URL=192.168.0.233:32400
+      - PLEX_TOKEN=JtRnwQWD__XMJF8sT3jc
+      - PLEX_USERS_ALLOW=foxx
+      - PLEX_LIBRARIES_ALLOW=oldies
+
+      # lastfm
+      - LASTFM_ID=myLFM
+      - LASTFM_API_KEY=myApiKey
+      - LASTFM_SECRET=mySecret
+      - LASTFM_REDIRECT_URI=https://multiscrobbler.example.com/lastfm/callback
+
+      # koito
+      - KOITO_ID=foxxKoi
+      - KOITO_TOKEN=029b081ba-9156-4pe7-88e5-3be671f5ea2b
+      - KOITO_USER=admin
+      - KOITO_URL=http://192.168.0.100:4110
+
+    volumes:
+      - "./config:/config"
+    ports:
+      - "9078:9078"
+    restart: unless-stopped
+```
+
+</TabItem>
+<TabItem value="file" label="File">
+
+Using [File Config](/configuration/?configType=file#configuration-types)
+
+```json5 title="CONFIG_DIR/spotify.json"
+[
+  {
+    "id": "foxxSpotify",
+    "name": "Foxx Spotify",
+    "data": {
+      "clientId": "a89cba1569901a0671d5a9875fed4be1",
+      "clientSecret": "ec42e09d5ae0ee0f0816ca151008412a",
+      "redirectUri": "http://localhost:9078/callback",
+      "interval": 60
+    }
+  }
+]
+```
+
+```json5 title="CONFIG_DIR/endpointlz.json"
+[
+  {
+    "id": "myLzNavidrome",
+    "name": "LZ for Navidrome",
+    "data": {
+      "token": "myToken"
+    }
+  }
+]
+```
+
+```json5 title="CONFIG_DIR/plex.json"
+[
+  {
+    "id": "foxxPlex",
+    "name": "Foxx Plex",
+    "data": {
+      "token": "JtRnwQWD__XMJF8sT3jc",
+      "url": "192.168.0.233:32400",
+      "usersallow": ["foxx"],
+      "librariesAllow": ["oldies"],
+    }
+  }
+]
+```
+
+```json5 title="CONFIG_DIR/lastfm.json"
+[
+  {
+    "id": "myLFM",
+    "name": "Old Lastfm",
+    "configureAs": "client",
+    "data": {
+      "apiKey": "myApiKey",
+      "secret": "mySecret",
+      "redirectUri": "http://localhost:9078/lastfm/callback"
+    }
+  }
+]
+```
+
+```json5 title="CONFIG_DIR/koito.json"
+[
+  {
+    "id": "foxxKoi",
+    "name": "Foxx Koito",
+    "configureAs": "client",
+    "data": {
+      "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
+      "username": "admin",
+      "url": "http://192.168.0.100:4110"
+    }
+  }
+]
+```
+
+</TabItem>
+
+<TabItem value="aio" label="AIO">
+
+Using [AIO Config](/configuration/?configType=aio#configuration-types)
+
+```json5 title="CONFIG_DIR/config.json"
+{
+  "sources": [
+    {
+      "type": "spotify",
+      "id": "foxxSpotify",
+      "name": "Foxx Spotify",
+      "data": {
+        "clientId": "a89cba1569901a0671d5a9875fed4be1",
+        "clientSecret": "ec42e09d5ae0ee0f0816ca151008412a",
+        "redirectUri": "http://localhost:9078/callback",
+        "interval": 60
+      }
+    },
+    {
+      "type": "endpointlz",
+      "name": "LZ for Navidrome",
+      "id": "myLzNavidrome",
+      "data": {
+        "token": "myToken"
+      }
+    },
+    {
+      "type": "plex",
+      "id": "foxxPlex",
+      "name": "Foxx Plex",
+      "data": {
+        "token": "JtRnwQWD__XMJF8sT3jc",
+        "url": "192.168.0.233:32400",
+        "usersallow": ["foxx"],
+        "librariesAllow": ["oldies"]
+      }
+    }
+  ],
+  "clients": [
+    {
+      "type": "lastfm",
+      "id": "myLFM",
+      "name": "Old Lastfm",
+      "configureAs": "client",
+      "data": {
+        "apiKey": "myApiKey",
+        "secret": "mySecret",
+        "redirectUri": "http://localhost:9078/lastfm/callback"
+      }
+    },
+    {
+      "type": "koito",
+      "id": "foxxKoi",
+      "name": "Foxx Koito",
+      "configureAs": "client",
+      "data": {
+        "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
+        "username": "admin",
+        "url": "http://192.168.0.100:4110"
+      }
+    }
+  ]
+}
+```
+</TabItem>
+</Tabs>
@@ -0,0 +1,226 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs groupId="configType" queryString>
+<TabItem value="env" label="ENV">
+
+Using [ENV Config](/configuration/?configType=env#configuration-types)
+
+```yaml title="compose.yaml"
+services:
+  multi-scrobbler:
+    image: foxxmd/multi-scrobbler
+    container_name: multi-scrobbler
+    environment:
+      - TZ=Etc/GMT # Specify timezone from TZ Database name found here https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+
+      # required setup for musicbrainz
+      - MB_CONTACT=contact@mydomain.com # a real email
+       # searches with sensible release sorting with the searchOrder
+       # isrc => basic => artist (native mode)
+      - MB_PRESETS=default,sensible,native
+
+      # spotify
+      - SPOTIFY_ID=foxxSpotify
+      - SPOTIFY_CLIENT_ID=H2UvGv8okrFlv2OUoc1lAtK7Xe5EGDgs
+      - SPOTIFY_CLIENT_SECRET=HvoFE5Ce2hdblNE6vaFBEx6dRVcDdo43
+      - SPOTIFY_REDIRECT_URI=https://multiscrobbler.example.com/callback
+
+      # navidrome listenbrainz endpoint
+      - LZE_ID=myLzNavidrome
+      - LZE_TOKEN=myToken
+      # applies musicbrainz Stage to preTransform of navidrome source
+      - LZE_TRANSFORMS=musicbrainz
+
+      # lastfm
+      - LASTFM_ID=myLFM
+      - LASTFM_API_KEY=myApiKey
+      - LASTFM_SECRET=mySecret
+      - LASTFM_REDIRECT_URI=https://multiscrobbler.example.com/lastfm/callback
+
+    volumes:
+      - "./config:/config"
+    ports:
+      - "9078:9078"
+    restart: unless-stopped
+```
+
+</TabItem>
+<TabItem value="file" label="File">
+
+Using [File Config](/configuration/?configType=file#configuration-types)
+
+For non-ENV config, [Musicbrainz Transformer](/configuration/transforms/musicbrainz/#api-setup) must be setup using the [AIO Config](/configuration/?configType=aio#configuration-types) `config.json` file. This configuration uses the [sensible defaults](/configuration/transforms/musicbrainz/#sensible-default) in the `defaults` property. This is a suggestion and can be removed if not desired.
+
+```json5 title="CONFIG_DIR/config.json"
+{
+  "transformers": [
+    {
+      "type": "musicbrainz",
+      "name": "MyMB",
+      "data": {
+        "apis": [
+          {
+            "contact": "contact@mydomain.com"
+          }
+        ]
+      },
+      "defaults": {
+        "releaseStatusPriority": ["official"],
+        "releaseGroupPrimaryTypePriority": [
+          "album",
+          "single",
+          "ep"
+        ],
+        "releaseCountryPriority": ["XW"],
+        "searchArtistMethod": "native",
+        "searchOrder": [
+          "isrc",
+          "basic",
+          "artist"
+        ]
+      }
+    }
+  ]
+}
+```
+
+```json5 title="CONFIG_DIR/spotify.json"
+[
+  {
+    "id": "foxxSpotify",
+    "name": "Foxx Spotify",
+    "data": {
+      "clientId": "a89cba1569901a0671d5a9875fed4be1",
+      "clientSecret": "ec42e09d5ae0ee0f0816ca151008412a",
+      "redirectUri": "http://localhost:9078/callback",
+      "interval": 60
+    }
+  }
+]
+```
+
+```json5 title="CONFIG_DIR/endpointlz.json"
+[
+  {
+    "id": "myLzNavidrome",
+    "name": "LZ for Navidrome",
+    "data": {
+      "token": "myToken"
+    },
+    "options": {
+      "playTransform": {
+        "preCompare": [
+          {
+            "type": "musicbrainz",
+            "name": "MyMB"
+          }
+        ]
+      }
+    }
+  }
+]
+```
+
+
+```json5 title="CONFIG_DIR/lastfm.json"
+[
+  {
+    "id": "myLFM",
+    "name": "Old Lastfm",
+    "configureAs": "client",
+    "data": {
+      "apiKey": "myApiKey",
+      "secret": "mySecret",
+      "redirectUri": "http://localhost:9078/lastfm/callback"
+    }
+  }
+]
+```
+
+</TabItem>
+
+<TabItem value="aio" label="AIO">
+
+Using [AIO Config](/configuration/?configType=aio#configuration-types)
+
+This configuration uses the [sensible defaults](/configuration/transforms/musicbrainz/#sensible-default) in the `defaults` property. This is a suggestion and can be removed if not desired.
+
+```json5 title="CONFIG_DIR/config.json"
+{
+  "transformers": [
+    {
+      "type": "musicbrainz",
+      "name": "MyMB",
+      "data": {
+        "apis": [
+          {
+            "contact": "contact@mydomain.com"
+          }
+        ]
+      },
+      "defaults": {
+        "releaseStatusPriority": ["official"],
+        "releaseGroupPrimaryTypePriority": [
+          "album",
+          "single",
+          "ep"
+        ],
+        "releaseCountryPriority": ["XW"],
+        "searchArtistMethod": "native",
+        "searchOrder": [
+          "isrc",
+          "basic",
+          "artist"
+        ]
+      }
+    }
+  ],
+  "sources": [
+    {
+      "type": "spotify",
+      "id": "foxxSpotify",
+      "name": "Foxx Spotify",
+      "data": {
+        "clientId": "a89cba1569901a0671d5a9875fed4be1",
+        "clientSecret": "ec42e09d5ae0ee0f0816ca151008412a",
+        "redirectUri": "http://localhost:9078/callback",
+        "interval": 60
+      }
+    },
+    {
+      "type": "endpointlz",
+      "name": "LZ for Navidrome",
+      "id": "myLzNavidrome",
+      "data": {
+        "token": "myToken"
+      },
+      "options": {
+        "playTransform": {
+          "preCompare": [
+            {
+              "type": "musicbrainz",
+              "name": "MyMB"
+            }
+          ]
+        }
+      }
+    }
+  ],
+  "clients": [
+    {
+      "type": "lastfm",
+      "id": "myLFM",
+      "name": "Old Lastfm",
+      "configureAs": "client",
+      "data": {
+        "apiKey": "myApiKey",
+        "secret": "mySecret",
+        "redirectUri": "http://localhost:9078/lastfm/callback"
+      }
+    }
+  ]
+}
+```
+</TabItem>
+</Tabs>
@@ -34,60 +34,9 @@ For each Play, MS fetches (cached) scrobbles from the Client in a time range inc
 * Temporal closeness of the Play's timestamp to the existing scrobble's timestamp
 * Whether MS detected the Play as a repeat (applicable to Sources that report realtime Player data)

-Detailed scoring breakdowns against each existing scrobble are logged at the `TRACE` level.
+Detailed scoring breakdowns against each existing scrobble are logged at the `TRACE` logging level or in the [debug data](/help#copy-play-debug-data) for a scrobble.

-<details>
-
-<summary>Detailed Explanation</summary>
-
-A **candidate** (to be scrobbled) Play is first transformed using the configured [`compare.candidate` Hook](/configuration/transforms/#hook), if any exists.
-
-Next, MS checks (up to) the last 100 scrobbles *in-memory* scrobbles that it has made. These are *not* from the Client but the actual scrobbles MS made while it has been running. The data from these scrobbles is much richer than what is usually parsed from the Client which makes it easier to detect duplicates from.
-
-If no in-memory scrobble matches then MS starts comparing the candidate against historical scrobbles fetched from an inclusive time range of the candidate's timestamp.
-
-<h3>Matching Title/Artist/Album</h3>
-
-For these string-based values MS uses an [token-order-invariant](https://github.com/FoxxMD/multi-scrobbler/blob/0dfa4c7aad6df98e13aee6d395827665c2414adb/src/backend/utils/StringUtils.ts#L299) method that scores string similarity based on a (token count) weighted average of two [similarity](https://foxxmd.github.io/string-sameness/#md:strategies) algorithms, [Levenshtien Distance](https://en.wikipedia.org/wiki/Levenshtein_distance) and [Dice's Coefficient](https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient). The weighted average ensures that very long strings (Track titles) are scored with a confidence proportional to their length.
-
-<h3>Matching Timestamp</h3>
-
-Timestamps are scored on how temporally close they are. There are four possible scores with decreasing value:
-
-* **Exact** - Timestamps are within 1 second of each other
-* **Close** - Timestamps are within `threshold` seconds of each other
-  * This is determined by the smallest update interval of Source
-    * Some Sources (subsonic) only update every 60 seconds so this is the smallest "close" value possible. Most are 10 seconds. Signified by `(Needed <10s)` in the breakdown example below.
-* **Fuzzy** - One timestamp is within `threshold` seconds of the *end* of the other timestamp
-  * Sources can set the scrobble timestamp at different times. Some do it when the track is started listening to, some when it ends, some when the *player* stops.
-  * Where possible, MS knows and keeps track of when this timestamp *should* be, for each Source. If it's not possible then Fuzzy may be allowed.
-* **None** - There is no correlation between timestamps
-
-<h3>Scoring and Breakdows</h3>
-
-A candidate Play must score >= 1 to be detected as a duplicate of an existing scrobble.
-
-Each score and a breakdown of the scores for its individual components can be see at the `TRACE` logging level or in the [debug data](/help#copy-play-debug-data) for a scrobble. An example:
-
-```
-* Artist: 0.06 * 0.3 = 0.02
-* Title: 0.04 * 0.4 = 0.02
-* Time: (Exact) 1 * 0.5 = 0.50
-  * Existing: 19:13:33-04:00 - Candidate: 19:13:33-04:00
-  * Temporal Sameness: Exact
-  * Play Diff: 0s (Needed <10s)
-  * Range Comparison N/A
-Score 0.54 => No Match
-```
-
-In each component equation, the first number is the similarity (or temporal closeness).
-
-* 0 = no correlation
-* 1 = exactly the same
-
-The second number is the *weight* of that component in the final score.
-
-</details>
+See the [**Duplicate Scrobble Guidance**](/configuration/duplicates#how-duplicates-are-detected) page to learn how duplicates are detected and how you can ensure your configuration avoids possible duplicates.

 ### Dead Scrobbles

@@ -22,7 +22,7 @@ Check the [main Discord docs page](/configuration/clients/discord) for a compari

 <DetailsAdmo type="note" summary="How MS Uses Discord API">

-Multi-scrobbler does its upmost to implement, to-spec, [Gateway API communication](https://docs.discord.com/developers/events/gateway) and respect usage. It requires no [permissions](https://docs.discord.com/developers/events/gateway#gateway-intents) and reads no data other than monitoring what other user sessions are active.
+Multi-scrobbler does its utmost to implement, to-spec, [Gateway API communication](https://docs.discord.com/developers/events/gateway) and respect usage. It requires no [permissions](https://docs.discord.com/developers/events/gateway#gateway-intents) and reads no data other than monitoring what other user sessions are active.

 Aside from the on-paper violation of using a user token programmatically (on your behalf), there is no misuse of the API to achieve rich presence.

@@ -45,7 +45,7 @@ Using the URL path `/apis/listenbrainz` [Koito docs describe](https://koito.io/g

 :::tip

-Ensure that Koito is configured to allow requests from multi-scrobbler! In Koito config set [`KOITO_ALLOWED_HOSTS`](https://koito.io/reference/configuration/#koito_allowed_hosts) to the IP the multi-scrobbler dashboard is accessible from.
+For Koito versions `<=0.1.7`, you must have the environment variable `KOITO_ALLOWED_HOSTS` set correctly in your Koito environment/container. Ensure it is set to the IP address or domain name that you use to access Koito with e.g. `koito.mydomain.com`. 

 :::

@@ -54,7 +54,9 @@ Ensure that Koito is configured to allow requests from multi-scrobbler! In Koito
 <Config config="KoitoClientConfig" fileContent={JsonConfig} client name="koito">
        | Environmental Variable | Required? | Default | Description                       |
        | :--------------------- | --------- | ------- | --------------------------------- |
+        | `KOITO_ID`             | Yes       |         | A unique id                       |
        | `KOITO_TOKEN`          | Yes       |         | API Key from your Koito Account   |
        | `KOITO_USER`           | Yes       |         | Your Koito username               |
        | `KOITO_URL`            | No        |         | The base URL for the Koito server |
-</Config>
+        | `KOITO_NAME`           | No        |         | A vanity name, different than ID  |
+</Config>
@@ -16,6 +16,20 @@ import JsonConfig from '!!raw-loader!@site/../config/lastfm.json.example';

 :::

+<DetailsAdmo type="warning" summary="Limits for Old Scrobbles">
+
+Last.fm will not accept scrobbles that are timestamped as **older than 2 weeks** from the current time.
+
+This is not officially documented but has been confirmed by multiple people/mods in the last.fm support forums: [[1]](https://support.last.fm/t/importing-listening-history-spotify-apple-music-and-itunes-wmp/1424/3) [[2]](https://support.last.fm/t/suggestion-allow-last-fm-pro-members-to-use-the-api-to-submit-scrobbles-older-than-2-weeks/69190/2) [[3]](https://support.last.fm/t/how-to-scrobble-complete-spotify-history/44558)
+
+Multi-scrobbler can queue scrobbles for you if the Last.fm service is unavailable, or if there is an issue with a specific scrobble. However, you are responsible for making sure these scrobbles are eventually sent to Last.fm (by retrying in the UI or retarting Last.fm client in UI) before the two week window has passed or else they will not be scrobblable *at all* unless the timestamp is changed.
+
+A future update to Multi-scrobbler will enable editing of unsent scrobble data and modifying the timestamp from the UI.
+
+If you have issues with specific scrobbles not being sent and retries/restarts do not fix it, please make sure to [create a new issue](https://github.com/FoxxMD/multi-scrobbler/issues/new?template=01-bug-report.yml) in a timely manner so that it can be resolved before the window has passed.
+
+</DetailsAdmo>
+
 You will need a [Last.fm](https://www.last.fm) account to use the Last.fm API.

 After creating your account, [register for an API account here.](https://www.last.fm/api/account/create)
@@ -51,8 +65,10 @@ The Redirect URL can be explicitly specified in the configuration below, or by u
 <Config config="LastfmClientConfig" fileContent={JsonConfig} client name="lastfm">
        | Environmental Variable | Required? | Default                                 | Description                                                                   |
        | ---------------------- | --------- | --------------------------------------- | ----------------------------------------------------------------------------- |
+        | `LASTFM_ID`            | Yes       |                                         | A unique id                                                                   |
        | `LASTFM_API_KEY`       | Yes       |                                         | Api Key from your API Account                                                 |
        | `LASTFM_SECRET`        | Yes       |                                         | Shared secret from your API Account                                           |
        | `LASTFM_REDIRECT_URI`  | No        | `http://localhost:9078/lastfm/callback` | Url to use for authentication. Must include `lastfm/callback` somewhere in it |
        | `LASTFM_SESSION`       | No        |                                         | Session id. Will be generated by authentication flow if not provided.         |
+        | `LASTFM_NAME`          | No        |                                         | A vanity name, different than ID                                              |
 </Config>
@@ -56,10 +56,12 @@ https://my.cool.libre.com/2.0/
 <Config config="LibrefmClientConfig" fileContent={JsonConfig} client name="librefm">
        | Environmental Variable | Required? | Default                                  | Description                                                                                      |
        | ---------------------- | --------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
-        | `LIBREFM_ENABLE`       | No        |                                          | Set to `true` to enable Libre.fm, if not using any of the below variables                                                                                                 |
+        | `LIBREFM_ID`           | Yes       |                                          | A unique ID                                                                                      |
+        | `LIBREFM_ENABLE`       | No        |                                          | Set to `true` to enable Libre.fm, if not using any of the below variables                        |
        | `LIBREFM_API_KEY`      | No        | `anything`                               | Optional API Key                                                                                 |
        | `LIBREFM_SECRET`       | No        | `anything`                               | Optional shared secret                                                                           |
        | `LIBREFM_REDIRECT_URI` | No        | `http://localhost:9078/librefm/callback` | Url to use for authentication. Must include `librefm/callback` somewhere in it                   |
        | `LIBREFM_SESSION`      | No        |                                          | Session id. Will be generated by authentication flow if not provided.                            |
        | `LIBREFM_URLBASE`      | No        |                                          | Use for custom Libre.fm instance only. The host + path prefix EX `https://my.libre.example/2.0/` |
+        | `LIBREFM_NAME`         | No        |                                          | A vanity name different than ID                                                                  |
 </Config>
@@ -25,7 +25,9 @@ On your [profile page](https://listenbrainz.org/profile/) find your **User Token
 <Config config="ListenBrainzClientConfig" fileContent={JsonConfig} client name="listenbrainz">
        | Environmental Variable | Required? | Default                       | Description                     |
        | ---------------------- | --------- | ----------------------------- | ------------------------------- |
+        | `LZE_ID`               | Yes       |                               | A unique ID                     |
        | `LZ_TOKEN`             | Yes       |                               | User token from your LZ profile |
        | `LZ_USER`              | Yes       |                               | Your LZ username                |
        | `LZ_URL`               | No        | https://api.listenbrainz.org/ | The base URL for the LZ server  |
+        | `LZ_NAME`              | No        |                               | A vanity name different than ID |
 </Config>
@@ -38,8 +38,10 @@ Finally, add the Maloja server URL and API Key to the configuration type you cho
 ## Configuration

 <Config config="MalojaClientConfig" fileContent={JsonConfig} client name="maloja">
-        | Environmental Variable | Required? | Default | Description                   |
-        |------------------------|-----------|---------|-------------------------------|
-        | `MALOJA_URL`           | Yes       |         | Base URL of your installation |
-        | `MALOJA_API_KEY`       | Yes       |         | Api Key                       |
+        | Environmental Variable | Required? | Default | Description                     |
+        | ---------------------- | --------- | ------- | ------------------------------- |
+        | `MALOJA_ID`            | Yes       |         | A unique ID                     |
+        | `MALOJA_URL`           | Yes       |         | Base URL of your installation   |
+        | `MALOJA_API_KEY`       | Yes       |         | Api Key                         |
+        | `MALOJA_NAME`          | No        |         | A vanity name different than ID |
 </Config>
@@ -67,6 +67,8 @@ If you do not include a TLD then multi-scrobbler will automatically append `.bsk
 <Config config="RockSkyClientConfig" fileContent={JsonConfig} client name="rocksky">
        | Environmental Variable | Required? | Default | Description                                                                         |
        | :--------------------- | --------- | ------- | ----------------------------------------------------------------------------------- |
+        | `ROCKSKY_ID`           | Yes       |         | A unique ID                                                                         |
        | `ROCKSKY_HANDLE`       | Yes       |         | Your **full** ATProto handle. For Bluesky account this is like `myUser.bsky.social` |
        | `ROCKSKY_KEY`          | Yes       |         | API Key obtained from Rocksky developer dashboard                                   |
+        | `ROCKSKY_NAME`         | No        |         | A vanity name different than ID                                                     |
 </Config>
@@ -73,6 +73,8 @@ If your identifier does not look like a DID and does not include a TLD then mult
 <Config config="TealClientConfig" fileContent={JsonConfig} client name="tealfm">
        | Environmental Variable | Required? | Default | Description                                                                                |
        | :--------------------- | --------- | ------- | ------------------------------------------------------------------------------------------ |
+        | `TEAMFM_ID`            | Yes       |         | A unique ID                                                                                |
        | `TEALFM_IDENTIFIER`    | Yes       |         | Your **full** ATProto handle or DID. For Bluesky account this is like `myUser.bsky.social` |
        | `TEALFM_APP_PW`        | Yes       |         | Bluesky/ATProto network App Password                                                       |
+        | `TEALFM_NAME`          | No        |         | A vanity name different than ID                                                            |
 </Config>
@@ -245,11 +245,8 @@ WARN : [App] [Sources] [spotify Secrets] Matched: None | Unmatched: SPOTIFY_SECR

 </DetailsAdmo>

-## Application Options

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

 Defines the URL that is used to generate default redirect URLs for authentication on [spotify](/configuration/sources/spotify) and [lastfm](/configuration/clients/lastfm) -- as well as some logging hints.

@@ -280,79 +277,51 @@ Useful when running with [docker](../installation/installation.mdx#docker) so th

 </details>

-### Caching
+## Caching

-Multi-scrobbler caches some activities to persist important data across restarts, reduce external API calls, and make some actions faster.
+Multi-scrobbler implements caching 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](#secondary-caching-configuration) for persistence.
+A default **in-memory** cache store is used so that you always benefit from some caching. An optional, [**secondary** store](#secondary-caching) can be configured for greater caching capabilities.

-<Tabs groupId="cachedThings" queryString>
-<TabItem value="scrobbles" label="Scrobbles">
-
-**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](#secondary-caching-configuration) [File](./?cacheType=file#secondary-caching-configuration) store, configured for you automatically.
-
-If you have configured a [persisted volume/bind mount](/installation?dockerSetting=storage#recommended-settings) for configuration (`/config` is mounted in [docker compose](/quickstart#create-docker-compose-file)) then you are already done. If you are not persisting this directory then you should consider setting up [Valkey Cache](./?cacheType=valkey#secondary-caching-configuration) for this.
-
-:::
-
-##### Configuration
-
-Use any [Secondary Cache](#secondary-caching-configuration), the config examples below show the default values:
-
-<Tabs>
-<TabItem value="env" label="ENV">
-
-| Environmental Variable | Required? | Default   | Description           |
-| :--------------------- | --------- | --------- | --------------------- |
-| `CACHE_SCROBBLE`       | No        | `file`    | The cache type to use |
-| `CACHE_SCROBBLE_CONN`  | No        | `/config` |                       |
+<DetailsAdmo type="note" summary="What is Cached?">

+<Tabs groupId="cachedThings">
+<TabItem value="auth" label="Auth Data">
+Authentication sessions/tokens/etc... are cached for quicker requests and for persistence across restarts.
 </TabItem>
-
-<TabItem value="aio" label="AIO">
-
-```json5 title="config.json"
-{
-    "cache": {
-        "scrobble": {
-            "provider": "file",
-            "connection": "/config"
-        }
-    },
-    // ...
-}
-```
+<TabItem value="transform" label="Scrobble Transforms">
+The results of [transform rules](/configuration/transforms) are cached so that if a scrobble with identical data (track/artists/album) is identified and it has the same set of transform rules then the cached transform results can be applied.
+</TabItem>
+<TabItem value="metadata" label="Transform API Calls">
+API Calls to external (metadata) services used to [Enhance Scrobbles](/configuration/transforms), like calls to [Musicbrainz](/configuration/transforms/musicbrainz), can be cached to avoid duplicate calls and speed up scrobble transformations.
 </TabItem>
 </Tabs>

-</TabItem>
-<TabItem value="auth" label="Auth Data">
+</DetailsAdmo>

-Authentication sessions/tokens/etc... are cached for quicker requests and for persistence across restarts.
+<DetailsAdmo type="important" summary="Auth Cache Configuration">

-:::tip
+Auth caching defaults to a **file** that is stored in the `CONFIG_DIR` directory using the pre-defined file name `ms-auth.cache`.

-By default, this data use a [Secondary](#secondary-caching-configuration) [File](./?cacheType=file#secondary-caching-configuration) store, configured for you automatically.
+This provides automatic persistence across restarts for long-lived auth data/credentials if you have configured a [persisted volume/bind mount](/installation?dockerSetting=storage#recommended-settings) for configuration (`/config` is mounted in [docker compose](/quickstart#create-docker-compose-file)).

-If you have configured a [persisted volume/bind mount](/installation?dockerSetting=storage#recommended-settings) for configuration (`/config` is mounted in [docker compose](/quickstart#create-docker-compose-file)) then you are already done. If you are not persisting this directory then you should consider setting up [Valkey Cache](./?cacheType=valkey#secondary-caching-configuration) for this.
+If you wish to use the [secondary store](#secondary-caching) for caching Auth you must explicitly configure it. This is because valkey can potentially be *ephemeral* if you do not provide a volume for its data directory.

-:::
+To explicitly configure auth to use the secondary store:

-##### Configuration
-
-Use any [Secondary Cache](#secondary-caching-configuration), the config examples below show the default values:
-
-<Tabs>
+<Tabs groupId="configType" queryString>
 <TabItem value="env" label="ENV">

-| Environmental Variable | Required? | Default   | Description           |
-| :--------------------- | --------- | --------- | --------------------- |
-| `CACHE_AUTH`           | No        | `file`    | The cache type to use |
-| `CACHE_AUTH_CONN`      | No        | `/config` |                       |
+```yaml title="compose.yaml"
+services:
+  multi-scrobbler:
+  # ...
+  environment:
+  // highlight-start
+    - CACHE_AUTH=valkey
+  // highlight-end
+    # ...
+```

 </TabItem>

@@ -362,8 +331,7 @@ Use any [Secondary Cache](#secondary-caching-configuration), the config examples
 {
    "cache": {
        "auth": {
-            "provider": "file",
-            "connection": "/config"
+            "provider": "valkey"
        }
    },
    // ...
@@ -372,93 +340,19 @@ Use any [Secondary Cache](#secondary-caching-configuration), the config examples
 </TabItem>
 </Tabs>

-</TabItem>
-<TabItem value="metadata" label="Transform API Calls">
+</DetailsAdmo>

-API Calls to external (metadata) services used to [Enhance Scrobbles](/configuration/transforms), like calls to [Musicbrainz](/configuration/transforms/musicbrainz), can be cached to avoid duplicate calls and speed up scrobble transformations.
+### Secondary Caching Store {#secondary-caching}

-By default, these calls are only cached in memory. If you wish for cached calls to be persisted across restarts then setup [Valkey Cache](./?cacheType=valkey#secondary-caching-configuration).
+Using a secondary store enables:

-##### Configuration
+* persistence of cached data across restarts
+* a larger store (more data is saved)
+* a longer time-to-live in the store (cached data is fetchable for a longer period)

-Use any [Secondary Cache](#secondary-caching-configuration), the config examples below show the default values:
+These benefits are particularly beneficial when using [transforms](/configuration/transforms) like Musicbrainz and it is **strongly recommended** for these scenarios.

-<Tabs>
-<TabItem value="env" label="ENV">
-
-| Environmental Variable | Required? | Default | Description           |
-| :--------------------- | --------- | ------- | --------------------- |
-| `CACHE_METADATA`       | No        |         | The cache type to use |
-| `CACHE_METADATA_CONN`  | No        |         |                       |
-
-</TabItem>
-
-<TabItem value="aio" label="AIO">
-
-```json5 title="config.json"
-{
-    "cache": {
-        "metadata": {
-            "provider": "valkey",
-            "connection": "yourConnectionStringHere"
-        }
-    },
-    // ...
-}
-```
-</TabItem>
-</Tabs>
-
-</TabItem>
-</Tabs>
-
-#### Secondary Caching Configuration
-
-The type of cache used, and its connection properties, can be configured through **ENV** or **AIO** config.
-
-<Tabs groupId="cacheType" queryString>
-
-<TabItem value="file" label="File">
-
-**File** cache is stored in the `CONFIG_DIR` directory using the pre-defined file name `ms-[cacheName].cache`.
-
-<Tabs groupId="configType" queryString>
-
-<TabItem value="env" label="ENV">
-
-Example
-
-| Environmental Variable | Required? | Default   | Description                                                  |
-| :--------------------- | --------- | --------- | ------------------------------------------------------------ |
-| `CACHE_SCROBBLE`       | No        | `file`    | The cache type to use                                        |
-| `CACHE_SCROBBLE_CONN`  | No        | `/config` | The directory, within the container, to store the cache file |
-
-</TabItem>
-
-<TabItem value="aio" label="AIO">
-
-Example
-
-```json5 title="config.json"
-{
-    "cache": {
-        "scrobble": {
-            "provider": "file",
-            "connection": "/config"
-        }
-    },
-    // ...
-}
-```
-
-</TabItem>
-
-</Tabs>
-</TabItem>
-
-<TabItem value="valkey" label="Valkey">
-
-[**Valkey**](https://valkey.io/) is an open-source fork of Redis.
+Currently, Multi-scrobbler only supports [**Valkey**](https://valkey.io/), an open-source fork of Redis, as a secondary store.

 <details>

@@ -466,11 +360,13 @@ Example

 A valkey container can be added to the [multi-scrobbler docker compose stack](/installation?runType=docker-compose#docker):

+<Tabs>
+<TabItem value="named" label="Named Volume">
+
 ```yaml title="docker-compose.yml"
 services:
  multi-scrobbler:
  # ...
-  # adding everything below
  // highlight-start
  valkey:
    image: valkey/valkey
@@ -483,6 +379,25 @@ volumes:
  // highlight-end
 ```

+</TabItem>
+<TabItem value="bind" label="Bind Mount">
+
+```yaml title="docker-compose.yml"
+services:
+  multi-scrobbler:
+  # ...
+  // highlight-start
+  valkey:
+    image: valkey/valkey
+    volumes:
+      - ./valkeyData:/data
+  // highlight-end
+```
+
+</TabItem>
+
+</Tabs>
+
 Use `redis://valkey:6379` as the connection string in the configurations below.

 </details>
@@ -497,12 +412,16 @@ redis://HOST_IP:HOST_PORT

 <TabItem value="env" label="ENV">

-Example
-
-| Environmental Variable | Required? | Default  | Description                                                         |
-| :--------------------- | --------- | -------- | ------------------------------------------------------------------- |
-| `CACHE_METADATA`       | Yes       | `valkey` | The cache type to use                                               |
-| `CACHE_METADATA_CONN`  | Yes       |          | The host/IP and port to connect to EX: `redis://192.168.0.120:6379` |
+```yaml title="compose.yaml"
+services:
+  multi-scrobbler:
+  # ...
+  environment:
+  // highlight-start
+    - CACHE_VALKEY=redis://192.168.0.120:6379
+  // highlight-end
+    # ...
+```

 </TabItem>

@@ -513,10 +432,7 @@ Example
 ```json5 title="config.json"
 {
    "cache": {
-        "metadata": {
-            "provider": "valkey",
-            "connection": "redis://192.168.0.120:6379"
-        }
+        "valkey": "redis://192.168.0.120:6379"
    },
    // ...
 }
@@ -525,11 +441,275 @@ Example
 </TabItem>

 </Tabs>
+
+## Database
+
+Multi-scrobbler depends on a SQLite database (`ms.db`) that is created on first run and stored in the [`CONFIG_DIR`](/installation/?dockerSetting=storage#recommended-settings). When upgrading Multi-scrobbler version, if there are any required database changes than this database is [automatically backed up and migrated.](/updating#database)
+
+The database stores *all* Plays for your Sources/Clients as well as metadata and debugging information to help troubleshoot issues. Each Play is associated with a Source/Config in the database based on your configuration.
+
+You **should set IDs for each Source/Client** so that the database can identify these even when the configuration is changed.
+
+### Retention
+
+<DetailsAdmo status="note" summary="How much storage does the database use?">
+
+The amount of data stored for each Play can widely vary based on a few factors:
+
+* how much data the Source service exposes
+* how many clients each Source is scrobble to (Plays are duplicated for each Client a Source sends a scrobble to)
+* if you are using any [Transforms](/configuration/transforms) the diff of each step is stored, along with any external request/response data (like [Musicbrainz queries](/configuration/transforms/musicbrainz))
+
+The [MS repository contains a benchmark](https://github.com/FoxxMD/multi-scrobbler/blob/master/src/backend/tests/database/drizzle.test.ts#L551) to measure an average database size in a few common scenarios.
+
+<Tabs groupId="dbSize">
+
+<TabItem label="Minimal" value="minimal">
+
+Assuming your Sources send a minimal amount of data or you have compacted all plays:
+
+| Play Count | DB Size  |
+| ---------- | -------- |
+| 100        | `160kb`  |
+| 1000       | `1MB`    |
+| 10k        | `10.2MB` |
+
+</TabItem>
+
+<TabItem label="With Original Input" value="input">
+
+Assuming your Sources have a non-trivial amount of input data (like Spotify or Listenbrainz) that is not compacted:
+
+| Play Count | DB Size  |
+| ---------- | -------- |
+| 100        | `356kb`  |
+| 1000       | `3MB`    |
+| 10k        | `29.6MB` |
+
+</TabItem>
+
+<TabItem label="All Debug Deta" value="all">
+
+Assuming your Sources/Clients:
+
+* have a non-trivial amount of input data (like Spotify or Listenbrainz)
+* and has many [Transforms](/configuration/transforms) steps that include requests
+* nothing is compacted
+
+| Play Count | DB Size  |
+| ---------- | -------- |
+| 100        | `684kb`  |
+| 1000       | `6.28MB` |
+| 10k        | `61.3MB` |
+
 </TabItem>

 </Tabs>

-### Debug Mode
+</DetailsAdmo>
+
+A retention policy can be configured to delete Plays, or unused debug data, from the database after a certain amount of time. If no configuration is provided then a default policy is used that should be reasonable for most users.
+
+<Tabs groupId="policy" queryString>
+
+<TabItem label="Compaction" value="compaction">
+
+The **Compaction** Retention Policy is used to delete different types of debug data from your stored Plays.
+
+This is a useful way to reduce used storage space when you are not having problems with your Plays, or iterating on a configuration, that requires referencing all this extra data.
+
+There are two types of data that can be compacted (deleted from the Play):
+
+* `input` - this is the untouched data retrieved by Multi-scrobbler, from a Source, and used to generate a Play/scrobble. This can be used to reconstruct and replay a Play, when used from troubleshooting or reporting an issue
+* `transform` - this is all of the steps generated by [transforms](/configuration/transforms), the diff of the Play resulting from the step, and any request/responses used to complete the step
+
+:::note[Defaults]
+
+When no Compact configuration is provided, Multi-scrobbler uses this policy:
+
+* Compact (delete) `input` and `transform` data on all Plays after 3 days
+
+:::
+
+#### Configuring Compaction Policy
+
+<details>
+
+<summary>Details</summary>
+
+Each value in the configuration properties below can be either
+
+* a number of seconds EX `3600` = 10 minutes
+* a unit of a common duration with the pattern `X unit` EX
+  * `30 minutes`
+  * `5 hours`
+  * `2 days`
+
+<Tabs groupId="configType" queryString>
+
+<TabItem value="env" label="ENV">
+
+* `COMPACT_PROPERTIES` - which properties to compact
+* `RETENTION_COMPACT_AFTER` - Default to use for all Plays
+* `RETENTION_COMPACT_COMPLETED_AFTER` - Compact only completed Plays after...
+* `RETENTION_COMPACT_FAILED_AFTER` - Compact only failed Plays after...
+* `RETENTION_COMPACT_DUPED_AFTER` - Compact only duped/discard Plays after...
+
+Example
+
+```ini
+# only delete input when compacting
+COMPACT_PROPERTIES=input
+# compact all plays after 3 days 
+RETENTION_COMPACT_AFTER=3 days
+# specifically compact completed plays after 30 minutes
+RETENTION_COMPACT_COMPLETED_AFTER=30 minutes
+```
+
+</TabItem>
+<TabItem value="aio" label="AIO">
+
+Compacting all Play types and deleting both input and transform: 
+
+```json title="config.json"
+{
+  "database": {
+    "retention": {
+      "compactAfter": "3 days",
+      "compact": [
+        "input",
+        "transform"
+      ]
+    }
+  }
+}
+```
+
+* Delete only input during compacting
+* Compact all after 3 days except completed which compacts after 30 minutes
+
+```json title="config.json"
+{
+  "database": {
+    "retention": {
+      "compactAfter": {
+        "completed": "30 minutes",
+        "duped": "3 days",
+        "failed": "3 days"
+      },
+      "compact": [
+        "input"
+      ]
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+</details>
+
+</TabItem>
+
+<TabItem label="Deletion" value="deletion">
+
+The **Deletion** Retention Policy is used to delete different types of stored Plays from Multi-scrobbler database.
+
+**This does not delete Plays from your Clients.** It's only deleting the "in-flight" data MS used to create the scrobble that was eventually sent to your clients.
+
+:::warning[Plays Should be Ephemeral]
+
+**Multi-Scrobbler is not designed to store Plays/Scrobbles indefinitely.**
+
+It should scale fine for thousands of scrobbles but it not meant to store 10's of thousands of scrobbles forever. It is not a scrobbler server.
+
+You **should** set a reasonable deletion policy so that MS stores less than 1000 scrobbles at a time, ideally less.
+
+:::
+
+:::note[Defaults]
+
+When no Deletion policy configuration is provided, Multi-scrobbler uses this policy:
+
+* Delete all Plays after 7 days
+
+:::
+
+#### Configuring Deletion Policy
+
+<details>
+
+<summary>Details</summary>
+
+Each value in the configuration properties below can be either
+
+* a number of seconds EX `3600` = 10 minutes
+* a unit of a common duration with the pattern `X unit` EX
+  * `30 minutes`
+  * `5 hours`
+  * `2 days`
+
+<Tabs groupId="configType" queryString>
+
+<TabItem value="env" label="ENV">
+
+* `RETENTION_DELETE_AFTER` - Default to use for all Plays
+* `RETENTION_DELETE_COMPLETED_AFTER` - Delete only completed Plays after...
+* `RETENTION_DELETE_FAILED_AFTER` - Delete only failed Plays after...
+* `RETENTION_DELETE_DUPED_AFTER` - Delete only duped/discard Plays after...
+
+Example
+
+```ini
+# delete all plays after 3 days 
+RETENTION_DELETE_AFTER=3 days
+# specifically, delete completed plays after 30 minutes
+RETENTIOND_DELETE_COMPLETED_AFTER=30 minutes
+```
+
+</TabItem>
+<TabItem value="aio" label="AIO">
+
+Deleting all Play types after 3 days: 
+
+```json title="config.json"
+{
+  "database": {
+    "retention": {
+      "deleteAfter": "3 days"
+    }
+  }
+}
+```
+
+* Delete all after 3 days except completed which are deleted after 30 minutes
+
+```json title="config.json"
+{
+  "database": {
+    "retention": {
+      "deleteAfter": {
+        "completed": "30 minutes",
+        "duped": "3 days",
+        "failed": "3 days"
+      },
+    }
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+</details>
+
+</TabItem>
+
+
+</Tabs>
+
+## Debug Mode

 Turning on Debug Mode will

@@ -550,7 +730,7 @@ To set debug mode either add it to [AIO `config.json`](./?configType=aio#configu

 or set the [ENV](./?configType=env#configuration-types) `DEBUG_MODE=true`

-### Disable Web
+## 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.

@@ -0,0 +1,267 @@
+---
+sidebar_position: 4
+title: Duplicate Scrobble Guidance
+description: Common Scenarios and Solutions for Duplicate Scrobbles
+---
+
+Multi-scrobbler's flexibility in configuration allows you to build some complex pipelines for scrobbling but it can also be a footgun for duplicating scrobbles.
+
+## How Duplicates Are Detected
+
+Multi-scrobbler uses multiple techniques for evaluating the **similarity** of text in scrobbles against existing data.
+
+These techniques are used on all text from a scrobble (title, artist, album...):
+
+<details>
+
+<summary>Character and string normalization</summary>
+
+Symbols and multiple whitespaces are removed. All characters are converted to lowercase. Non ascii characters are converted to their ascii counterparts.
+
+```
+this string! is the. same    => this string is the same
+this string   is the    same => this string is the same
+ThIs STRING iS THe SAMe      => this string is the same
+
+Dina Ögon => Dina Ogon
+Nanã      => Nana
+```
+
+</details>
+
+<details>
+
+<summary>Word-order invariant text similarity</summary>
+
+Strings with multiple words (tokens) are re-arranged so that tokens are ordered to be as close to other, similar tokens are possible:
+
+Example 1
+
+```
+String A: there change is  => there change is
+String B: there is change  => there change is
+```
+
+Example 2
+
+```
+String A: you, doin hwat are  => you doin hwat are
+String B: what are you doing  => you doing what are
+```
+
+Then, the strings are independently compared using [Levenshtein Distance](https://en.wikipedia.org/wiki/Levenshtein_distance) and [Dice's Coefficient](https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient). The algorithm that gives the highest score for similarity is used so that matching is aggressive.
+
+
+</details>
+
+For **Artists**, Multi-scrobbler attempts to extract unique Artists from common patterns in **single-string** artist values and track **titles**.
+
+<details>
+
+<summary>Matching Common Artist Patterns</summary>
+
+Common joiners and patterns are detected in artist/track strings and the artists are extracted. Example of common joiners are: `ft.` `feat` `vs.` etc...
+
+Example 1
+
+```
+Melendi, Ryan Lewis, The Righteous Brothers (featuring Joan Jett & The Blackhearts, Robin Schulz)
+
+becomes
+
+Melendi, Ryan Lewis, The Righteous Brothers, Joan Jett, The Blackhearts, Robin Schulz
+```
+
+Example 2
+
+```
+Childish Gambino - 12.38 (feat. 21 Savage, Ink & Kadhja Bonet)
+
+becomes
+
+Childish Gambino, 21 Savage, Ink, Kadhja Bonet - 12.38
+```
+
+:::note
+
+* MS uses "smart" heuristics to prevent artists with actual punctuation (`Tyler, The Creator`) from accidentally being separated
+* The extraction examples above are done **only for matching** other scrobble data (which is also parsed like the above), the resulting scrobble data is never transformed unless the user explicitly configures it via a [native transform](/configuration/transforms/native)
+
+:::
+
+</details>
+
+The **timestamps** for Scrobbles are compared at different levels of granularity based on where they originate from.
+
+<details>
+
+<summary>Temporally Comparing Scrobbles</summary>
+
+Timestamp closeness for two scrobbles can be classified in one of these states:
+
+**Exact**
+
+Timestamps differ by 1 seconds or less.
+
+**Close**
+
+Timestamps differ by less than the known granularity of the Source they are from. For most Sources (and all Clients) this is 10 seconds or less. For some sources (subsonic) the granularity is 60 seconds because they only report "now playing" changes every 60 seconds.
+
+**During**
+
+If the Play was monitoring in real-time by Multi-scrobbler then it knows the time range during which the Play was listened to. If an existing scrobble with similar artist/track/album has a timestamp that occurred *during* the known listening time then it is classified as during.
+
+**Fuzzy**
+
+If the timestamp occurs within a few seconds +/- of (existing scrobble + track duration) then, potentially, the Source timestamped the existing scrobble at the *end* of when the user listened to it, rather than when the user *started* listening to it. This is common for Spotify plays.
+
+___
+
+Each of the above classification results in a different score that is *roughly* descending from the order given above. Exact score is based on the Souce of the scrobble and if it was monitored in real-time by Multi-Scrobbler.
+
+</details>
+
+Finally, all of the above comparison/normalization techniques are combined when comparing a "new" Play/Scrobble against existing data. Each comparison is given a weighted score. If the score is above the match threshold then it is marked as a duplicated.
+
+<details>
+
+<summary>Match Scoring Example</summary>
+
+```
+Frédéric Chopin - Ballade No. 4 in F Minor, Op. 52 @ 2026-05-04T13:01:51-04:00 <-- New scrobble
+Frédéric Chopin / Krystian Zimerman - Ballade No. 4 in F Minor, Op. 52 @ 2026-05-04T13:01:48-04:00 <-- Existing scrobble from client
+```
+
+After comparing against all existing scrobbles from the client, in a timerange around the new scrobble, MS finds a match and logs the match along with the score breakdown of the consistuent parts:
+
+```
+Source: 
+Frédéric Chopin - Ballade No. 4 in F Minor, Op. 52 @ 2026-05-04T13:01:51-04:00 (S) 
+
+Closest Scrobble: 
+Frédéric Chopin / Krystian Zimerman - Ballade No. 4 in F Minor, Op. 52 @ 2026-05-04T13:01:48-04:00 (S)
+
+Artist: (0.30 + Whole Match Bonus 0.52) * (0.3 + Whole Match Bonus 0.05) = 0.29
+Title: 1.00 * 0.4 = 0.40
+Time: (Close) 1 * 0.5 = 0.50
+Time Detail => Existing: 13:01:48-04:00 - Candidate: 13:01:51-04:00 | Temporal Sameness: Close | Play Diff: 3s (Needed <10s) | Range Comparison N/A
+Score 1.19 => Matched!
+```
+
+</details>
+
+All of the above techniques and scoring gives Multi-scrobbler a *very good chance* of detecting duplicate scrobbles, regardless of where they were originally from. Of Multi-Scrobbler's [400+ unit tests](https://github.com/FoxxMD/multi-scrobbler/tree/master/src/backend/tests), 70+ are related to testing scoring, artist extraction, and [fuzzing](https://en.wikipedia.org/wiki/Fuzzing) string normalization/simiarlity.
+
+The dupe detection is so good that it is virtually gauranteed for [most configurations](#valid-configs) and is used for *backlogging* missed scrobbles for Sources that support fetching history.
+
+**However**, it's not possible to gaurantee this for *all* possible Multi-scrobbler configurations. See the below sections to learn more.
+
+## Configurations Where Duplicates DO NOT Occur {#valid-configs}
+
+* Any Source/Client configuration where there is only one Source and one Client and they are not the same service/account
+* Any Source/Client configuration where scrobbles only flow in **one direction**
+  * IE you *do not* have a Last.fm **Client** Account A that is *also* a Last.fm **Source** Account A
+
+:::tip
+
+**The majority of simple Multi-scrobbler configurations fall into these categories. If your workflow is straightforward you do not need to worry about duplicates at all.**
+
+:::
+
+Multi-scrobbler can handle recieving the same data from a Source multiple times. This is fine because the data is *always the same* and *always unique* to each Source. Since MS scrobbled the data to your clients you can be pretty confident that the *same* cleanup/matching process for that data will result in an indentical/similar match to the existing scrobble.
+
+IE Same inputs in -> same inputs out.
+
+**Even this scenario with multiple, mixed Sources is OK:**
+
+<img className='image-center' src={require('/img/diagrams/unidirectional-flow.png').default}/>
+
+Because the scrobbles coming from each **Source** are **independent** of each other. And they end up in Clients that are not *also* used as Sources.
+
+:::tip
+
+This is a common scenario when scrobbles are *backlogged* from a Source IE on startup MS fetches the last 50 Plays from Spotify/Lastfm/Listenbrainz.
+
+:::
+
+## Configurations Where Duplicates CAN Occur {#invalid-configs}
+
+### Upstream Scrobbles Sent to Multiple Sources
+
+In this scenario your device using Spotify is configured in MS as a Spotify **Source** but it **also** is scrobbling to Last.fm (via Pano Scrobbler, as an example).
+
+<img className='image-center' src={require('/img/diagrams/dupe sources.png').default}/>
+
+
+❌ **Time Race Condition**: Potentially, the scrobbles arrive in Multi-scrobbler at exactly the same time. There are no existing scrobbles in Koito to check against, yet. So Multi-scrobbler scrobbles both to Koito, resulting in duplicate scrobbles.
+
+❌ **Different Scrobble Data**: Pano Scrobbler, or Last.fm, [may modify the scrobble data.](#lastfm) When MS recieves the scrobble from Last.fm it may be *just different enough* that it does not get detected as a duplicate.
+
+### Sources and Clients are Dependent {#dependent-source-client}
+
+In this scenario, you have a **Client** that is also a **Source** and that Source is feeding scrobbles to a different Client that receives scrobbles from everywhere (or has some overlap with the original Client).
+
+<img className='image-center' src={require('/img/diagrams/duped client source.png').default}/>
+
+❌ **Different Scrobble Data**: [Last.fm may modify the scrobble data.](#lastfm) When MS recieves the scrobble from Last.fm it may be *just different enough* that it does not get detected as a duplicate.
+
+❌ **Consistency Issues**: If the Koito Client has a backed up queue or is not currently scrobbling (imagine it was Last.fm or Listenbrainz, and they had upstream availability issues), then there is no existing scrobble yet and nothing to match against.
+
+## Configuration Solutions to Avoid Duplicates
+
+### Independent Sources
+
+Use a configuration mentioned in [Configurations Where Duplicates DO NOT Occur](#valid-configs): make sure all of your Sources are **independent**. The activity/scrobbles from each Source do not have any upstream duplicates of activity.
+
+<img className='image-center' src={require('/img/diagrams/independent source.png').default}/>
+
+### Alternative Sources
+
+Imagine you have a scenario where a device/player can **only** scrobble to Last.fm. But you want to use MS for all other devices/sources and still have all your scrobbles end up in your "main" Last.fm account for social reasons/stats.
+
+Instead of using the same Last.fm account for all activity and potentially having [dependent client/sources](#dependent-source-client), create an *additional* last.fm account that is used *only for the device that needs it*. This ensures the scrobbles from that device are isolated from the main account and do not prevent duplicates, so you can continue to use the main account as an MS Client:
+
+<img className='image-center' src={require('/img/diagrams/alt source.png').default}/>
+
+### Mirror-Only Clients or Limiting Scrobble Destination {#isolated-sources}
+
+In Multi-scrobbler, by default, all Sources scrobble to all Clients. Using [Limit Scrobble Destinations](/configuration/sources/#limiting-scrobble-destination) configuration can ensure that your dependent Source/Clients only scrobble to destinations where the scrobbles won't be duplicated. And/or limit other Sources to *not* scrobble to dependent Sources/Clients.
+
+Here is an example where all Sources only scrobble to a *dependent* Last.fm Client, and then the *dependent* Last.fm Source only scrobbles to a "mirror-only" (backup) Koito Client:
+
+<img className='image-center' src={require('/img/diagrams/mirror source.png').default}/>
+
+### Normalize All Scrobbles
+
+If using one of the above solutions is not possible you can also try to *aggressively normalize all scrobble data* using [the Musicbrainz transform stage](/configuration/transforms/musicbrainz).
+
+In this scenario you still have [dependent Source/Clients](#dependent-source-client) that are [not isolated](#isolated-sources) but you can *potentially* improve duplicate detection by first using a transform stage to match scrobbles against the Musibrainz database and normalize their track/artist/album data.
+
+:::warning
+
+**There is no gaurantee this will work** but it is better than nothing. You should attempt to re-configure MS to use any of the other solutions before using this one.
+
+:::
+
+<img className='image-center' src={require('/img/diagrams/normalized dupes.png').default}/>
+
+## The Last.fm Problem {#lastfm}
+
+Last.fm will happily accept almost any scrobble data you throw at it.
+
+It can then decide, opaquely, to match or modify that scrobble to some more "official" data it has server-side. This could be modifying the artists, title, or album sent in the scrobble. It can also mean modifying the [`mbid` (unique identifier)](https://musicbrainz.org/doc/MusicBrainz_Identifier) or adding what it _thinks_ is the correct one.
+
+There is nothing in the scrobble history API response from Last.fm that identifies it has done any of this. And [it's not super great at being right about these modifications](https://github.com/FoxxMD/multi-scrobbler/issues/333#issuecomment-3145161339).
+
+What this means for you, the user, is that this is very plausible scenario:
+
+* You scrobble `Artist Foo, Artist Bar - My Cool Track` to Last.fm via Pano Scrobbler (outside of Multi-scrobbler)
+  * Last.fm modifies the data to  `The Artist Foo - My Cool Track ft. Artist Bar (Album Version)` 
+* You _also_ scrobble  `Artist Foo, Artist Bar - My Cool Track` to Multi-scrobbler via Pano LFM endpoint **Source**
+  * MS forwards this to Koito Client as-is
+* Soon after, MS polls your Last.fm **Source** for new scrobbles and finds `The Artist Foo - My Cool Track ft. Artist Bar (Album Version)` 
+  * It queries Koito to see if this was scrobbled
+  * It sees that a scrobble did happen at almost the same time BUT the track titles and artist strings are _just different enough_ that it decides it's not a duplicate
+  * MS forwards the scrobble to Koito and you now have a duplicate
+
+This behavior is unique to Last.fm. It's truly the **worst** out of all the scrobbler services in terms of preserving your data as-is, or providing a unqiue identifier for your data.
@@ -1,317 +1,93 @@
 ---
-sidebar_position: 3
+sidebar_position: 5
 title: Kitchen Sink
-description: Kitchen Sink Example
+description: Kitchen Sink Examples
 ---

-# Example Complex Scenario
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import MultiUsecase from "@site/src/components/snippets/_scenario-config-multi.mdx"
+import MultiPersonsServices from "@site/docs/configuration/_kitchensink_configs/_multi-persons-services.mdx"
+import MultiSourcesClients from "@site/docs/configuration/_kitchensink_configs/_multi-sources-clients.mdx"
+import Musicbrainz from "@site/docs/configuration/_kitchensink_configs/_musicbrainz.mdx"
+import SingleUsecase from "@site/src/components/snippets/_scenario-config-single.mdx"

-Scenario: 
+## What's This?

-* You want to scrobble plays for yourself (Foxx), Fred, and Mary
-* Each person has their own [Maloja](/configuration/clients/maloja) server
-* Each person has their own Spotify account
-* You have your own Airsonic ([subsonic](/configuration/sources/subsonic)) server you to scrobble from
-* You have your own [Youtube Music](/configuration/sources/youtube-music) account you want to scrobble from
-* Mary has her own [Last.fm](/configuration/clients/lastfm) account she also wants to scrobble to
-* Fred has his own [Spotify](/configuration/sources/spotify) application and provides you with just his access and refresh token because he doesn't trust you (wtf Fred)
-* Fred has a Plex server and wants to scrobble everything he plays
-* Mary uses Fred's Plex server but only wants to scrobble her plays from the `podcast` library
-* The three of you have a shared library on [Plex](/configuration/sources/plex) called `party` that you only play when you are hanging out. You want plays from that library to be scrobbled to everyone's servers.
-* Fred also has his own [Jellyfin server](/configuration/sources/jellyfin) and wants to scrobble everything he plays
-* You have an android music app that can scrobble to a [custom listenbrainz server](/configuration/sources/listenbrainz-endpoint)
+On this page you find contrived, complex usecases for multi-scrobbler that provide examples of equivalent [configuration types](/configuration#configuration-types) to fulfill that usecase.

-### All-in-one Config
+These example are useful for:

-```json5 title="CONFIG_DIR/config.json"
-{
-  "sourceDefaults": {
-    "maxPollRetries": 0,          // optional, default # of automatic polling restarts on error. can be overridden by property in individual config
-    "maxRequestRetries": 1,       // optional, default # of http request retries a source can make before error is thrown. can be overridden by property in individual config
-    "retryMultiplier": 1.5,       // optional, default retry delay multiplier (retry attempt * multiplier = # of seconds to wait before retrying). can be overridden by property in individual config
-  },
-  "clientDefaults": {
-    "maxRequestRetries": 1,       // optional, default # of http request retries a client can make before error is thrown. can be overridden by property in individual config
-    "retryMultiplier": 1.5,       // optional, default retry delay multiplier (retry attempt * multiplier = # of seconds to wait before retrying). can be overridden by property in individual config
-  },
-  "sources": [
-    {
-      "type": "spotify",
-      "name": "foxxSpot",
-      "clients": ["foxxMaloja"],
-      "data": {
-        "clientId": "foxxSpotifyAppId", 
-        "clientSecret": "foxxSpotifyAppSecret",
-      },
-      "options": {
-        "maxRequestRetries": 2,  // override default max retries because spotify can...spotty
-      }
-    },
-    {
-      "type": "spotify",
-      "name": "marySpot",
-      "clients": ["maryMaloja"],
-      "data": {
-        "clientId": "foxxSpotifyAppId", // only need one application, it can be used by all users of this multi-scrobbler instance 
-        "clientSecret": "foxxSpotifyAppSecret",
-      }
-    },
-    {
-      "type": "spotify",
-      "name": "fredSpot",
-      "clients": ["fredMaloja"],
-      "data": {
-        "accessToken": "fredsToken",
-        "refreshToken": "fredsRefreshToken",
-        "interval": 120, // he also wants a slower check interval because his application already has heavy api usage
-      }
-    },
-    {
-      "type": "plex",
-      "name": "fredPlex",
-      "clients": ["fredMaloja"],
-      "data": {
-        "token": "JtRnwQWD__XMJF8sT3jc",
-        "url": "192.168.0.233:32400",
-        "usersallow": ["fredUser"]
-      }
-    },
-    {
-      "type": "plex",
-      "name": "maryPlex",
-      "clients": ["maryMaloja"],
-      "data": {
-        "token": "JtRnwQWD__XMJF8sT3jc",
-        "url": "192.168.0.233:32400",
-        "usersallow": ["maryUser"], // still need to specify mary as user so not all users who play from 'podcasts' get scrobbled
-        "librariesAllow": ["podcasts"]
-      }
-    },
-    {
-      "type": "plex",
-      "name": "partyPlex",
-      // omitting clients (or making it empty) will make this Source scrobble to all Clients
-      "data": {
-        "token": "JtRnwQWD__XMJF8sT3jc",
-        "url": "192.168.0.233:32400",
-        "librariesAllow": ["party"]
-      }
-    },
-    {
-      "type": "jellyfin",
-      "name": "FredJelly",
-      // omitting clients (or making it empty) will make this Source scrobble to all Clients
-      "data": {
-        "url": "http://localhost:8096",
-        "user": "FoxxMD",
-        "apiKey": "c9fae8756fbf481ebd9c5bb56bd6540c",
-        "usersAllow": ["fredUser"]
-      }
-    },
-    {
-      "type": "subsonic",
-      "name": "foxxAirsonic",
-      "clients": ["foxxMaloja"],
-      "data": {
-        "user": "foxx",
-        "password": "foxxPassword",
-        "url": "https://airsonic.foxx.example"
-      }
-    },
-    {
-      "type": "ytmusic",
-      "name": "foxxYoutube",
-      "clients": ["foxxMaloja"],
-      "data": {
-        "cookie": "__Secure-3PAPISID=3AxsXpy0MKGu75Qb/AkISXGqOnSDn1jEKn; DEVICE_INFO=ChxOekU0Tmpjek5EWTBPRGd3TlRBMk16QXpNdz09EJbS8Z0GGJbS8Z0G; ...",
-      }
-    },
-    {
-      "type": "endpointlz",
-      "name": "listenbrainzfoxx",
-      "clients": ["foxxMaloja"],
-      "data": {
-        "token": "myToken"
-      }
-    }
-  ],
-  "clients": [
-    {
-      "type": "maloja",
-      "name": "foxxMaloja",
-      "data": {
-        "url": "https://maloja.foxx.example",
-        "apiKey": "foxxApiKey"
-      }
-    },
-    {
-      "type": "maloja",
-      "name": "fredMaloja",
-      "data": {
-        "url": "https://maloja.fred.example",
-        "apiKey": "fredApiKey"
-      }
-    },
-    {
-      "type": "maloja",
-      "name": "maryMaloja",
-      "data": {
-        "url": "https://maloja.mary.example",
-        "apiKey": "maryApiKey"
-      }
-    },
-    {
-      "type": "lastfm",
-      "name": "maryLFM",
-      "data": {
-        "apiKey": "maryApiKey",
-        "secret": "marySecret",
-        "redirectUri": "http://localhost:9078/lastfm/callback"
-      }
-    }
-  ]
-}
+* getting an idea of what you can do with Multi-scrobbler
+* using these examples as a starting point for your own configuration
+* providing an example of the same configuration across different [configuration types](/configuration#configuration-types)

-```
+:::tip

-### Separate JSON files
+More common, straightforward scenarios can be found in the [**quickstart**](/quickstart) guide.

-```json5 title="CONFIG_DIR/spotify.json"
-[
-  {
-    // may omit 'type' property since app knows this is file is for spotify configs
-    "name": "foxxSpot",
-    "clients": ["foxxMaloja"],
-    "data": {
-      "clientId": "foxxSpotifyAppId",
-      "clientSecret": "foxxSpotifyAppSecret"
-    }
-  },
-  {
-    "name": "marySpot",
-    "clients": ["maryMaloja"],
-    "data": {
-      "clientId": "foxxSpotifyAppId",
-      "clientSecret": "foxxSpotifyAppSecret"
-    }
-  },
-  {
-    "name": "fredSpot",
-    "clients": ["fredMaloja"],
-    "data": {
-      "accessToken": "fredsToken",
-      "refreshToken": "fredsRefreshToken",
-      "interval": 120
-    }
-  },
-]
-```
+:::

-```json5 title="CONFIG_DIR/plex.json"
-[
-  {
-    "name": "fredPlex",
-    "clients": ["fredMaloja"],
-    "data": {
-      "token": "JtRnwQWD__XMJF8sT3jc",
-      "url": "192.168.0.233:32400",
-      "usersallow": ["fredUser"]
-    }
-  },
-  {
-    "name": "maryPlex",
-    "clients": ["maryMaloja"],
-    "data": {
-      "token": "JtRnwQWD__XMJF8sT3jc",
-      "url": "192.168.0.233:32400",
-      "usersallow": ["maryUser"],
-      "librariesAllow": ["podcasts"]
-    }
-  },
-  {
-    "name": "partyPlex",
-    "data": {
-      "token": "JtRnwQWD__XMJF8sT3jc",
-      "url": "192.168.0.233:32400",
-      "librariesAllow": ["party"]
-    }
-  }
-]
-```
+## Examples

-```json5 title="CONFIG_DIR/jellyfin.json"
-[
-  {
-    "name": "FredJelly",
-    "data": {
-      "url": "http://localhost:8096",
-      "user": "FoxxMD",
-      "apiKey": "c9fae8756fbf481ebd9c5bb56bd6540c",
-      "usersAllow": ["fredUser"]
-    }
-  }
-]
-```
+### Multiple Sources to Multiple Clients {#multi-sources-clients}

-```json5 title="CONFIG_DIR/ytmusic.json"
-[
-  {
-    "name": "foxxYoutube",
-    "clients": ["foxxMaloja"],
-    "data": {
-      "cookie": "__Secure-3PAPISID=3AxsXpy0MKGu75Qb/AkISXGqOnSDn1jEKn; DEVICE_INFO=ChxOekU0Tmpjek5EWTBPRGd3TlRBMk16QXpNdz09EJbS8Z0GGJbS8Z0G; ...",
-    }
-  }
-]
-```
-```json5 title="CONFIG_DIR/endpointlz.json"
-[
-  {
-    "name": "listenbrainzfoxx",
-    "clients": ["foxxMaloja"],
-    "data": {
-      "token": "myToken",
-    }
-  }
-]
-```
+You are the only user of Multi-scrobbler. You have many Sources you listen to and want to scrobble them to multiple services.

-```json5 title="CONFIG_DIR/maloja.json"
-[
-  {
-    "name": "foxxMaloja",
-    "data": {
-      "url": "https://maloja.foxx.example",
-      "apiKey": "foxxApiKey"
-    }
-  },
-  {
-    "name": "fredMaloja",
-    "data": {
-      "url": "https://maloja.fred.example",
-      "apiKey": "fredApiKey"
-    }
-  },
-  {
-    "name": "maryMaloja",
-    "data": {
-      "url": "https://maloja.mary.example",
-      "apiKey": "maryApiKey"
-    }
-  }
-]
-```
+* You want to **scrobble from...**
+  * A [Spotify](/configuration/sources/spotify) account
+  * A Navidrome instance that you want to use with the built-in [listenbrainz](/configuration/sources/listenbrainz-endpoint) scrobble function
+  * A shared [Plex](/configuration/sources/plex) instance that you want to scrobble only from a specific library named `oldies`
+* You want to **scrobble to...**
+  * Your decades-old [Last.fm](/configuration/clients/lastfm) account
+  * A [Koito](/configuration/clients/koito) server for backup

-```json5 title="CONFIG_DIR/lastfm.json"
-[
-  {
-    "name": "maryLFM",
-    "data": {
-      "apiKey": "maryApiKey",
-      "secret": "marySecret",
-      "redirectUri": "http://localhost:9078/lastfm/callback"
-    }
-  }
-]
-```
+<details>

+<summary>Configuration</summary>
+
+<MultiSourcesClients/>
+
+</details>
+
+### Scrobble for Multiple People to Multiple Clients {#multi-persons-services}
+
+<MultiUsecase/>
+
+You want to scrobble plays for yourself (Foxx), Fred, and Mary:
+
+* The three of you want to **scrobble from...**
+  * Fred and Mary each have their own [Jellyfin servers](/configuration/sources/jellyfin)
+  * You have a [Plex](/configuration/sources/plex) server
+* The three of you want to **scrobble to...**
+  * Fred and Mary each have their own [Last.fm](/configuration/clients/lastfm) accounts
+  * You have a [Koito](/configuration/clients/koito) server 
+
+<details>
+
+<summary>Configuration</summary>
+
+<MultiPersonsServices/>
+
+</details>
+
+### Use Musicbrainz to Fix Scrobbles from Navidrome
+
+You have multiple Sources of music but your personal, on-filesystem music collection is not well organized.
+
+You want to use the [Musicbrainz Transformer](/configuration/transforms/musicbrainz) to fix any scrobbles that use Navidrome, where your personal collection is located, so that the scrobble artists/album/title are all standardized.
+
+* You want to **scrobble from...**
+  * A [Spotify](/configuration/sources/spotify) account
+  * A Navidrome instance that you want to use with the built-in [listenbrainz](/configuration/sources/listenbrainz-endpoint) scrobble function
+    * Plays from this Source should be fixed by Musicbrainz before going to your scrobble Clients
+* You want to **scrobble to...**
+  * A [Last.fm](/configuration/clients/lastfm) account
+
+<details>
+
+<summary>Configuration</summary>
+
+<Musicbrainz/>
+
+</details>
@@ -52,8 +52,10 @@ If neither is configured automatic scrobble defaults to **off** and you should e
 <Config config="AzuracastSourceConfig" fileContent={AzuracastConfig} name="azuracast">
        | Environmental Variable | Required? | Default | Description                                                                                    |
        | :--------------------- | :-------- | :------ | ---------------------------------------------------------------------------------------------- |
-        | `AZ_URL`               | Yes       |         | Azuracast URL *without station name*                                                           |
-        | `AZ_STATION`           | Yes       |         | The station name shown on the public page                                                      |
+        | `AZURA_ID`             | Yes       |         | A unique ID                                                                                    |
+        | `AZURA_URL`            | Yes       |         | Azuracast URL *without station name*                                                           |
+        | `AZURA_STATION`        | Yes       |         | The station name shown on the public page                                                      |
        | `AZURA_LIVE`           | No        | Yes     | Only scrobble when station status is ONLINE                                                    |
        | `AZURA_LISTENERS_NUM`  | No        | `true`  | Only scrobble if station has any listeners (`true`) or listeners are equal-to/greater-than `X` |
+        | `AZURA_NAME`           | No        |         | A vanity name different than ID                                                                |
 </Config>
@@ -176,10 +176,12 @@ import DeezerDeprecatedConfig from '!!raw-loader!@site/../config/deezer-deprecat
        <Tabs groupId="configType" queryString>
            <TabItem value="env" label="ENV">
                | Environmental Variable | Required? | Default                                 | Description                       |
-                |------------------------|-----------|-----------------------------------------|-----------------------------------|
+                | ---------------------- | --------- | --------------------------------------- | --------------------------------- |
+                | `DEEZER_ID`            | Yes       |                                         | A unique ID                       |
                | `DEEZER_CLIENT_ID`     | Yes       |                                         | Your **Application ID**           |
                | `DEEZER_CLIENT_SECRET` | Yes       |                                         | Your **Secret Key**               |
                | `DEEZER_REDIRECT_URI`  | No        | `http://localhost:9078/deezer/callback` | URI must end in `deezer/callback` |
+                | `DEEZER_NAME`          | No        |                                         | A vanity name different than ID   |
            </TabItem>
            <TabItem value="file" label="File">

@@ -149,11 +149,13 @@ To diagnose bad/incomplete track information or strange MS player behavior pleas
        [Manually configuring cast device connections](#connecting-devices) is only available through file-based config.
        :::

-        | Environmental Variable | Required? | Default |                                     Description                                      |
-        |------------------------|-----------|---------|--------------------------------------------------------------------------------------|
-        | CC_ENABLE              | No        |         | Set to 'true' to enable Cast monitoring without needing to define other ENVs         |
-        | CC_WHITELIST_DEVICES   | No        |         | Only scrobble from these Cast devices. Comma-delimited list. EX mini-home, family-tv |
-        | CC_BLACKLIST_DEVICES   | No        |         | Do not scrobble from these Cast devices. Comma-delimited list                        |
-        | CC_WHITELIST_APPS      | No        |         | Only scrobble from these casted Apps. Comma-delimited list. EX spotify, pandora      |
-        | CC_BLACKLIST_APPS      | No        |         | Do not scrobble from these casted Apps. Comma-delimited list                         |
+        | Environmental Variable | Required? | Default | Description                                                                          |
+        | ---------------------- | --------- | ------- | ------------------------------------------------------------------------------------ |
+        | `CC_ID`                | Yes       |         | A unique ID                                                                          |
+        | `CC_ENABLE`            | No        |         | Set to 'true' to enable Cast monitoring without needing to define other ENVs         |
+        | `CC_WHITELIST_DEVICES` | No        |         | Only scrobble from these Cast devices. Comma-delimited list. EX mini-home, family-tv |
+        | `CC_BLACKLIST_DEVICES` | No        |         | Do not scrobble from these Cast devices. Comma-delimited list                        |
+        | `CC_WHITELIST_APPS`    | No        |         | Only scrobble from these casted Apps. Comma-delimited list. EX spotify, pandora      |
+        | `CC_BLACKLIST_APPS`    | No        |         | Do not scrobble from these casted Apps. Comma-delimited list                         |
+        | `CC_NAME`              | No        |         | A vanity name different than ID                                                      |
 </Config>
@@ -64,7 +64,9 @@ If no `sources` are configured for multi-scrobbler it will automatically try to
 ## Configuration

 <Config config="IcecastSourceConfig" fileContent={IcecastConfig} name="icecast">
-        | Environmental Variable | Required? | Default | Description |
-        | :--------------------- | :-------- | :------ | ----------- |
-        | `ICECAST_URL`          | Yes       |         | Icecast URL |
+        | Environmental Variable | Required? | Default | Description                     |
+        | :--------------------- | :-------- | :------ | ------------------------------- |
+        | `ICECAST_ID`           | Yes       |         | A unique ID                     |
+        | `ICECAST_URL`          | Yes       |         | Icecast URL                     |
+        | `ICECAST_NAME`         | No        |         | A vanity name different than ID |
 </Config>
@@ -54,6 +54,7 @@ Use `JELLYFIN_FRONTEND_URL_OVERRIDE=https://jellyfin.mydomain.com` in order for
 <Config config="JellyApiSourceConfig" fileContent={JellyfinConfig} name="jellyfin">
        | Environmental Variable           | Required? | Default | Description                                                                                                                                                                                   |
        | -------------------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+        | `JELLYFIN_ID`                    | **Yes**   |         | A unique ID                                                                                                                                                                                   |
        | `JELLYFIN_URL`                   | **Yes**   |         | The URL of the Jellyfin server IE `http://localhost:8096`                                                                                                                                     |
        | `JELLYFIN_USER`                  | **Yes**   |         | The user to authenticate with the API                                                                                                                                                         |
        | `JELLYFIN_APIKEY`                | No        |         | The API Key to use for authentication **(Must provide either apikey or password)**                                                                                                            |
@@ -66,4 +67,5 @@ Use `JELLYFIN_FRONTEND_URL_OVERRIDE=https://jellyfin.mydomain.com` in order for
        | `JELLYFIN_LIBRARIES_BLOCK`       | No        |         | Comma-separated list of libraries to disallow scrobbles from                                                                                                                                  |
        | `JELLYFIN_MEDIATYPES_ALLOW`      | No        |         | Comma-separated list of [media types](https://github.com/jellyfin/jellyfin-sdk-typescript/blob/master/src/generated-client/models/media-type.ts#L22) to allow scrobbling. Defaults to `audio` |
        | `JELLYFIN_FRONTEND_URL_OVERRIDE` | No        |         | The external URL to use for album art assets instead of `JELLYFIN_URL`                                                                                                                        |
+        | `JELLYFIN_NAME`                  | No        |         | A vanity name different than ID                                                                                                                                                               |
 </Config>
@@ -50,9 +50,11 @@ If any part of this URL is missing multi-scrobbler will use a default value. Thi
 ## Configuration

 <Config config="JRiverSourceConfig" fileContent={JriverConfig} name="jriver">
-        | Environmental Variable | Required |             Default             |                  Description                   |
-        |------------------------|----------|---------------------------------|------------------------------------------------|
+        | Environmental Variable | Required | Default                         | Description                                    |
+        | ---------------------- | -------- | ------------------------------- | ---------------------------------------------- |
+        | JRIVER_ID              | Yes      |                                 | A unique ID                                    |
        | JRIVER_URL             | Yes      | http://localhost:52199/MCWS/v1/ | The URL of the JRiver server                   |
        | JRIVER_USERNAME        | No       |                                 | If authentication is enabled, the username set |
        | JRIVER_PASSWORD        | No       |                                 | If authenticated is enabled, the password set  |
+        | JRIVER_NAME            | No       |                                 | A vanity name different than ID                |
 </Config>
@@ -51,9 +51,11 @@ If any part of this URL is missing multi-scrobbler will use a default value. Thi
 ## Configuration

 <Config config="KodiSourceConfig" fileContent={KodiConfig} name="kodi">
-        | Environmental Variable | Required | Default                       | Description                |
-        |------------------------|----------|-------------------------------|----------------------------|
-        | KODI_URL               | Yes      | http://localhost:8080/jsonrpc | The URL of the Kodi server |
-        | KODI_USERNAME          | No       |                               | The username set           |
-        | KODI_PASSWORD          | No       |                               | The password set           |
+        | Environmental Variable | Required | Default                       | Description                     |
+        | ---------------------- | -------- | ----------------------------- | ------------------------------- |
+        | KODI_ID                | Yes      |                               | A unique ID                     |
+        | KODI_URL               | Yes      | http://localhost:8080/jsonrpc | The URL of the Kodi server      |
+        | KODI_USERNAME          | No       |                               | The username set                |
+        | KODI_PASSWORD          | No       |                               | The password set                |
+        | KODI_NAME              | No       |                               | A vanity name different than ID |
 </Config>
@@ -27,7 +27,9 @@ See the [Koito (Client)](/configuration/clients/koito) configuration for general
 <Config config="KoitoSourceConfig" fileContent={KoitoConfig} name="koito">
        | Environmental Variable | Required? | Default | Description                       |
        | :--------------------- | --------- | ------- | --------------------------------- |
+        | `SOURCE_KOITO_ID`      | Yes       |         | A unique ID                       |
        | `SOURCE_KOITO_TOKEN`   | Yes       |         | API Key from your Koito Account   |
        | `SOURCE_KOITO_USER`    | Yes       |         | Your Koito username               |
        | `SOURCE_KOITO_URL`     | No        |         | The base URL for the Koito server |
+        | `SOURCE_KOITO_NAME`    | No        |         | A vanity name differen than ID    |
 </Config>
@@ -41,6 +41,8 @@ http://localhost:9078/api/lastfm/mySlug
 <Config config="LastFMEndpointSourceConfig" fileContent={LastfmEndpointConfig} name="endpointlfm">
        | Environmental Variable | Required? | Default | Description                                                                                                        |
        | :--------------------- | :-------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
-        | `LFMENDPOINT_ENABLE`   | No        |         | Use LFM Endpoint as a Source without any other configuration. Only required if slug/token are not provided as ENVs |
+        | `LFM_ID`               | Yes       |         | A unique ID                                                                                                        |
+        | `LFM_ENABLE`           | No        |         | Use LFM Endpoint as a Source without any other configuration. Only required if slug/token are not provided as ENVs |
        | `LFM_SLUG`             | No        |         | (Optional) The URL suffix to use for accepting LFM scrobbles                                                       |
+        | `LFM_NAME`             | No        |         | A vanity name different than ID                                                                                    |
 </Config>
@@ -26,8 +26,10 @@ To configure this Source use the same registration instructions and configuratio
 <Config config="LastfmSourceConfig" fileContent={LastfmConfig} name="lastfm">
        | Environmental Variable       | Required? | Default                                 | Description                                                                   |
        | ---------------------------- | --------- | --------------------------------------- | ----------------------------------------------------------------------------- |
+        | `SOURCE_LASTFM_ID`           | Yes       |                                         | A unique ID                                                                   |
        | `SOURCE_LASTFM_API_KEY`      | Yes       |                                         | Api Key from your API Account                                                 |
        | `SOURCE_LASTFM_SECRET`       | Yes       |                                         | Shared secret from your API Account                                           |
        | `SOURCE_LASTFM_REDIRECT_URI` | No        | `http://localhost:9078/lastfm/callback` | Url to use for authentication. Must include `lastfm/callback` somewhere in it |
        | `SOURCE_LASTFM_SESSION`      | No        |                                         | Session id. Will be generated by authentication flow if not provided.         |
+        | `SOURCE_LASTFM_NAME`         | No        |                                         | A vanity name different than ID                                               |
 </Config>
@@ -25,10 +25,12 @@ To configure this Source use the same registration instructions and configuratio
 <Config config="LibrefmSourceConfig" fileContent={JsonConfig} name="librefm">
        | Environmental Variable        | Required? | Default                                  | Description                                                                                      |
        | ----------------------------- | --------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
+        | `SOURCE_LIBREFM_ID`           | Yes       |                                          | A unique ID                                                                                      |
        | `SOURCE_LIBREFM_ENABLE`       | No        |                                          | Set to `true` to enable Libre.fm, if not using any of the below variables                        |
        | `SOURCE_LIBREFM_API_KEY`      | No        | `anything`                               | Optional API Key                                                                                 |
        | `SOURCE_LIBREFM_SECRET`       | No        | `anything`                               | Optional shared secret                                                                           |
        | `SOURCE_LIBREFM_REDIRECT_URI` | No        | `http://localhost:9078/librefm/callback` | Url to use for authentication. Must include `librefm/callback` somewhere in it                   |
        | `SOURCE_LIBREFM_SESSION`      | No        |                                          | Session id. Will be generated by authentication flow if not provided.                            |
        | `SOURCE_LIBREFM_URLBASE`      | No        |                                          | Use for custom Libre.fm instance only. The host + path prefix EX `https://my.libre.example/2.0/` |
+        | `SOURCE_LIBREFM_NAME`         | No        |                                          | A vanity name different than ID                                                                  |
 </Config>
@@ -109,9 +109,12 @@ To troubleshoot any errors, and assuming you are using Home Assistant, view the
 ## Configuration

 <Config config="ListenbrainzEndpointSourceConfig" fileContent={ListenbrainzEndpointConfig} name="endpointlz">
-        | Environmental Variable | Required? | Default | Description                                                                                                       |
-        | :--------------------- | :-------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
-        | `LZENDPOINT_ENABLE`    | No        |         | Use LZ Endpoint as a Source without any other configuration. Only required if slug/token are not provided as ENVs |
-        | `LZE_TOKEN`            | No        |         | LZ "Authentication Token" you provided to the scrobbling application                                              |
-        | `LZE_SLUG`             | No        |         | (Optional) The URL suffix to use for accepting LZ scrobbles                                                       |
+        | Environmental Variable | Required? | Default | Description                                                                                                                                                |
+        | :--------------------- | :-------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+        | `LZE_ID`               | Yes       |         | A unique ID                                                                                                                                                |
+        | `LZE_ENABLE`           | No        |         | Use LZ Endpoint as a Source without any other configuration. Only required if slug/token are not provided as ENVs                                          |
+        | `LZE_TOKEN`            | No        |         | LZ "Authentication Token" you provided to the scrobbling application                                                                                       |
+        | `LZE_SLUG`             | No        |         | (Optional) The URL suffix to use for accepting LZ scrobbles                                                                                                |
+        | `LZE_USERNAME`         | No        |         | (Optional) A fake username that will be returned for token validation and on now-playing responses. If none is provided the Source's name is used instead. |
+        | `LZE_NAME`             | No        |         | A vanity name different than ID                                                                                                                            |
 </Config>
@@ -28,7 +28,9 @@ On your [profile page](https://listenbrainz.org/profile/) find your **User Token
 <Config config="ListenBrainzSourceConfig" fileContent={ListenbrainzConfig} name="listenbrainz">
        | Environmental Variable | Required? | Default                       | Description                     |
        | ---------------------- | --------- | ----------------------------- | ------------------------------- |
+        | `SOURCE_LZ_ID`         | Yes       |                               | A unique ID                     |
        | `SOURCE_LZ_TOKEN`      | Yes       |                               | User token from your LZ profile |
        | `SOURCE_LZ_USER`       | Yes       |                               | Your LZ username                |
        | `SOURCE_LZ_URL`        | No        | https://api.listenbrainz.org/ | The base URL for the LZ server  |
+        | `SOURCE_LZ_NAME`       | No        |                               | A vanity name different than ID |d
 </Config>
@@ -22,8 +22,10 @@ See the [Maloja (Client)](/configuration/clients/maloja) configuration for gener
 ## Configuration

 <Config config="MalojaSourceConfig" fileContent={MalojaConfig} name="maloja">
-        | Environmental Variable  | Required? | Default | Description                   |
-        | ----------------------- | --------- | ------- | ----------------------------- |
-        | `SOURCE_MALOJA_URL`     | Yes       |         | Base URL of your installation |
-        | `SOURCE_MALOJA_API_KEY` | Yes       |         | Api Key                       |
+        | Environmental Variable  | Required? | Default | Description                     |
+        | ----------------------- | --------- | ------- | ------------------------------- |
+        | `SOURCE_MALOJA_ID`      | Yes       |         | A unique ID                     |
+        | `SOURCE_MALOJA_URL`     | Yes       |         | Base URL of your installation   |
+        | `SOURCE_MALOJA_API_KEY` | Yes       |         | Api Key                         |
+        | `SOURCE_MALOJA_NAME`    | Yes       |         | A vanity name different than ID |
 </Config>
@@ -18,11 +18,15 @@ bind_to_address	"any"   # or a specific ipv4/v6 address
 port            "6600"
 ```

+Multi-scrobbler requires only the [`read`](https://mpd.readthedocs.io/en/stable/user.html#permissions-and-passwords) permission in order to monitor your activity.
+
 ## Configuration

 <Config config="MPDSourceConfig" fileContent={MPDConfig} name="mpd">
-        | Environmental Variable | Required? | Default          | Description |
-        |------------------------|-----------|------------------|-------------|
-        | `MPD_URL`              | No        | `localhost:6600` |             |
-        | `MPD_PASSWORD`         | No        |                  |             |
+        | Environmental Variable | Required? | Default          | Description                     |
+        | ---------------------- | --------- | ---------------- | ------------------------------- |
+        | `MPD_ID`               | Yes       |                  | A unique ID                     |
+        | `MPD_URL`              | No        | `localhost:6600` |                                 |
+        | `MPD_PASSWORD`         | No        |                  |                                 |
+        | `MPD_NAME`             | No        |                  | A vanity name different than ID |
 </Config>
@@ -72,8 +72,10 @@ MPRIS communication requires multi-scrobbler to have access to the host's dbus-d

 <Config config="MPRISSourceConfig" fileContent={MPRISConfig} name="mpris">
        | Environmental Variable | Required? | Default | Description                                                                      |
-        |------------------------|-----------|---------|----------------------------------------------------------------------------------|
+        | ---------------------- | --------- | ------- | -------------------------------------------------------------------------------- |
+        | MPRIS_ID               | Yes       |         | A unique ID                                                                      |
        | MPRIS_ENABLE           | No        |         | Use MPRIS as a Source (useful when you don't need any other options)             |
        | MPRIS_BLACKLIST        | No        |         | Comma-delimited list of player names not to scrobble from                        |
        | MPRIS_WHITELIST        | No        |         | Comma-delimited list of players names to ONLY scrobble from. Overrides blacklist |
+        | MPRIS_NAME             | No        |         | A vanity name different than ID                                                  |
 </Config>
@@ -32,7 +32,9 @@ If no URL is provided to MS it will try to use `ws://localhost:7905`

 <Config config="MusikcubeSourceConfig" fileContent={MusikcubeConfig} name="musikcube">
        | Environmental Variable | Required? | Default               | Description                          |
-        |------------------------|-----------|-----------------------|--------------------------------------|
+        | ---------------------- | --------- | --------------------- | ------------------------------------ |
+        | `MC_ID`                | Yes       |                       | A unique ID                          |
        | `MC_URL`               | No        | `ws://localhost:7905` | Use port set for **metadata server** |
        | `MC_PASSWORD`          | Yes       |                       |                                      |
+        | `MC_NAME`              | No        |                       | A vanity name different than ID      |
 </Config>
@@ -196,6 +196,7 @@ To configure MS to use Musicbrainz with your Plex metadata use one of the method
 <Config config="PlexApiSourceConfig" fileContent={PlexConfig} name="plex">
        | Environmental Variable | Required? | Default | Description                                                            |
        | ---------------------- | --------- | ------- | ---------------------------------------------------------------------- |
+        | `PLEX_ID`              | **Yes**   |         | A unique ID                                                            |
        | `PLEX_URL`             | **Yes**   |         | The URL of the Plex server IE `http://localhost:32400`                 |
        | `PLEX_TOKEN`           | **Yes**   |         | The **Plex Token** to use with the API                                 |
        | `PLEX_USERS_ALLOW`     | No        |         | Comma-separated list of usernames (from Plex) to scrobble for          |
@@ -204,4 +205,5 @@ To configure MS to use Musicbrainz with your Plex metadata use one of the method
        | `PLEX_DEVICES_BLOCK`   | No        |         | Comma-separated list of devices to disallow scrobbles from             |
        | `PLEX_LIBRARIES_ALLOW` | No        |         | Comma-separated list of libraries to allow scrobbles from              |
        | `PLEX_LIBRARIES_BLOCK` | No        |         | Comma-separated list of libraries to disallow scrobbles from           |
+        | `PLEX_NAME`            | No        |         | A vanity name different than ID                                        |
 </Config>
@@ -35,6 +35,8 @@ See the [Rocksky (Client)](/configuration/clients/rocksky#setup) configuration f
 <Config config="RockskySourceConfig" fileContent={JsonConfig} name="rocksky">
        | Environmental Variable  | Required? | Default | Description                                                                         |
        | :---------------------- | --------- | ------- | ----------------------------------------------------------------------------------- |
+        | `SOURCE_ROCKSKY_ID`     | Yes       |         | A unique ID                                                                         |
        | `SOURCE_ROCKSKY_HANDLE` | Yes       |         | Your **full** ATProto handle. For Bluesky account this is like `myUser.bsky.social` |
        | `SOURCE_ROCKSKY_KEY`    | Yes       |         | API Key obtained from Rocksky developer dashboard                                   |
+        | `SOURCE_ROCKSKY_NAME`   | No        |         | A vanity name different than ID                                                     |
 </Config>
@@ -92,9 +92,11 @@ You **must** define the IP address of at least one Sonos/accessory in order for
 <Config config="SonosSourceConfig" fileContent={JsonConfig} name="sonos">
        | Environmental Variable | Required? | Default | Description                                                            |
        | ---------------------- | --------- | ------- | :--------------------------------------------------------------------- |
+        | `SONOS_ID`             | Yes       |         | A unique ID                                                            |
        | `SONOS_HOST`           | Yes       |         | The IP address of any active Sonos device/accessory EX `192.168.0.150` |
        | `SONOS_DEVICES_ALLOW`  | No        |         | Comma-separated list of Sonos device names to scrobble from            |
        | `SONOS_DEVICES_BLOCK`  | No        |         | Comma-separated list of Sonos device names to disallow scrobbles from  |
        | `SONOS_GROUPS_ALLOW`   | No        |         | Comma-separated list of device group names to scrobble from            |
        | `SONOS_GROUPS_BLOCK`   | No        |         | Comma-separated list of devices group names to disallow scrobbles from |
+        | `SONOS_NAME`           | No        |         | A vanity name different than ID                                        |
 </Config>
@@ -111,9 +111,11 @@ Use **one** of the following methods to specify a valid Redirect URI and complet
 ## Configuration

 <Config config="SpotifySourceConfig" fileContent={SpotifyConfig} name="spotify">
-    | Environmental Variable  | Required? | Default                          | Description                |
-    | ----------------------- | --------- | -------------------------------- | -------------------------- |
-    | `SPOTIFY_CLIENT_ID`     | Yes       |                                  |                            |
-    | `SPOTIFY_CLIENT_SECRET` | Yes       |                                  |                            |
-    | `SPOTIFY_REDIRECT_URI`  | No        | `http://localhost:9078/callback` | URI must end in `callback` |
+    | Environmental Variable  | Required? | Default                          | Description                     |
+    | ----------------------- | --------- | -------------------------------- | ------------------------------- |
+    | `SPOTIFY_ID`            | Yes       |                                  | A unique ID                     |
+    | `SPOTIFY_CLIENT_ID`     | Yes       |                                  |                                 |
+    | `SPOTIFY_CLIENT_SECRET` | Yes       |                                  |                                 |
+    | `SPOTIFY_REDIRECT_URI`  | No        | `http://localhost:9078/callback` | URI must end in `callback`      |
+    | `SPOTIFY_NAME`          | No        |                                  | A vantiy name different than ID |
 </Config>
@@ -32,8 +32,10 @@ Use the optional `usersAllow` property with **File** or **AIO** configuration to

 <Config config="SubSonicSourceConfig" fileContent={SubsonicConfig} name="subsonic">
        | Environmental Variable | Required? | Default | Description                          |
-        |------------------------|-----------|---------|--------------------------------------|
+        | ---------------------- | --------- | ------- | ------------------------------------ |
+        | `SUBSONIC_ID`          | Yes       |         | A unique ID                          |
        | `SUBSONIC_USER`        | Yes       |         |                                      |
        | `SUBSONIC_PASSWORD`    | Yes       |         |                                      |
        | `SUBSONIC_URL`         | Yes       |         | Base url of your subsonic-api server |
+        | `SUBSONIC_NAME`        | No        |         | A vanity name different than ID      |
 </Config>
@@ -106,6 +106,8 @@ Allow scrobbles from plyr.fm and unknown services:
 <Config config="TealClientConfig" fileContent={JsonConfig} name="tealfm">
        | Environmental Variable     | Required? | Default | Description                                                                                |
        | :------------------------- | --------- | ------- | ------------------------------------------------------------------------------------------ |
+        | `SOURCE_TEALFM_ID`         | Yes       |         | A unique ID                                                                                |
        | `SOURCE_TEALFM_IDENTIFIER` | Yes       |         | Your **full** ATProto handle or DID. For Bluesky account this is like `myUser.bsky.social` |
        | `SOURCE_TEALFM_APP_PW`     | Yes       |         | Bluesky/ATProto network App Password                                                       |
+        | `SORUCE_TEALFM_NAME`       | No        |         | A vanity name different than ID                                                            |
 </Config>
@@ -99,8 +99,10 @@ If you find that VLC is incorrectly reporting track information (in its interfac
 ## Configuration

 <Config config="VLCSourceConfig" fileContent={JsonConfig} name="vlc">
-        | Environmental Variable | Required?  | Default          | Description |
-        |------------------------|------------|------------------|-------------|
-        | `VLC_URL`              | No         | `localhost:8080` |             |
-        | `VLC_PASSWORD`         | Yes        |                  |             |
+        | Environmental Variable | Required? | Default          | Description                     |
+        | ---------------------- | --------- | ---------------- | ------------------------------- |
+        | `VLC_ID`               | Yes       |                  | A unique ID                     |
+        | `VLC_URL`              | No        | `localhost:8080` |                                 |
+        | `VLC_PASSWORD`         | Yes       |                  |                                 |
+        | `VLC_NAME`             | No        |                  | A vanity name different than ID |
 </Config>
@@ -88,8 +88,10 @@ This affects **only** MS's behavior and does not affect the general connector be

 <Config config="WebScrobblerSourceConfig" fileContent={JsonConfig} name="webscrobbler">
        | Environmental Variable | Required? | Default | Description                                                              |
-        |------------------------|-----------|---------|--------------------------------------------------------------------------|
+        | ---------------------- | --------- | ------- | ------------------------------------------------------------------------ |
+        | WS_ID                  | Yes       |         | A unique ID                                                              |
        | WS_ENABLE              | No        |         | Set to 'true' to enable WS without needing to define other ENVs          |
        | WS_WHITELIST           | No        |         | Only scrobble from these WebScrobbler Connectors. Comma-delimited list   |
        | WS_BLACKLIST           | No        |         | Do not scrobble from these WebScrobbler Connectors. Comma-delimited list |
+        | WS_NAME                | No        |         | A vanity name different than ID                                          |
 </Config>
@@ -31,7 +31,9 @@ EX
 ## Configuration

 <Config config="MusicCastSourceConfig" fileContent={JsonConfig} name="musiccast">
-        | Environmental Variable | Required? | Default | Description              |
-        | :--------------------- | :-------- | ------- | :----------------------- |
-        | `MCAST_URL`            | Yes       |         | The Musiccast device URL |  
+        | Environmental Variable | Required? | Default | Description                     |
+        | :--------------------- | :-------- | ------- | :------------------------------ |
+        | `MCAST_ID`             | Yes       |         | A unique ID                     |
+        | `MCAST_URL`            | Yes       |         | The Musiccast device URL        |
+        | `MCAST_NAME`           | No        |         | A vanity name different than ID |
 </Config>
@@ -74,6 +74,8 @@ If you have issues specifically with the MS Source please mention [**Druidblack*
 <Config config="YandexMusicBridgeSourceConfig" fileContent={JsonConfig} name="ymbridge">
        | Environmental Variable | Required? | Default | Description                                                               |
        | :--------------------- | :-------- | ------- | :------------------------------------------------------------------------ |
+        | `YMBRIDGE_ID`          | Yes       |         | A unique ID                                                               |
        | `YMBRIDGE_URL`         | Yes       |         | `http://URL:PORT` for the `yandex-music-bridge` container                 |
        | `YMBRIDGE_API_KEY`     | No        |         | The same key used for `YM_API_KEY` on the `yandex-music-bridge` container |
+        | `YMBRIDGE_NAME`        | No        |         | A vanity name different than ID                                           |
 </Config>
@@ -179,11 +179,13 @@ Only one of these methods needs to be used.
 ## Configuration

 <Config config="YTMusicSourceConfig" fileContent={JsonConfig} name="ytmusic">
-| Environmental Variable | Required? | Default |                  Description                  |
-|------------------------|-----------|---------|-----------------------------------------------|
+| Environmental Variable | Required? | Default | Description                                   |
+| ---------------------- | --------- | ------- | --------------------------------------------- |
+| YTM_ID                 | Yes       |         | A unique ID                                   |
 | YTM_COOKIE             | No        |         | Value for Cookie Authentication               |
 | YTM_CLIENT_ID          | No        |         | Client ID for OAuth Athentication             |
 | YTM_CLIENT_SECRET      | No        |         | Client Secret for OAuth Athentication         |
 | YTM_REDIRECT_URI       | No        |         | A custom redirect URI for OAuth Athentication |
 | YTM_LOG_DIFF           | No        | false   | Log YTM history changes                       |
+| YTM_NAME               | No        |         | A vanity name different than ID               |
 </Config>
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 3
 title: Enhancing Scrobbles
 toc_max_heading_level: 5
 ---
@@ -591,7 +591,7 @@ The output shows the diff between the previous stage (or original Play) and the

 MS uses [caching](/configuration/#caching) to reduce the number of API calls needed for stages like [Musicbrainz](/configuration/transforms/musicbrainz) and to speed up all transforms by caching steps and results. However, the default caching strategy uses a small cache size and very short [TTLs](https://en.wikipedia.org/wiki/Time_to_live) because it is *in-memory*.

-**If you are using any Transform stages you should configure [secondary caching with Valkey for Metadata](/configuration/?cacheType=valkey&cachedThings=metadata#secondary-caching-configuration)** to increase the cache size and lifetime of cached items. This will also reduce memory usage in MS.
+**If you are using any Transform stages you should configure [secondary caching](/configuration#secondary-caching)** to increase the cache size and lifetime of cached items. This will also reduce memory usage in MS.

 <details>

@@ -84,6 +84,14 @@ Use the **Last.fm** tab in the [Quickstart Sources](/quickstart/#setup-sources)

 You set up [configurations](/configuration) for one or more [**Sources**](/configuration/sources) and one or more [**Clients**](/configuration/clients). MS monitors all of your configured **Sources**. When new tracks are played by a Source MS grabs that information and then sends it (scrobbles it) to all **Clients** that Source is configured to forward to.

+<details>
+
+<summary>Diagram</summary>
+
+<img className='image-center' src={require('/img/diagrams/ms-visual.png').default}/>
+
+</details>
+
 ### Source

 A [**Source**](/configuration/sources) is a data source that contains information about music you are playing or have listened to, such as: a desktop player, web music player, or cloud music service. Examples are **Spotify, Jellyfin, Plex, Youtube Music, Navidrome**, etc...
@@ -132,7 +132,7 @@ services:

 </TabItem>
 <TabItem value="caching" label="Caching">
-**Optionally**, add a [Valkey](https://valkey.io/) service to your stack for [secondary caching](/configuration/?cacheType=valkey#secondary-caching-configuration) to take advantage of faster performance and reduced memory usage.
+**Optionally**, add a [Valkey](https://valkey.io/) service to your stack for [secondary caching](/configuration#secondary-caching) to take advantage of faster performance and reduced memory usage.

 ```yaml title="docker-compose.yml"
 services:
@@ -142,8 +142,7 @@ services:
    environment:
      # ...
      // highlight-start
-      CACHE_METADATA=valkey
-      CACHE_METADATA_CONN=redis://valkey:6379
+      CACHE_VALKEY=redis://valkey:6379
      // highlight-end
    # ...

@@ -54,6 +54,7 @@ services:
        - JELLYFIN_URL=192.168.0.110:8096 # URL to Jellyfin UI
        - JELLYFIN_APIKEY=c9fae8756fbf481ebd9c5bb56b # Api Key created in previous step
        - JELLYFIN_USER=MyUser # Your username in Jellyfin
+        - JELLYFIN_ID=myJellyin
        ```
    </TabItem>
    <TabItem value="spotify" label="Spotify">
@@ -68,6 +69,7 @@ services:
        - SPOTIFY_CLIENT_ID=yourClientId
        - SPOTIFY_CLIENT_SECRET=yourClientSecret
        - SPOTIFY_REDIRECT_URI=https://multi-scrobbler.mydomain.com/callback
+        - SPOTIFY_ID=mySpotify
        ```

        Later, after [starting multi-scrobbler](#start-multi-scrobbler), visit the dashboard at `http://192.168.0.100:9078` and click **(Re)authenticate** on the Spotify card to authorize multi-scrobbler to use your account. Monitoring will begin automatically after authorization is complete.
@@ -83,6 +85,7 @@ services:

        ```yaml title="~/msData/docker-compose.yml"
        - LZE_TOKEN=myCoolToken
+        - LZE_ID=navidromeLZ
        ```

        The token can be anything. [(Re)start multi-scrobbler](#start-multi-scrobbler) after making this change.
@@ -105,6 +108,7 @@ services:
        ```yaml title="~/msData/docker-compose.yml"
        - PLEX_URL=http://192.168.0.101:32400
        - PLEX_TOKEN=6c0ihz8j7__f5r18oa0zm8
+        - PLEX_ID=myPlex
        # optional, restrict scrobbling to a list of comma-delimited users
        #- PLEX_USERS_ALLOW=myPlexUsername
        ```
@@ -132,6 +136,7 @@ services:
        - SOURCE_LASTFM_API_KEY=MY_API_KEY_PLACEDHOLDER
        - SOURCE_LASTFM_SECRET=MY_SECRET_PLACEHOLDER
        - SOURCE_LASTFM_REDIRECT_URI=http://192.168.0.100:9078/lastfm/callback
+        - SOURCE_LASTFM_ID=myLFMSource
        ```

        Later, after [starting multi-scrobbler](#start-multi-scrobbler), visit the dashboard at `http://192.168.0.100:9078` and click **(Re)authenticate** on the **Last.fm (Source)** card to authorize multi-scrobbler to use your account. Monitoring will begin automatically after authorization is complete.
@@ -251,12 +256,13 @@ Modify the `lastfm.json` file you created in the [Setup Sources](#setup-sources)
        - KOITO_TOKEN=myToken
        - KOITO_USER=myUser
        - KOITO_URL=myURL
+        - KOITO_ID=myKoito
        ```

        :::tip
-
-        Ensure that Koito is configured to allow requests from multi-scrobbler! In Koito config set [`KOITO_ALLOWED_HOSTS`](https://koito.io/reference/configuration/#koito_allowed_hosts) to the IP the multi-scrobbler dashboard is accessible from.
-
+        
+        For Koito versions `<=0.1.7`, you must have the environment variable `KOITO_ALLOWED_HOSTS` set correctly in your Koito environment/container. Ensure it is set to the IP address or domain name that you use to access Koito with e.g. `koito.mydomain.com`. 
+        
        :::

    </TabItem>
@@ -274,6 +280,7 @@ Modify the `lastfm.json` file you created in the [Setup Sources](#setup-sources)
        ```yaml title="~/msData/docker-compose.yml"
        - LASTFM_API_KEY=myApiKey
        - LASTFM_SECRET=myApiSecret
+        - LASTFM_ID=myLfmClient
        ```
    </TabItem>
    <TabItem value="maloja" label="Maloja">
@@ -306,6 +313,7 @@ Modify the `lastfm.json` file you created in the [Setup Sources](#setup-sources)
        ```yaml title="~/msData/docker-compose.yml"
        - MALOJA_URL=http://192.168.0.100:42010
        - MALOJA_API_KEY=myApiKey
+        - MALOJA_ID=myMaloja
        ```
    </TabItem>
 </Tabs>
@@ -336,7 +344,7 @@ Visit `http://192.168.0.100:9078` to see the dashboard where
 ## Next Steps

 * See more advanced docker options as well as other install methods in the [**Installation**](/installation#docker) docs
-  * Setup [secondary caching](/configuration/?cacheType=valkey#secondary-caching-configuration) with [valkey](/installation?dockerSetting=caching#recommended-settings) for increased performance and reduced memory usage
+  * Setup [secondary caching](/configuration#secondary-caching) with [valkey](/installation?dockerSetting=caching#recommended-settings) for increased performance and reduced memory usage
 * Review the [**Configuration**](/configuration) docs
  * Learn about how to configure multi-scrobbler using files for more complicated Source/Client scenarios
  * See all available [**Sources**](/configuration/sources) and [**Clients**](/configuration/clients) alongside configuration examples
@@ -10,11 +10,37 @@ import CodeBlock from '@theme/CodeBlock';

 ## Updating

-Currently, multi-scrobbler does not have any databases or dependencies that require additional interaction when updating.
+The majority of Multi-scrobbler updates can be completed without any manual intervention. This is **guaranteed** for [patch version updates](#versioning).

-Any **breaking changes** will be related to [configuration](/configuration) that has been deprecated/changed, or tooling that usually only affects [Local Installations.](/installation#local-installation)
+Regardless, it is recommended to consult the [**Github Release Notes**](https://github.com/FoxxMD/multi-scrobbler/releases) before any upgrades. The release notes contain all changelogs as well as most **breaking changes**/notices.

-These changes, and how to update configs accordingly, are detailed in [**Github Release Notes**](https://github.com/FoxxMD/multi-scrobbler/releases). It is recommended to check this page before upgrading [minor or major versions.](#versioning)
+The [**Upgrade Path** docs](/updating/upgrade-path) contain information for upgrading through **required versions** or in-depth migration guides. Check this section before upgrading any [minor versions](#versioning).
+
+### Database
+
+Multi-scrobbler depends on a SQLite database (`ms.db`) that is created on first run and stored in the [`CONFIG_DIR`](/installation/?dockerSetting=storage#recommended-settings).
+
+If any database migrations are required for an update then your database is **automatically backed up** before migration occurs. The backup file is created in the same directory.
+
+You can manually make a backup of this database by making a copy of `ms.db` and any similarly named files like `ms.db-journal`.
+
+:::tip
+
+If upgrading a [minor version](#versioning) you may want to make a backup for extra safety.
+
+:::
+
+### Configuration
+
+[Minor versions](#versioning) may have **breaking changes** related to [configuration](/configuration). Consult the [**Github Release Notes**](https://github.com/FoxxMD/multi-scrobbler/releases) and [Upgrade Paths](/updating/upgrade-path) before upgrading.
+
+
+## Update Instructions
+
+Assuming:
+
+* upgrade(s) are only [patch versions](#versioning) and the [Release Notes](https://github.com/FoxxMD/multi-scrobbler/releases) do not contain any other guidance or
+* you have checked the release notes, upgrade paths docs, and completed all migration steps for the specific version upgrade

 <Tabs groupId="installType" queryString>
    <TabItem value="docker-compose" label="Docker Compose">
@@ -0,0 +1,218 @@
+---
+sidebar_position: 1
+title: From < 0.14.0
+description: Upgrading to 0.14.0
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+import RequiredUpgrade from "@site/src/components/snippets/_upgrade-required.mdx"
+
+<RequiredUpgrade before='< 0.14.0' current='0.14.0' old='0.13.2' />
+
+## 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](/configuration/clients/koito/) 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
+
+<Tabs groupId="configType" queryString>
+
+<TabItem value="env" label="ENV">
+
+For each Source/Client in your environmental variables, add a key with the suffix `_ID` and the ID value. EX
+
+```yaml title="compose.yaml"
+services:
+  multi-scrobbler:
+  # ...
+  environment:
+    - KOTIO_TOKEN=...
+    # ...more koito config
+  // highlight-start
+    - KOITO_ID=myKoitoID
+  // highlight-end
+
+    - JELLYFIN_URL=...
+    # ...more jellyin config
+  // highlight-start
+    - JELLYFIN_ID=myJellyfinID
+  // highlight-end    
+```
+
+</TabItem>
+<TabItem value="file" label="File">
+
+Add an `id` to the top-level for each Source/Client configuration, next to `data`:
+
+```json title="koito.json"
+[
+  {
+    "name": "koito-source",
+    "configureAs": "source",
+    // highlight-start
+    "id": "myKoitoID",
+    // highlight-end   
+    "data": {
+      "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
+      "username": "admin",
+      "url": "http://192.168.0.100:4110" 
+    }
+  }
+]
+```
+
+</TabItem>
+<TabItem value="aio" label="AIO">
+
+Add an `id` to the top-level for each Source/Client configuration, next to `data`:
+
+```json title="koito.json"
+[
+  {
+    "name": "koito-source",
+    "configureAs": "source",
+    "type": "koito",
+    // highlight-start
+    "id": "myKoitoID",
+    // highlight-end    
+    "data": {
+      "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
+      "username": "admin",
+      "url": "http://192.168.0.100:4110" 
+    }
+  }
+]
+```
+
+</TabItem>
+</Tabs>
+
+:::note[Default ID]
+
+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 name as the ID in order to keep Plays/Scobbles associated with the same config.
+
+:::
+
+## Cached Scrobble Migration
+
+:::tip
+
+Before upgrading, if your MS dashboard shows 0 queued/failed for all [Scrobble Clients](/configuration/clients) then you can **ignore this step.**
+
+:::
+
+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`](/installation/?dockerSetting=storage#recommended-settings) named `ms-scrobble.cache`.
+
+When a [Client](/configuration/clients) 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](/configuration#caching) has been simplified with much of the required configuration being removed.
+
+:::tip
+
+This only applies to users who have `cache` in their [AIO Config](/configuration/?configType=aio#configuration-types) `config.json` or are using `CACHE_*` [ENV Config](/configuration/?configType=env#configuration-types)
+
+If you do not have any of the above [Cache](/configuration#caching) configuration defined then you can **ignore this step.** 
+
+:::
+
+#### Scrobble Caching Removed
+
+[Scrobble caching has removed and replaced by the new database.](#cached-scrobble-migration)
+
+* 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](/configuration/#secondary-caching) update your config:
+
+<Tabs groupId="configType" queryString>
+
+<TabItem value="env" label="ENV">
+
+* Remove `CACHE_METADATA`
+* Rename `CACHE_METADATA_CONN` to [`CACHE_VALKEY`](/configuration/#secondary-caching)
+
+</TabItem>
+<TabItem value="aio" label="AIO">
+
+Remove `cache.metadata` and add a new string key `valkey` to the `cache` object, containing your valkey connection string:
+
+```diff
+  "cache": {
+    "valkey": "redis://valkey:6379"
+-    "metadata": {
+-      "provider": "valkey",
+-      "connection": "redis://valkey:6379"
+-    }
+  }
+```
+
+</TabItem>
+</Tabs>
+
+
+#### 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.
+
+<Tabs groupId="configType" queryString>
+
+<TabItem value="env" label="ENV">
+
+* Remove `CACHE_AUTH_CONN`
+* Add [`CACHE_VALKEY`](/configuration/#secondary-caching) (if using valkey)
+
+</TabItem>
+<TabItem value="aio" label="AIO">
+
+Remove the `connection` property from the `auth` object. If using `file` the entire `auth` object can be removed.
+
+```diff
+  "cache": {
+   "valkey": "redis://valkey:6379",
+    "auth": {
+      "provider": "valkey",
+-     "connection": "redis://valkey:6379"
+    }
+  }
+```
+
+</TabItem>
+</Tabs>
+
+### Renamed ENV Keys
+
+In an effort to standard ENV prefixes some ENV keys have been renamed:
+
+* `LZENDPOINT_ENABLE` => `LZE_ENABLE`
+* `LFMENDPOINT_ENABLE` => `LFM_ENABLE`
@@ -0,0 +1,7 @@
+{
+  "label": "Upgrade Path",
+  "link": {
+    "type": "doc",
+    "id": "updating/upgrade-path/upgrade-path"
+  }
+}
@@ -0,0 +1,39 @@
+---
+sidebar_position: 1
+title: Upgrade Path
+description: Updating Multi-Scrobbler
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+The majority of changes are detailed in [**Github Release Notes**](https://github.com/FoxxMD/multi-scrobbler/releases), including *most* breaking changes. You should consult the release notes for each version you will be updating through/to.
+
+Upgrade paths for specific version, detailed here, are reserved for:
+
+<Tabs groupId="upgradeType" queryString>
+
+<TabItem value="required" label="Required Upgrades">
+
+:::warning[Required Upgrade]
+
+Versions you **must** upgrade to **before** upgrading to a newer version. Likely due to the codebase containing functionality to upgrade persistent data that cannot be migrating across multiple versions.
+
+:::
+
+</TabItem>
+
+<TabItem value="depth" label="In Depth Upgrades">
+
+:::note[Optional Upgrade]
+
+(Breaking) Changes to configuration/data that require more detail or formatting than is feasible in Github release notes. These upgrades may be skipped.
+
+:::
+
+</TabItem>
+
+</Tabs>
+
+The type of upgrade is shown at the top of each page with the same colored callout shown above.
@@ -5,17 +5,27 @@ import * as Renderers from './lib/socialCard/ImageRenderers.js';
 import path from 'node:path';
 //import sidebars from './sidebars';

-let baseSite = 'https://foxxmd.github.io';
-// https://docs.netlify.com/build/configure-builds/environment-variables/#deploy-urls-and-metadata
-const netlifyDeploy = process.env.DEPLOY_PRIME_URL;
-if(netlifyDeploy !== undefined && netlifyDeploy !== null && netlifyDeploy.trim() !== '') {
-  baseSite = netlifyDeploy;
-} else {
-  const baseSiteEnv = process.env.BASE_SITE;
-  if(baseSiteEnv !== undefined && baseSiteEnv !== null && baseSiteEnv.trim() !== '') {
-    baseSite = baseSiteEnv;
+let baseSite: string = 'https://foxxmd.github.io';
+
+const baseUrlEnvs = [
+  // To build with base URL via normal docker build with build-args/env
+  // or if specified, to override the subsequent set ENVs
+  process.env.BASE_SITE,
+  // To build with base URL set via netlify CI
+  // https://docs.netlify.com/build/configure-builds/environment-variables/#deploy-urls-and-metadata
+  process.env.DEPLOY_PRIME_URL,
+  // To build with base URL set via cloudflare pages CI
+  // https://developers.cloudflare.com/pages/configuration/build-configuration/#environment-variables  
+  process.env.CF_PAGES_URL
+];
+
+for(const baseUrlVal of baseUrlEnvs) {
+  if(baseUrlVal !== undefined && baseUrlVal !== null && baseUrlVal.trim() !== '') {
+    baseSite = baseUrlVal;
+    break;
  }
 }
+console.log(`Base URL => ${baseSite}`);

 const config: Config = {
  future: {
@@ -12266,9 +12266,10 @@
      }
    },
    "node_modules/hast-util-to-jsx-runtime": {
-      "version": "2.3.2",
-      "resolved": "https://registry.npmjs.org/hast-util-to-jsx-runtime/-/hast-util-to-jsx-runtime-2.3.2.tgz",
-      "integrity": "sha512-1ngXYb+V9UT5h+PxNRa1O1FYguZK/XL+gkeqvp7EdHlB9oHUG0eYRo/vY5inBdcqo3RkPMC58/H94HvkbfGdyg==",
+      "version": "2.3.6",
+      "resolved": "https://registry.npmjs.org/hast-util-to-jsx-runtime/-/hast-util-to-jsx-runtime-2.3.6.tgz",
+      "integrity": "sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==",
+      "license": "MIT",
      "dependencies": {
        "@types/estree": "^1.0.0",
        "@types/hast": "^3.0.0",
@@ -12280,9 +12281,9 @@
        "mdast-util-mdx-expression": "^2.0.0",
        "mdast-util-mdx-jsx": "^3.0.0",
        "mdast-util-mdxjs-esm": "^2.0.0",
-        "property-information": "^6.0.0",
+        "property-information": "^7.0.0",
        "space-separated-tokens": "^2.0.0",
-        "style-to-object": "^1.0.0",
+        "style-to-js": "^1.0.0",
        "unist-util-position": "^5.0.0",
        "vfile-message": "^4.0.0"
      },
@@ -12291,6 +12292,16 @@
        "url": "https://opencollective.com/unified"
      }
    },
+    "node_modules/hast-util-to-jsx-runtime/node_modules/property-information": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/property-information/-/property-information-7.1.0.tgz",
+      "integrity": "sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/wooorm"
+      }
+    },
    "node_modules/hast-util-to-parse5": {
      "version": "8.0.0",
      "resolved": "https://registry.npmjs.org/hast-util-to-parse5/-/hast-util-to-parse5-8.0.0.tgz",
@@ -12883,9 +12894,10 @@
      }
    },
    "node_modules/inline-style-parser": {
-      "version": "0.2.4",
-      "resolved": "https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.2.4.tgz",
-      "integrity": "sha512-0aO8FkhNZlj/ZIbNi7Lxxr12obT7cL1moPfE4tg1LkX7LlLfC6DeX4l2ZEud1ukP9jNQyNnfzQVqwbwmAATY4Q=="
+      "version": "0.2.7",
+      "resolved": "https://registry.npmjs.org/inline-style-parser/-/inline-style-parser-0.2.7.tgz",
+      "integrity": "sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==",
+      "license": "MIT"
    },
    "node_modules/invariant": {
      "version": "2.2.4",
@@ -20835,12 +20847,22 @@
      "integrity": "sha512-i/n8VsZydrugj3Iuzll8+x/00GH2vnYsk1eomD8QiRrSAeW6ItbCQDtfXCeJHd0iwiNagqjQkvpvREEPtW3IoQ==",
      "license": "MIT"
    },
-    "node_modules/style-to-object": {
-      "version": "1.0.8",
-      "resolved": "https://registry.npmjs.org/style-to-object/-/style-to-object-1.0.8.tgz",
-      "integrity": "sha512-xT47I/Eo0rwJmaXC4oilDGDWLohVhR6o/xAQcPQN8q6QBuZVL8qMYL85kLmST5cPjAorwvqIA4qXTRQoYHaL6g==",
+    "node_modules/style-to-js": {
+      "version": "1.1.21",
+      "resolved": "https://registry.npmjs.org/style-to-js/-/style-to-js-1.1.21.tgz",
+      "integrity": "sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ==",
+      "license": "MIT",
      "dependencies": {
-        "inline-style-parser": "0.2.4"
+        "style-to-object": "1.0.14"
+      }
+    },
+    "node_modules/style-to-object": {
+      "version": "1.0.14",
+      "resolved": "https://registry.npmjs.org/style-to-object/-/style-to-object-1.0.14.tgz",
+      "integrity": "sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==",
+      "license": "MIT",
+      "dependencies": {
+        "inline-style-parser": "0.2.7"
      }
    },
    "node_modules/stylehacks": {
@@ -66,6 +66,7 @@
  },
  "overrides": {
    "lodash": "4.18.1",
-    "satori": "0.25.0"
+    "satori": "0.25.0",
+    "hast-util-to-jsx-runtime": "2.3.6"
  }
 }
@@ -5,9 +5,10 @@ import IconDanger from '@theme/Admonition/Icon/Danger';
 import IconTip from '@theme/Admonition/Icon/Tip';
 import IconNote from '@theme/Admonition/Icon/Note';
 import { ReactElement } from 'react';
+import AdmonitionIconImportant from './ImportantIcon';

 export interface DetailsAdmoProps extends DetailProps {
-    type?: 'warning' | 'danger' | 'note' | 'tip'
+    type?: 'warning' | 'danger' | 'note' | 'tip' | 'important'
 }

 const DetailsAdmo = (props: DetailsAdmoProps) => {
@@ -32,6 +33,10 @@ const DetailsAdmo = (props: DetailsAdmoProps) => {
            cn = 'alert--success';
            icon = <IconTip/>
            break;
+        case 'important':
+            cn = 'alert--important';
+            icon = <AdmonitionIconImportant/>;
+            break;            
    }

    const iconWrapper = icon === undefined ? null : <span className="admoIcon">{icon}</span>;
@@ -27,7 +27,7 @@ const FileConfigExample = (props: FileConfigProps) => {
    try {
        configObj = json5.parse(data) as object[];
    } catch (e) {
-        console.error(e);
+        console.error(new Error(`Unable to parse content for ${aio === true ? 'aio ' :''}${name}`, {cause: e}));
        return <Admonition type="danger" title="Unexpected Error">
            <p>Example component crashed because of error!</p>
            <CodeBlock>{e.message}</CodeBlock>
@@ -37,7 +37,11 @@ const FileConfigExample = (props: FileConfigProps) => {
    const transformed = useMemo(() => {
        let content: object;
        if(typeof data === 'string') {
+            try {
            content = json5.parse(data);
+            } catch (e) {
+                console.error(new Error(`Unable to parse transformed content for ${aio === true ? 'aio ' :''}${name}`, {cause: e}));
+            }
        } else {
            content = data;
        }
@@ -0,0 +1,13 @@
+import type { Props } from '@theme/Admonition/Icon/Info';
+
+export default function AdmonitionIconImportant(props: Props) {
+    // based on https://icon-sets.iconify.design/zondicons/exclamation-outline/
+  return (
+    <svg viewBox="0 0 22 22" {...props}>
+      <path
+        fillRule="evenodd"
+        d="M2.93 17.07A10 10 0 1 1 17.07 2.93A10 10 0 0 1 2.93 17.07m12.73-1.41A8 8 0 1 0 4.34 4.34a8 8 0 0 0 11.32 11.32M9 5h2v6H9zm0 8h2v2H9z"
+      />
+    </svg>
+  );
+}
@@ -0,0 +1,7 @@
+<DetailsAdmo type="important" summary="ENV Config Not Possible">
+
+In this usescase there is **more than one of the same type of Source/Client.**
+
+This means only **File** or **AIO** [configuration types](/configuration#configuration-types) are possible because [ENV](/configuration/?configType=env#configuration-types) configuration only supports one Source/Client per type.
+
+</DetailsAdmo>
--- a/Show More
+++ b/Show More