chore: Bump version for release

#291

.devcontainer/devcontainer.json

@@ -0,0 +1,38 @@
+// For format details, see https://aka.ms/devcontainer.json. For config options, see the
+// README at: https://github.com/devcontainers/templates/tree/main/src/javascript-node
+{
+	"name": "Node.js",
+	// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
+	"image": "mcr.microsoft.com/devcontainers/javascript-node:1-20-bookworm",
+
+	// Features to add to the dev container. More info: https://containers.dev/features.
+	// "features": {},
+
+	// Use 'forwardPorts' to make a list of ports inside the container available locally.
+	"forwardPorts": [9078,3000],
+
+	// Use 'postCreateCommand' to run commands after the container is created.
+	"postCreateCommand": "npm install",
+
+	// Configure tool-specific properties.
+	"customizations": {
+		"vscode": {
+			"extensions": [
+				"hbenl.vscode-mocha-test-adapter",
+				"dbaeumer.vscode-eslint",
+				"unifiedjs.vscode-mdx"
+			]
+		}
+	},
+	"portsAttributes": {
+		"3000": {
+			"label": "Docusaurus"
+		},
+		"9078": {
+			"label": "App"
+		}
+	}
+
+	// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
+	// "remoteUser": "root"
+}

.dockerignore

@@ -23,3 +23,8 @@ docsite/.docusaurus
 docsite/.cache-loader
 build
 *.secrets
+.devcontainer
+.vscode
+**/act/*
+tmp-*
+.env

.github/ISSUE_TEMPLATE/01-bug-report.yml

@@ -0,0 +1,67 @@
+name: Bug Report
+description: Report a reproducible problem
+title: "bug: "
+labels: ["bug"]
+body:
+  - type: checkboxes
+    attributes:
+      label: Please check existing knowledge before opening an issue
+      options:
+      - label: I have [checked the FAQ](https://foxxmd.github.io/multi-scrobbler/docs/FAQ/) and [documentation](https://foxxmd.github.io/multi-scrobbler/docs/configuration/)
+        required: true
+      - label: I have [searched through existing issues](https://github.com/FoxxMD/multi-scrobbler/issues?q=sort%3Aupdated-desc) and [discussions.](https://github.com/FoxxMD/multi-scrobbler/discussions)
+        required: true
+  - type: markdown
+    attributes:
+      value: |
+        If this a how-do-I question, troublehooting, or generally **not** a bug/error with multi-scrobbler please consider [**starting a discussion**](https://github.com/FoxxMD/multi-scrobbler/discussions) instead of opening an issue.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: Describe the Bug
+      description: Describe what you expected to happen and what happened instead. Please provide as much detail as possible.
+      placeholder: The app should have scrobbled from Spotify but instead it crashed with an error about undefined properties, etc...
+    validations:
+      required: true
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Platform
+      description: What platform are you running multi-scrobbler on?
+      options:
+        - Docker
+        - Local (NodeJS)
+        - Flatpak
+      default: 0
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Versions
+      description: What version of multi-scrobbler and issue-related sources/clients are running?
+      placeholder: |
+        - multi-scrobbler: 0.8.3 on docker
+        - maloja 3.1.4
+        - jellyfin 10.8.9
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: |
+        Please copy and paste any/all relevant from the DEBUG level log output. 
+        Even if your issue does not seem to be shown in the logs you should still add as much detail as possible, a _lack_ of issues in logs may be a good hint during debugging.
+        Your logs will be automatically formatted into code, do not need use backticks.
+        If possible reproduce the issue with [**Debug Mode** enabled](https://foxxmd.github.io/multi-scrobbler/docs/configuration#debug-mode).
+      render: shell
+      placeholder: |
+        [2025-02-14 12:47:57.170 -0500] VERBOSE: [Init] Config Dir ENV: undefined -> Resolved: CWD/config
+        [2025-02-14 12:47:57.236 -0500] INFO   : [Init] Debug Mode: NO
+        [2025-02-14 12:47:57.258 -0500] INFO   : [Init] Version: master
+        [2025-02-14 12:47:57.259 -0500] INFO   : [Init] Generating schema definitions...
+        [2025-02-14 12:47:59.148 -0500] DEBUG  : [App] [Scrobblers] [Maloja - default] Found 100 recent scrobbles
+  - type: textarea
+    attributes:
+      label: Additional Context
+      description: Add any other context about the problem here.

.github/ISSUE_TEMPLATE/02-feature-request.yml

@@ -0,0 +1,31 @@
+name: Feature Request
+description: Suggest a new feature or functionality
+title: "feat: "
+labels: ["enhancement"]
+body:
+  - type: checkboxes
+    attributes:
+      label: Please check existing knowledge before opening an issue
+      options:
+      - label: I have checked the [documentation](https://foxxmd.github.io/multi-scrobbler/docs/configuration/)
+        required: true
+      - label: I have [searched through existing issues](https://github.com/FoxxMD/multi-scrobbler/issues?q=sort%3Aupdated-desc) and [discussions.](https://github.com/FoxxMD/multi-scrobbler/discussions)
+        required: true
+  - type: textarea
+    attributes:
+      label: Describe the new functionality
+      description: Please describe the feature or functionality you want multi-scrobbler to have. Use as much detail as possible about the exact behavior you wish to see.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Configuration Example
+      description: |
+        If the functionality involves changes to configuration files please provide an example here
+      render: json5
+  - type: checkboxes
+    attributes:
+      label: Will you help implement it?
+      options:
+        - label: I am willing to contribute code towards completing this feature
+        - label: I am willing to help test preview builds for this feature

.github/ISSUE_TEMPLATE/03-new-source-client.yml

@@ -0,0 +1,75 @@
+name: Request a new Source or Client
+description: Request a new Source or Client to be implemented
+title: "feat: "
+labels: ["enhancement"]
+body:
+  - type: checkboxes
+    attributes:
+      label: Please check existing knowledge before opening an issue
+      options:
+      - label: I have checked the [documentation](https://foxxmd.github.io/multi-scrobbler/docs/configuration/)
+        required: true
+      - label: I have [searched through existing issues](https://github.com/FoxxMD/multi-scrobbler/issues?q=sort%3Aupdated-desc) and [discussions.](https://github.com/FoxxMD/multi-scrobbler/discussions)
+        required: true
+  - type: dropdown
+    attributes:
+      label: What Type?
+      description: Is this a Source or a Client?
+      options:
+        - Source
+        - Client
+      default: 1
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: Name
+      description: "What is the name of the new service/software?"
+      placeholder: "My Cool Player"
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: Website
+      description: "Website for the service/software. Preferably a github repo or other source-code homepage"
+    validations:
+      required: true
+  - type: dropdown
+    attributes:
+      label: API Available?
+      description: Does the service have an API or other protocol that multi-scrobbler can use to communicate? **Without this the likelyhood of implementation is very low.**
+      options:
+        - 'Yes'
+        - 'No'
+      default: 1
+    validations:
+      required: true
+  - type: dropdown
+    attributes:
+      label: Free To Use?
+      description: Is this service/software freely available or does it require purchasing/subscription?
+      options:
+        - 'Yes'
+        - 'No'
+      default: 1
+    validations:
+      required: true
+  - type: dropdown
+    attributes:
+      label: Willing to finance development?
+      description: If the software is **non-free** are you will to provide a paid account/subscription to multi-scrobbler developer's in order to facilitate development/testing?
+      options:
+        - 'Yes'
+        - 'No'
+    validations:
+      required: false
+  - type: checkboxes
+    attributes:
+      label: Will you help implement it?
+      options:
+        - label: I am willing to contribute code towards completing this feature
+        - label: I am willing to help test preview builds for this feature
+  - type: textarea
+    attributes:
+      label: Additional Context
+      description: Add any other context about the new Source/Client here

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,40 +0,0 @@
----
-name: Bug report
-about: Create a report to help us improve
-title: ''
-labels: ''
-assignees: ''
-
----
-
-[Please check the FAQ](https://github.com/FoxxMD/multi-scrobbler/blob/master/docsite/docs/FAQ.md) before submitting a bug report.
-
-**Describe the bug**
-A clear and concise description of what the bug is.
-
-**To Reproduce**
-Steps to reproduce the behavior:
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
-
-**Expected behavior**
-A clear and concise description of what you expected to happen.
-
-**Logs**
-If possible reproduce the issue with [debug logging ON](https://github.com/FoxxMD/multi-scrobbler/blob/master/docsite/docs/FAQ.md#turn-on-debug-logging)
-
-```
-Copy and paste as much log data as possible related to this issue here.
-```
-
-**Versions (please complete the following information):**
-Provide version information for any related sources/clients.
-
-- multi-scrobbler: [e.g. 0.4.0 on docker]
-- maloja [e.g. 3.1.4]
-- jellyfin [e.g. 10.8.9]
-
-**Additional context**
-Add any other context about the problem here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/act/.actrc

@@ -0,0 +1,5 @@
+--directory ../../
+--env-file .github/act/.env
+--secret-file .github/act/.secrets
+--artifact-server-path out
+#--action-offline-mode

.github/act/.env.example

@@ -0,0 +1,5 @@
+NO_DOCKER_BUILD=true
+#https://github.com/nektos/act/issues/329#issuecomment-1905955589
+ACTIONS_RUNTIME_URL=http://YOUR_HOST_IP:8082/
+ACTIONS_RUNTIME_TOKEN=foo
+ACTIONS_CACHE_URL=http://YOUR_HOST_IP:8082/

.github/act/.secrets.example

@@ -0,0 +1,3 @@
+DOCKER_PASSWORD=
+DOCKER_USERNAME=
+GITHUB_TOKEN=

.github/act/README.md

@@ -1,4 +1,24 @@
-Testing GH Actions with [ACT]
+Testing GH Actions with ACT
+
+Need to have credentials in a [`.secrets` file](https://nektosact.com/usage/index.html#secrets), copy and rename [`.secrets.example`](./secrets.example) to `.secrets`, then fill out blank fields. Required for docker/metadata-action to read...something. Fails with `Parameter token or opts.auth is required` if they are not supplied.
+
+An ENV file can also be made by copy and renaming [`.env.example`](./env.example). Set `NO_DOCKER_BUILD=true` if you only want to test APP_VERSION and docker tags output. 
+
+If running a full docker build for multi-runner workflows you will need to create an [artifact server](https://github.com/nektos/act/issues/329#issuecomment-1905955589) for ACT to work:
+
+
+```shell
+docker pull ghcr.io/jefuller/artifact-server:latest
+docker run -d --name artifact-server -p 8082:8080 --add-host host.docker.internal:host-gateway -e AUTH_KEY=foo ghcr.io/jefuller/artifact-server:latest
+```
+
+Run the following **from this directory** to make use of `.actrc` and proper working directory.
+
+### Test Branch Test Suite
+
+```shell
+act -W '.github/act/testSuite.yml' -e '.github/act/actBranchEvent.json'
+```
 
 ### Test Branch Push
 
@@ -7,8 +27,27 @@ act -W '.github/act/actTest.yml' -e '.github/act/actBranchEvent.json'
 ```
 
 
-### Test Tag Push
+### Test Tag (Release) Push
 
 ```shell
 act -W '.github/act/actTest.yml' -e '.github/act/actTagEvent.json'
 ```
+
+
+### Test Tag (Pre-Release) Push
+
+```shell
+act -W '.github/act/actTest.yml' -e '.github/act/actTagPreEvent.json'
+```
+
+### Test Multi-Runner Push (WIP)
+
+```shell
+act -W '.github/act/multiRunnerTest.yml' -e '.github/act/actBranchEvent.json'
+```
+
+### Test Multi-Runner Bake Push (WIP)
+
+```shell
+act -W '.github/act/multiRunnerBakeTest.yml' -e '.github/act/actBranchEvent.json'
+```

.github/act/actBranchEvent.json

@@ -1,4 +1,4 @@
 {
   "ref": "refs/heads/master",
-  "sha": "0a1a94d9ad4efa373f8d34aace5e7f0a3fff42ad"
+  "sha": "14d5eb3313110f2cfd1aa8fe9c229c21901c1eeb"
 }

.github/act/actPREvent.json

@@ -0,0 +1,164 @@
+{
+    "action": "synchronize",
+    "number": 210,
+    "pull_request": {
+      "url": "https://api.github.com/repos/FoxxMD/multi-scrobbler/pulls/210",
+      "id": 2123337348,
+      "node_id": "PR_kwDOEpP-x85-j46E",
+      "number": 210,
+      "state": "open",
+      "locked": false,
+      "merge_commit_sha": "349bea1f4580b9e61aa22446eae73f8b1225bbb7",
+      "labels": [
+        {
+          "id": 2494982061,
+          "node_id": "MDU6TGFiZWwyNDk0OTgyMDYx",
+          "url": "https://api.github.com/repos/FoxxMD/multi-scrobbler/labels/bug",
+          "name": "bug",
+          "color": "d73a4a",
+          "default": true,
+          "description": "Something isn't working"
+        },
+        {
+          "id": 7131135993,
+          "node_id": "LA_kwDOEpP-x88AAAABqQx_-Q",
+          "url": "https://api.github.com/repos/FoxxMD/multi-scrobbler/labels/safe%20to%20test",
+          "name": "safe to test",
+          "color": "D4C5F9",
+          "default": false,
+          "description": "trusted to build image"
+        }
+      ],
+      "milestone": null,
+      "draft": false,
+      "head": {
+        "label": "FoxxMD:GH-209/jellyfinCleanup",
+        "ref": "GH-209/jellyfinCleanup",
+        "sha": "e251da9b8eecfcb3aba8756393e5075d0092794b",
+        "user": {
+          "login": "FoxxMD",
+          "id": 4663766,
+          "node_id": "MDQ6VXNlcjQ2NjM3NjY=",
+          "avatar_url": "https://avatars.githubusercontent.com/u/4663766?v=4",
+          "gravatar_id": "",
+          "url": "https://api.github.com/users/FoxxMD",
+          "html_url": "https://github.com/FoxxMD",
+          "followers_url": "https://api.github.com/users/FoxxMD/followers",
+          "following_url": "https://api.github.com/users/FoxxMD/following{/other_user}",
+          "gists_url": "https://api.github.com/users/FoxxMD/gists{/gist_id}",
+          "starred_url": "https://api.github.com/users/FoxxMD/starred{/owner}{/repo}",
+          "subscriptions_url": "https://api.github.com/users/FoxxMD/subscriptions",
+          "organizations_url": "https://api.github.com/users/FoxxMD/orgs",
+          "repos_url": "https://api.github.com/users/FoxxMD/repos",
+          "events_url": "https://api.github.com/users/FoxxMD/events{/privacy}",
+          "received_events_url": "https://api.github.com/users/FoxxMD/received_events",
+          "type": "User",
+          "site_admin": false
+        },
+        "repo": {
+          "id": 311688903,
+          "node_id": "MDEwOlJlcG9zaXRvcnkzMTE2ODg5MDM=",
+          "name": "multi-scrobbler",
+          "full_name": "FoxxMD/multi-scrobbler",
+          "private": false,
+          "owner": {
+            "login": "FoxxMD",
+            "id": 4663766,
+            "node_id": "MDQ6VXNlcjQ2NjM3NjY=",
+            "avatar_url": "https://avatars.githubusercontent.com/u/4663766?v=4",
+            "gravatar_id": "",
+            "url": "https://api.github.com/users/FoxxMD",
+            "html_url": "https://github.com/FoxxMD",
+            "followers_url": "https://api.github.com/users/FoxxMD/followers",
+            "following_url": "https://api.github.com/users/FoxxMD/following{/other_user}",
+            "gists_url": "https://api.github.com/users/FoxxMD/gists{/gist_id}",
+            "starred_url": "https://api.github.com/users/FoxxMD/starred{/owner}{/repo}",
+            "subscriptions_url": "https://api.github.com/users/FoxxMD/subscriptions",
+            "organizations_url": "https://api.github.com/users/FoxxMD/orgs",
+            "repos_url": "https://api.github.com/users/FoxxMD/repos",
+            "events_url": "https://api.github.com/users/FoxxMD/events{/privacy}",
+            "received_events_url": "https://api.github.com/users/FoxxMD/received_events",
+            "type": "User",
+            "site_admin": false
+          },
+          "html_url": "https://github.com/FoxxMD/multi-scrobbler",
+          "description": "Scrobble plays from multiple sources to multiple clients",
+          "fork": false,
+          "created_at": "2020-11-10T14:45:38Z",
+          "updated_at": "2024-10-14T09:21:37Z",
+          "pushed_at": "2024-10-14T15:43:00Z",
+          "allow_forking": true,
+          "is_template": false,
+          "web_commit_signoff_required": false,
+          "visibility": "public",
+          "forks": 16,
+          "open_issues": 19,
+          "watchers": 369,
+          "default_branch": "master",
+          "allow_squash_merge": true,
+          "allow_merge_commit": true,
+          "allow_rebase_merge": true,
+          "allow_auto_merge": false,
+          "delete_branch_on_merge": false,
+          "allow_update_branch": false,
+          "use_squash_pr_title_as_default": false,
+          "squash_merge_commit_message": "COMMIT_MESSAGES",
+          "squash_merge_commit_title": "COMMIT_OR_PR_TITLE",
+          "merge_commit_message": "PR_TITLE",
+          "merge_commit_title": "MERGE_MESSAGE"
+        }
+      },
+      "base": {
+        "label": "FoxxMD:master",
+        "ref": "master",
+        "sha": "9c21db8172b6beff9d321e831e9353bf17e92a37",
+        "repo": {
+          "id": 311688903,
+          "node_id": "MDEwOlJlcG9zaXRvcnkzMTE2ODg5MDM=",
+          "name": "multi-scrobbler",
+          "full_name": "FoxxMD/multi-scrobbler",
+          "private": false,
+          "fork": false,
+          "created_at": "2020-11-10T14:45:38Z",
+          "updated_at": "2024-10-14T09:21:37Z",
+          "pushed_at": "2024-10-14T15:43:00Z",
+          "allow_forking": true,
+          "is_template": false,
+          "web_commit_signoff_required": false,
+          "visibility": "public",
+          "forks": 16,
+          "open_issues": 19,
+          "watchers": 369,
+          "default_branch": "master",
+          "allow_squash_merge": true,
+          "allow_merge_commit": true,
+          "allow_rebase_merge": true,
+          "allow_auto_merge": false,
+          "delete_branch_on_merge": false,
+          "allow_update_branch": false,
+          "use_squash_pr_title_as_default": false,
+          "squash_merge_commit_message": "COMMIT_MESSAGES",
+          "squash_merge_commit_title": "COMMIT_OR_PR_TITLE",
+          "merge_commit_message": "PR_TITLE",
+          "merge_commit_title": "MERGE_MESSAGE"
+        }
+      },
+      "author_association": "OWNER",
+      "auto_merge": null,
+      "active_lock_reason": null,
+      "merged": false,
+      "mergeable": null,
+      "rebaseable": null,
+      "mergeable_state": "unknown",
+      "merged_by": null,
+      "comments": 0,
+      "review_comments": 0,
+      "maintainer_can_modify": false,
+      "commits": 5,
+      "additions": 84,
+      "deletions": 28,
+      "changed_files": 5
+    },
+    "before": "335ee0cd601f5a82e36643c812507b2b53e7daf0",
+    "after": "e251da9b8eecfcb3aba8756393e5075d0092794b"
+  }

.github/act/actTagEvent.json

@@ -1,5 +1,8 @@
 {
-  "ref": "refs/tags/0.8.0",
-  "ref_name": "0.8.0",
-  "sha": "0a1a94d9ad4efa373f8d34aace5e7f0a3fff42ad"
+  "ref": "refs/tags/0.8.4",
+  "ref_name": "0.8.4",
+  "before": "0000000000000000000000000000000000000000",
+  "after": "005dae76ab51799d3d55112738e301cb1af0dafd",
+  "sha": "005dae76ab51799d3d55112738e301cb1af0dafd",
+  "base_ref": "refs/heads/master"
 }

.github/act/actTagPreEvent.json

@@ -0,0 +1,8 @@
+{
+  "ref": "refs/tags/0.8.5-gh-runner",
+  "ref_name": "0.8.5-gh-runner",
+  "before": "0000000000000000000000000000000000000000",
+  "after": "005dae76ab51799d3d55112738e301cb1af0dafd",
+  "sha": "005dae76ab51799d3d55112738e301cb1af0dafd",
+  "base_ref": "refs/heads/master"
+}

.github/act/actTest.yml

@@ -1,15 +1,17 @@
 name: Publish Docker image to Dockerhub
 
 on:
+  workflow_dispatch:
   push:
     branches:
       - 'master'
-      - 'develop'
     tags:
       - '*.*.*'
     # don't trigger if just updating docs
     paths-ignore:
-      - '**.md'
+      - 'README.md'
+      - '.github/**'
+      - 'flatpak/**'
   # use release instead of tags once version is correctly parsed
   # https://github.com/docker/metadata-action/issues/422
   # https://github.com/docker/metadata-action/issues/240
@@ -18,16 +20,10 @@ on:
 
 jobs:
 
-  test:
+  push_to_registry:
     name: Build and push container images
+    if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
-#    strategy:
-#      fail-fast: false
-#      matrix:
-#        include:
-#          - dockerfile: ./Dockerfile
-#            suffix: ''
-#            platforms: 'linux/amd64'
     steps:
       - name: Check out the repo
         uses: actions/checkout@v4
@@ -47,11 +43,6 @@ jobs:
           echo "COMMIT_SHORT_SHA=$calculatedSha" >> $GITHUB_ENV
           echo "COMMIT_BRANCH=$branchName" >> $GITHUB_ENV
 
-#      - name: Set push event short ref
-#        run: |
-#          shortEventRef=${github.event.push.ref:10}
-#          echo "SHORT_REF=$shortEventRef" >> $GITHUB_ENV
-
       - name: Check App Version
         env:
           # use release instead of tags once version is correctly parsed
@@ -63,26 +54,38 @@ jobs:
         run: |
           echo $APP_VERSION
 
-#      - name: Extract metadata (tags, labels) for Docker
-#        id: meta
-#        uses: docker/metadata-action@v5
-#        with:
-#          # generate Docker tags based on the following events/attributes
-#          # https://github.com/docker/metadata-action/issues/247#issuecomment-1511259674 for NOT is default branch, eventually
-#          tags: |
-#            type=raw,value=latest,enable={{endsWith(github.ref, 'master')}},suffix=${{ matrix.suffix }}
-#            type=ref,event=branch,enable=${{ !endsWith(github.ref, 'master') }},suffix=${{ matrix.suffix }}
-#            type=semver,pattern={{version}},suffix=${{ matrix.suffix }}
-#          flavor: |
-#            latest=false
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+         # generate Docker tags based on the following events/attributes
+         # https://github.com/docker/metadata-action/issues/247#issuecomment-1511259674 for NOT is default branch, eventually
+         tags: |
+            type=edge
+
+            # maybe re-enable branch-named tags in the futures
+            #type=ref,event=branch,enable=${{ !endsWith(github.ref, 'master') }}
+            
+            # tag non-prelease as latest -- has a higher priority than regular tag so it shows first in registries
+            type=match,pattern=\d.\d.\d$,priority=901
+            
+            # tag all semver (include pre-release)
+            type=semver,pattern={{version}}
+        #  flavor: |
+        #    latest=false
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
+        id: qemu
+        if: ${{ !env.NO_DOCKER_BUILD }}
 
-#      - name: Set up Docker Buildx
-#        uses: docker/setup-buildx-action@v3
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        if: ${{ steps.qemu.outcome == 'success' }}
+        continue-on-error: true
 
       - name: Build and push Docker image
+        if: ${{ steps.qemu.outcome == 'success' }}
         env:
           # use release instead of tags once version is correctly parsed
           #APP_VERSION: ${{ github.event.release.tag_name }}
@@ -96,9 +99,7 @@ jobs:
           # https://github.com/docker/build-push-action/issues/1026#issue-2041857786
           build-args: |
             APP_BUILD_VERSION=${{env.APP_VERSION}}
-          file: ${{ matrix.dockerfile }}
           push: false
-          tags: mstest:latest
-          #tags: ${{ steps.meta.outputs.tags }}
-          #labels: ${{ steps.meta.outputs.labels }}
-          #platforms: ${{ matrix.platforms }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          platforms: linux/amd64,linux/arm64

.github/act/docker-bake.hcl

@@ -0,0 +1,30 @@
+variable "DEFAULT_TAG" {
+  default = "multi-scrobbler:local"
+}
+
+// Special target: https://github.com/docker/metadata-action#bake-definition
+target "docker-metadata-action" {
+  tags = ["${DEFAULT_TAG}"]
+}
+
+// Default target if none specified
+group "default" {
+  targets = ["image-local"]
+}
+
+target "image" {
+  inherits = ["docker-metadata-action"]
+}
+
+target "image-local" {
+  inherits = ["image"]
+  output = ["type=docker"]
+}
+
+target "image-all" {
+  inherits = ["image"]
+  platforms = [
+    "linux/amd64",
+    "linux/arm64"
+  ]
+}

.github/act/multiRunnerBakeTest.yml

@@ -0,0 +1,233 @@
+# Based on https://docs.docker.com/build/ci/github-actions/multi-platform/#with-bake (https://github.com/docker/build-push-action/issues/671#issuecomment-1609106171)
+# with example from here https://github.com/crazy-max/docker-linguist/blob/master/.github/workflows/build.yml that uses caching
+#
+# may have to use this to enable pushing to multiple registries? https://github.com/docker/build-push-action/discussions/1067#discussioncomment-8677682
+
+name: build
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches:
+      - 'master'
+    tags:
+      - '*.*.*'
+    paths-ignore:
+      - 'README.md'
+      - '.github/**'
+      - 'flatpak/**'
+
+env:
+  DOCKERHUB_SLUG: foxxmd/multi-scrobbler
+  GHCR_SLUG: ghcr.io/foxxmd/multi-scrobbler
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.platforms.outputs.matrix }}
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set short git commit SHA
+        id: appvars
+        # https://dev.to/hectorleiva/github-actions-and-creating-a-short-sha-hash-8b7
+        # short sha available under env.COMMIT_SHORT_SHA
+        run: |
+          calculatedSha=$(git rev-parse --short HEAD)
+          branchName=$(git rev-parse --abbrev-ref HEAD)
+          echo "COMMIT_SHORT_SHA=$calculatedSha" >> $GITHUB_ENV
+          echo "COMMIT_BRANCH=$branchName" >> $GITHUB_ENV
+
+      - name: Get App Version
+        id: appversion
+        env:
+          # use release instead of tags once version is correctly parsed
+          #APP_VERSION: ${{ github.event.release.tag_name }}
+
+          # https://github.com/actions/runner/issues/409#issuecomment-752775072
+          # https://stackoverflow.com/a/69919067/1469797
+          APP_VERSION: ${{ contains(github.ref, 'refs/tags/') && github.ref_name || format('{0}-{1}', env.COMMIT_BRANCH, env.COMMIT_SHORT_SHA ) }}
+        run: |
+          echo appversion=$APP_VERSION >>${GITHUB_OUTPUT}
+
+      -
+        name: Create matrix
+        id: platforms
+        run: |
+          echo "matrix=$(docker buildx bake --file ./docker-bake.hcl image-all --print | jq -cr '.target."image-all".platforms')" >>${GITHUB_OUTPUT}
+      -
+        name: Show matrix
+        run: |
+          echo ${{ steps.platforms.outputs.matrix }}
+      -
+        name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ${{ env.DOCKERHUB_SLUG }}
+            ${{ env.GHCR_SLUG }}
+          tags: |
+            type=edge
+
+            # maybe re-enable branch-named tags in the futures
+            #type=ref,event=branch,enable=${{ !endsWith(github.ref, 'master') }}
+            
+            # tag non-prelease as latest -- has a higher priority than regular tag so it shows first in registries
+            type=match,pattern=\d.\d.\d$,priority=901
+            
+            # tag all semver (include pre-release)
+            type=semver,pattern={{version}}
+          labels: |
+            org.opencontainers.image.title=Multi-Scrobbler
+            org.opencontainers.image.description=Scrobble from many sources to many clients
+            org.opencontainers.image.vendor=FoxxMD
+      -
+        name: Rename meta bake definition file
+        run: |
+          mv "${{ steps.meta.outputs.bake-file }}" "/tmp/bake-meta.json"
+      -
+        name: Upload meta bake definition
+        uses: actions/upload-artifact@v3
+        with:
+          name: bake-meta
+          path: /tmp/bake-meta.json
+          if-no-files-found: error
+          retention-days: 1
+
+  build:
+    runs-on: ubuntu-latest
+    needs:
+      - prepare
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: ${{ fromJson(needs.prepare.outputs.matrix) }}
+    steps:
+      -
+        name: Prepare
+        run: |
+          platform=${{ matrix.platform }}
+          echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV
+      -
+        name: Checkout
+        uses: actions/checkout@v4
+      -
+        name: Test App Version Transfer
+        run: |
+          echo "App Version in Build ${{ needs.prepare.appversion.outputs.appversion }}"
+      -
+        name: Download meta bake definition
+        uses: actions/download-artifact@v3
+        with:
+          name: bake-meta
+          path: /tmp
+      -
+        name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          buildkitd-flags: "--debug"
+      -
+        name: Login to DockerHub
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+      -
+        name: Login to GHCR
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      -
+        name: Build
+        id: bake
+        uses: docker/bake-action@v5
+        with:
+          files: |
+            ./.github/act/docker-bake.hcl
+            /tmp/bake-meta.json
+          targets: image
+          set: |
+            *.args.APP_BUILD_VERSION=${{ needs.prepare.appversion.outputs.appversion }}
+            *.tags=
+            *.platform=${{ matrix.platform }}
+            *.cache-from=type=gha,scope=build-${{ env.PLATFORM_PAIR }}
+            *.cache-to=type=gha,scope=build-${{ env.PLATFORM_PAIR }}
+            *.output=type=image,"name=${{ env.DOCKERHUB_SLUG }},${{ env.GHCR_SLUG }}",push-by-digest=true,name-canonical=true,push=${{ github.event_name != 'pull_request' }}
+      -
+        name: Export digest
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ fromJSON(steps.bake.outputs.metadata).image['containerimage.digest'] }}"
+          touch "/tmp/digests/${digest#sha256:}"
+      -
+        name: Upload digest
+        uses: actions/upload-artifact@v3
+        with:
+          name: digests-${{ env.PLATFORM_PAIR }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge:
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request'
+    needs:
+      - build
+    steps:
+      -
+        name: Download meta bake definition
+        uses: actions/download-artifact@v3
+        with:
+          name: bake-meta
+          path: /tmp
+      -
+        name: Download digests
+        uses: actions/download-artifact@v3
+        with:
+          path: /tmp/digests
+          pattern: digests-*
+          merge-multiple: true
+      -
+        name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      -
+        name: Login to DockerHub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+      -
+        name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      -
+        name: Create manifest list and push
+        working-directory: /tmp/digests
+        run: |
+          docker buildx imagetools create $(jq -cr '.target."docker-metadata-action".tags | map(select(startswith("${{ env.DOCKERHUB_SLUG }}")) | "-t " + .) | join(" ")' /tmp/bake-meta.json) \
+            $(printf '${{ env.DOCKERHUB_SLUG }}@sha256:%s ' *)
+          docker buildx imagetools create $(jq -cr '.target."docker-metadata-action".tags | map(select(startswith("${{ env.GHCR_SLUG }}")) | "-t " + .) | join(" ")' /tmp/bake-meta.json) \
+            $(printf '${{ env.GHCR_SLUG }}@sha256:%s ' *)
+      -
+        name: Inspect image
+        run: |
+          tag=$(jq -r '.target."docker-metadata-action".args.DOCKER_META_VERSION' /tmp/bake-meta.json)
+          docker buildx imagetools inspect ${{ env.DOCKERHUB_SLUG }}:${tag}
+          docker buildx imagetools inspect ${{ env.GHCR_SLUG }}:${tag}

.github/act/multiRunnerTest.yml

@@ -0,0 +1,198 @@
+# Based on https://docs.docker.com/build/ci/github-actions/multi-platform/#distribute-build-across-multiple-runners
+
+name: build
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  push:
+    branches:
+      - 'master'
+    tags:
+      - '*.*.*'
+    paths-ignore:
+      - 'README.md'
+      - '.github/**'
+      - 'flatpak/**'
+
+env:
+  DOCKERHUB_SLUG: foxxmd/multi-scrobbler
+  GHCR_SLUG: ghcr.io/foxxmd/multi-scrobbler
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+          - linux/amd64
+          - linux/arm64
+    steps:
+      - name: Prepare
+        run: |
+          platform=${{ matrix.platform }}
+          echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV          
+
+      - name: Check out the repo
+        uses: actions/checkout@v5
+
+      - name: Set short git commit SHA
+        id: appvars
+        # https://dev.to/hectorleiva/github-actions-and-creating-a-short-sha-hash-8b7
+        # short sha available under env.COMMIT_SHORT_SHA
+        run: |
+          calculatedSha=$(git rev-parse --short HEAD)
+          branchName=$(git rev-parse --abbrev-ref HEAD)
+          echo "COMMIT_SHORT_SHA=$calculatedSha" >> $GITHUB_ENV
+          echo "COMMIT_BRANCH=$branchName" >> $GITHUB_ENV
+
+      - name: Get App Version
+        id: appversion
+        env:
+          # use release instead of tags once version is correctly parsed
+          #APP_VERSION: ${{ github.event.release.tag_name }}
+
+          # https://github.com/actions/runner/issues/409#issuecomment-752775072
+          # https://stackoverflow.com/a/69919067/1469797
+          APP_VERSION: ${{ contains(github.ref, 'refs/tags/') && github.ref_name || format('{0}-{1}', env.COMMIT_BRANCH, env.COMMIT_SHORT_SHA ) }}
+        run: |
+          echo appversion=$APP_VERSION >>${GITHUB_OUTPUT}
+      
+      # - name: Extract metadata (tags, labels) for Docker
+      #   id: meta
+      #   uses: docker/metadata-action@v5
+      #   with:
+      #     images: |
+      #       ${{ env.DOCKERHUB_SLUG }}
+      #       ${{ env.GHCR_SLUG }}
+      #     labels: |
+      #       org.opencontainers.image.title=Multi-Scrobbler
+      #       org.opencontainers.image.description=Scrobble from many sources to many clients
+      #       org.opencontainers.image.vendor=FoxxMD
+      
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      
+      # https://github.com/docker/build-push-action/issues/671#issuecomment-1619353328
+      # for caching
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          build-args: |
+            APP_BUILD_VERSION=${{steps.appversion.outputs.appversion}}
+          platforms: ${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          #tags: ${{ steps.meta.outputs.tags }}
+          outputs: type=image,"name=${{ env.DOCKERHUB_SLUG }},${{ env.GHCR_SLUG }}",push-by-digest=true,name-canonical=true,push=true
+          #cache-from: type=gha,scope=build-${{ env.PLATFORM_PAIR }}
+          #cache-to: type=gha,scope=build-${{ env.PLATFORM_PAIR }}
+      
+      - name: Export digest
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.build.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"          
+      
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: digests-${{ env.PLATFORM_PAIR }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge:
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    needs:
+      - build
+    steps:
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/digests
+          pattern: digests-*
+          merge-multiple: true
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ${{ env.DOCKERHUB_SLUG }}
+            ${{ env.GHCR_SLUG }}
+          # generate Docker tags based on the following events/attributes
+          # https://github.com/docker/metadata-action/issues/247#issuecomment-1511259674 for NOT is default branch, eventually
+          tags: |
+            type=edge
+
+            # maybe re-enable branch-named tags in the futures
+            type=ref,event=branch,enable=${{ !endsWith(github.ref, 'master') }}
+            
+            # tag non-prelease as latest -- has a higher priority than regular tag so it shows first in registries
+            type=match,pattern=\d.\d.\d$,priority=901
+            
+            # tag all semver (include pre-release)
+            type=semver,pattern={{version}}
+        #  flavor: |
+        #    latest=false
+          labels: |
+            org.opencontainers.image.title=Multi-Scrobbler
+            org.opencontainers.image.description=Scrobble from many sources to many clients
+            org.opencontainers.image.vendor=FoxxMD
+      
+
+      
+      - name: Create manifest list and push
+        working-directory: /tmp/digests
+        run: |
+          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf '${{ env.DOCKERHUB_SLUG }}@sha256:%s ' *)
+          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf '${{ env.GHCR_SLUG }}@sha256:%s ' *)        
+      
+      - name: Inspect image
+        run: |
+          docker buildx imagetools inspect ${{ env.DOCKERHUB_SLUG }}:${{ steps.meta.outputs.version }}
+          docker buildx imagetools inspect ${{ env.GHCR_SLUG }}:${{ steps.meta.outputs.version }}      

.github/act/testSuite.yml

@@ -0,0 +1,10 @@
+name: PR Workflow
+
+on:
+  push:
+    branches:
+      - 'master'
+
+jobs:
+  test:
+      uses: ./.github/workflows/testAndSanity.yml

.github/pull_request_template.md

@@ -1,6 +1,5 @@
 ## Checklist before requesting a review
 
-- [ ] **I am opening this PR for the [`develop` branch](https://github.com/FoxxMD/multi-scrobbler/tree/develop) and NOT `master`.**
 - [ ] I have read the [contributing guidelines.](../CONTRIBUTING.md)
 
 ## Type of change

.github/workflows/dependabotTest.yml

@@ -0,0 +1,16 @@
+name: Test Dependabot PR
+
+on:
+  pull_request_target:
+    types:
+      - synchronize
+      - reopened
+      - opened
+    branches:
+      - 'master'
+
+jobs:
+  test:
+    name: Tests / Build / Sanity Run
+    if: github.actor == 'dependabot[bot]'
+    uses: ./.github/workflows/testAndSanity.yml

.github/workflows/docsDeploy.yml

@@ -2,10 +2,8 @@ name: Deploy to GitHub Pages
 
 on:
   workflow_dispatch:
-  push:
-    branches:
-      - master
-      - developDocs
+  release:
+    types: [released]
     # Review gh actions docs if you want to further define triggers, paths, etc
     # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
 
@@ -20,13 +18,19 @@ jobs:
           node-version: 20
           cache: npm
 
-      - name: Install dependencies
+      - name: Install app dev dependencies
+        run: npm ci
+      - name: Generate schema files
+        run: npm run schema
+
+      - name: Install docusaurus dependencies
         run: npm ci
         working-directory: ./docsite
       - name: Build website
         env:
           ANALYTICS: ${{ vars.ANALYTICS }}
           ANALYTICS_DOMAIN: ${{ vars.ANALYTICS_DOMAIN }}
+          GSITEVERIFICATION: ${{ vars.GSITEVERIFICATION }}
           DOCS_BASE: '/multi-scrobbler'
         run: npm run build
         working-directory: ./docsite

.github/workflows/packagesDeleteUntagged.yml

@@ -1,7 +1,7 @@
 name: Delete Untagged Packages
 on:
   schedule:
-    - cron: '30 1 * * *'
+    - cron: '30 1 * * 0'
   workflow_run:
     workflows: ["Publish Docker image to Dockerhub"]
     types:

.github/workflows/pr.yml

@@ -1,5 +1,9 @@
 name: PR Workflow
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.head.sha }}
+  cancel-in-progress: true
+
 on:
   pull_request_target:
     types:
@@ -8,33 +12,20 @@ on:
       - reopened
       - opened
     branches:
-      - 'develop'
+      - 'master'
 
 jobs:
   test:
-    name: Run Tests
-    runs-on: ubuntu-latest
     if: contains(github.event.pull_request.labels.*.name, 'safe to test')
-    steps:
-      - name: Check out the repo
-        uses: actions/checkout@v4
-      - name: Use Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '18.x'
-          cache: 'npm'
-      - name: Install dev dependencies
-        run: npm ci
-      - name: Build Backend
-        run: 'npm run build:backend'
-      - name: Test Backend
-        run: npm run test
+    uses: ./.github/workflows/testAndSanity.yml
+    with:
+      ref: ${{ github.event.pull_request.head.sha }}
 
-  release-snapshot:
-    name: Release snapshot
-    runs-on: ubuntu-latest
+  build-snapshot:
+    name: Build OCI snapshot
     needs: test
     if: contains(github.event.pull_request.labels.*.name, 'safe to test')
+    runs-on: ${{ matrix.os }}
     permissions:
       packages: write
       contents: read
@@ -42,62 +33,172 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - dockerfile: ./Dockerfile
-            suffix: ''
-            platforms: 'linux/amd64,linux/arm64'
-          - dockerfile: ./alpine.Dockerfile
-            suffix: '-alpine'
-            platforms: 'linux/amd64,linux/arm64'
+          - os: ubuntu-latest
+            arch: amd64
+            platform: linux/amd64
+          - os: ubuntu-24.04-arm
+            arch: arm64
+            platform: linux/arm64
     steps:
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+      - name: Prepare
+        run: |
+          platform=${{ matrix.platform }}
+          echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV     
 
-      - name: Set up Buildx
-        uses: docker/setup-buildx-action@v3
+          # list all registries to push to and join all non-empty with comma
+          # https://unix.stackexchange.com/a/693165/116849
+          # https://stackoverflow.com/a/9429887/1469797
+          strings=("${{vars.DOCKERHUB_SLUG}}" "${{vars.GHCR_SLUG}}")
+          for i in ${!strings[@]}; do [[ -z ${strings[i]} ]] && unset strings[i]; done
+          joined_string=$(IFS=, ; echo "${strings[*]}")
+          echo "REGISTRIES_JOINED=$joined_string" >> $GITHUB_ENV 
 
-      - name: Log in to Docker Hub
+      # do not use here!
+      # instead we can specify repo#sha in build-push-action so we only deal with foreign SHA for actually building image
+      # - uses: actions/checkout@v4
+      #   with:
+      #     ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Set short git commit SHA
+        run: |
+          short=$(echo "${{ github.event.pull_request.head.sha }}" | head -c7)
+          echo "COMMIT_SHORT_SHA=$short" >> $GITHUB_ENV
+
+      - name: Get App Version
+        id: appversion
+        env:
+          APP_VERSION: ${{ format('pr{0}-{1}', github.event.number, env.COMMIT_SHORT_SHA ) }}
+        run: |
+          echo appversion=$APP_VERSION >>${GITHUB_OUTPUT}
+
+      - name: Login to Docker Hub
+        if: ${{ vars.DOCKERHUB_SLUG != '' }}
         uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
-
+  
       - name: Login to GitHub Container Registry
+        if: ${{ vars.GHCR_SLUG != '' }}
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Extract metadata (tags, labels) for Docker
+      # metadata extract for docker labels/image names is done in merge job
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v3
+
+      # https://github.com/docker/build-push-action/issues/671#issuecomment-1619353328
+      # for caching
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          # specify foreign repo#sha from PR that is used to build image
+          context: ${{github.event.pull_request.head.repo.clone_url}}#${{github.event.pull_request.head.sha}}
+          build-args: |
+            APP_BUILD_VERSION=${{steps.appversion.outputs.appversion}}
+          platforms: ${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          outputs: type=image,"name=${{ env.REGISTRIES_JOINED }}",push-by-digest=true,name-canonical=true,push=true
+          #cache-from: type=gha,scope=build-${{ env.PLATFORM_PAIR }}
+          #cache-to: type=gha,scope=build-${{ env.PLATFORM_PAIR }}
+
+      - name: Export digest
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.build.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"          
+      
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: digests-${{ env.PLATFORM_PAIR }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  release-snapshot:
+    name: Merge OCI Images and Push
+    if: ${{ vars.DOCKERHUB_SLUG != '' ||  vars.GHCR_SLUG != '' }}
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    needs:
+      - build-snapshot
+      - test
+    steps:
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/digests
+          pattern: digests-*
+          merge-multiple: true
+
+      - name: Login to Docker Hub
+        if: ${{ vars.DOCKERHUB_SLUG != '' }}
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Login to GitHub Container Registry
+        if: ${{ vars.GHCR_SLUG != '' }}
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      
+      - name: Extract metadata (tags, labels)
         id: meta
         uses: docker/metadata-action@v5
         with:
           images: |
-            foxxmd/multi-scrobbler
-            ghcr.io/foxxmd/multi-scrobbler
+            ${{ vars.DOCKERHUB_SLUG }}
+            ${{ vars.GHCR_SLUG }}
+          # generate Docker tags based on the following events/attributes
+          # https://github.com/docker/metadata-action/issues/247#issuecomment-1511259674 for NOT is default branch, eventually
           tags: |
-            type=ref,event=pr,suffix=${{ matrix.suffix }}
+            type=ref,event=pr
           flavor: |
             latest=false
+          labels: |
+            org.opencontainers.image.title=Multi-Scrobbler
+            org.opencontainers.image.description=Scrobble from many sources to many clients
+            org.opencontainers.image.vendor=FoxxMD
+      
+      - name: Create manifest list and push dockerhub
+        if: ${{ vars.DOCKERHUB_SLUG != '' }}
+        working-directory: /tmp/digests
+        run: |
+          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf '${{ vars.DOCKERHUB_SLUG }}@sha256:%s ' *)
+      
+      - name: Create manifest list and push gchr
+        if: ${{ vars.GHCR_SLUG != '' }}
+        working-directory: /tmp/digests
+        run: |
+          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf '${{ vars.GHCR_SLUG }}@sha256:%s ' *)    
+      
+      - name: Inspect image dockerhub
+        if: ${{ vars.DOCKERHUB_SLUG != '' }}
+        run: |
+          docker buildx imagetools inspect ${{ vars.DOCKERHUB_SLUG }}:${{ steps.meta.outputs.version }}
 
-      - uses: actions/checkout@v4
-        with:
-          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Inspect image ghcr
+        if: ${{ vars.GHCR_SLUG != '' }}
+        run: |
+            docker buildx imagetools inspect ${{ vars.GHCR_SLUG }}:${{ steps.meta.outputs.version }}   
 
-      - name: Build and push
-        id: docker_build
-        uses: docker/build-push-action@v5
-        env:
-          APP_VERSION: ${{ format('pr{0}-{1}', github.event.number, github.event.pull_request.head.sha ) }}
-        with:
-          context: .
-          build-args: |
-            APP_BUILD_VERSION=${{env.APP_VERSION}}
-          file: ${{ matrix.dockerfile }}
-          push: ${{ !env.ACT}}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          platforms: ${{ matrix.platforms }}
 
   combine-and-comment:
     name: Leave comment
@@ -115,7 +216,6 @@ jobs:
 
             To play around with this PR, pull an image:
             * `foxxmd/multi-scrobbler:pr-${{ github.event.number }}`
-            * `foxxmd/multi-scrobbler:pr-${{ github.event.number }}-alpine`.
 
             Images are available for x86_64 and ARM64.
 

.github/workflows/publishImage.yml

@@ -1,11 +1,16 @@
+# Based on https://docs.docker.com/build/ci/github-actions/multi-platform/#distribute-build-across-multiple-runners
+
 name: Publish Docker image to Dockerhub
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 on:
   workflow_dispatch:
   push:
     branches:
       - 'master'
-      - 'develop'
     tags:
       - '*.*.*'
     # don't trigger if just updating docs
@@ -19,51 +24,54 @@ on:
 #  release:
 #    types: [ published ]
 
+# define in GH Repository -> Actions -> Variables (or act .variables) to enable pushing to registries
+# -- will only push to registries that are defined
+# EX
+# DOCKERHUB_SLUG=foxxmd/multi-scrobbler
+# GHCR_SLUG=ghcr.io/foxxmd/multi-scrobbler
+  
 jobs:
   test:
-    name: Run Tests
     if: github.event_name != 'pull_request'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out the repo
-        uses: actions/checkout@v4
-      - name: Use Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '18.x'
-          cache: 'npm'
-      - name: Install dev dependencies
-        run: npm ci
-      - name: Build Backend
-        run: 'npm run build:backend'
-      - name: Test Backend
-        run: npm run test
+    uses: ./.github/workflows/testAndSanity.yml
 
-  push_to_registry:
-    name: Build and push container images
-    if: github.event_name != 'pull_request'
-    runs-on: ubuntu-latest
+  build:
+    name: Build OCI Images
+    if: ${{ github.event_name != 'pull_request' && (vars.DOCKERHUB_SLUG != '' ||  vars.GHCR_SLUG != '') }}
     needs: test
+    runs-on: ${{ matrix.os }}
+    permissions:
+      packages: write
+      contents: read
     strategy:
       fail-fast: false
       matrix:
         include:
-          - dockerfile: ./Dockerfile
-            suffix: ''
-            platforms: 'linux/amd64,linux/arm64'
-          - dockerfile: ./alpine.Dockerfile
-            suffix: '-alpine'
-            platforms: 'linux/amd64,linux/arm64'
-    # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token
-    permissions:
-      packages: write
-      contents: read
+          - os: ubuntu-latest
+            arch: amd64
+            platform: linux/amd64
+          - os: ubuntu-24.04-arm
+            arch: arm64
+            platform: linux/arm64
     steps:
+      - name: Prepare
+        run: |
+          platform=${{ matrix.platform }}
+          echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV     
+
+          # list all registries to push to and join all non-empty with comma
+          # https://unix.stackexchange.com/a/693165/116849
+          # https://stackoverflow.com/a/9429887/1469797
+          strings=("${{vars.DOCKERHUB_SLUG}}" "${{vars.GHCR_SLUG}}")
+          for i in ${!strings[@]}; do [[ -z ${strings[i]} ]] && unset strings[i]; done
+          joined_string=$(IFS=, ; echo "${strings[*]}")
+          echo "REGISTRIES_JOINED=$joined_string" >> $GITHUB_ENV 
+
       - name: Check out the repo
         uses: actions/checkout@v4
 
       - name: Set short git commit SHA
-        id: vars
+        id: appvars
         # https://dev.to/hectorleiva/github-actions-and-creating-a-short-sha-hash-8b7
         # short sha available under env.COMMIT_SHORT_SHA
         run: |
@@ -72,57 +80,149 @@ jobs:
           echo "COMMIT_SHORT_SHA=$calculatedSha" >> $GITHUB_ENV
           echo "COMMIT_BRANCH=$branchName" >> $GITHUB_ENV
 
-      - name: Log in to Docker Hub
+      - name: Get App Version
+        id: appversion
+        env:
+          # use release instead of tags once version is correctly parsed
+          #APP_VERSION: ${{ github.event.release.tag_name }}
+
+          # https://github.com/actions/runner/issues/409#issuecomment-752775072
+          # https://stackoverflow.com/a/69919067/1469797
+          APP_VERSION: ${{ contains(github.ref, 'refs/tags/') && github.ref_name || format('{0}-{1}', env.COMMIT_BRANCH, env.COMMIT_SHORT_SHA ) }}
+        run: |
+          echo appversion=$APP_VERSION >>${GITHUB_OUTPUT}
+
+      - name: Login to Docker Hub
+        if: ${{ github.event_name != 'pull_request' && vars.DOCKERHUB_SLUG != '' }}
         uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
-
+  
       - name: Login to GitHub Container Registry
+        if: ${{ github.event_name != 'pull_request' && vars.GHCR_SLUG != '' }}
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
       
-      - name: Extract metadata (tags, labels) for Docker
+      # metadata extract for docker labels/image names is done in merge job
+      
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      
+      # https://github.com/docker/build-push-action/issues/671#issuecomment-1619353328
+      # for caching
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          build-args: |
+            APP_BUILD_VERSION=${{steps.appversion.outputs.appversion}}
+          platforms: ${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          outputs: type=image,"name=${{ env.REGISTRIES_JOINED }}",push-by-digest=true,name-canonical=true,push=true
+          #cache-from: type=gha,scope=build-${{ env.PLATFORM_PAIR }}
+          #cache-to: type=gha,scope=build-${{ env.PLATFORM_PAIR }}
+      
+      - name: Export digest
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.build.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"          
+      
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: digests-${{ env.PLATFORM_PAIR }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge:
+    name: Merge OCI Images and Push
+    if: ${{ github.event_name != 'pull_request' && (vars.DOCKERHUB_SLUG != '' ||  vars.GHCR_SLUG != '') }}
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    needs:
+      - build
+      - test
+    steps:
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: /tmp/digests
+          pattern: digests-*
+          merge-multiple: true
+
+      - name: Login to Docker Hub
+        if: ${{ github.event_name != 'pull_request' && vars.DOCKERHUB_SLUG != '' }}
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+
+      - name: Login to GitHub Container Registry
+        if: ${{ github.event_name != 'pull_request' && vars.GHCR_SLUG != '' }}
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      
+      - name: Extract metadata (tags, labels)
         id: meta
         uses: docker/metadata-action@v5
         with:
           images: |
-            foxxmd/multi-scrobbler
-            ghcr.io/foxxmd/multi-scrobbler
+            ${{ vars.DOCKERHUB_SLUG }}
+            ${{ vars.GHCR_SLUG }}
           # generate Docker tags based on the following events/attributes
           # https://github.com/docker/metadata-action/issues/247#issuecomment-1511259674 for NOT is default branch, eventually
           tags: |
-            type=raw,value=latest,enable={{is_default_branch}},suffix=${{ matrix.suffix }}
-            type=ref,event=branch,enable=${{ !endsWith(github.ref, 'master') }},suffix=${{ matrix.suffix }}
-            type=semver,pattern={{version}},suffix=${{ matrix.suffix }}
-          flavor: |
-            latest=false
+            type=edge
 
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+            # push with branch name as tag if not master/main
+            type=ref,event=branch,enable=${{ !endsWith(github.ref, 'master') }}
+            
+            # tag non-prelease as latest -- has a higher priority than regular tag so it shows first in registries
+            type=match,pattern=\d.\d.\d$,priority=901
+            
+            # tag all semver (include pre-release)
+            type=semver,pattern={{version}}
+        #  flavor: |
+        #    latest=false
+          labels: |
+            org.opencontainers.image.title=Multi-Scrobbler
+            org.opencontainers.image.description=Scrobble from many sources to many clients
+            org.opencontainers.image.vendor=FoxxMD
+      
+      - name: Create manifest list and push dockerhub
+        if: ${{ vars.DOCKERHUB_SLUG != '' }}
+        working-directory: /tmp/digests
+        run: |
+          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf '${{ vars.DOCKERHUB_SLUG }}@sha256:%s ' *)
+      
+      - name: Create manifest list and push gchr
+        if: ${{ vars.GHCR_SLUG != '' }}
+        working-directory: /tmp/digests
+        run: |
+          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf '${{ vars.GHCR_SLUG }}@sha256:%s ' *)    
+      
+      - name: Inspect image dockerhub
+        if: ${{ vars.DOCKERHUB_SLUG != '' }}
+        run: |
+          docker buildx imagetools inspect ${{ vars.DOCKERHUB_SLUG }}:${{ steps.meta.outputs.version }}
 
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Build and push Docker image
-        env:
-          # use release instead of tags once version is correctly parsed
-          #APP_VERSION: ${{ github.event.release.tag_name }}
-
-        # https://github.com/actions/runner/issues/409#issuecomment-752775072
-        # https://stackoverflow.com/a/69919067/1469797
-          APP_VERSION: ${{ contains(github.ref, 'refs/tags/') && github.ref_name || format('{0}-{1}', env.COMMIT_BRANCH, env.COMMIT_SHORT_SHA ) }}
-        uses: docker/build-push-action@v5
-        with:
-          context: .
-          # https://github.com/docker/build-push-action/issues/1026#issue-2041857786
-          build-args: |
-            APP_BUILD_VERSION=${{env.APP_VERSION}}
-          file: ${{ matrix.dockerfile }}
-          push: ${{ !env.ACT}}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          platforms: ${{ matrix.platforms }}
+      - name: Inspect image ghcr
+        if: ${{ vars.GHCR_SLUG != '' }}
+        run: |
+            docker buildx imagetools inspect ${{ vars.GHCR_SLUG }}:${{ steps.meta.outputs.version }}   

.github/workflows/testAndSanity.yml

@@ -0,0 +1,65 @@
+name: Tests and Sanity Run
+
+on:
+  workflow_call:
+    inputs:
+      node-version:
+        description: "Node version"
+        required: false
+        default: '20.x'
+        type: string
+      ref:
+        description: "Ref to checkout"
+        required: false
+        type: string
+
+jobs:
+  test:
+    name: Tests / Build / Sanity Run
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ inputs.node-version }}
+          cache: 'npm'
+
+      - name: Install concurrently
+        run: npm install -g concurrently
+
+      - name: Install dev dependencies
+        run: npm run install:parallel
+
+      - name: Test Backend
+        run: npm run test
+
+      - name: Build
+        run: npm run build:parallel
+      
+        # remove modules that might include dev stuff
+        # so that in the next step we are sure that prod-only runs work correctly
+      - name: Install Prod Deps
+        run: |
+          rm -rf node_modules && \
+          rm -rf docsite/node_modules && \
+          NODE_ENV=production npm ci --omit=dev
+
+        # run app for 10 seconds as sanity check to see if it errors for any reason
+        # easy testcase for missing packages and init errors
+      - name: Sanity Run
+        run: |
+          set +e
+          export NODE_ENV=production
+          timeout --preserve-status 10s node node_modules/.bin/tsx src/backend/index.ts
+          exitcode="$?"
+          if [[ "$exitcode" -eq 143 ]] || [[ "$exitcode" -eq 137 ]]; then
+            echo "App stayed up long enough and exited with expected status"
+            exit 0
+          else
+            echo "App exited with unexpected code $exitcode"
+            exit "$exitcode"
+          fi

.gitignore

@@ -118,6 +118,7 @@ dist
 .pnp.*
 
 config/*.json
+config/yti-*
 *.txt
 .idea/
 
@@ -133,3 +134,5 @@ flatpak/generated-sources.json
 build
 !setupProxy.js
 **/generated-sources.*
+.github/act/out
+tmp-*

.lnav.config.json

@@ -0,0 +1,28 @@
+{
+    "$schema": "https://lnav.org/schemas/format-v1.schema.json",
+    "error_log": {
+        "title": "Multi-Scrobbler Log",
+        "description": "Logs from Multi Scrobbler",
+        "regex": {
+            "std": {
+                "pattern": "^\\[(?<timestamp>\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}(?:\\.\\d{3})?)(?:.*?)\\] (?<level>[A-Z]*)  : (?<body>.*)"
+            }
+        },
+        "level-field": "level",
+        "level": {
+            "info": "^(?i)(?:info)$",
+            "debug": "^(?i)(?:debug)$",
+            "error": "^(?i)(error)$",
+            "warning": "^(?i)(warn)$",
+            "trace": "^(?i)verbose$",
+            "critical": "^(?i)(?:crit|Cr)$",
+            "fatal": "^(?i)(?:alert|fatal|panic|Al|Em)$"
+        },
+        "sample": [
+            {
+                "line": "[2024-12-26 01:58:48.261 -0500] DEBUG  : [App] [Sources] [Jellyfin - unnamed] Last activity was at 01:58:48-05:00 | Next check in 10.00s | No new tracks discovered",
+                "level": "debug"
+            }
+        ]
+    }
+}

.mocharc.json

@@ -1,5 +1,7 @@
 {
   "reporter": "dot",
   "extension": "ts",
-  "import": "tsx/esm"
+  "import": "tsx/esm",
+  "spec": "./src/backend/tests/**/*.test.ts",
+  "exit": true
 }

.vscode/launch.json

@@ -0,0 +1,104 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "dev",
+            "type": "node",
+            "request": "launch",
+            // Debug app in VSCode
+            "program": "${workspaceFolder}/src/backend/index.ts",
+            "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
+            "console": "integratedTerminal",
+            "internalConsoleOptions": "neverOpen",
+            "skipFiles": [
+                "<node_internals>/**",
+                // Ignore all dependencies (optional)
+                "${workspaceFolder}/node_modules/**",
+            ],
+        },
+        {
+            "name": "tsx",
+            "type": "node",
+            "request": "launch",
+            // Debug current file in VSCode
+            "program": "${file}",
+            "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
+            "console": "integratedTerminal",
+            "internalConsoleOptions": "neverOpen",
+            "skipFiles": [
+                "<node_internals>/**",
+                // Ignore all dependencies (optional)
+                "${workspaceFolder}/node_modules/**",
+            ],
+        },
+        {
+            "name": "schema",
+            "type": "node",
+            "request": "launch",
+            // Debug app in VSCode
+            "program": "${workspaceFolder}/src/backend/utils/SchemaStaticUtil.ts",
+            "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
+            "console": "integratedTerminal",
+            "internalConsoleOptions": "neverOpen",
+            "skipFiles": [
+                "<node_internals>/**",
+                // Ignore all dependencies (optional)
+                //"${workspaceFolder}/node_modules/**",
+            ],
+            "resolveSourceMapLocations": [
+                "${workspaceFolder}/src/**/*",
+                "${workspaceFolder}/node_modules/**/*"
+            ]
+        },
+        {
+            "args": [
+                "-u",
+                "bdd",
+                "--timeout",
+                "999999",
+                "--reporter",
+                "spec",
+                "--colors",
+                "--config", 
+                "${workspaceRoot}/.mocharc.json",
+                "--recursive",
+                "${workspaceFolder}/src/backend/tests/**/*.test.ts"
+            ],
+            "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
+            "internalConsoleOptions": "openOnSessionStart",
+            "name": "Mocha Tests",
+            "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
+            "request": "launch",
+            "skipFiles": [
+                "<node_internals>/**",
+                // Ignore all dependencies (optional)
+                "${workspaceFolder}/node_modules/**",
+            ],
+            "type": "node"
+        },
+        {
+            "args": [
+                "-u",
+                "bdd",
+                "--timeout",
+                "999999",
+                "--reporter",
+                "spec",
+                "--colors",
+                "--config", "${workspaceRoot}/.mocharc.json",
+                "${file}"
+            ],
+            "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/tsx",
+            "internalConsoleOptions": "openOnSessionStart",
+            "name": "Mocha Test on File",
+            "program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
+            "request": "launch",
+            "skipFiles": [
+                "<node_internals>/**",
+                // Ignore all dependencies (optional)
+                "${workspaceFolder}/node_modules/**",
+            ],
+            "type": "node"
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "mochaExplorer.require": "tsx/esm",
+    "mochaExplorer.timeout": 1200000,
+    "mochaExplorer.exit": true
+}

.vscode/tasks.json

@@ -0,0 +1,37 @@
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"type": "typescript",
+			"tsconfig": "src/backend/tsconfig.json",
+			"problemMatcher": [
+				"$tsc"
+			],
+			"group": {
+				"kind": "build",
+				"isDefault": true
+			},
+			"label": "tsc: build - src/backend/tsconfig.json"
+		},
+		{
+			"type": "shell",
+			"label": "compose-up-dev",
+			"command": "docker-compose -f docker-compose.dev.yml up",
+			"presentation": {
+			  "reveal": "always",
+			  "panel": "new"
+			},
+			"problemMatcher": []
+		  },
+		  {
+			"type": "shell",
+			"label": "compose-build-dev",
+			"command": "docker-compose -f docker-compose.dev.yml build",
+			"presentation": {
+				"reveal": "always",
+				"panel": "new"
+			  },
+			  "problemMatcher": []
+		  }
+	]
+}

CONTRIBUTING.md

@@ -2,7 +2,6 @@
 
 Please follow these guidelines when contributing code to this repository:
 
-* The PR **must be for the [`develop` branch.](https://github.com/FoxxMD/multi-scrobbler/tree/develop)** The `master` branch is for releases only.
 * Use [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/#summary) format when creating commits.
-* Preferably, please use a [feature branch](https://stackoverflow.com/a/39586780/1469797) instead of committing directly to `develop`.
+* Preferably, please use a [feature branch](https://stackoverflow.com/a/39586780/1469797) instead of committing directly to `master`.
 * Ensure that if your code is covered by [an existing test](./src/backend/tests) that you have updated the test accordingly

Dockerfile

@@ -1,7 +1,7 @@
-FROM ghcr.io/linuxserver/baseimage-debian:bookworm as base
+FROM ghcr.io/linuxserver/baseimage-debian:bookworm AS base
 
 ENV TZ=Etc/GMT
-ENV NODE_VERSION 20.11.1
+ENV NODE_VERSION=20.18.1
 
 # borrowing openssl header removal trick from offical docker-node
 # https://github.com/nodejs/docker-node/blob/main/18/bookworm-slim/Dockerfile#L8
@@ -49,6 +49,8 @@ RUN \
 
 RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
 
+RUN npm install -g concurrently
+
 ARG data_dir=/config
 VOLUME $data_dir
 ENV CONFIG_DIR=$data_dir
@@ -57,10 +59,11 @@ COPY docker/root /
 
 WORKDIR /app
 
-FROM base as build
+FROM base AS build
 
 COPY --chown=abc:abc package*.json tsconfig.json ./
 COPY --chown=abc:abc patches ./patches
+COPY --chown=abc:abc docsite/package*.json tsconfig.json ./docsite/
 
 # for debugging, so the build fails faster when timing out (arm64)
 #RUN npm config set fetch-retries 1 && \
@@ -74,21 +77,20 @@ COPY --chown=abc:abc patches ./patches
 
 # This FAILED for node < 20 when building arm64 but not amd64 (and alpine-based Dockerfile has no issues building arm64)
 # see https://github.com/FoxxMD/multi-scrobbler/issues/126
-RUN npm ci \
-    --verbose \
-#   --no-audit \
-    && chown -R root:root node_modules
+RUN npm run install:parallel \
+    && chown -R root:root node_modules \
+    && chown -R root:root docsite/node_modules
 
 COPY --chown=abc:abc . /app
 
 # need to set before build so server/client build is optimized and has constants (if needed)
 ENV NODE_ENV=production
 
-RUN npm run docs:install && npm run build && rm -rf node_modules && rm -rf docsite/node_modules
+RUN npm run build:parallel && rm -rf node_modules && rm -rf docsite/node_modules
 
-FROM base as app
+FROM base AS app
 
-COPY --chown=abc:abc package*.json ./
+COPY --chown=abc:abc *.json *.js *.ts index.html ./
 COPY --chown=abc:abc patches ./patches
 COPY --from=build --chown=abc:abc /app/dist /app/dist
 COPY --from=build --chown=abc:abc /app/src /app/src
@@ -103,11 +105,11 @@ ENV IS_DOCKER=true
 ARG APP_BUILD_VERSION
 ENV APP_VERSION=$APP_BUILD_VERSION
 
-RUN npm ci --omit=dev \
+RUN npm ci --omit=dev --no-audit \
     && npm cache clean --force \
     && chown -R abc:abc node_modules \
-    && rm -rf node_modules/@types \
-              /root/.cache
+    && rm -rf /root/.cache
+
 
 ARG webPort=9078
 ENV PORT=$webPort

README.md

@@ -13,20 +13,27 @@ A javascript app to scrobble music you listened to, to [Maloja](https://github.c
 
 * Supports scrobbling from many **Sources**
   * [Spotify](https://foxxmd.github.io/multi-scrobbler/docs/configuration#spotify)
-  * [Plex](https://foxxmd.github.io/multi-scrobbler/docs/configuration#plex) or [Tautulli](https://foxxmd.github.io/multi-scrobbler/docs/configuration#tautulli)
+  * [Plex](https://foxxmd.github.io/multi-scrobbler/docs/configuration#plex) or [~~Tautulli~~](https://foxxmd.github.io/multi-scrobbler/docs/configuration#tautulli)
   * [Subsonic-compatible APIs](https://foxxmd.github.io/multi-scrobbler/docs/configuration#subsonic) (like [Airsonic](https://airsonic.github.io/) and [Navidrome](https://www.navidrome.org/))
   * [Jellyfin](https://foxxmd.github.io/multi-scrobbler/docs/configuration#jellyfin)
   * [WebScrobbler](https://foxxmd.github.io/multi-scrobbler/docs/configuration#webscrobbler)
   * [Youtube Music](https://foxxmd.github.io/multi-scrobbler/docs/configuration#youtube-music)
   * [Last.fm](https://foxxmd.github.io/multi-scrobbler/docs/configuration#lastfm-source)
+  * [Last.fm (Endpoint)](https://foxxmd.github.io/multi-scrobbler/docs/configuration#lastfm-endpoint)
   * [ListenBrainz](https://foxxmd.github.io/multi-scrobbler/docs/configuration#listenbrainz-source)
-  * [Deezer](https://foxxmd.github.io/multi-scrobbler/docs/configuration#deezer)
+  * [ListenBrainz (Endpoint)](https://foxxmd.github.io/multi-scrobbler/docs/configuration#listenbrainz-endpoint)
+  * [~~Deezer~~](https://foxxmd.github.io/multi-scrobbler/docs/configuration#deezer)
   * [MPRIS (Linux Desktop)](https://foxxmd.github.io/multi-scrobbler/docs/configuration#mpris)
   * [Mopidy](https://foxxmd.github.io/multi-scrobbler/docs/configuration#mopidy)
   * [JRiver](https://foxxmd.github.io/multi-scrobbler/docs/configuration#jriver)
   * [Kodi](https://foxxmd.github.io/multi-scrobbler/docs/configuration#kodi)
   * [Google Cast (Chromecast)](https://foxxmd.github.io/multi-scrobbler/docs/configuration#google-cast-chromecast)
   * [Musikcube](https://foxxmd.github.io/multi-scrobbler/docs/configuration#muikcube)
+  * [MPD (Music Player Daemon)](https://foxxmd.github.io/multi-scrobbler/docs/configuration#mpd-music-player-daemon)
+  * [VLC](https://foxxmd.github.io/multi-scrobbler/docs/configuration#vlc)
+  * [Azuracast](https://foxxmd.github.io/multi-scrobbler/docs/configuration#azuracast)
+  * [Yamaha MusicCast](https://foxxmd.github.io/multi-scrobbler/docs/configuration#yamaha-musiccast)
+  * [Icecast](https://foxxmd.github.io/multi-scrobbler/docs/configuration#icecast)
 * Supports scrobbling to many **Clients**
   * [Maloja](https://foxxmd.github.io/multi-scrobbler/docs/configuration#maloja)
   * [Last.fm](https://foxxmd.github.io/multi-scrobbler/docs/configuration#lastfm)
@@ -37,7 +44,8 @@ A javascript app to scrobble music you listened to, to [Maloja](https://github.c
 * Graceful network and client failure handling (queued scrobbles that auto-retry)
 * Smart handling of credentials (persistent, authorization through app)
 * Easy configuration through ENVs or JSON
-* Install using [Docker images for x86/ARM](https://foxxmd.github.io/multi-scrobbler/docs/installation#docker#docker), [flatpak](https://foxxmd.github.io/multi-scrobbler/docs/installation#docker#flatpak), or [locally with NodeJS](https://foxxmd.github.io/multi-scrobbler/docs/installation#docker#nodejs)
+* Modify data before scrobbling with [regular expression or search patterns](https://foxxmd.github.io/multi-scrobbler/docs/configuration/transforms)
+* Install using [Docker images for x86/ARM](https://foxxmd.github.io/multi-scrobbler/docs/installation#docker) or [locally with NodeJS](https://foxxmd.github.io/multi-scrobbler/docs/installation#nodejs)
 
 [**Quick Start Guide**](https://foxxmd.github.io/multi-scrobbler/docs/quickstart)
 

config/azuracast.json.example

@@ -0,0 +1,13 @@
+[
+  {
+    "type": "azuracast",
+    "enable": true,
+    "name": "azura",
+    "data": {
+      "url": "ws://192.168.0.101",
+      "station": "my-station-name",
+      "monitorWhenLive": true,
+      "monitorWhenListeners": 1
+    }
+  }
+]

config/endpointlfm.json.example

@@ -0,0 +1,9 @@
+[
+  {
+    "name": "myLfm",
+    "enable": true,
+    "data": {
+      "slug": "mySlug"
+    }
+  }
+]

config/endpointlz.json.example

@@ -0,0 +1,9 @@
+[
+  {
+    "name": "myLz",
+    "enable": true,
+    "data": {
+      "token": "myToken"
+    }
+  }
+]

config/icecast.json.example

@@ -0,0 +1,10 @@
+[
+    {
+      "name": "myIcy",
+      "enable": true,
+      "data": {
+        "url": "http://myIcecast.com/radio"
+      }
+    }
+  ]
+  

config/jellyfin.json.example

@@ -4,12 +4,23 @@
     "enable": true,
     "clients": [],
     "data": {
-      "users": ["FoxxMD"],
-      "servers": ["myServer","anotherServer"]
+      "url": "http://localhost:8096",
+      "user": "FoxxMD",
+      "apiKey": "c9fae8756fbf481ebd9c5bb56bd6540c",
+
+      // everything below is optional
+      "usersAllow": ["FoxxMD","SomeOtherUser"],
+      "usersBlock": ["AnotherUser"],
+      "devicesAllow": ["firefox"],
+      "devicesBlock": ["google-home"],
+      "librariesAllow": ["GoodMusic"],
+      "librariesBlock": ["BadMusic"],
+      "additionalAllowedLibraryTypes": ["musicvideos"],
+      "allowUnknown": false,
     },
     "options": {
-      "logPayload": false,
-      "logFilterFailure": "warn"
+      "logPayload": true,
+      "logFilterFailure": "debug"
     }
   }
 ]

config/lastfm.json.example

@@ -1,6 +1,6 @@
 [
   {
-    "name": "myLastFm",
+    "name": "myLastFmClient",
     "enable": true,
     "configureAs": "client",
     "data": {
@@ -8,5 +8,15 @@
       "secret": "ec42e09d5ae0ee0f0816ca151008412a",
       "redirectUri": "http://localhost:9078/lastfm/callback"
     }
+  },
+  {
+    "name": "myLastFmSource",
+    "enable": true,
+    "configureAs": "source",
+    "data": {
+      "apiKey": "a89cba1569901a0671d5a9875fed4be1",
+      "secret": "ec42e09d5ae0ee0f0816ca151008412a",
+      "redirectUri": "http://localhost:9078/lastfm/callback"
+    }
   }
 ]

config/listenbrainz.json.example

@@ -1,11 +1,20 @@
 [
   {
-    "name": "brainz",
+    "name": "brainzClient",
     "enable": true,
     "configureAs": "client",
     "data": {
       "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
       "username": "FoxxMD"
     }
+  },
+  {
+    "name": "brainzSource",
+    "enable": true,
+    "configureAs": "source",
+    "data": {
+      "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
+      "username": "FoxxMD"
+    }
   }
 ]

config/mpd.json.example

@@ -0,0 +1,13 @@
+[
+  {
+    "enable": true,
+    "name": "MyMPD",
+    "data": {
+      "url": "192.168.0.100:6600",
+      "password": "MY_PASSWORD"
+    },
+    "options": {
+      "disableDiscovery": false
+    }
+  }
+]

config/musiccast.json.example

@@ -0,0 +1,9 @@
+[
+  {
+    "name": "myYamaha",
+    "enable": true,
+    "data": {
+      "url": "192.168.0.101"
+    }
+  }
+]

config/musikcube.json.example

@@ -4,6 +4,7 @@
     "enable": true,
     "name": "musikcube",
     "data": {
+      "url": "ws://localhost:7905",
       "password": "MY_PASSWORD"
     }
   }

config/plex.json.example

@@ -1,15 +1,21 @@
 [
   {
-    "name": "MyPlex",
+    "name": "MyPlexApi",
     "enable": true,
     "clients": [],
     "data": {
-      "user": ["username@gmail.com","anotherUser@gmail.com"],
-      "libraries": ["music","my podcasts"],
-      "servers": ["myServer","anotherServer"],
-      "options": {
-        "logFilterFailure": "warn"
+      "token": "1234",
+      "url": "http://192.168.0.120:32400",
+      "usersAllow": ["FoxxMD","SomeOtherUser"],
+      "usersBlock": ["AnotherUser"],
+      "devicesAllow": ["firefox"],
+      "devicesBlock": ["google-home"],
+      "librariesAllow": ["GoodMusic"],
+      "librariesBlock": ["BadMusic"]
+    },
+    "options": {
+      "logPayload": true,
+      "logFilterFailure": "debug"
       }
-    }
   }
 ]

config/plex.webhook.json.example

@@ -0,0 +1,17 @@
+[
+  // DEPRECATED, use API Source instead
+  // rename files to plex.json to use
+  {
+    "name": "MyPlex",
+    "enable": true,
+    "clients": [],
+    "data": {
+      "user": ["username@gmail.com","anotherUser@gmail.com"],
+      "libraries": ["music","my podcasts"],
+      "servers": ["myServer","anotherServer"],
+      "options": {
+        "logFilterFailure": "warn"
+      }
+    }
+  }
+]

config/vlc.json.example

@@ -0,0 +1,10 @@
+[
+  {
+    "enable": true,
+    "name": "MyVlc",
+    "data": {
+      "url": "localhost:8080",
+      "password": "changeme"
+    }
+  }
+]

config/webscrobbler.json.example

@@ -2,7 +2,7 @@
   {
     "name": "MyWebScrobbler",
     "data": {
-      "slug": null,
+      "slug": "MyOptionalSlug",
       "whitelist": [],
       "blacklist": []
     }

config/ytmusic.json.example

@@ -4,8 +4,16 @@
     "enable": true,
     "clients": [],
     "data": {
-      "cookie": "VISITOR_INFO1_LIVE=jMDXz2_L8rY; __Secure-3PAPISID=3AxsXpSXGqOInSDn1jEKn; DEVICE_INFO=ChxOekU0TmTBpjek5EWZ0G; YSC=7gZdl3Zdl3; SID=TwhNsaZRXYTAtXxzGyu6rZdpg2HvGROeW8J4Ym_FhkhoZMUYEQ.; __Secure-1PSID=TwhNOsaZRXYTyRBe4rxAtXRIKsIEtk_Qot2VLBNfHQrQ.; __Secure-3PSID=ZRXYTAtXRIKsIEtk_Qot2yRBerZdpg2HvvZRXYTAtXRIKsIEtk_Qot2yRBerkuZICFQ.; HSID=A1UMmELW79; SSID=AKhomOs; APISID=IlHHmuzkPdQzZZDhHn3; SAPISID=3AxsXpy0u75Qb/n1jEKn; __Secure-1PAPISID=3AxsXpQb/AkSDn1jEKn; LOGIN_INFO=AFmP6vFpyVCZZAIgDwbkhWMBBhluaIWAPP:QUQ314UW5NWMjNmd2ZUJnYnJsakdIMjZoaE5zVVMjNmd2ZZUiHRlb3ZlV3ZIcUVyRVIMjNmdjNmd2ZZUivYlNqX2ZNZUiHdUNFNFdaYmJIW1NkJRX3hqdlU2YnFESkFuSS1uTldnZVRmLXNjWFc5OUJuR3dTd3JsZGZYa2EtZFQ2a0k2Ry1KQQ==; PREF=volume=26; SIDCC=AFvI_94PxXwls-ndqpGfPgFX3FWj80y_94PxXwls-ndqfSh15sP; __Secure-1PSIDCC=AFvIBnUbRr96I96UCIp2U4T8HRVk2B0HfKzhzxwsiP; __Secure-3PSIDCC=AFvIB3bINuUN0ETDR9gO91wpwWIVmpGki3BxT3bINuUN0ETDR9gO91wCH",
-      "authUser": "0"
+      "cookie": "__Secure-1PSIDTS=sidts-CjEB3EgAEvCd-......",
+      // either cookie or id/secret needs to be provided
+      "clientId": "891098404....apps.googleusercontent.com",
+      "clientSecret": "GOCS..."
+
+      // optional
+      //"redirectUri": "http://my.custom.tld/api/ytmusic/callback?name=MyYTMusic"
+    },
+    "options": {
+      "logDiff": true
     }
   }
 ]

docker-compose.dev.yml

@@ -0,0 +1,29 @@
+version: '3.7'
+
+services:
+  multi-scrobbler:
+    build:
+      context: .
+    env_file:
+      - path: ./.env
+        required: false
+    #environment:
+      #- TZ=Etc/GMT # Specify timezone from TZ Database name found here https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+      #- SPOTIFY_CLIENT_ID=
+      #- SPOTIFY_CLIENT_SECRET=
+      #- SPOTIFY_REDIRECT_URI=http://multi-scrobbler-host-IP:9078/callback ## Need to be whitelisted in Spotify dashboard and is used for creating the connection first time
+      #- MALOJA_URL=http://maloja:42010
+      #- MALOJA_API_KEY=
+      #- PUID=1000 # required if running docker on linux host, see main README Docker setup instructions
+      #- PGID=1000 # required if running docker on linux host, see main README Docker setup instructions
+
+      # set if using a source/client with redirect URI that you have not explicitly set and MS is NOT running on the same machine that you will view the dashboard from
+      # EX: You will view MS dashboard at 'http://192.168.0.101:9078' -> set BASE_URL=http://192.168.0.101:9078
+      #- BASE_URL=http://MyHostIP:9078
+    volumes:
+      - "./config:/config"
+    #networks:
+    #  - (optional to add container to the same bridge network that maloja is inside to be able to use docker internal networking & dns to resolve and connect to maloja URL via http://maloja:port)
+    ports:
+      - 9078:9078 # first port is the HOST port multi-scrobbler will serve UI and API on
+    restart: unless-stopped

docker-compose.yml

@@ -1,5 +1,3 @@
-version: '3.7'
-
 services:
   multi-scrobbler:
     image: foxxmd/multi-scrobbler
@@ -18,7 +16,7 @@ services:
       # EX: You will view MS dashboard at 'http://192.168.0.101:9078' -> set BASE_URL=http://192.168.0.101:9078
       #- BASE_URL=http://MyHostIP:9078
     volumes:
-      - /path_on_host/multi-scrobbler-config:/config
+      - "./config:/config"
     #networks:
     #  - (optional to add container to the same bridge network that maloja is inside to be able to use docker internal networking & dns to resolve and connect to maloja URL via http://maloja:port)
     ports:

docsite/babel.config.js

@@ -1,3 +0,0 @@
-module.exports = {
-  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
-};

docsite/docs/FAQ.md

@@ -5,7 +5,7 @@ toc_max_heading_level: 5
 
 ## Connection Issues
 
-### Plex/Tautulli/Jellyfin/Webscrobbler don't connect
+### Plex (Webhook)/Tautulli/Jellyfin(Webhook)/Webscrobbler don't connect
 
 These sources are **ingress-based** which means that multi-scrobbler waits for the Plex/Tautulli/Jellyfin server (or Webscrobbler extension) to contact multi-scrobbler, as opposed to multi-scrobbler contacting them.
 
@@ -30,12 +30,7 @@ Check or try all these steps before submitting an issue:
 
 ##### Turn on Debug Logging
 
-First, turn on **debug** logging for multi-scrobbler by setting the environmental variable `LOG_LEVEL=debug`:
-
-* using node `LOG_LEVEL=debug ... node src/index.js`
-* using docker `docker run -e LOG_LEVEL=debug ... foxxmd/multi-scrobbler`
-
-Check the output for any additional information.
+First, turn on **debug** logging for multi-scrobbler by setting the environmental variable `DEBUG_MODE=true`. Then, check the output for any additional information.
 
 ##### Check Host name and URL
 
@@ -67,7 +62,7 @@ Administration -> Dashboard -> Advanced -> Logs
 
 See [Debugging the extension](https://github.com/web-scrobbler/web-scrobbler/wiki/Debug-the-extension) to get logs which should have information about failed requests.
 
-### Jellyfin has warnings about undefined or missing data
+### Jellyfin (Webhook) has warnings about undefined or missing data
 
 Make sure you have 
 * [Configured the webhook plugin correctly](configuration/configuration.mdx#jellyfin)
@@ -75,26 +70,11 @@ Make sure you have
 
 multi-scrobbler is known to work on Jellyfin `10.8.9` with Webhook version `11.0.0.0`.
 
-You can verify the payload sent from the webhook by modifying your jellyfin configuration to include `logPayload: true` which will output the raw payload to DEBUG level logging:
-
-```json
-[
-  {
-    "name": "MyJellyfin",
-    "clients": [],
-    "data": {
-      "users": ["FoxxMD"]
-    },
-    "options": {
-      "logPayload": true
-    }
-  }
-]
-```
+You can verify the payload sent from the webhook by enabling Debug Mode with the env `DEBUG_MODE=true` which will output the raw payload to DEBUG level logging.
 
 If your issue persists and you open an Issue for it please include the raw payload logs in your report.
 
-### Jellyfin has warnings about missing headers
+### Jellyfin (Webhook) has warnings about missing headers
 
 If you experience issues trying to scrobble with Jellyfin and find this in your MS logs
 
@@ -124,6 +104,32 @@ If multi-scrobbler is not running on the same machine your browser is on then th
 
 EX `http://localhost:9078/lastfm/callback` -> `http://192.168.0.220:9078/lastfm/callback`
 
+### Deezer is not working
+
+Deezer has discontinued support for their API and the Deezer Source is now [**deprecated.**](configuration/configuration.mdx#deezer) See [this issue for more discussion.](https://github.com/FoxxMD/multi-scrobbler/issues/175#issuecomment-2296776625)
+
+### Youtube Music fails after some time
+
+If you see errors in multi-scrobbler for YTM that contain **401** or **403** like
+
+```
+Error: Could not send the specified request to browse. Status code: 401
+```
+
+then YTM has invalidated your authentication.
+
+First, ensure you are NOT using [YoutubeTV authentication.](configuration/configuration.mdx?ytmAuth=ytt#youtube-music) If you completed authentication by entering a "User Code" you are using YoutubeTV which has stopped working. You should reauthenticate using **Cookies** or **Custom OAuth.**
+
+#### When using OAuth Client Authentication
+
+Refresh your authentication by using the **(Re)authenticate** link from MS's web dashboard.
+
+#### When using Cookies Authentication
+
+The library MS uses relies on scraping the YTM site by using cookies from your actual browser to pretend it is a browser. It does its best to keep these up to date but since this is not an official way to access the service YTM may invalidate your access _to the authenticated session_ at any time. How this is triggered is unknown and not something multi-scrobbler can control. You can help limit the chance of your session being invalidated by [getting the cookie from an Incognito/Private Session](https://github.com/LuanRT/YouTube.js/issues/803#issuecomment-2504032666) and then immediately closing the browser afterwards.
+
+To re-authenticate MS [follow the YTM instructions to retrieve a new set of cookies for multi-scrobbler](configuration/configuration.mdx?ytmAuth=cookie#youtube-music) and then restart MS to potentially resolve the problem.
+
 ## Configuration Issues
 
 ### Config could not be parsed
@@ -146,10 +152,12 @@ This is a limitation of the [Last.fm API](https://www.last.fm/api/show/track.scr
 
 Multi-scrobbler works the same was the official Spotify-Last.fm integration works -- it only scrobbles the **first** artist on a multi-artist track.
 
-### Jellyfin does not scrobble tracks with multiple artists correctly
+### Jellyfin (Webhook) does not scrobble tracks with multiple artists correctly
 
 This is a limitation caused by the [Jellyfin webhook plugin](https://github.com/FoxxMD/multi-scrobbler/issues/70#issuecomment-1443804712) only sending the first artist to multi-scrobbler. This issues needs to be [fixed upstream on the Jellyfin webhook repository.](https://github.com/jellyfin/jellyfin-plugin-webhook/issues/166)
 
+You can avoid this entirely by using the newer [Jellyfin API Source](configuration/configuration.mdx#jellyfin) which correctly handles multiple artists.
+
 ### Google Cast track information is missing/incorrect or MS player has weird times
 
 The Google Cast integration relies on a few common fields in the data it receives from your casting device. Every platform that can cast (Spotify, Pandora, etc...) *should* use these fields the same but there are slight differences between their implementations that may confuse multi-scrobbler. Specific platforms may also return more information in non-common fields that are undocumented.
@@ -173,3 +181,93 @@ My Artist - Example Track has 'movie' media type so will not track
 ```
 
 Refer to [Force Media Tracking](configuration/configuration.mdx#forcing-media-tracking) section to fix this
+
+### VLC is not scrobbling fields correctly
+
+Before reporting an issue turn on metadata logging in the MS VLC configuration, [see the VLC documentation.](configuration/configuration.mdx#vlc-information-reporting)
+
+### Youtube Music misses or duplicates scrobbles
+
+<details>
+
+  <summary>How MS detects YTM history</summary>
+
+  In order for multi-scrobbler to accurately determine if a song has been scrobbled it needs **a source of truth.** For YTM this is a "history" list scraped from the YTM website. Unfortunately, the data in this list can be (often) inconsistent which makes it hard for multi-scrobbler to "trust" that it is correct and determine when/if new scrobbles occur. This inconsistency is not something multi-scrobbler can control -- it is a side-effect of having to use an unofficial method to access YTM (scraping).
+
+  To compensate for this multi-scrobbler resets when it considers this list the "source of truth" based on if the list changes in an inconsistent way between consecutive checks. New scrobbles can only be detected when this list is "OK" as a source of truth for N+1 checks. Therefore, any new tracks that appear when the list is inconsistent will be ignored.
+
+  Duplicate scrobbles can also occur if the change between two checks is technically consistent. For instance, if you listen to a track twice in some period, separated by other music, YTM will sometimes "remove" the track from the earlier time (further down in your history) and "re-add" it at the top of the history.
+
+</details>
+
+#### Reporting YTM scrobble issues
+
+If you experience scrobble detection issues you can help improve MS's YTM heureistic by providing thorough feedback as [an issue.](https://github.com/FoxxMD/multi-scrobbler/issues/new?assignees=&labels=bug&projects=&template=01-bug-report.yml&title=bug%3A+) **Please do the following to provide the most useful report:**
+
+##### Turn on Change Detection
+
+In your YTM configuration (`ytmusic.json`) add `logDiff` under `options` like this:
+
+
+```json
+{
+    "type": "ytmusic",
+    "name": "MyYTM",
+    "data": { ... },
+    "options": {
+        "logDiff": true
+    }
+}
+```
+
+or set either ENVs:
+
+* `YTM_LOG_DIFF=true`
+* [`DEBUG_MODE=true`](configuration/configuration.mdx?#debug-mode)
+
+This will cause MS to log YTM history changes similar to this:
+
+```
+[Ytmusic - MyYTM] Changes from last seen list:
+1. (tuhe1CpHRxY) KNOWER - I’m The President --- undefined => Moved -  Originally at 6
+2. (Mtg8V6Xa2nc) Vulfpeck - Romanian Drinking Song --- Schvitz => Moved -  Originally at 1
+3. (rxbCaiyYSXM) Nightmares On Wax - You Wish --- In A Space Outta Sound => Moved -  Originally at 2
+4. (tMt_YXr90AM) Gorillaz - O Green World --- undefined => Moved -  Originally at 3
+...
+```
+
+Which are essential to troubleshooting this behavior.
+
+
+##### Turn on File Logging
+
+Optionally, if your logs are busy due to many other sources, you can log **only** YTM logs to a file. Turn this on with the `logToFile` config option:
+
+```json
+{
+    "type": "ytmusic",
+    "name": "MyYTM",
+    "data": { ... },
+    "options": {
+        "logDiff": true,
+        "logToFile": true
+    }
+}
+```
+
+This will cause MS to write YTM logs to a file in your `logs` folder named `ytmusic-MyYTM.log` (based on your source name).
+
+##### Provide Detail and Context
+
+Provide a detailed account of how you were using YTM when the issue occurred, including things like:
+
+* the platform listening on (desktop, mobile, 3rd party client, etc...)
+* any changes in platform
+  * > I switched from desktop to listening on my phone...
+* how you were listening to music
+  * > I was playing an album start to finish
+  * > I listened to two songs in a row, then browsed for a new song in library by artist, then went back to a song in the queue...
+
+Explain the expected behavior (it should have scrobbled songs x, y, then z) and what actually happened (it scrobbled songs x, then y, then x again, then z)
+
+Provide ALL logs from the time when the issue occurred including logs from BEFORE (ideally 2-3 minutes of logs) and AFTER the issue.

docsite/docs/configuration/kitchensink.md

@@ -69,7 +69,9 @@ Scenario:
       "name": "fredPlex",
       "clients": ["fredMaloja"],
       "data": {
-        "user": ["fred@email.com"]
+        "token": "JtRnwQWD__XMJF8sT3jc",
+        "url": "192.168.0.233:32400",
+        "usersallow": ["fredUser"]
       }
     },
     {
@@ -77,8 +79,10 @@ Scenario:
       "name": "maryPlex",
       "clients": ["maryMaloja"],
       "data": {
-        "user": ["mary@email.com"], // still need to specify mary as user so not all users who play from 'podcasts' get scrobbled
-        "libraries": ["podcasts"]
+        "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"]
       }
     },
     {
@@ -86,7 +90,9 @@ Scenario:
       "name": "partyPlex",
       // omitting clients (or making it empty) will make this Source scrobble to all Clients
       "data": {
-        "libraries": ["party"],
+        "token": "JtRnwQWD__XMJF8sT3jc",
+        "url": "192.168.0.233:32400",
+        "librariesAllow": ["party"]
       }
     },
     {
@@ -94,7 +100,10 @@ Scenario:
       "name": "FredJelly",
       // omitting clients (or making it empty) will make this Source scrobble to all Clients
       "data": {
-        "user": ["fred@email.com"]
+        "url": "http://localhost:8096",
+        "user": "FoxxMD",
+        "apiKey": "c9fae8756fbf481ebd9c5bb56bd6540c",
+        "usersAllow": ["fredUser"]
       }
     },
     {
@@ -113,7 +122,6 @@ Scenario:
       "clients": ["foxxMaloja"],
       "data": {
         "cookie": "__Secure-3PAPISID=3AxsXpy0MKGu75Qb/AkISXGqOnSDn1jEKn; DEVICE_INFO=ChxOekU0Tmpjek5EWTBPRGd3TlRBMk16QXpNdz09EJbS8Z0GGJbS8Z0G; ...",
-        "authUser": 1
       }
     },
   ],
@@ -195,21 +203,27 @@ Scenario:
     "name": "fredPlex",
     "clients": ["fredMaloja"],
     "data": {
-      "user": ["fred@email.com"]
+      "token": "JtRnwQWD__XMJF8sT3jc",
+      "url": "192.168.0.233:32400",
+      "usersallow": ["fredUser"]
     }
   },
   {
     "name": "maryPlex",
     "clients": ["maryMaloja"],
     "data": {
-      "user": ["mary@email.com"],
-      "libraries": ["podcasts"]
+      "token": "JtRnwQWD__XMJF8sT3jc",
+      "url": "192.168.0.233:32400",
+      "usersallow": ["maryUser"],
+      "librariesAllow": ["podcasts"]
     }
   },
   {
     "name": "partyPlex",
     "data": {
-      "libraries": ["party"]
+      "token": "JtRnwQWD__XMJF8sT3jc",
+      "url": "192.168.0.233:32400",
+      "librariesAllow": ["party"]
     }
   }
 ]
@@ -220,7 +234,10 @@ Scenario:
   {
     "name": "FredJelly",
     "data": {
-      "user": ["fred@email.com"]
+      "url": "http://localhost:8096",
+      "user": "FoxxMD",
+      "apiKey": "c9fae8756fbf481ebd9c5bb56bd6540c",
+      "usersAllow": ["fredUser"]
     }
   }
 ]
@@ -234,7 +251,6 @@ Scenario:
     "clients": ["foxxMaloja"],
     "data": {
       "cookie": "__Secure-3PAPISID=3AxsXpy0MKGu75Qb/AkISXGqOnSDn1jEKn; DEVICE_INFO=ChxOekU0Tmpjek5EWTBPRGd3TlRBMk16QXpNdz09EJbS8Z0GGJbS8Z0G; ...",
-      "authUser": 1
     }
   }
 ]

docsite/docs/configuration/plex.md

@@ -1,8 +1,16 @@
 ---
 sidebar_position: 2
-title: Plex/Tautulli
+title: Plex/Tautulli (Deprecated)
 ---
 
+:::warning[Deprecated]
+
+Multi-scrobbler >= 0.8.8 supports a Plex Source that [directly uses the API](configuration/configuration.mdx?plexType=api#plex) which removes the need to use Tautulli since it does not require Plex Pass.
+
+The Tautulli source **and** Plex Webhook source are deprecated and will be removed in an upcoming release. Existing users should migrate to the API source as soon as possible.
+
+:::
+
 Tracks played on [Plex](https://plex.tv/) can be scrobbled either by:
  * A [Tautulli](https://tautulli.com/) notification agent with a webhook.
  * Using Plex [Webhooks](https://support.plex.tv/articles/115002267687-webhooks) (restricted to Plex Pass users)

docsite/docs/configuration/transforms.mdx

@@ -0,0 +1,523 @@
+---
+sidebar_position: 4
+title: Scrobble Modification
+toc_max_heading_level: 4
+---
+
+Multi-scrobbler configs support the ability to modify scrobble data in an automated fashion by matching and replacing strings in **title, artists, and album** at many different times in multi-scrobbler's lifecycle.
+
+### Why?
+
+You may need to "clean up" data from a Source or before sending to a scrobble Client due to any number of reasons:
+
+* ID3 tags in your music collection are dirty or have repeating garbage IE `[YourMusicSource.com] My Artist - My Title`
+* A Source's service often incorrectly adds data to some field IE `My Artist - My Title (Album Version)` when the title should just be `My Title`
+* An Artist you listen to often is spelled different between a Source and a Client which causes duplicate scrobbles
+
+In any scenario where a repeating pattern can be found in the data it would be nice to be able to fix it before the data gets downstream or to help prevent duplicate scrobbling. Multi-scrobbler can help you do this.
+
+## Overview
+
+### Journey of a Scrobble
+
+First, let's recap the lifecycle of a scrobble in multi-scrobbler:
+
+**Sources** are the beginning of the journey for a **Play** (song you've listened to long enough to be scrobblable)
+
+* A Source finds a new valid **Play**
+* The Source **compares** this new Play to all the other Plays it has already seen, if the Play is unique (title/artist/album/listened datetime) then...
+* The Source **discovers** the Play, adds it to Plays it has seen already, and broadcasts the Play should be scrobbled to all Clients
+
+Scrobble **Clients** listen for discovered Plays from Sources, then...
+
+* A Client receives a **Play** from a Source
+* The Client **compares** this Play to all the other scrobbles it has already seen, if the Play is unique (title/artist/album/listened datetime) then...
+* The Client **scrobbles** the Play downstream to the scrobble service and adds it as a Scrobble it has seen already
+
+### Lifecyle Hooks
+
+You'll notice there is a pattern above that looks like this:
+
+* **Before** data is compared
+* Data is **compared**
+* **After** data is compared
+
+These points, during both Source and Client processes, are when you can hook into the scrobble lifecycle and modify it.
+
+#### TLDR
+
+In more concrete terms this is the structure of hooks within a configuration (can be used in any **Source** or **Client**):
+
+```json5 title="lastfm.json" {10-14}
+[
+  {
+    "name": "myLastFm",
+    "enable": true,
+    "configureAs": "source",
+    "data": {
+      // ...
+    },
+    "options": {
+      "playTransform": {
+        "preCompare": {/* ... */},
+        "compare": {/* ... */},
+        "postCompare": {/* ... */}
+      }
+    }
+  }
+]
+```
+
+##### Hook
+
+For **Sources**:
+
+* `preCompare` - modify Play data immediately when received
+* `compare` - temporarily modify Play data when it is being compared to see if Play was already discovered
+* `postCompare` - modify Play data before sending to scrobble **Clients**
+
+For **Clients**:
+
+* `preCompare` - modify Play data immediately when received
+* `compare` - temporarily modify Play data when it is being compared to see if it was already scrobbled
+* `postCompare` - modify Play data before scrobbling it to downstream service and adding to already seen scrobbles
+
+:::tip
+
+Keep in mind that modifying Scrobble/Play data earlier in the lifecycle will affect that data at all times later in the lifecycle.
+
+For example, to modify the track so it's the same anywhere it is processed in multi-scrobbler you only need to modify it in the **Source's** `preCompare` hook because all later processes will receive the data with the modified track.
+
+:::
+
+### Modification Parts
+
+
+Each [**hook**](#hook) (`preCompare` etc...) is an object that specifies what part of the **Play** to modify:
+
+```json5
+{
+    "title": [/* ... */],
+    "artists": [/* ... */],
+    "album": [/* ... */]
+}
+```
+
+##### Expression
+
+and then a **list** what pattern/replacements (expressions) to use for the modification by using either simple strings or `search-replace` objects:
+
+```json5
+[
+  "badTerm", // remove all instances of 'badTerm'
+  {
+    "search": "anotherBadTerm", // and also match all instances of 'anotherBadTerm'
+    "replace": "goodTerm" // replace with the string 'goodTerm'
+  }
+]
+```
+
+Putting it all together:
+
+```json5 title="lastfm.json"
+[
+  {
+    "name": "myLastFm",
+    "enable": true,
+    "configureAs": "source",
+    "data": {
+      // ...
+    },
+    "options": {
+      "playTransform": {
+        "preCompare": {
+          "title": [
+            "badTerm",
+            {
+              "search": "badTerm",
+              "replace": "goodTerm"
+            }
+          ]
+        },
+      }
+    }
+  }
+]
+```
+
+:::note
+
+If the value of the field (title, an artist, album) is an empty string after transforming then the field is **removed.**
+
+:::
+
+:::tip
+
+Modifications can also be applied to **all Sources** or **all Clients** when using the [AIO Config](./configuration.mdx?configType=aio#configuration-types) `config.json` by setting `playTransform` in `sourceDefaults` or `clientDefaults`:
+
+<details>
+
+    <summary>Example</summary>
+```json5 title="config.json"
+{
+  "sourceDefaults": { // will apply playTransform to all sources
+    "playTransform": {
+      "preCompare": {
+        "title": [
+          "(Album Version)"
+        ]
+      }
+    }
+  },
+  "sources": [/* ... */],
+  "clients": [/* ... */]
+}
+```
+</details>
+
+:::
+
+#### Compare Hook
+
+The `compare` [hook](#hook) is slightly different than `preCompare` and `postCompare`. It consists of an object where you define which side(s) of the comparison should be modified. It also **does not modify downstream data!** Instead, the modifications are made only for use in the comparison.
+
+```json5 title="lastfm.json"
+[
+  {
+    "name": "myLastFm",
+    // ...
+    "options": {
+      "playTransform": {
+        "compare": {
+          "candidate": {/* ... */}, // modify the "new" Play being compared
+          "existing": {/* ... */}, // modify all "existing" Play/Scrobbles the new Play is being compared against
+        },
+      }
+    }
+  }
+]
+```
+
+#### Regular Expressions
+
+In addition to plain strings [expressions](#expression) that are matched and removed you can also use Regular Expressions. Write your regex like you normally would, but as a string, and it'll automatically be parsed:
+
+```json5
+[
+  "/^\(\w+.com)/i", // matches any string that starts with '(YourMusic.com)' and removes it
+  {
+    "search": "/^\(\w+.com)/i", // matches any string that starts with '(YourMusic.com)'
+    "replace": "[MySite.com]" // replace with the string '[MySite.com]'
+  }
+]
+```
+
+The `replace` property uses javascript's [`replace()` function and so can use any special string characters.](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace#specifying_a_string_as_the_replacement)
+
+### Conditional Modification
+
+#### "When" Condition
+
+Top-level hooks **and** individual rules also support a `when` key for testing **if they should be run.**
+
+The `when` key is similar to a normal [modification](#modification-parts) except:
+
+* the keys accept a single string instead of an array
+* the `when` key data is an array instead of a single object
+
+All parts of an individual `when` clause must test true to "pass" but if **any** `when` clauses pass the hook/rule is processed. Example `when` data:
+
+```json5
+{
+  "when": [
+    {
+      "artist": "Elephant Gym", // both of these must match the Play object (AND)
+      "album": "Dreams" // both of these must match the Play object (AND)
+    },
+    // OR
+    {
+      "title": "/(Remastered)$/", // both of these must match the Play object (AND)
+      "album": "Various Artists" // both of these must match the Play object (AND)
+    }
+  ]
+}
+```
+
+More succinctly:
+
+* All parts (`artist` `album` `title`) of a `when` are `AND` conditions
+* All part-objects in the `when` array are `OR` conditions
+
+<details>
+
+<summary>Example of top-level hook with when condition</summary>
+
+```json5
+{
+  // IF the artist is Elephant Gym 
+  // THEN Run preCompare hook ELSE skip this hook
+  //
+  //    Run search-replace on album
+  //    Run regex title remove
+  "sourceDefaults": {
+    "playTransform": {
+      "preCompare": {
+        "when": [
+          {
+            "artist": "/Elephant Gym/"
+          }
+        ],
+        "album": [
+          {
+            "search": "Dreams",
+            "replace": "夢境"
+          }
+        ],
+        "title": ["/\s\-\s滾石40\s滾石撞樂隊\s40團拚經典(.+)$/i"]
+      },
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+
+<summary>Example of individual rule with when condition</summary>
+
+```json5
+{
+  // Always run preCompare
+  //
+  //   On search-replace in title...
+  //     IF artist matches "Elephant Gym"
+  //     THEN Run regex search-replace ELSE skip this rule
+  //
+  //   Run live|remastered regex remove
+  "sourceDefaults": {
+    "playTransform": {
+      "preCompare": {
+        "title": [
+          {
+            "search": "/\\s\\-\\s滾石40\\s滾石撞樂隊\\s40團拚經典(.+)$/i",
+            "replace": "",
+            "when": [
+              {
+                "artist": "/Elephant Gym/"
+              }
+            ]
+          },
+          "/(\\s\\-\\s|\\s)(feat\\.(.+)|live|remastered(.+))$/i"
+        ],
+      }
+    }
+  }
+}
+```
+
+</details>
+
+#### Top-level Hook array
+
+Top-level hooks can also be an array of hooks. This makes creating multiple scenarios for top-level `when`-gated hooks easier. All hooks in the array will be run (assuming their `when`'s pass, if they exist) and their **input will be the Play object output of the previous hook in the array.**
+
+<details>
+
+<summary>Example</summary>
+
+```json5
+{
+  "sourceDefaults": {
+    "playTransform": {
+      "preCompare": [
+        // first lifecycle hook of preCompare to run
+        {
+          "title": [
+            {
+              "search": "something",
+              "replace": "else unique"
+            }
+          ]
+        },
+        // second lifecycle hook of preCompare to run
+        {
+          "title": [
+            {
+              "search": "else unique",
+              "replace": "very demure"
+            }
+          ]
+        },
+      ]
+    }
+  }
+}
+```
+
+</details>
+
+### Logging
+
+MS can log the output of hook transformations if/when they occur. In the `playTransform` object of a Source/Client config use `log`:
+
+* `"log": true` => Output original play + final transformed output of last hook in the array
+* `"log": "all"` => Output original play + final transformed output of **each** hook in the array
+
+```json5
+{
+  "name": "myThing",
+  "data": {/*...*/},
+  "options": {
+    "playTransform": {
+      "preCompare": {/*...*/},
+      "log": true
+    }
+  }
+}
+```
+
+## Examples
+
+### Remove phrase from Title in all new Plays
+
+Removes the phrase `(Album Version)` from the Title of a Play
+
+
+<details>
+
+    <summary>Example</summary>
+```json5 title="config.json"
+{
+  "sourceDefaults": {
+    "playTransform": {
+      "preCompare": {
+        "title": [
+          "(Album Version)"
+        ]
+      }
+    }
+  }
+}
+
+```
+</details>
+
+### Remove all parenthesized content from the end of a title
+
+<details>
+
+    <summary>Example</summary>
+```json5 title="lastfm.json"
+[
+  {
+    "name": "myLastFm",
+    // ...
+    "options": {
+      "playTransform": {
+        "compare": {
+          "candidate": {
+          "title": [
+              "/(\(.+\))\s*$/"
+            ]
+          },
+          "existing": {
+          "title": [
+              "/(\(.+\))\s*$/"
+            ]
+          },
+        },
+      }
+    }
+  }
+]
+```
+</details>
+
+### Rename misspelled artist in all new Plays
+
+<details>
+
+    <summary>Example</summary>
+```json5 title="config.json"
+{
+  "sourceDefaults": {
+    "playTransform": {
+      "preCompare": {
+        "artists": [
+          {
+            "search": "Boz Skaggs",
+            "replace": "Boz Scaggs"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+</details>
+
+### Remove "Various Artists" albums in all new Plays
+
+<details>
+
+    <summary>Example</summary>
+```json5 title="config.json"
+{
+  "sourceDefaults": {
+    "playTransform": {
+      "preCompare": {
+        "album": [
+          {
+            "search": "Various Artists",
+            "replace": ""
+          }
+        ]
+      }
+    }
+  }
+}
+```
+</details>
+
+### Extract primary Artist from delimited, multi-Artist string
+
+<details>
+
+  When the Artist string is actually a multi-artist, delimited string, this search-and-replace will replace the string with just the first artist found.
+
+  Ex
+
+  ```
+  My Artist One / My Artist Two / Another Guy
+  My Artist One
+  ```
+
+  Artists are delimited with a spaced forward slash (`/`) in the regex below. Replace the contents of the `delim` capture group with the delimiter for your use case. Some more common scenarios:
+
+  * `(?<delim>\\/)` No spaces between slash IE `My Artist One/My Artist Two/Another Guy`
+  * `(?<delim>\\s*\\\\\s*)` Backslash instead of forward slash IE `My Artist One \ My Artist Two \ Another Guy`
+  * `(?<delim>,)` Comma IE `My Artist One, My Artist Two, Another Guy`
+
+  <details>
+
+      <summary>Example</summary>
+  ```json5 title="config.json"
+  {
+    "sourceDefaults": {
+      "playTransform": {
+        "preCompare": {
+          "artists": [
+            {
+              "search": "(.*?)(?<delim>\\s*\\/\\s*)(.*$)",
+              "replace": "$1"
+            }
+          ]
+        }
+      }
+    }
+  }
+  ```
+  </details>
+
+</details>

docsite/docs/development/dev-common.md

@@ -14,21 +14,33 @@ Multi-scrobbler is written entirely in [Typescript](https://www.typescriptlang.o
 
 ## Project Setup
 
-Development requires [Node v18.19.1](https://nodejs.org/en) or higher is installed on your system. It is recommended to use [nvm](https://github.com/nvm-sh/nvm) to manage the installed node version.
+Development requires [Node v18.19.1](https://nodejs.org/en) or higher is installed on your system. 
 
+:::tip
+
+When running locally (not with a devcontainer) you can use [nvm](https://github.com/nvm-sh/nvm) to manage the installed node version.
+
+:::
 
 Clone this repository somewhere and then install from the working directory
 
 ```shell
 git clone https://github.com/FoxxMD/multi-scrobbler.git .
 cd multi-scrobbler
-git checkout --track origin/develop
-nvm use # optional, to set correct Node version
+nvm use # optional, sets correct node version when running without devcontainer
 npm install
 npm run start
 ```
 
-Use the [`develop`](https://github.com/FoxxMD/multi-scrobbler/tree/develop) branch as the target for any Pull Requests. The `master` branch is reserved for releases and minor documentation updates only.
+### VSCode
+
+This repository contains [workspace settings](https://github.com/FoxxMD/multi-scrobbler/blob/master/.devcontainer) for development with VSCode. These include:
+
+* Run/Debug [Launch configurations](https://code.visualstudio.com/Docs/editor/debugging#_launch-configurations) for the application and tests
+* [Devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) for development with all dependencies already installed
+* Useful extensions for linting and running tests
+
+To use the Devcontainer simple open the repository in VSCode and "Use Devcontainer" when the notification is presented. `npm install` will be run when a new container is created.
 
 ## Common Development
 
@@ -47,7 +59,7 @@ In both parts Source/Clients share some common properties/behavior before diverg
 
 ### Config
 
-The configuration for a Component should always have this minimum shape, enforced respectively by the interfaces [CommonSourceConfig](https://github.com/FoxxMD/multi-scrobbler/blob/develop/src/backend/common/infrastructure/config/source/index.ts#L105) and [CommonClientConfig](https://github.com/FoxxMD/multi-scrobbler/blob/ce1c70a4e1e87fb5bea7cca960eaafbd15881a1f/src/backend/common/infrastructure/config/client/index.ts#L68):
+The configuration for a Component should always have this minimum shape, enforced respectively by the interfaces [CommonSourceConfig](https://github.com/FoxxMD/multi-scrobbler/blob/master/src/backend/common/infrastructure/config/source/index.ts#L105) and [CommonClientConfig](https://github.com/FoxxMD/multi-scrobbler/blob/ce1c70a4e1e87fb5bea7cca960eaafbd15881a1f/src/backend/common/infrastructure/config/client/index.ts#L68):
 
 ```ts
 interface MyConfig {
@@ -62,7 +74,7 @@ interface MyConfig {
 
 ### Concrete Class
 
-Components inherit from an abstract base class, [`AbstractComponent`](https://github.com/FoxxMD/multi-scrobbler/blob/develop/src/backend/common/AbstractComponent.ts), that defines different "stages" of how a Component is built and initialized when MS first starts as well as when restarting the Component in the event it stops due to an error/network failure/etc...
+Components inherit from an abstract base class, [`AbstractComponent`](https://github.com/FoxxMD/multi-scrobbler/blob/master/src/backend/common/AbstractComponent.ts), that defines different "stages" of how a Component is built and initialized when MS first starts as well as when restarting the Component in the event it stops due to an error/network failure/etc...
 
 #### Stages
 
@@ -81,7 +93,7 @@ This stage should be used to validate user configuration, parse any additional d
 
 :::info
 
-Implement [`doBuildInitData`](https://github.com/FoxxMD/multi-scrobbler/blob/develop/src/backend/common/AbstractComponent.ts#L71) in your child class to invoke this stage.
+Implement [`doBuildInitData`](https://github.com/FoxxMD/multi-scrobbler/blob/master/src/backend/common/AbstractComponent.ts#L71) in your child class to invoke this stage.
 
 ::::
 
@@ -103,7 +115,7 @@ If the Component depends on **ingress** (like Jellyfin/Plex webhook) this stage
 
 :::info
 
-Implement [`doCheckConnection`](https://github.com/FoxxMD/multi-scrobbler/blob/develop/src/backend/common/AbstractComponent.ts#L103) in your child class to invoke this stage.
+Implement [`doCheckConnection`](https://github.com/FoxxMD/multi-scrobbler/blob/master/src/backend/common/AbstractComponent.ts#L103) in your child class to invoke this stage.
 
 ::::
 
@@ -136,7 +148,7 @@ You _should_ attempt to re-authenticate, if possible. Only throw an exception or
 
 :::info
 
-Implement [`doAuthentication`](https://github.com/FoxxMD/multi-scrobbler/blob/develop/src/backend/common/AbstractComponent.ts#L111) in your child class to invoke this stage.
+Implement [`doAuthentication`](https://github.com/FoxxMD/multi-scrobbler/blob/master/src/backend/common/AbstractComponent.ts#L111) in your child class to invoke this stage.
 
 ::::
 

docsite/docs/development/flatpak.md

@@ -6,12 +6,6 @@ title: Flatpak
 description: Building Flatpak App locally
 ---
 
-:::note
-
-These steps are for building the flatpak from source. If you want to install the application normally then [get it through flathub](../installation/installation.mdx#flatpak)
-
-:::
-
 The final build repo for the flathub version can be found at [flathub/io.github.foxxmd.multiscrobbler](https://github.com/flathub/io.github.foxxmd.multiscrobbler)
 
 ## Install Requirements

docsite/docs/installation/installation.mdx

@@ -5,6 +5,8 @@ title: 'Overview'
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+import ComposeStack from '!!raw-loader!../../../docker-compose.yml';
 
 :::tip
 
@@ -103,12 +105,6 @@ The web UI and API is served on port `9078`. This can be modified using the `POR
 
 ### Flatpak
 
-You must have [Flatpak](https://flatpak.org/) installed on your system.
-
-```shell
-flatpak install flathub io.github.foxxmd.multiscrobbler
-```
-
 :::warning
 
 Flatpak users have experienced issues when using multi-scrobbler as a long-running process. Due to the relative difficulty in debugging issues with flatpak installations it is recommended:
@@ -116,7 +112,9 @@ Flatpak users have experienced issues when using multi-scrobbler as a long-runni
 * to use a [Docker](#docker) installation if possible or
 * only if you need access to host-level resources like dbus for [MPRIS](https://foxxmd.github.io/multi-scrobbler/docs/configuration#mpris) and cannot run a [nodejs](#nodejs) installation
 
-::::
+:::
+
+Flatpak/Flathub installs are no longer supported. You can still build MS as a [Flatpak app from source.](../development/flatpak) See more information about [Flatpak EOL.](https://github.com/FoxxMD/multi-scrobbler/issues/287)
 
 #### Usage Examples
 
@@ -160,7 +158,15 @@ Cross-platform images are built for x86 (Intel/AMD) and ARM64 (IE Raspberry Pi)
 
 :::
 
-Or use the provided [docker-compose.yml](../../../docker-compose.yml) after modifying it to fit your configuration.
+Or use the example `docker-compose.yml`, found in the repo, after modifying it to fit your configuration:
+
+<details>
+
+<summary>`docker-compose.yml`</summary>
+
+<CodeBlock language="yaml">{ComposeStack}</CodeBlock>
+
+</details>
 
 Recommended configuration steps for docker or docker-compose usage:
 
@@ -253,7 +259,7 @@ set the [Base URL](../configuration/configuration.mdx#base-url) as the IP of the
           multi-scrobbler:
             # ...
             environment:
-              - BASE_URL="http://hostMachineIP"
+              - BASE_URL=http://hostMachineIP
         ```
     </TabItem>
 </Tabs>
@@ -316,7 +322,7 @@ The example scenario:
         </Tabs>
     </TabItem>
     <TabItem value="docker-compose" label="Docker Compose">
-        See [`docker-compose.yml`](../../../docker-compose.yml) file for more options and annotations.
+        See [`docker-compose.yml`](#docker) sample above for more options and annotations.
 
         ```yaml title="docker-compose.yml"
         services:
@@ -327,7 +333,7 @@ The example scenario:
                     - TZ=Etc/GMT # Specify timezone from TZ Database name found here https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
                     - SPOTIFY_CLIENT_ID=yourId
                     - SPOTIFY_CLIENT_SECRET=yourSecret
-                    - BASE_URL="http://192.168.0.100:9078"
+                    - BASE_URL=http://192.168.0.100:9078
                     - MALOJA_URL=http://domain.tld:42010
                     - MALOJA_API_KEY=1234
                     - PUID=1000

docsite/docs/installation/service.md

@@ -31,27 +31,14 @@ After=network.target
 
 [Service]
 Type=simple
-ExecStart=flatpak run io.github.multiscrobbler
+WorkingDirectory=/path/to/multi-scrobbler/directory
+ExecStart=npm run start
 Restart=no
 
 [Install]
 WantedBy=default.target
 ```
 
-The above assumes you [installed multi-scrobbler using flatpak](installation.mdx#flatpak)
-
-### Node.js Installs
-
-If you are running multi-scrobbler directly with [nodejs from a clone repository directory](installation.mdx#nodejs) you should modify the `[Service]`:
-
-```ini
-[Service]
-Type=simple
-WorkingDirectory=/path/to/multi-scrobbler/directory
-ExecStart=node src/index.js
-Restart=no
-```
-
 ## Start the Service
 
 Save the file then run:

docsite/docs/quickstart.mdx

@@ -30,7 +30,7 @@ services:
     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
-      - BASE_URL="http://192.168.0.100:9078"
+      - BASE_URL=http://192.168.0.100:9078
       # all Environmental Variables in below examples go here!
 
     volumes:
@@ -46,13 +46,14 @@ services:
 
 <Tabs>
     <TabItem value="jellyfin" label="Jellyfin">
-        Follow the Jellyfin configuration [instructions for setting up a **webhook**.](./configuration/configuration.mdx#jellyfin)
+        Follow the Jellyfin configuration [instructions for setting up an **API Key**.](./configuration/configuration.mdx#jellyfin)
 
-        After webhook is setup add **at least one** of these values to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)
+        Then, add these values to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)
 
         ```yaml title="~/msData/docker-compose.yml"
-        - JELLYFIN_USER=myUserName # comma-separated list of users to monitor
-        - JELLYFIN_SERVER=myServerName # comma-separated list of servers that should be monitored
+        - 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
         ```
     </TabItem>
     <TabItem value="spotify" label="Spotify">
@@ -109,7 +110,7 @@ services:
         Finally, add these values to the `environment` section in the [`docker-compose.yml` you created for multi-scrobbler earlier.](#create-docker-compose-file)
 
         ```yaml title="~/msData/docker-compose.yml"
-        - MALOJA_URL="http://192.168.0.100:42010"
+        - MALOJA_URL=http://192.168.0.100:42010
         - MALOJA_API_KEY=myApiKey
         ```
     </TabItem>

docsite/docusaurus.config.ts

@@ -4,6 +4,9 @@ import * as themes from 'prism-react-renderer';
 //import sidebars from './sidebars';
 
 const config: Config = {
+  future: {
+    experimental_faster: true
+  },
   title: 'Multi-Scrobbler',
   tagline: 'Scrobble all the things',
   favicon: 'img/favicon.ico',
@@ -19,7 +22,7 @@ const config: Config = {
   organizationName: 'foxxmd', // Usually your GitHub org/user name.
   projectName: 'multi-scrobbler', // Usually your repo name.
 
-  trailingSlash: false,
+  trailingSlash: true,
 
   onBrokenLinks: 'warn',
   onBrokenMarkdownLinks: 'warn',
@@ -170,11 +173,21 @@ const config: Config = {
         runmeLinkLabel: 'Checkout via Runme'
       }
     } satisfies Preset.ThemeConfig,
+    headTags: [
+      {
+        tagName: 'meta',
+        attributes: {
+          name: 'google-site-verification',
+          content: process.env.GSITEVERIFICATION ?? 'none'
+        }
+      }
+    ]
 };
 
 if (process.env.ANALYTICS !== undefined && process.env.ANALYTICS !== '') {
   const script = {
     src: process.env.ANALYTICS,
+    defer: true
   }
   if (process.env.ANALYTICS_DOMAIN !== undefined && process.env.ANALYTICS_DOMAIN !== '') {
     script['data-domain'] = process.env.ANALYTICS_DOMAIN;

docsite/package.json

@@ -3,24 +3,26 @@
   "version": "0.0.0",
   "private": true,
   "scripts": {
-    "start": "npx docusaurus start",
-    "build": "npx docusaurus build",
-    "swizzle": "npx docusaurus swizzle",
-    "deploy": "npx docusaurus deploy",
-    "clear": "npx docusaurus clear",
-    "serve": "npx docusaurus serve",
-    "write-translations": "npx docusaurus write-translations",
-    "write-heading-ids": "npx docusaurus write-heading-ids",
+    "start": "docusaurus start --host 0.0.0.0",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc"
   },
   "dependencies": {
-    "@docusaurus/core": "^3.4.0",
-    "@docusaurus/preset-classic": "^3.4.0",
-    "@easyops-cn/docusaurus-search-local": "^0.44.3",
+    "@docusaurus/core": "^3.6.3",
+    "@docusaurus/faster": "^3.7.0",
+    "@docusaurus/preset-classic": "^3.6.3",
+    "@easyops-cn/docusaurus-search-local": "^0.48.3",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "docusaurus-json-schema-plugin": "^1.12.1",
     "docusaurus-theme-github-codeblock": "^2.0.2",
+    "json5": "^2.2.3",
     "micromark-extension-directive": "^3.0.1",
     "prism-react-renderer": "^2.3.0",
     "raw-loader": "^4.0.2",
@@ -28,11 +30,11 @@
     "react-dom": "^18.0.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^3.4.0",
-    "@docusaurus/tsconfig": "^3.4.0",
-    "@docusaurus/types": "^3.4.0",
+    "@docusaurus/module-type-aliases": "^3.6.3",
+    "@docusaurus/tsconfig": "^3.6.3",
+    "@docusaurus/types": "^3.6.3",
     "@types/react": "^18.2.29",
-    "typescript": "~5.2.2"
+    "typescript": "~5.6.2"
   },
   "browserslist": {
     "production": [

docsite/src/components/AIOExample.tsx

@@ -5,6 +5,7 @@ import ErrorBoundary from "@docusaurus/ErrorBoundary"
 import Error from "@theme/Error"
 import { Simulate } from "react-dom/test-utils";
 import error = Simulate.error;
+import json5 from 'json5';
 
 export interface AIOProps {
     data: string
@@ -22,7 +23,7 @@ const AIOExample = (props: AIOProps) => {
     let configObj;
     // eslint-disable-next-line prefer-const
     try {
-        configObj = JSON.parse(data);
+        configObj = json5.parse(data);
     } catch (e) {
         console.error(e);
         return <Admonition type="danger" title="Unexpected Error">

docsite/src/pages/index.mdx

@@ -14,20 +14,27 @@ A javascript app to scrobble music you listened to, to [Maloja](https://github.c
 
 * Supports scrobbling from many **Sources**
     * [Spotify](docs/configuration#spotify)
-    * [Plex](docs/configuration#plex) or [Tautulli](docs/configuration#tautulli)
+    * [Plex](docs/configuration#plex) or [~~Tautulli~~](docs/configuration#tautulli)
     * [Subsonic-compatible APIs](docs/configuration#subsonic) (like [Airsonic](https://airsonic.github.io/) and [Navidrome](https://www.navidrome.org/))
     * [Jellyfin](docs/configuration#jellyfin)
     * [WebScrobbler](docs/configuration#webscrobbler)
     * [Youtube Music](docs/configuration#youtube-music)
     * [Last.fm](docs/configuration#lastfm-source)
+    * [Last.fm (Endpoint)](docs/configuration#lastfm-endpoint)
     * [ListenBrainz](docs/configuration#listenbrainz-source)
-    * [Deezer](docs/configuration#deezer)
+    * [ListenBrainz (Endpoint)](docs/configuration#listenbrainz-endpoint)
+    * [~~Deezer~~](docs/configuration#deezer)
     * [MPRIS (Linux Desktop)](docs/configuration#mpris)
     * [Mopidy](docs/configuration#mopidy)
     * [JRiver](docs/configuration#jriver)
     * [Kodi](docs/configuration#kodi)
     * [Google Cast (Chromecast)](docs/configuration#google-cast-chromecast)
     * [Musikcube](docs/configuration#musikcube)
+    * [MPD (Music Player Daemon)](docs/configuration#mpd-music-player-daemon)
+    * [VLC](docs/configuration#vlc)
+    * [Azuracast](docs/configuration#azuracast)
+    * [Yamaha MusicCast](docs/configuration#yamaha-musiccast)
+    * [Icecast](docs/configuration#icecast)
 * Supports scrobbling to many **Clients**
     * [Maloja](docs/configuration#maloja)
     * [Last.fm](docs/configuration#lastfm)
@@ -38,7 +45,8 @@ A javascript app to scrobble music you listened to, to [Maloja](https://github.c
 * Graceful network and client failure handling (queued scrobbles that auto-retry)
 * Smart handling of credentials (persistent, authorization through app)
 * Easy configuration through ENVs or JSON
-* Install using [Docker images for x86/ARM](docs/installation#docker), [flatpak](docs/installation#flatpak), or [locally with NodeJS](docs/installation#nodejs)
+* Modify data before scrobbling with [regular expression or search patterns](docs/configuration/transforms)
+* Install using [Docker images for x86/ARM](docs/installation#docker) or [locally with NodeJS](docs/installation#nodejs)
 
 [**Quick Start Guide**](docs/quickstart)
 

eslint.config.js

@@ -4,40 +4,33 @@ import eslint from '@eslint/js';
 import tsEslint from 'typescript-eslint';
 import arrow from 'eslint-plugin-prefer-arrow-functions';
 
-export default tsEslint.config(
-    eslint.configs.recommended,
-    ...tsEslint.configs.recommended,
-// use to enable typed linting (way more errors) https://typescript-eslint.io/linting/typed-linting
-/*    ...tsEslint.configs.recommendedTypeChecked,
-    {
-        languageOptions: {
-            parserOptions: {
-                project: true,
-                tsconfigDirName: import.meta.dirname,
-            },
-        },
-    },*/
-    {
-        files: ['src/backend/**/*.ts'],
-        ignores: ['eslint.config.js'],
-        plugins: {
-            "prefer-arrow-functions": arrow
-        },
-        rules: {
-            'no-useless-catch': 'off',
-            '@typescript-eslint/no-unused-vars': 'off',
-            "prefer-arrow-functions/prefer-arrow-functions": [
-                "warn",
-                {
-                    "allowNamedFunctions": false,
-                    "classPropertiesAllowed": false,
-                    "disallowPrototype": false,
-                    "returnStyle": "unchanged",
-                    "singleReturnOnly": false
-                }
-            ],
-            "arrow-body-style": ["warn", "as-needed"],
-            "@typescript-eslint/no-explicit-any": "warn"
-        }
+export default tsEslint.config({
+    files: ['src/backend/**/*.ts'],
+    plugins: {
+        "prefer-arrow-functions": arrow
+    },
+    ignores: [
+        'eslint.config.js',
+        'src/backend/tests/**/*.ts'
+    ],
+    extends: [
+        eslint.configs.recommended,
+        ...tsEslint.configs.recommended,
+    ],
+    rules: {
+        'no-useless-catch': 'off',
+        '@typescript-eslint/no-unused-vars': 'off',
+        "prefer-arrow-functions/prefer-arrow-functions": [
+            "warn",
+            {
+                "allowNamedFunctions": false,
+                "classPropertiesAllowed": false,
+                "disallowPrototype": false,
+                "returnStyle": "unchanged",
+                "singleReturnOnly": false
+            }
+        ],
+        "arrow-body-style": ["warn", "as-needed"],
+        "@typescript-eslint/no-explicit-any": "warn"
     }
-);
+});

flatpak/io.github.foxxmd.multiscrobbler.metainfo.xml

@@ -22,11 +22,10 @@
         <ul>
             <li>Spotify</li>
             <li>Plex (Tautulli)</li>
-            <li>Any subsonic-based music player (Airsonic)</li>
+            <li>Any subsonic-based music player (Airsonic or Navidrome)</li>
             <li>Jellyfin</li>
             <li>WebScrobbler</li>
             <li>Mopidy</li>
-            <li>Deezer</li>
             <li>JRiver</li>
             <li>Kodi</li>
             <li>Webscrobbler</li>
@@ -34,6 +33,12 @@
             <li>MPRIS (linux desktop)</li>
             <li>Google Cast (Chromecast)</li>
             <li>Musikcube</li>
+            <li>MPD (Music Player Daemon)</li>
+            <li>VLC</li>
+            <li>Azuracast</li>
+            <li>Icecast</li>
+            <li>Yamaha MusicCast</li>
+            <li>Listenbrainz and Last.fm Endpoints</li>
         </ul>
         <p>and consolidate your listens (scrobbles) into one or more scrobbling servers/services:</p>
         <ul>
@@ -50,6 +55,11 @@
         </screenshot>
     </screenshots>
     <releases>
+        <release version="0.9.2" date="2025-03-24"/>
+        <release version="0.9.0" date="2025-01-15"/>
+        <release version="0.8.4" date="2024-09-27"/>
+        <release version="0.8.3" date="2024-08-28"/>
+        <release version="0.8.2" date="2024-08-20"/>
         <release version="0.8.1" date="2024-07-17"/>
         <release version="0.8.0" date="2024-07-08"/>
         <release version="0.7.1" date="2024-04-11"/>

package.json

@@ -1,27 +1,24 @@
 {
   "name": "multi-scrobbler",
-  "version": "0.8.1",
+  "version": "0.9.3",
   "type": "module",
   "description": "scrobble plays from multiple sources to multiple clients",
   "scripts": {
-    "schema": "npm run -s schema-aio & npm run -s schema-source & npm run -s schema-client & npm run -s schema-aiosource & npm run -s schema-aioclient",
-    "schema-client": "typescript-json-schema src/backend/tsconfig.json ClientConfig --out src/backend/common/schema/client.json --required --titles --tsNodeRegister --refs --validationKeywords deprecationMessage",
-    "schema-source": "typescript-json-schema src/backend/tsconfig.json SourceConfig --out src/backend/common/schema/source.json --required --titles --tsNodeRegister --refs --validationKeywords deprecationMessage",
-    "schema-aio": "typescript-json-schema src/backend/tsconfig.json AIOConfig --out src/backend/common/schema/aio.json --required --titles --tsNodeRegister --refs --validationKeywords deprecationMessage",
-    "schema-aiosource": "typescript-json-schema src/backend/tsconfig.json AIOSourceConfig --out src/backend/common/schema/aio-source.json --titles --required --tsNodeRegister --refs --validationKeywords deprecationMessage",
-    "schema-aioclient": "typescript-json-schema src/backend/tsconfig.json AIOClientConfig --out src/backend/common/schema/aio-client.json --titles --required --tsNodeRegister --refs --validationKeywords deprecationMessage",
+    "schema": "tsx src/backend/utils/SchemaStaticUtil.ts",
     "circular": "madge --circular --extensions ts src/index.ts",
     "test": "npm run -s test:backend",
-    "test:backend": "mocha --reporter spec --recursive src/backend/tests/**/*.test.ts",
+    "test:backend": "mocha --reporter spec",
     "dev": "nodemon -w src/backend -x tsx src/backend/index.ts",
     "start": "NODE_ENV=production tsx src/backend/index.ts",
     "build:frontend": "vite build",
     "build:backend": "tsc -p src/backend",
     "build": "npm run -s build:backend && npm run -s build:frontend && npm run -s docs:build",
-    "docs:install": "cd docsite && npm ci",
+    "build:parallel": "concurrently --kill-others-on-fail --names backend,frontend,docs \"npm run -s build:backend\" \"npm run -s build:frontend\" \"npm run docs:build\"",
+    "docs:install": "cd docsite && npm ci --no-audit",
     "docs:start": "cd docsite && npm start",
-    "docs:build": "cd docsite && npm run build",
-    "postinstall": "patch-package"
+    "docs:build": "npm run schema && cd docsite && npm run build",
+    "postinstall": "patch-package",
+    "install:parallel": "concurrently --kill-others-on-fail --names app,docs \"npm ci --no-audit\" \"npm run docs:install\""
   },
   "exports": {
     ".": {
@@ -54,12 +51,17 @@
     "@fortawesome/react-fontawesome": "^0.2.0",
     "@foxxmd/chromecast-client": "^1.0.4",
     "@foxxmd/get-version": "^0.0.3",
-    "@foxxmd/logging": "^0.1.14",
+    "@foxxmd/logging": "^0.2.2",
+    "@foxxmd/regex-buddy-core": "^0.1.2",
     "@foxxmd/string-sameness": "^0.4.0",
+    "@gr2m/net-interceptor": "^1.0.0",
+    "@jellyfin/sdk": "^0.11.0",
     "@kenyip/backoff-strategies": "^1.0.4",
+    "@lukehagar/plexjs": "^0.32.1",
     "@react-nano/use-event-source": "^0.13.0",
     "@reduxjs/toolkit": "^1.9.5",
     "@supercharge/promise-pool": "^3.0.0",
+    "@types/express-serve-static-core": "^4.19.6",
     "address": "^1.2.2",
     "ajv": "^8.12.0",
     "autoprefixer": "^10.4.17",
@@ -77,24 +79,29 @@
     "dotenv": "^10.0.0",
     "express": "^4.17.1",
     "express-session": "^1.17.2",
+    "fast-deep-equal": "^3.1.3",
     "fixed-size-list": "^0.3.0",
-    "formidable": "^2.1",
+    "formidable": "^3.5",
+    "glob": "^11.0.0",
+    "google-auth-library": "^9.15.0",
     "gotify": "^1.1.0",
-    "iso-websocket": "^0.2.0",
+    "icecast-metadata-stats": "^0.1.12",
+    "iso-websocket": "^0.3.0",
     "iti": "^0.6.0",
     "json5": "^2.2.3",
     "kodi-api": "^0.2.1",
     "lastfm-node-client": "^2.2.0",
     "mopidy": "^1.3.0",
+    "mpd-api": "^1.1.2",
     "nanoid": "^3.3.1",
     "normalize-url": "^8.0.1",
-    "ntfy": "^1.5.4",
+    "ntfy": "^1.6.2",
     "object-hash": "^3.0.0",
     "p-event": "^4.2.0",
     "passport": "^0.6.0",
     "passport-deezer": "^0.2.0",
     "patch-package": "^8.0.0",
-    "postcss": "^8.4.33",
+    "postcss": "^8.4.41",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-redux": "^8.1.2",
@@ -104,15 +111,17 @@
     "superagent": "^8.0.9",
     "tailwindcss": "^3.4.4",
     "toad-scheduler": "^3.0.0",
+    "ts-json-schema-generator": "^2.3.0",
     "tsx": "^4.7.0",
     "vite-express": "^0.16.0",
-    "xml2js": "0.5.0",
-    "youtube-music-ts-api": "^1.7.0"
+    "vlc-client": "^1.1.1",
+    "xml2js": "0.6.1",
+    "youtubei.js": "^13.1.0"
   },
   "devDependencies": {
     "@dbus-types/notifications": "^0.0.5",
     "@eslint/js": "^8.56.0",
-    "@faker-js/faker": "^8.1.0",
+    "@faker-js/faker": "^9.0.1",
     "@istanbuljs/nyc-config-typescript": "^1.0.2",
     "@testing-library/jest-dom": "^5.17.0",
     "@testing-library/react": "^13.4.0",
@@ -126,7 +135,7 @@
     "@types/cors": "^2.8.17",
     "@types/express": "^4.17.13",
     "@types/express-session": "^1.17.4",
-    "@types/formidable": "^2.0.5",
+    "@types/formidable": "^3.4.5",
     "@types/jest": "^27.5.2",
     "@types/jscodeshift": "^0.11.6",
     "@types/mocha": "^9.1.0",
@@ -146,13 +155,14 @@
     "eslint": "^8.56.0",
     "eslint-plugin-prefer-arrow-functions": "^3.2.4",
     "mocha": "^10.3.0",
+    "mockdate": "^3.0.5",
     "msw": "^2.1.2",
     "nodemon": "^3.0.3",
     "ts-essentials": "^9.1.2",
-    "typescript": "^5.3.3",
+    "typescript": "5.5.4",
     "typescript-eslint": "^7.0.1",
-    "typescript-json-schema": "~0.55",
-    "vite": "^5.2.12"
+    "vite": "^5.2.12",
+    "with-local-tmp-dir": "^5.1.1"
   },
   "browserslist": {
     "production": [
@@ -169,6 +179,11 @@
   "overrides": {
     "spotify-web-api-node": {
       "superagent": "$superagent"
+    },
+    "with-local-tmp-dir": {
+      "tmp-promise": {
+        "tmp": "0.2.1"
+      }
     }
   }
 }

patches/icecast-metadata-stats+0.1.12.patch

@@ -0,0 +1,44 @@
+diff --git a/node_modules/icecast-metadata-stats/src/IcecastMetadataStats.js b/node_modules/icecast-metadata-stats/src/IcecastMetadataStats.js
+index 7b70725..8836a99 100644
+--- a/node_modules/icecast-metadata-stats/src/IcecastMetadataStats.js
++++ b/node_modules/icecast-metadata-stats/src/IcecastMetadataStats.js
+@@ -59,6 +59,7 @@ const sources = Symbol();
+ const interval = Symbol();
+ const onStats = Symbol();
+ const onStatsFetch = Symbol();
++const onError = Symbol();
+ 
+ const state = Symbol();
+ const intervalId = Symbol();
+@@ -106,6 +107,7 @@ export default class IcecastMetadataStats {
+       [interval]: (options.interval || 30) * 1000,
+       [onStats]: options.onStats || noOp,
+       [onStatsFetch]: options.onStatsFetch || noOp,
++      [onError]: options.onError,
+       [icyMetaInt]: options.icyMetaInt,
+       [icyCharacterEncoding]: options.icyCharacterEncoding,
+       [icyDetectionTimeout]: options.icyDetectionTimeout,
+@@ -425,13 +427,21 @@ export default class IcecastMetadataStats {
+         signal: p.get(this)[controller].signal,
+       })
+         .then((res) => {
+-          if (!res.ok) throw new Error(`HTTP Error ${res.status}`);
++          if (!res.ok) {
++            const responseError = new Error(`HTTP Error ${res.status}`);
++            responseError.res = res;
++            throw responseError;
++          } 
+           return res;
+         })
+         .then(mapper)
+         .catch((e) => {
+           if (e.name !== "AbortError") {
+-            console.warn(`Failed to fetch ${p.get(this)[endpoint]}`, e);
++            if(p.get(this)[onError] !== undefined) {
++              p.get(this)[onError](new Error(`Failed to fetch ${p.get(this)[endpoint]}`, {cause: e}));
++            } else {
++              console.warn(`Failed to fetch ${p.get(this)[endpoint]}`, e);
++            }
+           }
+         })
+         .finally(() => {

patches/ts-json-schema-generator+2.3.0.patch

@@ -0,0 +1,39 @@
+diff --git a/node_modules/ts-json-schema-generator/dist/src/AnnotationsReader/ExtendedAnnotationsReader.js b/node_modules/ts-json-schema-generator/dist/src/AnnotationsReader/ExtendedAnnotationsReader.js
+index 107dc62..d8cda3c 100644
+--- a/node_modules/ts-json-schema-generator/dist/src/AnnotationsReader/ExtendedAnnotationsReader.js
++++ b/node_modules/ts-json-schema-generator/dist/src/AnnotationsReader/ExtendedAnnotationsReader.js
+@@ -49,7 +49,7 @@ class ExtendedAnnotationsReader extends BasicAnnotationsReader_js_1.BasicAnnotat
+             .replace(/\r/g, "")
+             .trim();
+         const description = markdownDescription.replace(/(?<=[^\n])\n(?=[^\n*-])/g, " ").trim();
+-        return this.markdownDescription ? { description, markdownDescription } : { description };
++        return this.markdownDescription ? { description: markdownDescription } : { description };
+     }
+     getTypeAnnotation(node) {
+         const symbol = (0, symbolAtNode_js_1.symbolAtNode)(node);
+diff --git a/node_modules/ts-json-schema-generator/dist/src/SchemaGenerator.js b/node_modules/ts-json-schema-generator/dist/src/SchemaGenerator.js
+index e3b7761..93f914a 100644
+--- a/node_modules/ts-json-schema-generator/dist/src/SchemaGenerator.js
++++ b/node_modules/ts-json-schema-generator/dist/src/SchemaGenerator.js
+@@ -95,7 +95,7 @@ class SchemaGenerator {
+         children.reduce((definitions, child) => {
+             const name = child.getName();
+             if (!(name in definitions)) {
+-                definitions[name] = this.typeFormatter.getDefinition(child.getType());
++                definitions[name] = {...this.typeFormatter.getDefinition(child.getType()), title: name};
+             }
+             return definitions;
+         }, childDefinitions);
+diff --git a/node_modules/ts-json-schema-generator/src/AnnotationsReader/ExtendedAnnotationsReader.ts b/node_modules/ts-json-schema-generator/src/AnnotationsReader/ExtendedAnnotationsReader.ts
+index ba8fd57..806396c 100644
+--- a/node_modules/ts-json-schema-generator/src/AnnotationsReader/ExtendedAnnotationsReader.ts
++++ b/node_modules/ts-json-schema-generator/src/AnnotationsReader/ExtendedAnnotationsReader.ts
+@@ -57,7 +57,7 @@ export class ExtendedAnnotationsReader extends BasicAnnotationsReader {
+ 
+         const description = markdownDescription.replace(/(?<=[^\n])\n(?=[^\n*-])/g, " ").trim();
+ 
+-        return this.markdownDescription ? { description, markdownDescription } : { description };
++        return this.markdownDescription ? { description: markdownDescription } : { description };
+     }
+     private getTypeAnnotation(node: ts.Node): Annotations | undefined {
+         const symbol = symbolAtNode(node);

patches/typescript-json-schema+0.55.0.patch

@@ -1,26 +0,0 @@
-diff --git a/node_modules/typescript-json-schema/dist/typescript-json-schema.js b/node_modules/typescript-json-schema/dist/typescript-json-schema.js
-index 23cc6d1..221adc2 100644
---- a/node_modules/typescript-json-schema/dist/typescript-json-schema.js
-+++ b/node_modules/typescript-json-schema/dist/typescript-json-schema.js
-@@ -55,7 +55,7 @@ var crypto_1 = require("crypto");
- var ts = require("typescript");
- var path_equal_1 = require("path-equal");
- var vm = require("vm");
--var REGEX_FILE_NAME_OR_SPACE = /(\bimport\(".*?"\)|".*?")\.| /g;
-+var REGEX_FILE_NAME_OR_SPACE = /(\bimport\(".*?"(, \{ assert: \{ "resolution-mode": "(import|require)" \} \})?\)|".*?")\.| /g;// /(\bimport\(".*?"\)|".*?")\.| /g;
- var REGEX_TSCONFIG_NAME = /^.*\.json$/;
- var REGEX_TJS_JSDOC = /^-([\w]+)\s+(\S|\S[\s\S]*\S)\s*$/g;
- var REGEX_GROUP_JSDOC = /^[.]?([\w]+)\s+(\S|\S[\s\S]*\S)\s*$/g;
-diff --git a/node_modules/typescript-json-schema/typescript-json-schema.ts b/node_modules/typescript-json-schema/typescript-json-schema.ts
-index 5908567..c188383 100644
---- a/node_modules/typescript-json-schema/typescript-json-schema.ts
-+++ b/node_modules/typescript-json-schema/typescript-json-schema.ts
-@@ -9,7 +9,7 @@ export { Program, CompilerOptions, Symbol } from "typescript";
- 
- const vm = require("vm");
- 
--const REGEX_FILE_NAME_OR_SPACE = /(\bimport\(".*?"\)|".*?")\.| /g;
-+const REGEX_FILE_NAME_OR_SPACE = /(\bimport\(".*?"(, \{ assert: \{ "resolution-mode": "(import|require)" \} \})?\)|".*?")\.| /g;// /(\bimport\(".*?"\)|".*?")\.| /g;
- const REGEX_TSCONFIG_NAME = /^.*\.json$/;
- const REGEX_TJS_JSDOC = /^-([\w]+)\s+(\S|\S[\s\S]*\S)\s*$/g;
- const REGEX_GROUP_JSDOC = /^[.]?([\w]+)\s+(\S|\S[\s\S]*\S)\s*$/g;

src/backend/common/AbstractComponent.ts

@@ -1,6 +1,31 @@
-import { Logger } from "@foxxmd/logging";
+import { childLogger, Logger } from "@foxxmd/logging";
+import {
+    cacheFunctions,
+} from "@foxxmd/regex-buddy-core";
+import deepEqual from 'fast-deep-equal';
+import { Simulate } from "react-dom/test-utils";
+import { PlayObject } from "../../core/Atomic.js";
+import { buildTrackString, truncateStringToLength } from "../../core/StringUtils.js";
+
+import {
+    configPartsToStrongParts, countRegexes,
+    transformPlayUsingParts
+} from "../utils/PlayTransformUtils.js";
 import { hasNodeNetworkException } from "./errors/NodeErrors.js";
 import { hasUpstreamError } from "./errors/UpstreamError.js";
+import {
+    ConditionalSearchAndReplaceRegExp,
+    PlayTransformParts, PlayTransformPartsArray,
+    PlayTransformRules,
+    TRANSFORM_HOOK,
+    TransformHook
+} from "./infrastructure/Atomic.js";
+import { CommonClientConfig } from "./infrastructure/config/client/index.js";
+import { CommonSourceConfig } from "./infrastructure/config/source/index.js";
+import play = Simulate.play;
+import { WebhookPayload } from "./infrastructure/config/health/webhooks.js";
+import { AuthCheckError, BuildDataError, ConnectionCheckError, PostInitError, TransformRulesError } from "./errors/MSErrors.js";
+import { messageWithCauses, messageWithCausesTruncatedDefault } from "../utils/ErrorUtils.js";
 
 export default abstract class AbstractComponent {
     requiresAuth: boolean = false;
@@ -13,33 +38,79 @@ export default abstract class AbstractComponent {
 
     initializing: boolean = false;
 
+    config: CommonClientConfig | CommonSourceConfig;
+
+    transformRules!: PlayTransformRules;
+    regexCache!: ReturnType<typeof cacheFunctions>;
+
     logger: Logger;
+    componentLogger?: Logger;
+
+    protected constructor(config: CommonClientConfig | CommonSourceConfig) {
+        this.config = config;
+    }
+
+    public abstract notify(payload: WebhookPayload): Promise<void>;
+
+    protected abstract getIdentifier(): string;
+
+    initialize = async (options: {force?: boolean, notify?: boolean, notifyTitle?: string} = {}) => {
+
+        const {force = false, notify = false, notifyTitle = 'Init Error'} = options;
 
-    initialize = async () => {
         this.logger.debug('Attempting to initialize...');
         try {
             this.initializing = true;
-            await this.buildInitData();
-            await this.checkConnection();
-            await this.testAuth();
+            if(this.componentLogger === undefined) {
+                await this.buildComponentLogger();
+            }
+            await this.buildInitData(force);
+            this.buildTransformRules();
+            await this.checkConnection(force);
+            await this.testAuth(force);
             this.logger.info('Fully Initialized!');
             try {
                 await this.postInitialize();
             } catch (e) {
-                this.logger.warn(new Error('Error occurred during post-initialization hook but was caught', {cause: e}));
+                throw new PostInitError('Error occurred during post-initialization hook', {cause: e});
             }
             return true;
         } catch(e) {
-            this.logger.error(new Error('Initialization failed', {cause: e}));
-            return false;
+            if(notify) {
+                await this.notify({title: `${this.getIdentifier()} - ${notifyTitle}`, message: truncateStringToLength(500)(messageWithCausesTruncatedDefault(e)), priority: 'error'});
+            }
+            throw new Error('Initialization failed', {cause: e});
         } finally {
             this.initializing = false;
         }
     }
 
-    public async buildInitData() {
+    private async buildComponentLogger() {
+        await this.doBuildComponentLogger();
+        return;
+    }
+
+    protected async doBuildComponentLogger() {
+        return;
+    }
+
+    tryInitialize = async (options: {force?: boolean, notify?: boolean, notifyTitle?: string} = {}) => {
+        if(this.initializing) {
+            throw new Error(`Already trying to initialize, cannot attempt while an existing initialization attempt is running.`)
+        }
+        try {
+            return await this.initialize(options);
+        } catch (e) {
+            throw e;
+        }
+    }
+
+    public async buildInitData(force: boolean = false) {
         if(this.buildOK) {
-            return;
+            if(!force) {
+                return;
+            }
+            this.logger.debug('Build OK but step was forced');
         }
         try {
             const res = await this.doBuildInitData();
@@ -56,7 +127,7 @@ export default abstract class AbstractComponent {
             this.buildOK = true;
         } catch (e) {
             this.buildOK = false;
-            throw new Error('Building required data for initialization failed', {cause: e});
+            throw new BuildDataError('Building required data for initialization failed', {cause: e});
         }
     }
 
@@ -72,8 +143,88 @@ export default abstract class AbstractComponent {
         return;
     }
 
+    public buildTransformRules() {
+        try {
+            this.doBuildTransformRules();
+        } catch (e) {
+            this.buildOK = false;
+            throw new TransformRulesError('Could not build playTransform rules. Check your configuration is valid.', {cause: e});
+        }
+        try {
+            const ruleCount = countRegexes(this.transformRules);
+            this.regexCache = cacheFunctions(ruleCount);
+        } catch (e) {
+            this.logger.warn(new TransformRulesError('Failed to count number of rule regexes for caching but will continue will fallback to 100', {cause: e}));
+        }
+    }
 
-    public async checkConnection() {
+    protected doBuildTransformRules() {
+        const {
+            options: {
+                playTransform
+            } = {}
+        } = this.config;
+
+        if (playTransform === undefined) {
+            this.transformRules = {};
+            return;
+        }
+
+        const {
+            preCompare: preConfig,
+            compare: {
+                candidate: candidateConfig,
+                existing: existingConfig,
+            } = {},
+            postCompare: postConfig
+        } = playTransform;
+
+        let preCompare,
+            candidate,
+            existing,
+            postCompare;
+
+        try {
+            preCompare = configPartsToStrongParts(preConfig)
+        } catch (e) {
+            throw new Error('preCompare was not valid', {cause: e});
+        }
+
+        try {
+            candidate = configPartsToStrongParts(candidateConfig)
+        } catch (e) {
+            throw new Error('candidate was not valid', {cause: e});
+        }
+
+        try {
+            existing = configPartsToStrongParts(existingConfig)
+        } catch (e) {
+            throw new Error('existing was not valid', {cause: e});
+        }
+
+        try {
+            postCompare = configPartsToStrongParts(postConfig)
+        } catch (e) {
+            throw new Error('postCompare was not valid', {cause: e});
+        }
+
+        this.transformRules = {
+            preCompare,
+            compare: {
+                candidate,
+                existing,
+            },
+            postCompare,
+        }
+    }
+
+    public async checkConnection(force: boolean = false) {
+        if(this.connectionOK) {
+            if(!force) {
+                return;
+            }
+            this.logger.debug('Connection OK but step was forced')
+        }
         try {
             const res = await this.doCheckConnection();
             if (res === undefined) {
@@ -88,7 +239,7 @@ export default abstract class AbstractComponent {
             this.connectionOK = true;
         } catch (e) {
             this.connectionOK = false;
-            throw new Error('Communicating with upstream service failed', {cause: e});
+            throw new ConnectionCheckError('Communicating with upstream service failed', {cause: e});
         }
     }
 
@@ -108,13 +259,31 @@ export default abstract class AbstractComponent {
 
     canTryAuth = () => this.isUsable() && this.authGated() && this.authFailure !== true
 
+    canAuthUnattended = () => !this.authGated || !this.requiresAuthInteraction || (this.requiresAuthInteraction && !this.authFailure);
+
     protected doAuthentication = async (): Promise<boolean> => this.authed
 
     // default init function, should be overridden if auth stage is required
-    testAuth = async () => {
+    testAuth = async (force: boolean = false) => {
         if(!this.requiresAuth) {
             return;
         }
+        if(this.authed) {
+            if(!force) {
+                return;
+            }
+            this.logger.debug('Auth OK but step was forced');
+        }
+
+        if(this.authFailure) {
+            if(!force) {
+                if(this.requiresAuthInteraction) {
+                    throw new AuthCheckError('Authentication failure: Will not retry auth because user interaction is required for authentication');
+                }
+                throw new AuthCheckError('Authentication failure: Will not retry auth because authentication previously failed and must be reauthenticated');
+            }
+            this.logger.debug('Auth previously failed for non upstream/network reasons but retry is being forced');
+        }
 
         try {
             this.authed = await this.doAuthentication();
@@ -123,7 +292,7 @@ export default abstract class AbstractComponent {
             // only signal as auth failure if error was NOT either a node network error or a non-showstopping upstream error
             this.authFailure = !(hasNodeNetworkException(e) || hasUpstreamError(e, false));
             this.authed = false;
-            this.logger.error(new Error(`Authentication test failed!${this.authFailure === false ? ' Due to a network issue. Will retry authentication on next heartbeat.' : ''}`, {cause: e}));
+            throw new AuthCheckError(`Authentication test failed!${this.authFailure === false ? ' Due to a network issue. Will retry authentication on next heartbeat.' : ''}`, {cause: e});
         }
     }
 
@@ -146,4 +315,71 @@ export default abstract class AbstractComponent {
     protected async postInitialize(): Promise<void> {
         return;
     }
+
+    public transformPlay = (play: PlayObject, hookType: TransformHook, log?: boolean) => {
+
+        let logger: Logger;
+        const labels = ['Play Transform', hookType];
+        const getLogger = () => logger !== undefined ? logger : childLogger(this.logger, labels);
+
+        try {
+            let hook: PlayTransformPartsArray<ConditionalSearchAndReplaceRegExp> | undefined;
+
+            switch (hookType) {
+                case TRANSFORM_HOOK.preCompare:
+                    hook = this.transformRules.preCompare;
+                    break;
+                case TRANSFORM_HOOK.candidate:
+                    hook = this.transformRules.compare?.candidate;
+                    break;
+                case TRANSFORM_HOOK.existing:
+                    hook = this.transformRules.compare?.existing;
+                    break;
+                case TRANSFORM_HOOK.postCompare:
+                    hook = this.transformRules.postCompare;
+                    break;
+            }
+
+            if (hook === undefined) {
+                return play;
+            }
+
+            let transformedPlay: PlayObject = play;
+            const transformDetails: string[] = [];
+            for(const hookItem of hook) {
+                const newTransformedPlay = transformPlayUsingParts(transformedPlay, hookItem, {
+                    logger: getLogger,
+                    regex: {
+                        searchAndReplace: this.regexCache.searchAndReplace,
+                        testMaybeRegex: this.regexCache.testMaybeRegex,
+                    }
+                });
+                if(!deepEqual(newTransformedPlay, transformedPlay)) {
+                    transformDetails.push(buildTrackString(transformedPlay, {include: ['artist', 'track', 'album']}));
+                }
+                transformedPlay = newTransformedPlay;
+            }
+
+            if(transformDetails.length > 0) {
+                let transformStatements = [`Original: ${buildTrackString(play, {include: ['artist', 'track', 'album']})}`];
+                const shouldLog = log ?? this.config.options?.playTransform?.log ?? false;
+                if (shouldLog === true || shouldLog === 'all') {
+                    if(shouldLog === 'all') {
+                        transformStatements = transformStatements.concat(transformDetails.map(x => `=> ${x}`));
+                    } else {
+                        transformStatements.push(`=> ${transformDetails[transformDetails.length - 1]}`);
+                    }
+                    this.logger.debug({labels: [...labels, hookType]}, `Transform Pipeline:\n${transformStatements.join('\n')}`);
+                }
+            }
+            return transformedPlay;
+        } catch (e) {
+            getLogger().warn(new Error(`Unexpected error occurred, returning original play.`, {cause: e}));
+            return play;
+        }
+    }
+
+    public additionalApiData(): Record<string, any> {
+        return {};
+    }
 }

src/backend/common/errors/MSErrors.ts

@@ -0,0 +1,25 @@
+export abstract class NamedError extends Error {
+    public abstract name: string;
+}
+
+export abstract class StageError extends NamedError {}
+
+export class BuildDataError extends StageError {
+    name = 'Init Build Data';
+}
+
+export class TransformRulesError extends StageError {
+    name = 'Transform Rules';
+}
+
+export class ConnectionCheckError extends StageError {
+    name = 'Conenction Check';
+}
+
+export class AuthCheckError extends StageError {
+    name = 'Authentication Check';
+}
+
+export class PostInitError extends StageError {
+    name = 'Post Initialization';
+}

src/backend/common/infrastructure/Atomic.ts

@@ -1,9 +1,10 @@
 import { Logger } from '@foxxmd/logging';
+import { SearchAndReplaceRegExp } from "@foxxmd/regex-buddy-core";
 import { Dayjs } from "dayjs";
 import { Request, Response } from "express";
 import { NextFunction, ParamsDictionary, Query } from "express-serve-static-core";
 import { FixedSizeList } from 'fixed-size-list';
-import { PlayMeta, PlayObject } from "../../../core/Atomic.js";
+import { isPlayObject, PlayMeta, PlayObject } from "../../../core/Atomic.js";
 import TupleMap from "../TupleMap.js";
 
 export type SourceType =
@@ -14,15 +15,22 @@ export type SourceType =
     | 'jellyfin'
     | 'lastfm'
     | 'deezer'
+    | 'endpointlz'
+    | 'endpointlfm'
     | 'ytmusic'
     | 'mpris'
     | 'mopidy'
+    | 'musiccast'
     | 'listenbrainz'
     | 'jriver'
     | 'kodi'
     | 'webscrobbler'
     | 'chromecast'
-    | 'musikcube';
+    | 'musikcube'
+    | 'mpd'
+    | 'vlc'
+    | 'icecast'
+    | 'azuracast';
 
 export const sourceTypes: SourceType[] = [
     'spotify',
@@ -32,17 +40,28 @@ export const sourceTypes: SourceType[] = [
     'jellyfin',
     'lastfm',
     'deezer',
+    'endpointlz',
+    'endpointlfm',
     'ytmusic',
     'mpris',
     'mopidy',
+    'musiccast',
     'listenbrainz',
     'jriver',
     'kodi',
     'webscrobbler',
     'chromecast',
-    'musikcube'
+    'musikcube',
+    'mpd',
+    'vlc',
+    'icecast',
+    'azuracast'
 ];
 
+export const isSourceType = (data: string): data is SourceType => {
+    return sourceTypes.includes(data as SourceType);
+}
+
 export const lowGranularitySources: SourceType[] = ['subsonic', 'ytmusic'];
 
 export type ClientType =
@@ -54,6 +73,9 @@ export const clientTypes: ClientType[] = [
     'lastfm',
     'listenbrainz'
 ];
+export const isClientType = (data: string): data is ClientType => {
+    return clientTypes.includes(data as ClientType);
+}
 
 export type InitState = 0 | 1 | 2;
 export const NOT_INITIALIZED: InitState = 0;
@@ -70,6 +92,7 @@ export const readyStates: ReadyState[] = [NOT_READY, GETTING_READY, READY];
 export interface InternalConfig {
     localUrl: URL
     configDir: string
+    version: string
 
     logger: Logger
 }
@@ -97,17 +120,23 @@ export interface ConfigMeta {
 
 export type SourceData = (PlayObject | PlayerStateData);
 
-export interface PlayerStateData {
-    platformId: PlayPlatformId
+export interface PlayerStateData extends PlayerStateDataMaybePlay {
     play: PlayObject
+}
+
+export interface PlayerStateDataMaybePlay {
+    platformId: PlayPlatformId
+    /** The ID/Key for individual sessions on a device/platform */
+    sessionId?: string
+    play?: PlayObject
     status?: ReportedPlayerStatus
     position?: number
     timestamp?: Dayjs
 }
 
-export const asPlayerStateData = (obj: object): obj is PlayerStateData => {
-    return 'platformId' in obj && 'play' in obj;
-}
+export const asPlayerStateData = (obj: object): obj is PlayerStateData => asPlayerStateDataMaybePlay(obj) && 'play' in obj && isPlayObject(obj.play)
+
+export const asPlayerStateDataMaybePlay = (obj: object): obj is PlayerStateDataMaybePlay => 'platformId' in obj
 
 export interface FormatPlayObjectOptions {
     newFromSource?: boolean
@@ -238,3 +267,58 @@ export interface MdnsDeviceInfo {
 export type AbstractApiOptions = Record<any, any> & { logger: Logger }
 
 export type keyOmit<T, U extends keyof any> = T & { [P in U]?: never }
+
+export interface ConditionalSearchAndReplaceRegExp extends SearchAndReplaceRegExp{
+    when?: WhenConditionsConfig
+}
+
+export type ConditionalSearchAndReplaceTerm = Omit<ConditionalSearchAndReplaceRegExp, 'test'>
+
+export type SearchAndReplaceTerm = string | ConditionalSearchAndReplaceTerm;
+
+export type PlayTransformParts<T> = PlayTransformPartsAtomic<T[]> & { when?: WhenConditionsConfig };
+
+export type PlayTransformPartsArray<T> = PlayTransformParts<T>[];
+
+export type PlayTransformPartsConfig<T> = PlayTransformPartsArray<T> | PlayTransformParts<T>;
+
+export interface PlayTransformPartsAtomic<T> {
+    title?: T
+    artists?: T
+    album?: T
+}
+
+export interface PlayTransformHooksConfig<T> {
+    preCompare?: PlayTransformPartsConfig<T>
+    compare?: {
+        candidate?: PlayTransformPartsConfig<T>
+        existing?: PlayTransformPartsConfig<T>
+    }
+    postCompare?: PlayTransformPartsConfig<T>
+}
+
+export interface PlayTransformHooks<T> extends PlayTransformHooksConfig<T> {
+    preCompare?: PlayTransformPartsArray<T>
+    compare?: {
+        candidate?: PlayTransformPartsArray<T>
+        existing?: PlayTransformPartsArray<T>
+    }
+    postCompare?: PlayTransformPartsArray<T>
+}
+
+export type PlayTransformRules = PlayTransformHooks<ConditionalSearchAndReplaceRegExp>
+
+export type TransformHook = 'preCompare' | 'compare' | 'candidate' | 'existing' | 'postCompare';
+export const TRANSFORM_HOOK = {
+    preCompare: 'preCompare' as TransformHook,
+    candidate: 'candidate' as TransformHook,
+    existing: 'existing' as TransformHook,
+    postCompare: 'postCompare' as TransformHook,
+}
+export type PlayTransformConfig = PlayTransformHooksConfig<SearchAndReplaceTerm>;
+export type PlayTransformOptions = PlayTransformConfig & { log?: boolean | 'all' }
+
+export type WhenParts<T> = PlayTransformPartsAtomic<T>;
+
+export type WhenConditions<T> = WhenParts<T>[];
+export type WhenConditionsConfig = WhenConditions<string>;

src/backend/common/infrastructure/config/aioConfig.ts

@@ -5,6 +5,7 @@ import { RequestRetryOptions } from "./common.js";
 import { WebhookConfig } from "./health/webhooks.js";
 import { CommonSourceOptions, SourceRetryOptions } from "./source/index.js";
 import { SourceAIOConfig } from "./source/sources.js";
+import { ClientType, SourceType } from "../Atomic.js";
 
 
 export interface SourceDefaults extends CommonSourceOptions {
@@ -70,7 +71,22 @@ export interface AIOClientConfig {
     clients?: ClientAIOConfig[]
 }
 
+export interface AIOClientRelaxedConfig {
+    clientDefaults?: RequestRetryOptions
+    clients?: object[]
+}
+
 export interface AIOSourceConfig {
     sourceDefaults?: SourceRetryOptions
     sources?: SourceAIOConfig[]
 }
+
+export interface AIOSourceRelaxedConfig {
+    sourceDefaults?: SourceRetryOptions
+    sources?: object[]
+}
+
+export interface TypedConfig<T = string> {
+    type: T
+    // [key: string]: any
+}

src/backend/common/infrastructure/config/client/index.ts

@@ -1,3 +1,4 @@
+import { PlayTransformConfig, PlayTransformOptions } from "../../Atomic.js";
 import { CommonConfig, CommonData, RequestRetryOptions } from "../common.js";
 
 /**
@@ -30,18 +31,43 @@ export interface MatchLoggingOptions {
 export interface CommonClientData extends CommonData {
 }
 
-export interface CommonClientOptions extends RequestRetryOptions {
+export interface UpstreamRefreshOptions {
     /**
      * Try to get fresh scrobble history from client when tracks to be scrobbled are newer than the last scrobble found in client history
      * @default true
      * @examples [true]
      * */
     refreshEnabled?: boolean
+    /**
+     * Refresh scrobbled plays from upstream service if last refresh was at least X seconds ago
+     *
+     * **In most case this setting does NOT need to be changed.** The default value is sufficient for the majority of use-cases. Increasing this setting may increase upstream service load and slow down scrobbles.
+     *
+     * This setting should only be changed in specific scenarios where MS is handling multiple "relaying" client-services (IE lfm -> lz -> lfm) and there is the potential for a client to be out of sync after more than a few seconds.
+     *
+     * @examples [60]
+     * @default 60
+     * */
+    refreshStaleAfter?: number
 
     /**
-     * The number of tracks to retrieve on initial refresh (related to scrobbleBacklogCount). If not specified this is the maximum supported for the client.
+     * Minimum time (milliseconds) required to pass before upstream scrobbles can be refreshed.
+     *
+     * **In most case this setting does NOT need to be changed.** This will always be equal to or smaller than `refreshStaleAfter`.
+     *
+     * @default 5000
+     * @examples [5000]
+     * */
+    refreshMinInterval?: number
+
+    /**
+     * The number of tracks to retrieve on initial refresh (related to scrobbleBacklogCount). If not specified this is the maximum supported by the client in 1 API call.
      * */
     refreshInitialCount?: number
+}
+
+export interface CommonClientOptions extends RequestRetryOptions, UpstreamRefreshOptions {
+
     /**
      * Check client for an existing scrobble at the same recorded time as the "new" track to be scrobbled. If an existing scrobble is found this track is not track scrobbled.
      * @default true
@@ -55,7 +81,6 @@ export interface CommonClientOptions extends RequestRetryOptions {
 
         match?: MatchLoggingOptions
     }
-
     /**
      * Number of times MS should automatically retry scrobbles in dead letter queue
      *
@@ -63,6 +88,8 @@ export interface CommonClientOptions extends RequestRetryOptions {
      * @examples [1]
      * */
     deadLetterRetries?: number
+
+    playTransform?: PlayTransformOptions
 }
 
 export interface CommonClientConfig extends CommonConfig {

src/backend/common/infrastructure/config/common.ts

@@ -48,4 +48,32 @@ export interface PollingOptions {
      * @examples [30]
      * */
     maxInterval?: number
+
+    /**
+     * Number of seconds after which A Player is considered Stale
+     * 
+     * When Polling the source does not recieve data about a specific Player after X seconds it becomes Stale. When the Player becomes Stale:
+     * 
+     * * The current listening session is ended. If the Player becomes active again a new listening session is started (Player will miss `interval` seconds of listening)
+     * * If the player has an existing session w/ track then MS attempts to scrobble it
+     * 
+     * This option DOES NOT need to be set. It is automatically calculated as (`interval` * 3) when not defined.
+     */
+    staleAfter?: number
+
+    /**
+     * Number of seconds after which A Player is considered Orphaned
+     * 
+     * When Polling the source does not recieve data about a specific Player after X seconds it becomes Orphaned. When the Player becomes Orphaned:
+     * 
+     * * The current Player session is ended and the Player is removed from MS
+     * * MS attempts to scrobble, if the Player has an existing session w/ track
+     * 
+     * A Player should become Orphaned EQUAL TO OR AFTER it becomes Stale.
+     * 
+     * * This option DOES NOT need to be set. It is automatically calculated as (`interval` * 5) when not defined.
+     * * If it is set it must be equal to or larger than `staleAfter` or (`interval * 3`)
+     */
+     orphanedAfter?: number
 }
+

src/backend/common/infrastructure/config/source/azuracast.ts

@@ -0,0 +1,106 @@
+import { CommonSourceConfig, CommonSourceData, CommonSourceOptions, ManualListeningOptions } from "./index.js";
+
+export interface AzuraStationInfoResponse {
+    id: string
+    name: string
+    shortcode: string
+    is_public: boolean
+}
+
+export interface AzuraListenersResponse {
+    total: number
+    unique: number
+    current: number
+}
+
+export interface AzuraSongResponse {
+    id: string
+    text: string
+    artist: string
+    title: string
+    album: string
+    genre: string
+    isrc: string
+}
+
+export interface AzuraNowPlayingResponse {
+    sh_id: number
+    played_at: number
+    duration: number
+    streamer: string
+    elapsed: number
+    remaining: number
+    song: AzuraSongResponse
+}
+
+export interface AzuraLiveResponse {
+    is_live: boolean
+    streamer_name: string
+    broadcast_start: number | null
+}
+
+export interface AzuraStationResponse {
+    is_online: boolean
+    station: AzuraStationInfoResponse
+    listeners: AzuraListenersResponse
+    now_playing: AzuraNowPlayingResponse
+}
+
+
+export interface AzuracastData extends CommonSourceData {
+    /**
+     * Base URL of the Azuracast instance
+     *
+     * This does NOT include the station. If a station is included it will be ignored. Use `station` field to specify station, if necessary
+     *
+     *
+     * @examples ["https://radio.mydomain.tld", "http://localhost:80"]
+     * */
+    url: string
+
+    /**
+     * The specific station to monitor
+     * 
+     * Scrobbling will only occur if any of the monitor conditions are met AND the station is ONLINE.
+     * 
+     * To monitor multiple stations create a Source for each station.
+     *
+     * @examples ["my-station-1"]
+     * */
+    station: string
+
+    /**
+     * Only activate scrobble monitoring if station
+     * 
+     * * `true` => has any current listeners
+     * * `number` => has EQUAL TO or MORE THAN X number of listeners
+     * 
+     */
+    monitorWhenListeners?: boolean | number
+
+    /**
+     * Only activate scrobble monitoring if station has a live DJ/Streamer
+     * 
+     * @default true
+     */
+    monitorWhenLive?: boolean
+
+    /**
+     * API Key used to access data about private streams
+     *
+     * https://www.azuracast.com/docs/developers/apis/#api-authentication
+     * */
+    apiKey?: string
+}
+
+export interface AzuracastSourceoptions extends CommonSourceOptions, ManualListeningOptions {
+    
+}
+
+export interface AzuracastSourceConfig extends CommonSourceConfig {
+    data: AzuracastData
+}
+
+export interface AzuracastSourceAIOConfig extends AzuracastSourceConfig {
+    type: 'azuracast'
+}

src/backend/common/infrastructure/config/source/deezer.ts

@@ -19,7 +19,7 @@ export interface DeezerData extends CommonSourceData {
      * @default "http://localhost:9078/deezer/callback"
      * @examples ["http://localhost:9078/deezer/callback"]
      * */
-    redirectUri: string
+    redirectUri?: string
     /**
      * optional, how long to wait before calling spotify for new tracks (in seconds)
      *

src/backend/common/infrastructure/config/source/endpointlfm.ts

@@ -0,0 +1,25 @@
+import { CommonSourceConfig, CommonSourceData } from "./index.js";
+
+export interface LastFMEndpointData extends CommonSourceData {
+    /**
+     * The URL ending that should be used to identify scrobbles for this source
+     *
+     * If you are using multiple Last.fm endpoint sources (scrobbles for many users) you can use a slug to match Sources with individual users/origins
+     *
+     * Example:
+     *
+     * * slug: 'usera' => API URL: http://localhost:9078/api/lastfm/usera
+     * * slug: 'originb' => API URL: http://localhost:9078/api/lastfm/originb
+     *
+     * If no slug is found from an extension's incoming webhook event the first Last.fm source without a slug will be used
+     * */
+    slug?: string | null
+}
+
+export interface LastFMEndpointSourceConfig extends CommonSourceConfig {
+    data?: LastFMEndpointData
+}
+
+export interface LastFMEndpointSourceAIOConfig extends LastFMEndpointSourceConfig {
+    type: 'endpointlfm'
+}

src/backend/common/infrastructure/config/source/endpointlz.ts

@@ -0,0 +1,32 @@
+import { CommonSourceConfig, CommonSourceData } from "./index.js";
+
+export interface ListenbrainzEndpointData extends CommonSourceData {
+    /**
+     * The URL ending that should be used to identify scrobbles for this source
+     *
+     * If you are using multiple Listenbrainz endpoint sources (scrobbles for many users) you can use a slug to match Sources with individual users/origins
+     *
+     * Example:
+     *
+     * * slug: 'usera' => API URL: http://localhost:9078/api/listenbrainz/usera
+     * * slug: 'originb' => API URL: http://localhost:9078/api/listenbrainz/originb
+     *
+     * If no slug is found from an extension's incoming webhook event the first Listenbrainz source without a slug will be used
+     * */
+    slug?: string | null
+
+    /**
+     * If an LZ submission request contains this token in the Authorization Header it will be used to match the submission with this Source
+     *
+     * See: https://listenbrainz.readthedocs.io/en/latest/users/api/index.html#add-the-user-token-to-your-requests
+     * */
+    token?: string | null
+}
+
+export interface ListenbrainzEndpointSourceConfig extends CommonSourceConfig {
+    data?: ListenbrainzEndpointData
+}
+
+export interface ListenbrainzEndpointSourceAIOConfig extends ListenbrainzEndpointSourceConfig {
+    type: 'endpointlz'
+}

src/backend/common/infrastructure/config/source/icecast.ts

@@ -0,0 +1,47 @@
+import { CommonSourceConfig, CommonSourceData, CommonSourceOptions, ManualListeningOptions } from "./index.js";
+
+
+export interface IcecastMetadata {
+    icy?: {
+        /** Title of the ICY metadata update, usually Artist - Title */
+        StreamTitle?: string
+        /** URL of the ICY metadata update, usually album art */
+        StreamUrl?: string
+    }
+    ogg?: {
+        /** Title of the OGG metadata update, usually Artist - Title */
+        TITLE?: string
+        ALBUM?: string
+        ARTIST?: string
+    }
+}
+
+export type IcecastSource = 'icy' | 'ogg' | 'icestats' | 'stats' | 'sevenhtml' | 'nextsongs';
+
+export interface IcecastOptions {
+    sources?: IcecastSource[]
+    icestatsEndpoint?: string
+    statsEndpoint?: string
+    nextsongsEndpoint?: string
+    sevenhtmlEndpoint?: string
+    icyMetaInt?: number
+}
+
+export interface IcecastData extends CommonSourceData, IcecastOptions {
+    /**
+     * The Icecast stream URL
+     * */
+    url: string
+}
+
+export interface IcecastSourceOptions extends CommonSourceOptions, ManualListeningOptions {
+}
+
+export interface IcecastSourceConfig extends CommonSourceConfig {
+    data: IcecastData
+    options?: IcecastSourceOptions
+}
+
+export interface IcecastSourceAIOConfig extends IcecastSourceConfig {
+    type: 'icecast'
+}

src/backend/common/infrastructure/config/source/index.ts

@@ -1,3 +1,5 @@
+import { FileLogOptions, LogLevel } from "@foxxmd/logging";
+import { PlayTransformConfig, PlayTransformOptions } from "../../Atomic.js";
 import { CommonConfig, CommonData, RequestRetryOptions } from "../common.js";
 
 export interface SourceRetryOptions extends RequestRetryOptions {
@@ -41,8 +43,8 @@ export interface ScrobbleThresholds {
 
 export interface CommonSourceOptions extends SourceRetryOptions {
     /**
-     * If this source has INGRESS to MS (sends a payload, rather than MS GETTING requesting a payload)
-     * then setting this option to true will make MS log the payload JSON to DEBUG output
+     * * If this source has INGRESS to MS (sends a payload, rather than MS GETTING requesting a payload) then setting this option to true will make MS log the payload JSON to DEBUG output
+     * * If this source is POLLING then it will log the raw data for each unique track/response the first time it is seen
      *
      * @default false
      * @examples [false]
@@ -71,6 +73,13 @@ export interface CommonSourceOptions extends SourceRetryOptions {
      * */
     logPlayerState?: boolean
 
+    /**
+     * **Exprimental:** Log to a separate file for this Source.
+     * 
+     * Useful for debugging long-running Sources
+     */
+    logToFile?: true | LogLevel | FileLogOptions
+
     /**
      * If this source
      *
@@ -96,6 +105,17 @@ export interface CommonSourceOptions extends SourceRetryOptions {
      * * If not specified it defaults to the maximum number of listens the source API supports
      * */
     scrobbleBacklogCount?: number
+
+    playTransform?: PlayTransformOptions
+}
+
+export interface ManualListeningOptions {
+    /** 
+     * For Sources that support manual listening, should MS default to scrobbling when no user interaction has occurred?
+     * 
+     * If not specified MS will use a Source's specific behavior, see Source's documentation.
+     */
+    systemScrobble?: boolean
 }
 
 export interface CommonSourceData extends CommonData {

src/backend/common/infrastructure/config/source/jellyfin.ts

@@ -1,4 +1,8 @@
-import { CommonSourceConfig, CommonSourceData } from "./index.js";
+import { CommonSourceConfig, CommonSourceData, CommonSourceOptions } from "./index.js";
+import {
+    // @ts-expect-error weird typings?
+    CollectionType
+} from "@jellyfin/sdk/lib/generated-client/index.js";
 
 export interface JellyData extends CommonSourceData {
     /**
@@ -19,6 +23,75 @@ export interface JellyData extends CommonSourceData {
     servers?: string | string[]
 }
 
+export interface JellyApiData extends CommonSourceData {
+    /**
+     * HOST:PORT of the Jellyfin server to connect to
+     * */
+    url: string
+    /**
+     * The username of the user to authenticate for or track scrobbles for
+     * */
+    user: string
+    /**
+     * Password of the username to authenticate for
+     *
+     * Required if `apiKey` is not provided.
+     * */
+    password?: string
+    /**
+     * API Key to authenticate with.
+     *
+     * Required if `password` is not provided.
+     * */
+    apiKey?: string
+
+    /**
+     * Only scrobble for specific users (case-insensitive)
+     *
+     * If `true` MS will scrobble activity from all users
+     * */
+    usersAllow?: string | true | string[]
+    /**
+     * Do not scrobble for these users (case-insensitive)
+     * */
+    usersBlock?: string | string[]
+
+    /**
+     * Only scrobble if device or application name contains strings from this list (case-insensitive)
+     * */
+    devicesAllow?: string | string[]
+    /**
+     * Do not scrobble if device or application name contains strings from this list (case-insensitive)
+     * */
+    devicesBlock?: string | string[]
+
+    /**
+     * Only scrobble if library name contains string from this list (case-insensitive)
+     * */
+    librariesAllow?: string | string[]
+    /**
+     * Do not scrobble if library name contains strings from this list (case-insensitive)
+     * */
+    librariesBlock?: string | string[]
+
+    /**
+     * Allow MS to scrobble audio media in libraries classified other than 'music'
+     * 
+     * `librariesAllow` will achieve the same result as this but this is more convenient if you do not want to explicitly list every library name or are only using `librariesBlock`
+     */
+    additionalAllowedLibraryTypes?: CollectionType[]
+
+    /**
+    * Force media with a type of "Unknown" to be counted as Audio
+    * 
+    * @default false
+    */
+    allowUnknown?: boolean
+}
+
+export interface JellyApiOptions extends CommonSourceOptions {
+}
+
 export interface JellySourceConfig extends CommonSourceConfig {
     data: JellyData
 }
@@ -26,3 +99,15 @@ export interface JellySourceConfig extends CommonSourceConfig {
 export interface JellySourceAIOConfig extends JellySourceConfig {
     type: 'jellyfin'
 }
+
+export interface JellyApiSourceConfig extends CommonSourceConfig {
+    data: JellyApiData
+    options: JellyApiOptions
+}
+
+export interface JellyApiSourceAIOConfig extends JellyApiSourceConfig {
+    type: 'jellyfin'
+}
+
+
+export type JellyfinCompatConfig = JellyApiSourceConfig | JellySourceConfig;

src/backend/common/infrastructure/config/source/mpd.ts

@@ -0,0 +1,70 @@
+import { CommonSourceConfig, CommonSourceData, CommonSourceOptions } from "./index.js";
+
+export interface MPDData extends CommonSourceData {
+    /**
+     * URL:PORT of the MPD server to connect to
+     *
+     * To use this you must have TCP connections enabled for your MPD server https://mpd.readthedocs.io/en/stable/user.html#client-connections
+     *
+     * @examples ["localhost:6600"]
+     * @default "localhost:6600"
+     * */
+    url?: string
+
+    /**
+     * If using socket specify the path instead of url.
+     *
+     * trailing `~` is replaced by your home directory
+     * */
+    path?: string
+
+    /**
+     * Password for the server, if set https://mpd.readthedocs.io/en/stable/user.html#permissions-and-passwords
+     * */
+    password?: string
+
+}
+
+export interface MPDSourceOptions extends CommonSourceOptions {
+    //disableDiscovery?: boolean
+}
+
+export interface MPDSourceConfig extends CommonSourceConfig {
+    data: MPDData
+    options: MPDSourceOptions
+}
+
+export interface MPDSourceAIOConfig extends MPDSourceConfig {
+    type: 'mpd'
+}
+
+export type PlayerState = 'play' | 'stop' | 'pause';
+
+export interface StatusResponse {
+    state: PlayerState
+    /**
+     * Position within the current song in seconds
+     * */
+    elapsed?: number
+    /**
+     * Duration of the current song in seconds
+     * */
+    duration?: number
+    error?: string
+}
+
+export interface CurrentSongResponse {
+    file: string
+    time: number
+    name?: string
+    performer?: string
+    artist?: string
+    album?: string
+    albumartist?: string
+    title?: string
+    musicbrainz_albumartistid?: string
+    musicbrainz_albumid?: string
+    musicbrainz_artistid?: string
+    musicbrainz_releasetrackid?: string
+    musicbrainz_trackid?: string
+}

src/backend/common/infrastructure/config/source/musiccast.ts

@@ -0,0 +1,87 @@
+import { REPORTED_PLAYER_STATUSES, ReportedPlayerStatus } from "../../Atomic.js";
+import { CommonSourceConfig, CommonSourceData } from "./index.js";
+
+export type PlaybackStatus = 'play' | 'stop' | 'pause' | 'fast_reverse' | 'fast_forward'
+
+export interface MusicCastResponse {
+    response_code: number
+}
+
+export interface DeviceInfoResponse extends MusicCastResponse {
+    model_name: string
+    device_id: string
+    system_version: number
+    api_version: number
+}
+
+export interface DeviceStatusResponse extends MusicCastResponse {
+    power: 'on' | 'standby'
+}
+
+/** use with /netusb/getPlayInfo or /cd/getPlayInfo */
+export interface PlayInfoCDResponse extends MusicCastResponse {
+    device_status: 'open' | 'close' | 'ready' | 'not_ready'
+    playback: 'play' | 'stop' | 'pause' | 'fast_reverse' | 'fast_forward'
+    /** in seconds */
+    play_time: number
+    /** in seconds */
+    total_time: number
+    artist: string
+    album: string
+    track: string
+}
+
+export interface PlayInfoNetResponse extends PlayInfoCDResponse {
+    input: string
+}
+
+export const MusicCastResponseCodes = new Map<number, string>([
+    [0, 'Success'],
+    [1, 'Initializing'],
+    [2, 'Internal Error'],
+    [3, 'Invalid Request'],
+    [4, 'Invalid Parameter'],
+    [5, 'Guarded (Unable to setup in current status)'],
+    [6, 'Time out'],
+    [100, 'Access Error'],
+    [101, 'Other Error'],
+    [107, 'Service Maintenance'],
+    [109, 'License Error'],
+    [110, 'Read Only Mode'],
+    [112, 'Access Denied'],
+    [115, 'Simultaneous logins has reached the upper limit'],
+    [200, 'Linking in progress'],
+    [201, 'Unlinking in progress']
+]);
+
+export const playbackToReportedStatus = (pb: PlaybackStatus): ReportedPlayerStatus => {
+    switch(pb) {
+        case 'play':
+        case 'fast_forward':
+        case 'fast_reverse':
+            return REPORTED_PLAYER_STATUSES.playing;
+        case 'pause':
+            return REPORTED_PLAYER_STATUSES.paused;
+        case 'stop':
+            return REPORTED_PLAYER_STATUSES.stopped;
+        default:
+            return REPORTED_PLAYER_STATUSES.unknown;
+    }
+}
+
+export interface MusicCastData extends CommonSourceData {
+    /**
+     * The host or URL of the YamahaExtendedControl endpoint to use
+     *
+     * @examples [["192.168.0.101","http://192.168.0.101/YamahaExtendedControl"]]
+     * */
+    url: string
+}
+
+export interface MusicCastSourceConfig extends CommonSourceConfig {
+    data: MusicCastData
+}
+
+export interface MusicCastSourceAIOConfig extends MusicCastSourceConfig {
+    type: 'musiccast'
+}

src/backend/common/infrastructure/config/source/plex.ts

@@ -1,4 +1,5 @@
-import { CommonSourceConfig, CommonSourceData } from "./index.js";
+import { PollingOptions } from "../common.js";
+import { CommonSourceConfig, CommonSourceData, CommonSourceOptions } from "./index.js";
 
 export interface PlexSourceData extends CommonSourceData {
     /**
@@ -34,3 +35,54 @@ export interface PlexSourceConfig extends CommonSourceConfig {
 export interface PlexSourceAIOConfig extends PlexSourceConfig {
     type: 'plex'
 }
+
+export interface PlexApiData extends CommonSourceData, PollingOptions {
+    token?: string
+    /**
+     * http(s)://HOST:PORT of the Plex server to connect to
+     * */
+    url: string
+
+        /**
+     * Only scrobble for specific users (case-insensitive)
+     *
+     * If `true` MS will scrobble activity from all users
+     * */
+        usersAllow?: string | true | string[]
+        /**
+         * Do not scrobble for these users (case-insensitive)
+         * */
+        usersBlock?: string | string[]
+    
+        /**
+         * Only scrobble if device or application name contains strings from this list (case-insensitive)
+         * */
+        devicesAllow?: string | string[]
+        /**
+         * Do not scrobble if device or application name contains strings from this list (case-insensitive)
+         * */
+        devicesBlock?: string | string[]
+    
+        /**
+         * Only scrobble if library name contains string from this list (case-insensitive)
+         * */
+        librariesAllow?: string | string[]
+        /**
+         * Do not scrobble if library name contains strings from this list (case-insensitive)
+         * */
+        librariesBlock?: string | string[]
+}
+
+export interface PlexApiOptions extends CommonSourceOptions {
+}
+
+export interface PlexApiSourceConfig extends CommonSourceConfig {
+    data: PlexApiData
+    options: PlexApiOptions
+}
+
+export interface PlexApiSourceAIOConfig extends PlexApiSourceConfig {
+    type: 'plex'
+}
+
+export type PlexCompatConfig = PlexApiSourceConfig | PlexSourceConfig;

src/backend/common/infrastructure/config/source/sources.ts

@@ -1,28 +1,39 @@
+import { AzuracastSourceAIOConfig, AzuracastSourceConfig } from "./azuracast.js";
 import { ChromecastSourceAIOConfig, ChromecastSourceConfig } from "./chromecast.js";
+import { ListenbrainzEndpointSourceAIOConfig, ListenbrainzEndpointSourceConfig } from "./endpointlz.js";
+import { LastFMEndpointSourceAIOConfig, LastFMEndpointSourceConfig } from "./endpointlfm.js";
 import { DeezerSourceAIOConfig, DeezerSourceConfig } from "./deezer.js";
-import { JellySourceAIOConfig, JellySourceConfig } from "./jellyfin.js";
+import { JellyApiSourceAIOConfig, JellyApiSourceConfig, JellySourceAIOConfig, JellySourceConfig } from "./jellyfin.js";
 import { JRiverSourceAIOConfig, JRiverSourceConfig } from "./jriver.js";
 import { KodiSourceAIOConfig, KodiSourceConfig } from "./kodi.js";
 import { LastFmSouceAIOConfig, LastfmSourceConfig } from "./lastfm.js";
 import { ListenBrainzSourceAIOConfig, ListenBrainzSourceConfig } from "./listenbrainz.js";
 import { MopidySourceAIOConfig, MopidySourceConfig } from "./mopidy.js";
+import { MPDSourceAIOConfig, MPDSourceConfig } from "./mpd.js";
 import { MPRISSourceAIOConfig, MPRISSourceConfig } from "./mpris.js";
 import { MusikcubeSourceAIOConfig, MusikcubeSourceConfig } from "./musikcube.js";
-import { PlexSourceAIOConfig, PlexSourceConfig } from "./plex.js";
+import { MusicCastSourceConfig, MusicCastSourceAIOConfig } from "./musiccast.js";
+import { PlexSourceAIOConfig, PlexSourceConfig, PlexApiSourceConfig, PlexApiSourceAIOConfig } from "./plex.js";
 import { SpotifySourceAIOConfig, SpotifySourceConfig } from "./spotify.js";
 import { SubsonicSourceAIOConfig, SubSonicSourceConfig } from "./subsonic.js";
 import { TautulliSourceAIOConfig, TautulliSourceConfig } from "./tautulli.js";
+import { VLCSourceAIOConfig, VLCSourceConfig } from "./vlc.js";
 import { WebScrobblerSourceAIOConfig, WebScrobblerSourceConfig } from "./webscrobbler.js";
 import { YTMusicSourceAIOConfig, YTMusicSourceConfig } from "./ytmusic.js";
+import { IcecastSourceAIOConfig, IcecastSourceConfig } from "./icecast.js";
 
 
 export type SourceConfig =
     SpotifySourceConfig
     | PlexSourceConfig
+    | PlexApiSourceConfig
     | TautulliSourceConfig
     | DeezerSourceConfig
+    | ListenbrainzEndpointSourceConfig
+    | LastFMEndpointSourceConfig
     | SubSonicSourceConfig
     | JellySourceConfig
+    | JellyApiSourceConfig
     | LastfmSourceConfig
     | YTMusicSourceConfig
     | MPRISSourceConfig
@@ -32,15 +43,24 @@ export type SourceConfig =
     | KodiSourceConfig
     | WebScrobblerSourceConfig
     | ChromecastSourceConfig
-    | MusikcubeSourceConfig;
+    | MusikcubeSourceConfig
+    | MusicCastSourceConfig
+    | MPDSourceConfig
+    | VLCSourceConfig
+    | IcecastSourceConfig
+    | AzuracastSourceConfig;
 
 export type SourceAIOConfig =
     SpotifySourceAIOConfig
     | PlexSourceAIOConfig
+    | PlexApiSourceAIOConfig
     | TautulliSourceAIOConfig
     | DeezerSourceAIOConfig
+    | ListenbrainzEndpointSourceAIOConfig
+    | LastFMEndpointSourceAIOConfig
     | SubsonicSourceAIOConfig
     | JellySourceAIOConfig
+    | JellyApiSourceAIOConfig
     | LastFmSouceAIOConfig
     | YTMusicSourceAIOConfig
     | MPRISSourceAIOConfig
@@ -50,4 +70,9 @@ export type SourceAIOConfig =
     | KodiSourceAIOConfig
     | WebScrobblerSourceAIOConfig
     | ChromecastSourceAIOConfig
-    | MusikcubeSourceAIOConfig;
+    | MusikcubeSourceAIOConfig
+    | MusicCastSourceAIOConfig
+    | MPDSourceAIOConfig
+    | VLCSourceAIOConfig
+    | IcecastSourceAIOConfig
+    | AzuracastSourceAIOConfig;

src/backend/common/infrastructure/config/source/spotify.ts

@@ -20,7 +20,7 @@ export interface SpotifySourceData extends CommonSourceData, PollingOptions {
      * @default "http://localhost:9078/callback"
      * @examples ["http://localhost:9078/callback"]
      * */
-    redirectUri: string
+    redirectUri?: string
     /**
      * How long to wait before polling the source API for new tracks (in seconds)
      *

src/backend/common/infrastructure/config/source/vlc.ts

@@ -0,0 +1,72 @@
+import { VlcMeta } from "vlc-client/dist/Types.js";
+import { PollingOptions } from "../common.js";
+import { CommonSourceConfig, CommonSourceData, CommonSourceOptions } from "./index.js";
+
+export interface VLCData extends CommonSourceData, PollingOptions {
+    /**
+     * URL:PORT of the VLC server to connect to
+     *
+     * To use this you must have the Web (http) interface module enabled and a password set https://foxxmd.github.io/multi-scrobbler/docs/configuration#vlc
+     *
+     * @examples ["localhost:8080"]
+     * @default "localhost:8080"
+     * */
+    url?: string
+
+    /**
+     * Password for the server
+     * */
+    password: string
+
+}
+
+export interface VLCSourceOptions extends CommonSourceOptions {
+    /** A list of regular expressions to use to extract metadata (title, album, artist) from a filename
+     *
+     * Used when VLC reports only the filename for the current audio track
+     * */
+    filenamePatterns?: string | string[]
+    /**
+     * Log to DEBUG when a filename-only track is matched or not matched by filenamePatterns
+     *
+     * @default false
+     * */
+    logFilenamePatterns?: boolean
+    /**
+     * Dump all the metadata VLC reports for an audio track to DEBUG.
+     *
+     * Use this if reporting an issue with VLC not correctly capturing metadata for a track.
+     *
+     * @default false
+     * */
+    dumpVlcMetadata?: boolean
+}
+
+export interface VLCSourceConfig extends CommonSourceConfig {
+    data: VLCData
+    options?: VLCSourceOptions
+}
+
+export interface VLCSourceAIOConfig extends VLCSourceConfig {
+    type: 'vlc'
+}
+
+export type PlayerState = 'playing' | 'stopped' | 'paused';
+
+// if not provided the value is an EMPTY STRING or undefined
+export interface VlcAudioMeta extends VlcMeta {
+    track_id?: string
+    date?: string
+    description?: string
+    album?: string
+    genre?: string
+    title?: string
+    artist?: string
+    /** alt for artist */
+    Writer?: string
+    ALBUMARTIST?: string
+    artwork_url?: string
+    StreamTitle?: string
+    StreamArtist?: string
+    StreamAlbum?: string
+}