Merge branch 'develop'

Improve YTM experience

.dockerignore

@@ -2,12 +2,24 @@
 node_modules
 npm-debug.log
 Dockerfile
+*.Dockerfile
 .dockerignore
 .gitignore
+.github
 .git
-config/currentCreds.json
 *.log
-config/maloja.json
-config/spotify.json
-config/config.json
+.idea
+config/*.json
+config/*.bak
+config/*.p8
 /docs
+/logs
+.flatpak-builder
+**/generated-sources.*
+flatpak/.flatpak-builder
+docsite/build
+docsite/node_modules
+docsite/.docusaurus
+docsite/.cache-loader
+build
+*.secrets

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+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/act/README.md

@@ -0,0 +1,14 @@
+Testing GH Actions with [ACT]
+
+### Test Branch Push
+
+```shell
+act -W '.github/act/actTest.yml' -e '.github/act/actBranchEvent.json'
+```
+
+
+### Test Tag Push
+
+```shell
+act -W '.github/act/actTest.yml' -e '.github/act/actTagEvent.json'
+```

.github/act/actBranchEvent.json

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

.github/act/actTagEvent.json

@@ -0,0 +1,5 @@
+{
+  "ref": "refs/tags/0.8.0",
+  "ref_name": "0.8.0",
+  "sha": "0a1a94d9ad4efa373f8d34aace5e7f0a3fff42ad"
+}

.github/act/actTest.yml

@@ -0,0 +1,104 @@
+name: Publish Docker image to Dockerhub
+
+on:
+  push:
+    branches:
+      - 'master'
+      - 'develop'
+    tags:
+      - '*.*.*'
+    # don't trigger if just updating docs
+    paths-ignore:
+      - '**.md'
+  # 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
+#  release:
+#    types: [ published ]
+
+jobs:
+
+  test:
+    name: Build and push container images
+    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
+
+      - name: Debug
+        run: echo $JSON
+        env:
+          JSON: ${{ toJSON(github) }}
+
+      - name: Set git state to ENV
+        id: vars
+        # 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: 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
+          #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 $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: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+#      - 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: false
+          tags: mstest:latest
+          #tags: ${{ steps.meta.outputs.tags }}
+          #labels: ${{ steps.meta.outputs.labels }}
+          #platforms: ${{ matrix.platforms }}

.github/pull_request_template.md

@@ -0,0 +1,20 @@
+## 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
+
+Please delete options that are not relevant.
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] This change requires a documentation update
+
+## Describe your changes
+
+
+
+## Issue number and link, if applicable
+

.github/workflows/dockerhub.yml

@@ -1,49 +0,0 @@
-name: Publish Docker image to Dockerhub
-
-on:
-  push:
-    branches:
-      - 'master'
-      - 'develop'
-    tags:
-      - '*.*.*'
-    # don't trigger if just updating docs
-    paths-ignore:
-      - '**.md'
-
-jobs:
-  push_to_registry:
-    name: Push Docker image to Docker Hub
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out the repo
-        uses: actions/checkout@v2
-      
-      - name: Log in to Docker Hub
-        if: github.event_name != 'pull_request'
-        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
-        with:
-          username: ${{ secrets.DOCKER_USERNAME }}
-          password: ${{ secrets.DOCKER_PASSWORD }}
-      
-      - name: Extract metadata (tags, labels) for Docker
-        id: meta
-        uses: docker/metadata-action@v3
-        with:
-          images: foxxmd/multi-scrobbler
-          # generate Docker tags based on the following events/attributes
-          tags: |
-            type=raw,value=latest,enable=${{ endsWith(github.ref, 'master') }}
-            type=ref,event=branch,enable=${{ !endsWith(github.ref, 'master') }}
-            type=semver,pattern={{version}}
-          flavor: |
-            latest=false
-      
-      - name: Build and push Docker image
-        uses: docker/build-push-action@v2
-        with:
-          context: .
-          push: ${{ github.event_name != 'pull_request' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-

.github/workflows/docsDeploy.yml

@@ -0,0 +1,48 @@
+name: Deploy to GitHub Pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - master
+      - developDocs
+    # 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
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: ./docsite
+      - name: Build website
+        env:
+          ANALYTICS: ${{ vars.ANALYTICS }}
+          ANALYTICS_DOMAIN: ${{ vars.ANALYTICS_DOMAIN }}
+          DOCS_BASE: '/multi-scrobbler'
+        run: npm run build
+        working-directory: ./docsite
+
+      # Popular action to deploy to GitHub Pages:
+      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Build output to publish to the `gh-pages` branch:
+          publish_dir: ./docsite/build
+          # The following lines assign commit authorship to the official
+          # GH-Actions bot for deploys to `gh-pages` branch:
+          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
+          # The GH actions bot is used by default if you didn't specify the two fields.
+          # You can swap them out with your own user credentials.
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

.github/workflows/packagesDeleteUntagged.yml

@@ -0,0 +1,21 @@
+name: Delete Untagged Packages
+on:
+  schedule:
+    - cron: '30 1 * * 0'
+  workflow_run:
+    workflows: ["Publish Docker image to Dockerhub"]
+    types:
+      - completed
+  workflow_dispatch:
+jobs:
+  delete-untagged:
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+    steps:
+      - uses: dataaxiom/ghcr-cleanup-action@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+# maybe set up for PR close later
+# https://github.com/dataaxiom/ghcr-cleanup-action?tab=readme-ov-file#delete-image-when-pull-request-is-closed

.github/workflows/pr.yml

@@ -0,0 +1,122 @@
+name: PR Workflow
+
+on:
+  pull_request_target:
+    types:
+      - labeled
+      - synchronize
+      - reopened
+      - opened
+    branches:
+      - 'develop'
+
+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
+
+  release-snapshot:
+    name: Release snapshot
+    runs-on: ubuntu-latest
+    needs: test
+    if: contains(github.event.pull_request.labels.*.name, 'safe to test')
+    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'
+    steps:
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in 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: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            foxxmd/multi-scrobbler
+            ghcr.io/foxxmd/multi-scrobbler
+          tags: |
+            type=ref,event=pr,suffix=${{ matrix.suffix }}
+          flavor: |
+            latest=false
+
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - 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
+    runs-on: ubuntu-latest
+    needs: release-snapshot
+    if: contains(github.event.pull_request.labels.*.name, 'safe to test')
+    steps:
+      - name: Create comment
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          recreate: true
+          header: "pr-release"
+          message: |
+            #### :package: A new release has been made for this pull request.
+
+            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.
+
+            > Latest commit: ${{ github.event.pull_request.head.sha }}

.github/workflows/publishImage.yml

@@ -0,0 +1,128 @@
+name: Publish Docker image to Dockerhub
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - 'master'
+      - 'develop'
+    tags:
+      - '*.*.*'
+    # don't trigger if just updating docs
+    paths-ignore:
+      - '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
+#  release:
+#    types: [ published ]
+
+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
+
+  push_to_registry:
+    name: Build and push container images
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    needs: test
+    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
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v4
+
+      - name: Set short git commit SHA
+        id: vars
+        # 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: Log in 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: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            foxxmd/multi-scrobbler
+            ghcr.io/foxxmd/multi-scrobbler
+          # 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
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - 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 }}

.gitignore

@@ -1,7 +1,7 @@
 # Created by .ignore support plugin (hsz.mobi)
 ### Node template
 # Logs
-logs
+/logs
 *.log
 npm-debug.log*
 yarn-debug.log*
@@ -117,6 +117,19 @@ dist
 .yarn/install-state.gz
 .pnp.*
 
-*.json
+config/*.json
 *.txt
 .idea/
+
+src/**/**.js
+src/**/**.js.map
+
+*.bak
+*.p8
+.flatpak-builder
+flatpak/generated-sources.json
+*.secrets
+
+build
+!setupProxy.js
+**/generated-sources.*

.mocharc.json

@@ -0,0 +1,5 @@
+{
+  "reporter": "dot",
+  "extension": "ts",
+  "import": "tsx/esm"
+}

.nvmrc

@@ -1 +1 @@
-"lts/fermium"
+v18.19.1

.nycrc.json

@@ -0,0 +1,24 @@
+{
+  "extends": "@istanbuljs/nyc-config-typescript",
+  "exclude": [
+    "node_modules/",
+    "**/src/backend/common/schema/**",
+    "**/src/backend/tests/**",
+    "register.js",
+    "**/src/server/**/*.d.ts",
+    "**/src/client/**"
+  ],
+  "include": [
+    "**/src/backend/**/*.ts",
+    "**/src/**/backend/*.js",
+    "**/src/**/backend/*.js.map"
+  ],
+  "extension": [
+    ".ts"
+  ],
+  "reporter": [
+    "text-summary",
+    "html"
+  ],
+  "report-dir": "./coverage"
+}

CONTRIBUTING.md

@@ -0,0 +1,8 @@
+# Creating a Pull Request
+
+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`.
+* Ensure that if your code is covered by [an existing test](./src/backend/tests) that you have updated the test accordingly

Dockerfile

@@ -1,35 +1,114 @@
-FROM node:fermium-alpine3.10
+FROM ghcr.io/linuxserver/baseimage-debian:bookworm as base
 
 ENV TZ=Etc/GMT
+ENV NODE_VERSION 20.11.1
+
+# borrowing openssl header removal trick from offical docker-node
+# https://github.com/nodejs/docker-node/blob/main/18/bookworm-slim/Dockerfile#L8
+RUN \
+    ARCH= OPENSSL_ARCH= && dpkgArch="$(dpkg --print-architecture)" \
+        && case "${dpkgArch##*-}" in \
+          amd64) ARCH='x64' OPENSSL_ARCH='linux-x86_64';; \
+          ppc64el) ARCH='ppc64le' OPENSSL_ARCH='linux-ppc64le';; \
+          s390x) ARCH='s390x' OPENSSL_ARCH='linux*-s390x';; \
+          arm64) ARCH='arm64' OPENSSL_ARCH='linux-aarch64';; \
+          armhf) ARCH='armv7l' OPENSSL_ARCH='linux-armv4';; \
+          i386) ARCH='x86' OPENSSL_ARCH='linux-elf';; \
+          *) echo "unsupported architecture"; exit 1 ;; \
+        esac && \
+        set -ex && \
+  echo "**** install build packages ****" && \
+    apt-get update && \
+    apt-get install --no-install-recommends -y \
+        #ca-certificates \
+        xz-utils \
+        avahi-utils \
+        curl && \
+  echo "**** Fetch and install node****" && \
+    # get node/npm directly from nodejs dist \
+    # https://github.com/nodejs/docker-node/blob/main/18/bookworm-slim/Dockerfile#L41
+    curl -fsSLO --compressed "https://nodejs.org/dist/v$NODE_VERSION/node-v$NODE_VERSION-linux-$ARCH.tar.xz" && \
+    tar -xJf "node-v$NODE_VERSION-linux-$ARCH.tar.xz" -C /usr --strip-components=1 --no-same-owner && \
+    rm "node-v$NODE_VERSION-linux-$ARCH.tar.xz" && \
+    ln -s /usr/bin/node /usr/bin/nodejs && \
+    npm update -g npm && \
+  echo "**** cleanup ****" && \
+    # https://github.com/nodejs/docker-node/blob/main/18/bookworm-slim/Dockerfile#L49
+    # Remove unused OpenSSL headers to save ~34MB
+    # (does not affect arm64 issue below)
+    find /usr/include/node/openssl/archs -mindepth 1 -maxdepth 1 ! -name "$OPENSSL_ARCH" -exec rm -rf {} \; && \
+    apt-get purge --auto-remove -y perl xz-utils && \
+    apt-get autoclean && \
+    apt-get autoremove && \
+      rm -rf \
+        /config/.cache \
+        /root/cache \
+        /var/lib/apt/lists/* \
+        /var/tmp/* \
+        /tmp/*
 
 RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
 
-RUN mkdir -p /home/node/app/node_modules && chown -R node:node /home/node
+ARG data_dir=/config
+VOLUME $data_dir
+ENV CONFIG_DIR=$data_dir
 
-WORKDIR /home/node/app
+COPY docker/root /
 
-COPY package*.json ./
+WORKDIR /app
 
-USER node
+FROM base as build
 
-RUN npm install --production
+COPY --chown=abc:abc package*.json tsconfig.json ./
+COPY --chown=abc:abc patches ./patches
 
-COPY --chown=node:node . .
+# for debugging, so the build fails faster when timing out (arm64)
+#RUN npm config set fetch-retries 1 && \
+#    npm config set fetch-retry-mintimeout 5000 && \
+#    npm config set fetch-retry-maxtimeout 5000
 
-ENV NPM_CONFIG_LOGLEVEL debug
+# https://www.npmjs.com/package/tls-test
+# used to test that the OS supports downloading packages over HTTPS with TLS 1.2 enforced
+# -- this always succeeds but a good sanity check
+#RUN npm install -g https://tls-test.npmjs.com/tls-test-1.0.0.tgz
 
-ARG config_dir=/home/node/config
-RUN mkdir -p $config_dir
-VOLUME $config_dir
-ENV CONFIG_DIR=$config_dir
+# 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
 
-ARG log_dir=/home/node/logs
-RUN mkdir -p $log_dir
-VOLUME $log_dir
-ENV LOG_DIR=$log_dir
+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
+
+FROM base as app
+
+COPY --chown=abc:abc package*.json ./
+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
+COPY --from=build --chown=abc:abc /app/docsite /app/docsite
+COPY --from=base /usr/bin /usr/bin
+COPY --from=base /usr/lib /usr/lib
+
+ENV NODE_ENV=production
+ENV IS_DOCKER=true
+
+# https://stackoverflow.com/a/63640896/1469797
+ARG APP_BUILD_VERSION
+ENV APP_VERSION=$APP_BUILD_VERSION
+
+RUN npm ci --omit=dev \
+    && npm cache clean --force \
+    && chown -R abc:abc node_modules \
+    && rm -rf node_modules/@types \
+              /root/.cache
 
 ARG webPort=9078
 ENV PORT=$webPort
 EXPOSE $PORT
-
-CMD [ "node", "index.js" ]

README.md

@@ -3,93 +3,113 @@
 [![Latest Release](https://img.shields.io/github/v/release/foxxmd/multi-scrobbler)](https://github.com/FoxxMD/multi-scrobbler/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Docker Pulls](https://img.shields.io/docker/pulls/foxxmd/multi-scrobbler)](https://hub.docker.com/r/foxxmd/multi-scrobbler)
+[![Docs](https://img.shields.io/badge/Read%20The%20Docs-1082c2)](https://foxxmd.github.io/multi-scrobbler/)
 
-A javascript app to scrobble plays from multiple sources to [Maloja](https://github.com/krateng/maloja), [Last.fm](https://www.last.fm), and other clients (eventually!)
 
-* Supports scrobbling for many sources
-  * [Spotify](/docs/configuration.md#spotify)
-  * [Plex](/docs/configuration.md#plex) or [Tautulli](/docs/configuration.md#tautulli)
-  * [Subsonic-compatible APIs](/docs/configuration.md#subsonic) (like [Airsonic](https://airsonic.github.io/))
-  * [Jellyfin](/docs/configuration.md#jellyfin)
-  * [Last.fm](/docs/configuration.md#lastfm-source)
-* Supports scrobbling to many clients
-  * [Maloja](/docs/configuration.md#maloja)
-  * [Last.fm](/docs/configuration.md#lastfm)
+<img src="/assets/icon.png" align="right"
+alt="multi-scrobbler logo" width="180" height="180">
+
+A javascript app to scrobble music you listened to, to [Maloja](https://github.com/krateng/maloja), [Last.fm](https://www.last.fm), and [ListenBrainz](https://listenbrainz.org)
+
+* 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)
+  * [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)
+  * [ListenBrainz](https://foxxmd.github.io/multi-scrobbler/docs/configuration#listenbrainz-source)
+  * [~~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)
+* 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)
+  * [ListenBrainz](https://foxxmd.github.io/multi-scrobbler/docs/configuration#listenbrainz)
+* Monitor status of Sources and Clients using [webhooks (Gotify, Ntfy, Apprise)](https://foxxmd.github.io/multi-scrobbler/docs/configuration#webhook-configurations) or [healthcheck endpoint](https://foxxmd.github.io/multi-scrobbler/docs/configuration#health-endpoint)
 * Supports configuring for single or multiple users (scrobbling for your friends and family!)
 * Web server interface for stats, basic control, and detailed logs
+* 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
-* Built for Docker and unattended use!
+* Modify data before scrobbling with [regular expression or search patterns](https://foxxmd.github.io/multi-scrobbler/docs/transforms)
+* Install using [Docker images for x86/ARM](https://foxxmd.github.io/multi-scrobbler/docs/installation#docker), [flatpak](https://foxxmd.github.io/multi-scrobbler/docs/installationr#flatpak), or [locally with NodeJS](https://foxxmd.github.io/multi-scrobbler/docs/installation#nodejs)
+
+[**Quick Start Guide**](https://foxxmd.github.io/multi-scrobbler/docs/quickstart)
+
+<img src="/assets/status-ui.png" width="800">
 
 **Why should I use this over a browser extension and/or mobile app scrobbler?**
 
 * **Platform independent** -- Because multi-scrobbler communicates directly with service APIs it will scrobble everything you play regardless of where you play it. No more need for apps on every platform you use!
 * **Open-source** -- Get peace of mind knowing exactly how your personal data is being handled.
-* **Consolidate play sources** -- Scrobble from many sources to one client with ease and without duplicating tracks.
+* **Track your activity regardless of where you listen** -- Scrobble from many Sources to one Client with ease and without duplicating tracks.
 * **Manage scrobbling for others** -- Scrobble for your friends and family without any setup on their part. Easily silo sources to specific clients to keep plays separate.
 
-**But I already scrobble my music to Last.fm, is multi-scrobbler for me?**
+**But I already scrobble my music to Last.fm/ListenBrainz, is multi-scrobbler for me?**
 
-Yes! You can use [Last.fm as a Source](/docs/configuration.md#lastfm-source) to mirror scrobbles from your Last.fm profile to Maloja. That way you can keep your current scrobble setup as-is but still get the benefit of capturing your data to a self-hosted location.
+Yes! You can use [Last.fm as a **Source**](https://foxxmd.github.io/multi-scrobbler/docs/configuration#lastfm-source) or [Listenbrainz as a **Source**](https://foxxmd.github.io/multi-scrobbler/docs/configuration#listenbrainz-source) to forward scrobbles from your profile to any other Client! That way you can keep your current scrobble setup as-is but still get the benefit of capturing your data to a self-hosted location.
 
-<img src="/assets/status-ui.jpg" width="800">
+## How Does multi-scrobbler (MS) Work?
+
+You set up configurations for one or more **Sources** and one or more **Clients**. MS monitors all of your configured **Sources**. When new tracks are played by a Source it grabs that information and then sends it (scrobbles it) to all **Clients** that Source is configured to scrobble to.
+
+### Source
+
+A **Source** is a data source that contains information about tracks you are playing like a music player or platform. Examples are **Spotify, Jellyfin, Plex, Youtube Music, Airsonic**, etc...
+
+Source configurations consist of:
+
+* A friendly name.
+* Any data needed to communicate or authenticate with the Source.
+* An optional list of Client names that the Source should scrobble to. If omitted the Source also scrobbles to all configured Clients.
+
+### Client
+
+A **Client** is an application that stores the historical information about what songs you have played (scrobbles). Examples are **Maloja, Last.fm, Listenbrainz**...
+
+Client configurations consist of:
+
+* A friendly name.
+* Any data needed to communicate or authenticate with the Client.
+
+## Quick Start
+
+[See the **Quick Start Guide**](https://foxxmd.github.io/multi-scrobbler/docs/quickstart)
 
 ## Installation
 
+[See the **Installation** documentation](https://foxxmd.github.io/multi-scrobbler/docs/installation)
 
-### Locally
+## Configuration
 
-Clone this repository somewhere and then install from the working directory
-
-```bash
-git clone https://github.com/FoxxMD/multi-scrobbler.git .
-cd multi-scrobbler
-npm install
-```
-
-### [Docker](https://hub.docker.com/r/foxxmd/multi-scrobbler)
-
-```
-foxxmd/multi-scrobbler:latest
-```
-
-## Setup
-
-Some setup is required! See the [configuration](docs/configuration.md) docs for a full reference.
-
-### TLDR, Minimal Example
-
-You want to use multi-scrobbler to scrobble your plays from Spotify to Maloja:
-
-#### Local
-```bash
-SPOTIFY_CLIENT_ID=yourId SPOTIFY_CLIENT_SECRET=yourSecret MALOJA_URL=http://domain.tld MALOJA_API_KEY=1234 node index.js
-```
-
-#### Docker
-
-```bash
-docker run -e "SPOTIFY_CLIENT_ID=yourId" -e "SPOTIFY_CLIENT_SECRET=yourSecret" -e "MALOJA_URL=http://domain.tld" -e "MALOJA_API_KEY=1234" -v /path/on/host/config:/home/node/app/config foxxmd/multi-scrobbler
-```
-
-**But I want to use json for configuration?**
-
-Then use [config.json.example](/config/config.json.example) and drop it in your `CONFIG_DIR` directory
-
-**Is there an example configuration using everything?**
-
-Yes, check out the [kitchen sink example](/docs/kitchensink.md)
+[See the **Configuration** documentation](https://foxxmd.github.io/multi-scrobbler/docs/configuration)
 
 ## Usage
 
 A status page with statistics, recent logs, and some runtime configuration options can be found at
 
 ```
-https://localhost:9078
+http://localhost:9078
 ```
 Output is also provided to stdout/stderr as well as file if specified in configuration.
 
-On first startup you may need to authorize Spotify by visiting the callback URL (which can also be accessed from the status page). Visit the status page above to find the applicable link to trigger this.
+On first startup you may need to authorize Spotify and/or Last.fm by visiting the callback URL (which can also be accessed from the status page). Visit the status page above to find the applicable link to trigger this.
+
+## Help/FAQ
+
+Having issues with connections or configuration? Check the [FAQ](https://foxxmd.github.io/multi-scrobbler/docs/FAQ) before creating an issue!
+
+## Development
+
+[Detailed architecture and development guides for Sources/Clients](https://foxxmd.github.io/multi-scrobbler/docs/development/dev-common)
 
 ## License
 

alpine.Dockerfile

@@ -0,0 +1,71 @@
+FROM lsiobase/alpine:3.18 as base
+
+ENV TZ=Etc/GMT
+
+RUN \
+  echo "**** install build packages ****" && \
+  apk add --no-cache \
+    avahi \
+    avahi-tools \
+    nodejs \
+    npm \
+    && \
+  echo "**** cleanup ****" && \
+  rm -rf \
+    /root/.cache \
+    /tmp/*
+
+RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
+
+ARG data_dir=/config
+VOLUME $data_dir
+ENV CONFIG_DIR=$data_dir
+
+COPY docker/root/ /
+
+WORKDIR /app
+
+FROM base as build
+
+# copy dep/TS config and install dev dependencies
+COPY --chown=abc:abc package*.json tsconfig.json ./
+COPY --chown=abc:abc patches ./patches
+
+RUN npm ci \
+    && chown -R root:root node_modules
+#RUN yarn install
+
+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
+
+FROM base as app
+
+#COPY --chown=abc:abc package.json yarn.lock ./
+COPY --chown=abc:abc package*.json ./
+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
+COPY --from=build --chown=abc:abc /app/docsite /app/docsite
+COPY --from=base /usr/local/bin /usr/local/bin
+COPY --from=base /usr/local/lib /usr/local/lib
+
+ENV NODE_ENV=production
+ENV IS_DOCKER=true
+ENV COLORED_STD=true
+
+# https://stackoverflow.com/a/63640896/1469797
+ARG APP_BUILD_VERSION
+ENV APP_VERSION=$APP_BUILD_VERSION
+
+RUN npm ci --omit=dev \
+    && npm cache clean --force \
+    && chown -R abc:abc node_modules \
+    && rm -rf node_modules/@types
+
+ARG webPort=9078
+ENV PORT=$webPort
+EXPOSE $PORT

apis/AbstractApiClient.js

@@ -1,28 +0,0 @@
-import {capitalize, createLabelledLogger} from "../utils.js";
-
-export default class AbstractApiClient {
-    name;
-    type;
-    initialized = false;
-
-    config;
-    options;
-    logger;
-
-    client;
-    workingCredsPath;
-    redirectUri;
-
-    constructor(type, name, config = {}, options = {}) {
-        this.type = type;
-        this.name = name;
-        const identifier = `API - ${capitalize(this.type)} - ${name}`;
-        this.logger = createLabelledLogger(identifier, identifier);
-        this.config = config;
-        this.options = options;
-    }
-
-    static formatPlayObj = obj => {
-        throw new Error('should be overridden');
-    }
-}

apis/LastfmApiClient.js

@@ -1,164 +0,0 @@
-import LastFm from "lastfm-node-client";
-import AbstractApiClient from "./AbstractApiClient.js";
-import dayjs from "dayjs";
-import {readJson, sleep, writeFile} from "../utils.js";
-
-const badErrors = [
-    'api key suspended',
-    'invalid session key',
-    'invalid api key',
-    'authentication failed'
-];
-
-const retryErrors = [
-    'operation failed',
-    'service offline',
-    'temporarily unavailable',
-    'rate limit'
-]
-
-export default class LastfmApiClient extends AbstractApiClient {
-
-    user;
-
-    constructor(name, config = {}, options = {}) {
-        super('lastfm', name, config, options);
-        const {redirectUri, apiKey, secret, session, configDir} = config;
-        this.redirectUri = `${redirectUri}?state=${name}`;
-        if (apiKey === undefined) {
-            this.logger.warn("'apiKey' not found in config!");
-        }
-        this.workingCredsPath = `${configDir}/currentCreds-lastfm-${name}.json`;
-        this.client = new LastFm(apiKey, secret, session);
-    }
-
-    static formatPlayObj = obj => {
-        const {
-            artist: {
-                // last.fm doesn't seem consistent with which of these properties it returns...
-                '#text': artists,
-                name: artistName,
-            },
-            name: title,
-            album: {
-                '#text': album,
-            },
-            duration,
-            date: {
-                uts: time,
-            } = {},
-            '@attr': {
-                nowplaying = 'false',
-            } = {},
-            url,
-            mbid,
-        } = obj;
-        // arbitrary decision yikes
-        let artistStrings = artists !== undefined ? artists.split(',') : [artistName];
-        return {
-            data: {
-                artists: [...new Set(artistStrings)],
-                track: title,
-                album,
-                duration,
-                playDate: time !== undefined ? dayjs.unix(time) : undefined,
-            },
-            meta: {
-                nowPlaying: nowplaying === 'true',
-                mbid,
-                source: 'Lastfm',
-                url: {
-                    web: url,
-                }
-            }
-        }
-    }
-
-    callApi = async (func, retries = 0) => {
-        const {
-            maxRequestRetries = 2,
-            retryMultiplier = 1.5
-        } = this.config;
-
-        try {
-            return await func(this.client);
-        } catch (e) {
-            const {
-                message,
-            } = e;
-            // for now check for exceptional errors by matching error code text
-            const retryError = retryErrors.find(x => message.toLocaleLowerCase().includes(x));
-            if(undefined !== retryError) {
-                if(retries < maxRequestRetries) {
-                    const delay = (retries + 1) * retryMultiplier;
-                    this.logger.warn(`API call was not good but recoverable (${retryError}), retrying in ${delay} seconds...`);
-                    await sleep(delay * 1000);
-                    return this.callApi(func, retries + 1);
-                } else {
-                    this.logger.warn('Could not recover!');
-                    throw e;
-                }
-            }
-
-            throw e;
-        }
-    }
-
-    getAuthUrl = () => {
-        const redir = `${this.config.redirectUri}?state=${this.name}`;
-        return `http://www.last.fm/api/auth/?api_key=${this.config.apiKey}&cb=${encodeURIComponent(redir)}`
-    }
-
-    authenticate = async (token) => {
-        const sessionRes = await this.client.authGetSession({token});
-        const {
-            session: {
-                key: sessionKey,
-                name, // username
-            } = {}
-        } = sessionRes;
-        this.client.sessionKey = sessionKey;
-
-        await writeFile(this.workingCredsPath, JSON.stringify({
-            sessionKey,
-        }));
-    }
-
-    initialize = async () => {
-
-        try {
-            const creds = await readJson(this.workingCredsPath, {throwOnNotFound: false});
-            const {sessionKey} = creds || {};
-            if (this.client.sessionKey === undefined && sessionKey !== undefined) {
-                this.client.sessionKey = sessionKey;
-            }
-            return true;
-        } catch (e) {
-            this.logger.warn('Current lastfm credentials file exists but could not be parsed', {path: this.workingCredsPath});
-            return false;
-        }
-    }
-
-    testAuth = async () => {
-        if (this.client.sessionKey === undefined) {
-            this.logger.info('No session key found. User interaction for authentication required.');
-            return false;
-        }
-        try {
-            const infoResp = await this.callApi(client => client.userGetInfo());
-            const {
-                user: {
-                    name,
-                } = {}
-            } = infoResp;
-            this.user = name;
-            this.initialized = true;
-            this.logger.info(`Client authorized for user ${name}`)
-            return true;
-        } catch (e) {
-            this.logger.error('Testing auth failed');
-            throw e;
-        }
-    }
-
-}

assets/icon.svg

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
+  <defs>
+    <style>
+      .cls-1 {
+        fill: #c34a36;
+      }
+    </style>
+  </defs>
+  <path class="cls-1" d="M76.94,65.49c.87-7.85-5.27-14.51-12.94-14.51-4.56,0-8.57,2.36-10.9,5.91h-4.55c2.36-5.11,7.17-8.87,12.95-9.71V20c0-11.05-8.95-20-20-20H5C2.24,0,0,2.24,0,5V123c0,2.76,2.24,5,5,5H41.5c11.05,0,20-8.95,20-20v-27.17c-5.78-.84-10.59-4.6-12.95-9.72h4.55c2.59,3.96,7.27,6.43,12.46,5.82,6.08-.71,10.71-5.37,11.39-11.45ZM15.3,94.39c0,1.1-.9,2-2,2s-2-.9-2-2V33.61c0-1.1,.9-2,2-2s2,.9,2,2v60.78Zm11.12,14.55c0,1.1-.9,2-2,2s-2-.9-2-2V19.06c0-1.1,.9-2,2-2s2,.9,2,2V108.94Zm37.58-39.53c-2.28,0-4.23-1.41-5.02-3.41h-21.43v28.39c0,1.1-.9,2-2,2s-2-.9-2-2V33.61c0-1.1,.9-2,2-2s2,.9,2,2v28.39h21.43c.93-2.33,3.42-3.86,6.18-3.29,2.05,.42,3.7,2.08,4.13,4.12,.73,3.5-1.92,6.58-5.29,6.58Z"/>
+  <path class="cls-1" d="M123,0h-36.5c-11.05,0-20,8.95-20,20v27.18c7.55,1.12,13.5,7.2,14.4,14.82h9.55v-28.28c0-1,.68-1.92,1.66-2.08,1.25-.2,2.34,.76,2.34,1.97v60.67c0,1-.68,1.92-1.66,2.08-1.25,.2-2.34-.76-2.34-1.97v-28.39h-9.55c-.9,7.62-6.84,13.7-14.4,14.82v27.18c0,11.05,8.95,20,20,20h36.5c2.76,0,5-2.24,5-5V5c0-2.76-2.24-5-5-5Zm-17.42,108.94c0,1.1-.9,2-2,2s-2-.9-2-2V19.06c0-1.1,.9-2,2-2s2,.9,2,2V108.94Zm11.12-14.55c0,1.1-.9,2-2,2s-2-.9-2-2V33.61c0-1.1,.9-2,2-2s2,.9,2,2v60.78Z"/>
+</svg>

clients/AbstractScrobbleClient.js

@@ -1,151 +0,0 @@
-import dayjs from "dayjs";
-import {buildTrackString, capitalize, createLabelledLogger, playObjDataMatch} from "../utils.js";
-
-export default class AbstractScrobbleClient {
-
-    name;
-    type;
-    initialized = false;
-    requiresAuth = false;
-    requiresAuthInteraction = false;
-    authed = false;
-
-    recentScrobbles = [];
-    scrobbledPlayObjs = [];
-    newestScrobbleTime;
-    oldestScrobbleTime = dayjs();
-    tracksScrobbled = 0;
-
-    lastScrobbleCheck = dayjs();
-    refreshEnabled;
-    checkExistingScrobbles;
-    verboseOptions;
-
-    config;
-    logger;
-
-    constructor(type, name, config = {}) {
-        this.type = type;
-        this.name = name;
-        const identifier = `Client ${capitalize(this.type)} - ${name}`;
-        this.logger = createLabelledLogger(identifier, identifier);
-
-        const {
-            options: {
-                refreshEnabled = true,
-                checkExistingScrobbles = true,
-                verbose = {},
-            } = {},
-            ...rest
-        } = config;
-        this.config = rest;
-        this.refreshEnabled = refreshEnabled;
-        this.checkExistingScrobbles = checkExistingScrobbles;
-
-        const {
-            match: {
-                onNoMatch = false,
-                onMatch = false,
-                confidenceBreakdown = false,
-            } = {},
-            ...vRest
-        } = verbose
-        if (onMatch || onNoMatch) {
-            this.logger.warn('Setting verbose matching may produce noisy logs! Use with care.');
-        }
-        this.verboseOptions = {
-            ...vRest,
-            match: {
-                onNoMatch,
-                onMatch,
-                confidenceBreakdown
-            }
-        };
-    }
-
-    // default init function, should be overridden if init stage is required
-    initialize = async () => {
-        this.initialized = true;
-        return this.initialized;
-    }
-
-    // default init function, should be overridden if auth stage is required
-    testAuth = async () => {
-        return this.authed;
-    }
-
-    scrobblesLastCheckedAt = () => {
-        return this.lastScrobbleCheck;
-    }
-
-    formatPlayObj = obj => {
-        this.logger.warn('formatPlayObj should be defined by concrete class!');
-        return obj;
-    }
-
-    // time frame is valid as long as the play date for the source track is newer than the oldest play time from the scrobble client
-    // ...this is assuming the scrobble client is returning "most recent" scrobbles
-    timeFrameIsValid = (playObj, log = false) => {
-        const {
-            data: {
-                playDate,
-            } = {},
-        } = playObj;
-        const validTime = playDate.isAfter(this.oldestScrobbleTime);
-        if (log && !validTime) {
-            this.logger.debug(`${buildTrackString(playObj)} was in an invalid time frame (played before the oldest scrobble found)`);
-        }
-        return validTime;
-    }
-
-    addScrobbledTrack = (playObj, scrobbleResp) => {
-        this.scrobbledPlayObjs.push({play: playObj, scrobble: this.formatPlayObj(scrobbleResp)});
-    }
-
-    cleanSourceSearchTitle = (playObj) => {
-        const {
-            data: {
-                track,
-            } = {},
-        } = playObj;
-
-        return track;
-    };
-
-    findExistingSubmittedPlayObj = (playObj) => {
-        const {
-            data: {
-                playDate
-            } = {},
-            meta: {
-                source,
-            } = {}
-        } = playObj;
-
-        const dtInvariantMatches = this.scrobbledPlayObjs.filter(x => playObjDataMatch(playObj, x.play));
-
-        if (dtInvariantMatches.length === 0) {
-            return [undefined, undefined];
-        }
-
-        const matchPlayDate = dtInvariantMatches.find((x) => {
-            const {
-                play: {
-                    data: {
-                        playDate: sPlayDate
-                    } = {},
-                    meta: {
-                        source: playSource
-                    } = {},
-                } = {},
-            } = x;
-            // need to account for inaccurate DT from subsonic
-            if(source === 'Subsonic' && playSource === 'Subsonic') {
-                return playDate.isSame(sPlayDate) || playDate.diff(sPlayDate, 'minute') <= 1;
-            }
-            return playDate.isSame(sPlayDate);
-        });
-
-        return [matchPlayDate, dtInvariantMatches];
-    }
-}

clients/LastfmScrobbler.js

@@ -1,317 +0,0 @@
-import AbstractScrobbleClient from "./AbstractScrobbleClient.js";
-import dayjs from 'dayjs';
-
-import {
-    buildTrackString,
-    playObjDataMatch, removeUndefinedKeys,
-    setIntersection, sleep,
-    sortByPlayDate,
-    truncateStringToLength,
-} from "../utils.js";
-import LastfmApiClient from "../apis/LastfmApiClient.js";
-
-export default class LastfmScrobbler extends AbstractScrobbleClient {
-
-    api;
-    initialized = false;
-    requiresAuth = true;
-    requiresAuthInteraction = true;
-
-    constructor(name, config = {}, options = {}) {
-        super('lastfm', name, config, options);
-        this.api = new LastfmApiClient(name, config, options)
-    }
-
-    formatPlayObj = obj => LastfmApiClient.formatPlayObj(obj);
-
-    initialize = async () => {
-        this.initialized = await this.api.initialize();
-        return this.initialized;
-    }
-
-    testAuth = async () => {
-        try {
-            this.authed = await this.api.testAuth();
-        } catch (e) {
-            this.logger.error('Could not successfully communicate with Last.fm API');
-            this.logger.error(e);
-            this.authed = false;
-        }
-        return this.authed;
-    }
-
-    refreshScrobbles = async () => {
-        if (this.refreshEnabled) {
-            this.logger.debug('Refreshing recent scrobbles');
-            const resp = await this.api.callApi(client => client.userGetRecentTracks({user: this.api.user, limit: 20, extended: true}));
-            const {
-                recenttracks: {
-                    track: list = [],
-                }
-            } = resp;
-            this.recentScrobbles = list.reduce((acc, x) => {
-                try {
-                    const formatted = LastfmApiClient.formatPlayObj(x);
-                    const {
-                        data: {
-                            track,
-                            playDate,
-                        },
-                        meta: {
-                            mbid,
-                            nowPlaying,
-                        }
-                    } = formatted;
-                    if(nowPlaying === true) {
-                        // if the track is "now playing" it doesn't get a timestamp so we can't determine when it started playing
-                        // and don't want to accidentally count the same track at different timestamps by artificially assigning it 'now' as a timestamp
-                        // so we'll just ignore it in the context of recent tracks since really we only want "tracks that have already finished being played" anyway
-                        this.logger.debug("Ignoring 'now playing' track returned from Last.fm client", {track, mbid});
-                        return acc;
-                    } else if(playDate === undefined) {
-                        this.logger.warn(`Last.fm recently scrobbled track did not contain a timestamp, omitting from time frame check`, {track, mbid});
-                        return acc;
-                    }
-                    return acc.concat(formatted);
-                } catch (e) {
-                    this.logger.warn('Failed to format Last.fm recently scrobbled track, omitting from time frame check', {error: e.message});
-                    this.logger.debug('Full api response object:');
-                    this.logger.debug(x);
-                    return acc;
-                }
-            }, []).sort(sortByPlayDate);
-            if (this.recentScrobbles.length > 0) {
-                const [{data: {playDate: newestScrobbleTime = dayjs()} = {}} = {}] = this.recentScrobbles.slice(-1);
-                const [{data: {playDate: oldestScrobbleTime = dayjs()} = {}} = {}] = this.recentScrobbles.slice(0, 1);
-                this.newestScrobbleTime = newestScrobbleTime;
-                this.oldestScrobbleTime = oldestScrobbleTime;
-
-                this.scrobbledPlayObjs = this.scrobbledPlayObjs.filter(x => this.timeFrameIsValid(x.play));
-            }
-        }
-        this.lastScrobbleCheck = dayjs();
-    }
-
-    cleanSourceSearchTitle = (playObj) => {
-        const {
-            data: {
-                track,
-            } = {},
-        } = playObj;
-        return track.toLocaleLowerCase().trim();
-    }
-
-    alreadyScrobbled = (playObj, log = false) => {
-        return this.existingScrobble(playObj, (log || this.verboseOptions.match.onMatch)) !== undefined;
-    }
-
-    existingScrobble = (playObj, logMatch = false) => {
-        const tr = truncateStringToLength(27);
-        const scoreTrackOpts = {include: ['track', 'time'], transformers: {track: t => tr(t).padEnd(30)}};
-
-        // return early if we don't care about checking existing
-        if (false === this.checkExistingScrobbles) {
-            if (this.verboseOptions.match.onNoMatch) {
-                this.logger.debug(`(Existing Check) Source: ${buildTrackString(playObj, scoreTrackOpts)} => No Match because existing scrobble check is FALSE`);
-            }
-            return undefined;
-        }
-
-        let existingScrobble;
-        let closestMatch = {score: 0, breakdowns: ['None']};
-
-        // then check if we have already recorded this
-        const [existingExactSubmitted, existingDataSubmitted = []] = this.findExistingSubmittedPlayObj(playObj);
-
-        // if we have an submitted play with matching data and play date then we can just return the response from the original scrobble
-        if (existingExactSubmitted !== undefined) {
-            existingScrobble = existingExactSubmitted.scrobble;
-
-            closestMatch = {
-                score: 1,
-                breakdowns: ['Exact Match found in previously successfully scrobbled']
-            }
-        }
-        // if not though then we need to check recent scrobbles from scrobble api.
-        // this will be less accurate than checking existing submitted (obv) but will happen if backlogging or on a fresh server start
-
-        // if no recent scrobbles found then assume we haven't submitted it
-        // (either user doesnt want to check history or there is no history to check!)
-        if (this.recentScrobbles.length === 0) {
-            if (this.verboseOptions.match.onNoMatch) {
-                this.logger.debug(`(Existing Check) ${buildTrackString(playObj, scoreTrackOpts)} => No Match because no recent scrobbles returned from API`);
-            }
-            return undefined;
-        }
-
-        if (existingScrobble === undefined) {
-
-            // we have have found an existing submission but without an exact date
-            // in which case we can check the scrobble api response against recent scrobbles (also from api) for a more accurate comparison
-            const referenceApiScrobbleResponse = existingDataSubmitted.length > 0 ? existingDataSubmitted[0].scrobble : undefined;
-
-            const {
-                data: {
-                    artists: sourceArtists = [],
-                    playDate
-                } = {},
-                meta: {
-                    trackLength,
-                    source,
-                } = {},
-            } = playObj;
-
-            // clean source title so it matches title from the scrobble api response as closely as we can get it
-            let cleanSourceTitle = this.cleanSourceSearchTitle(playObj);
-
-            existingScrobble = this.recentScrobbles.find((x) => {
-
-                const referenceMatch = referenceApiScrobbleResponse !== undefined && playObjDataMatch(x, referenceApiScrobbleResponse);
-
-                const {data: {playDate: scrobbleTime, track: scrobbleTitle, artists = []} = {}} = x;
-
-                const playDiffThreshold = source === 'Subsonic' ? 60 : 10;
-                let closeTime = false;
-                // check if scrobble time is same as play date (when the track finished playing AKA entered recent tracks)
-                let scrobblePlayDiff = Math.abs(playDate.unix() - scrobbleTime.unix());
-                let scrobblePlayStartDiff;
-                if (scrobblePlayDiff <= playDiffThreshold) {
-                    //this.logger.debug(`Scrobble with same name (${scrobbleTitle}) found and the play (finish time) vs. scrobble time diff was smaller than 10 seconds`);
-                    closeTime = true;
-                }
-                // also need to check that scrobble time isn't the BEGINNING of the track -- if the source supports durations
-                if (closeTime === false && trackLength !== undefined) {
-                    scrobblePlayStartDiff = Math.abs(playDate.unix() - (scrobbleTime.unix() - trackLength));
-                    if (scrobblePlayStartDiff <= playDiffThreshold) {
-                        //this.logger.debug(`Scrobble with same name (${scrobbleTitle}) found and the play (start time) vs. scrobble time diff was smaller than 10 seconds`);
-                        closeTime = true;
-                    }
-                }
-
-                let titleMatch;
-                const lowerScrobbleTitle = scrobbleTitle.toLocaleLowerCase().trim();
-                // because of all this replacing we need a more position-agnostic way of comparing titles so use intersection on title split by spaces
-                // and compare against length of scrobble title
-                const sourceTitleTerms = new Set(cleanSourceTitle.split(' ').filter(x => x !== ''));
-                const commonTerms = setIntersection(new Set(lowerScrobbleTitle.split(' ')), sourceTitleTerms);
-
-                titleMatch = commonTerms.size / sourceTitleTerms.size;
-
-                let artistMatch;
-                const lowerSourceArtists = sourceArtists.map(x => x.toLocaleLowerCase());
-                const lowerScrobbleArtists = artists.map(x => x.toLocaleLowerCase());
-                artistMatch = setIntersection(new Set(lowerScrobbleArtists), new Set(lowerSourceArtists)).size / artists.length;
-
-                const artistScore = .2 * artistMatch;
-                const titleScore = .3 * titleMatch;
-                const timeScore = .5 * (closeTime ? 1 : 0);
-                const referenceScore = .5 * (referenceMatch ? 1 : 0);
-                const score = artistScore + titleScore + timeScore;
-
-                let scoreBreakdowns = [
-                    `Reference: ${(referenceMatch ? 1 : 0)} * .5 = ${referenceScore.toFixed(2)}`,
-                    `Artist ${artistMatch.toFixed(2)} * .2 = ${artistScore.toFixed(2)}`,
-                    `Title: ${titleMatch.toFixed(2)} * .3 = ${titleScore.toFixed(2)}`,
-                    `Time: ${closeTime ? 1 : 0} * .5 = ${timeScore.toFixed(2)}`,
-                    `Score ${score.toFixed(2)} => ${score >= .7 ? 'Matched!' : 'No Match'}`
-                ];
-
-                const confidence = `Score ${score.toFixed(2)} => ${score >= .7 ? 'Matched!' : 'No Match'}`
-
-                const scoreInfo = {
-                    score,
-                    scrobble: x,
-                    breakdowns: this.verboseOptions.match.confidenceBreakdown ? scoreBreakdowns : [confidence]
-                }
-
-                if (closestMatch.score <= score && score > 0) {
-                    closestMatch = scoreInfo
-                }
-
-                return score >= .7;
-            });
-        }
-
-        if ((existingScrobble !== undefined && this.verboseOptions.match.onMatch) || (existingScrobble === undefined && this.verboseOptions.match.onNoMatch)) {
-            const closestScrobble = closestMatch.scrobble === undefined ? closestMatch.breakdowns.join(' | ') : `Closest Scrobble: ${buildTrackString(closestMatch.scrobble, scoreTrackOpts)} => ${closestMatch.breakdowns.join(' | ')}`;
-            this.logger.debug(`(Existing Check) Source: ${buildTrackString(playObj, scoreTrackOpts)} => ${closestScrobble}`);
-        }
-        return existingScrobble;
-    }
-
-    scrobble = async (playObj) => {
-        const {
-            data: {
-                artists,
-                album,
-                track,
-                duration,
-                playDate
-            } = {},
-            data = {},
-            meta: {
-                source,
-                newFromSource = false,
-            } = {}
-        } = playObj;
-
-        const sType = newFromSource ? 'New' : 'Backlog';
-
-        try {
-            const response = await this.api.callApi(client => client.trackScrobble(
-                // i don't know if its lastfm-node-client building the request params incorrectly
-                // or the last.fm api not handling the params correctly...
-                //
-                // ...but in either case if any of the below properties is undefined (possibly also null??)
-                // then last.fm responds with an IGNORED scrobble and error code 1 (totally unhelpful)
-                // so remove all undefined keys from the object before passing to the api client
-                removeUndefinedKeys({
-                    artist: artists.join(', '),
-                    duration,
-                    track,
-                    album,
-                    timestamp: playDate.unix(),
-                })));
-            const {
-                scrobbles: {
-                    '@attr': {
-                        accepted = 0,
-                        ignored = 0,
-                        code,
-                    },
-                    scrobble: {
-                        track: {
-                           '#text': trackName,
-                        } = {},
-                        timestamp,
-                        ignoredMessage: {
-                            code: ignoreCode,
-                            '#text': ignoreMsg,
-                        } = {},
-                        ...rest
-                    } = {}
-                } = {},
-            } = response;
-            if(code === 5) {
-                this.initialized = false;
-                throw new Error('Service reported daily scrobble limit exceeded! 😬 Disabling client');
-            }
-            this.addScrobbledTrack(playObj, {...rest, date: { uts: timestamp}, name: trackName});
-            if (newFromSource) {
-                this.logger.info(`Scrobbled (New)     => (${source}) ${buildTrackString(playObj)}`);
-            } else {
-                this.logger.info(`Scrobbled (Backlog) => (${source}) ${buildTrackString(playObj)}`);
-            }
-            if(ignored > 0) {
-                this.logger.warn(`Service ignored this scrobble 😬 => (Code ${ignoreCode}) ${(ignoreMsg === '' ? '(No error message returned)' : ignoreMsg)} -- See https://www.last.fm/api/errorcodes for more information`);
-            }
-            // last fm has rate limits but i can't find a specific example of what that limit is. going to default to 1 scrobble/sec to be safe
-            await sleep(1000);
-        } catch (e) {
-            this.logger.error(`Scrobble Error (${sType})`, {playInfo: buildTrackString(playObj)});
-            throw e;
-        }
-
-        return true;
-    }
-}

clients/MalojaScrobbler.js

@@ -1,410 +0,0 @@
-import AbstractScrobbleClient from "./AbstractScrobbleClient.js";
-import request from 'superagent';
-import dayjs from 'dayjs';
-import {
-    buildTrackString,
-    playObjDataMatch,
-    setIntersection,
-    sleep,
-    sortByPlayDate,
-    truncateStringToLength,
-    parseRetryAfterSecsFromObj
-} from "../utils.js";
-
-const feat = ["ft.", "ft", "feat.", "feat", "featuring", "Ft.", "Ft", "Feat.", "Feat", "Featuring"];
-
-export default class MalojaScrobbler extends AbstractScrobbleClient {
-
-    requiresAuth = true;
-
-    constructor(name, config = {}, options = {}) {
-        super('maloja', name, config, options);
-        const {url, apiKey} = config;
-        if (apiKey === undefined) {
-            this.logger.warn("'apiKey' not found in config! Client will most likely fail when trying to scrobble");
-        }
-        if (url === undefined) {
-            throw new Error("Missing 'url' for Maloja config");
-        }
-    }
-
-    static formatPlayObj(obj) {
-        const {
-            artists,
-            title,
-            album,
-            duration,
-            time,
-        } = obj;
-        let artistStrings = artists.reduce((acc, curr) => {
-            let aString;
-            if (typeof curr === 'string') {
-                aString = curr;
-            } else if (typeof curr === 'object') {
-                aString = curr.name;
-            }
-            const aStrings = aString.split(',');
-            return [...acc, ...aStrings];
-        }, []);
-        return {
-            data: {
-                artists: [...new Set(artistStrings)],
-                track: title,
-                album,
-                duration,
-                playDate: dayjs.unix(time),
-            },
-            meta: {
-                source: 'Maloja',
-            }
-        }
-    }
-
-    formatPlayObj = obj => MalojaScrobbler.formatPlayObj(obj);
-
-    callApi = async (req, retries = 0) => {
-        const {
-            maxRequestRetries = 1,
-            retryMultiplier = 1.5
-        } = this.config;
-
-        try {
-            return await req;
-        } catch (e) {
-            if(retries < maxRequestRetries) {
-                const retryAfter = parseRetryAfterSecsFromObj(e) ?? (retryMultiplier * (retries + 1));
-                this.logger.warn(`Request failed but retries (${retries}) less than max (${maxRequestRetries}), retrying request after ${retryAfter} seconds...`);
-                await sleep(retryAfter * 1000);
-                return await this.callApi(req, retries + 1)
-            }
-            const {
-                message,
-                response: {
-                    status,
-                    body,
-                    text,
-                } = {},
-                response,
-            } = e;
-            let msg = response !== undefined ? `API Call failed: Server Response => ${message}` : `API Call failed: ${message}`;
-            const responseMeta = body ?? text;
-            this.logger.error(msg, {status, response: responseMeta});
-            throw e;
-        }
-    }
-
-    testConnection = async () => {
-
-        const {url} = this.config;
-        try {
-            const serverInfoResp = await this.callApi(request.get(`${url}/apis/mlj_1/serverinfo`));
-            const {
-                statusCode,
-                body: {
-                    version = [],
-                    versionstring = '',
-                } = {},
-            } = serverInfoResp;
-
-            if (statusCode >= 300) {
-                this.logger.info('Test connection failed');
-                return false;
-            }
-
-            this.logger.info('Test connection succeeded!');
-
-            if (version.length === 0) {
-                this.logger.warn('Server did not respond with a version. Either the base URL is incorrect or this Maloja server is too old :(');
-            } else {
-                this.logger.info(`Maloja Server Version: ${versionstring}`);
-                if (version[0] < 2 || version[1] < 7) {
-                    this.logger.warn('Maloja Server Version is less than 2.7, please upgrade to ensure compatibility');
-                }
-            }
-            return true;
-        } catch (e) {
-            this.logger.error('Testing connection failed');
-            this.logger.error(e);
-            return false;
-        }
-    }
-
-    initialize = async () => {
-        // just checking that we can get a connection
-        this.initialized = await this.testConnection();
-        return this.initialized;
-    }
-
-    testAuth = async (withKey = true) => {
-
-        const {url, apiKey} = this.config;
-        try {
-            const resp = await this.callApi(request
-                .get(`${url}/apis/mlj_1/test`)
-                .query({key: apiKey}));
-
-            const {
-                status,
-                body: {
-                    status: bodyStatus,
-                } = {},
-                body = {},
-                text = '',
-            } = resp;
-            if (bodyStatus.toLocaleLowerCase() === 'ok') {
-                this.logger.info('Auth test passed!');
-                this.authed = true;
-            } else {
-                this.authed = false;
-                this.logger.error('Testing connection failed => Server Response body was malformed -- should have returned "status: ok"...is the URL correct?', {
-                    status,
-                    body,
-                    text: text.slice(0, 50)
-                });
-            }
-        } catch (e) {
-            this.logger.error('Auth test failed');
-            this.logger.error(e);
-            this.authed = false;
-        }
-        return this.authed;
-    }
-
-    refreshScrobbles = async () => {
-        if (this.refreshEnabled) {
-            this.logger.debug('Refreshing recent scrobbles');
-            const {url} = this.config;
-            const resp = await this.callApi(request.get(`${url}/apis/mlj_1/scrobbles?max=20`));
-            const {
-                body: {
-                    list = [],
-                } = {},
-            } = resp;
-            this.recentScrobbles = list.map(x => MalojaScrobbler.formatPlayObj(x)).sort(sortByPlayDate);
-            if (this.recentScrobbles.length > 0) {
-                const [{data: {playDate: newestScrobbleTime = dayjs()} = {}} = {}] = this.recentScrobbles.slice(-1);
-                const [{data: {playDate: oldestScrobbleTime = dayjs()} = {}} = {}] = this.recentScrobbles.slice(0, 1);
-                this.newestScrobbleTime = newestScrobbleTime;
-                this.oldestScrobbleTime = oldestScrobbleTime;
-
-                this.scrobbledPlayObjs = this.scrobbledPlayObjs.filter(x => this.timeFrameIsValid(x.play));
-            }
-        }
-        this.lastScrobbleCheck = dayjs();
-    }
-
-    cleanSourceSearchTitle = (playObj) => {
-        const {
-            data: {
-                track,
-                artists: sourceArtists = [],
-            } = {},
-        } = playObj;
-        let lowerTitle = track.toLocaleLowerCase();
-        lowerTitle = feat.reduce((acc, curr) => acc.replace(curr, ''), lowerTitle);
-        // also remove [artist] from the track if found since that gets removed as well
-        const lowerArtists = sourceArtists.map(x => x.toLocaleLowerCase());
-        lowerTitle = lowerArtists.reduce((acc, curr) => acc.replace(curr, ''), lowerTitle);
-
-        // remove any whitespace in parenthesis
-        lowerTitle = lowerTitle.replace("\\s+(?=[^()]*\\))", '')
-            // replace parenthesis
-            .replace('()', '')
-            .replace('( )', '')
-            .trim();
-
-        return lowerTitle;
-    }
-
-    alreadyScrobbled = (playObj, log = false) => {
-        return this.existingScrobble(playObj, (log || this.verboseOptions.match.onMatch)) !== undefined;
-    }
-
-    existingScrobble = (playObj, logMatch = false) => {
-        const tr = truncateStringToLength(27);
-        const scoreTrackOpts = {include: ['track', 'time'], transformers: {track: t => tr(t).padEnd(30)}};
-
-        // return early if we don't care about checking existing
-        if (false === this.checkExistingScrobbles) {
-            if (this.verboseOptions.match.onNoMatch) {
-                this.logger.debug(`(Existing Check) Source: ${buildTrackString(playObj, scoreTrackOpts)} => No Match because existing scrobble check is FALSE`);
-            }
-            return undefined;
-        }
-
-        let existingScrobble;
-        let closestMatch = {score: 0, breakdowns: ['None']};
-
-        // then check if we have already recorded this
-        const [existingExactSubmitted, existingDataSubmitted = []] = this.findExistingSubmittedPlayObj(playObj);
-
-        // if we have an submitted play with matching data and play date then we can just return the response from the original scrobble
-        if (existingExactSubmitted !== undefined) {
-            existingScrobble = existingExactSubmitted.scrobble;
-
-            closestMatch = {
-                score: 1,
-                breakdowns: ['Exact Match found in previously successfully scrobbled']
-            }
-        }
-        // if not though then we need to check recent scrobbles from scrobble api.
-        // this will be less accurate than checking existing submitted (obv) but will happen if backlogging or on a fresh server start
-
-        // if no recent scrobbles found then assume we haven't submitted it
-        // (either user doesnt want to check history or there is no history to check!)
-        if (this.recentScrobbles.length === 0) {
-            if (this.verboseOptions.match.onNoMatch) {
-                this.logger.debug(`(Existing Check) ${buildTrackString(playObj, scoreTrackOpts)} => No Match because no recent scrobbles returned from API`);
-            }
-            return undefined;
-        }
-
-        if (existingScrobble === undefined) {
-
-            // we have have found an existing submission but without an exact date
-            // in which case we can check the scrobble api response against recent scrobbles (also from api) for a more accurate comparison
-            const referenceApiScrobbleResponse = existingDataSubmitted.length > 0 ? existingDataSubmitted[0].scrobble : undefined;
-
-            const {
-                data: {
-                    artists: sourceArtists = [],
-                    playDate
-                } = {},
-                meta: {
-                    trackLength,
-                    source,
-                } = {},
-            } = playObj;
-
-            // clean source title so it matches title from the scrobble api response as closely as we can get it
-            let cleanSourceTitle = this.cleanSourceSearchTitle(playObj);
-
-            existingScrobble = this.recentScrobbles.find((x) => {
-
-                const referenceMatch = referenceApiScrobbleResponse !== undefined && playObjDataMatch(x, referenceApiScrobbleResponse);
-
-                const {data: {playDate: scrobbleTime, track: scrobbleTitle, artists = []} = {}} = x;
-
-                const playDiffThreshold = source === 'Subsonic' ? 60 : 10;
-                let closeTime = false;
-                // check if scrobble time is same as play date (when the track finished playing AKA entered recent tracks)
-                let scrobblePlayDiff = Math.abs(playDate.unix() - scrobbleTime.unix());
-                let scrobblePlayStartDiff;
-                if (scrobblePlayDiff <= playDiffThreshold) {
-                    //this.logger.debug(`Scrobble with same name (${scrobbleTitle}) found and the play (finish time) vs. scrobble time diff was smaller than 10 seconds`);
-                    closeTime = true;
-                }
-                // also need to check that scrobble time isn't the BEGINNING of the track -- if the source supports durations
-                if (closeTime === false && trackLength !== undefined) {
-                    scrobblePlayStartDiff = Math.abs(playDate.unix() - (scrobbleTime.unix() - trackLength));
-                    if (scrobblePlayStartDiff <= playDiffThreshold) {
-                        //this.logger.debug(`Scrobble with same name (${scrobbleTitle}) found and the play (start time) vs. scrobble time diff was smaller than 10 seconds`);
-                        closeTime = true;
-                    }
-                }
-
-                let titleMatch;
-                const lowerScrobbleTitle = scrobbleTitle.toLocaleLowerCase().trim();
-                // because of all this replacing we need a more position-agnostic way of comparing titles so use intersection on title split by spaces
-                // and compare against length of scrobble title
-                const sourceTitleTerms = new Set(cleanSourceTitle.split(' ').filter(x => x !== ''));
-                const commonTerms = setIntersection(new Set(lowerScrobbleTitle.split(' ')), sourceTitleTerms);
-
-                titleMatch = commonTerms.size / sourceTitleTerms.size;
-
-                let artistMatch;
-                const lowerSourceArtists = sourceArtists.map(x => x.toLocaleLowerCase());
-                const lowerScrobbleArtists = artists.map(x => x.toLocaleLowerCase());
-                artistMatch = setIntersection(new Set(lowerScrobbleArtists), new Set(lowerSourceArtists)).size / artists.length;
-
-                const artistScore = .2 * artistMatch;
-                const titleScore = .3 * titleMatch;
-                const timeScore = .5 * (closeTime ? 1 : 0);
-                const referenceScore = .5 * (referenceMatch ? 1 : 0);
-                const score = artistScore + titleScore + timeScore;
-
-                let scoreBreakdowns = [
-                    `Reference: ${(referenceMatch ? 1 : 0)} * .5 = ${referenceScore.toFixed(2)}`,
-                    `Artist ${artistMatch.toFixed(2)} * .2 = ${artistScore.toFixed(2)}`,
-                    `Title: ${titleMatch.toFixed(2)} * .3 = ${titleScore.toFixed(2)}`,
-                    `Time: ${closeTime ? 1 : 0} * .5 = ${timeScore.toFixed(2)}`,
-                    `Score ${score.toFixed(2)} => ${score >= .7 ? 'Matched!' : 'No Match'}`
-                ];
-
-                const confidence = `Score ${score.toFixed(2)} => ${score >= .7 ? 'Matched!' : 'No Match'}`
-
-                const scoreInfo = {
-                    score,
-                    scrobble: x,
-                    breakdowns: this.verboseOptions.match.confidenceBreakdown ? scoreBreakdowns : [confidence]
-                }
-
-                if (closestMatch.score <= score && score > 0) {
-                    closestMatch = scoreInfo
-                }
-
-                return score >= .7;
-            });
-        }
-
-        if ((existingScrobble !== undefined && this.verboseOptions.match.onMatch) || (existingScrobble === undefined && this.verboseOptions.match.onNoMatch)) {
-            const closestScrobble = closestMatch.scrobble === undefined ? closestMatch.breakdowns.join(' | ') : `Closest Scrobble: ${buildTrackString(closestMatch.scrobble, scoreTrackOpts)} => ${closestMatch.breakdowns.join(' | ')}`;
-            this.logger.debug(`(Existing Check) Source: ${buildTrackString(playObj, scoreTrackOpts)} => ${closestScrobble}`);
-        }
-        return existingScrobble;
-    }
-
-    scrobble = async (playObj) => {
-        const {url, apiKey} = this.config;
-
-        const {
-            data: {
-                artists,
-                album,
-                track,
-                duration,
-                playDate
-            } = {},
-            meta: {
-                source,
-                newFromSource = false,
-            } = {}
-        } = playObj;
-
-        const sType = newFromSource ? 'New' : 'Backlog';
-
-        try {
-            const response = await this.callApi(request.post(`${url}/apis/mlj_1/newscrobble`)
-                .type('json')
-                .send({
-                    // maloja seems to detect this deliminator much better than commas
-                    // also less likely artist has a forward slash in their name than a comma
-                    artist: artists.join(' / '),
-                    seconds: duration,
-                    title: track,
-                    album,
-                    key: apiKey,
-                    time: playDate.unix(),
-                }));
-            const {body: {
-                track: {
-                    time: mTime = playDate.unix(),
-                    duration: mDuration = duration,
-                    album: mAlbum = album,
-                    ...rest
-                }
-            } = {}} = response;
-            this.addScrobbledTrack(playObj, {...rest, album: mAlbum, time: mTime, duration: mDuration});
-            if (newFromSource) {
-                this.logger.info(`Scrobbled (New)     => (${source}) ${buildTrackString(playObj)}`);
-            } else {
-                this.logger.info(`Scrobbled (Backlog) => (${source}) ${buildTrackString(playObj)}`);
-            }
-        } catch (e) {
-            this.logger.error(`Scrobble Error (${sType})`, {playInfo: buildTrackString(playObj)});
-            throw e;
-        }
-
-        return true;
-    }
-}

clients/ScrobbleClients.js

@@ -1,323 +0,0 @@
-import dayjs from "dayjs";
-import {
-    createLabelledLogger,
-    isValidConfigStructure,
-    playObjDataMatch,
-    readJson,
-    returnDuplicateStrings
-} from "../utils.js";
-import MalojaScrobbler from "./MalojaScrobbler.js";
-import LastfmScrobbler from "./LastfmScrobbler.js";
-
-export default class ScrobbleClients {
-
-    clients = [];
-    logger;
-    configDir;
-
-    clientTypes = ['maloja','lastfm'];
-
-    constructor(configDir) {
-        this.configDir = configDir;
-        this.logger = createLabelledLogger('scrobblers', 'Scrobblers');
-    }
-
-    getByName = (name) => {
-        return this.clients.find(x => x.name === name);
-    }
-
-    getByType = (type) => {
-        return this.clients.filter(x => x.type === type);
-    }
-
-    buildClientsFromConfig = async () => {
-        let configs = [];
-
-        let configFile;
-        try {
-            configFile = await readJson(`${this.configDir}/config.json`, {throwOnNotFound: false});
-        } catch (e) {
-            // think this should stay as show-stopper since config could include important defaults (delay, retries) we don't want to ignore
-            throw new Error('config.json could not be parsed');
-        }
-        let clientDefaults = {};
-        if (configFile !== undefined) {
-            const {
-                clients: mainConfigClientConfigs = [],
-                clientDefaults: cd = {},
-            } = configFile;
-            clientDefaults = cd;
-            const validMainConfigs = mainConfigClientConfigs.reduce((acc, curr, i) => {
-                if(curr === null) {
-                    this.logger.error(`The client config entry at index ${i} in config.json is null but should be an object, will not parse`);
-                    return acc;
-                }
-                if(typeof curr !== 'object') {
-                    this.logger.error(`The client config entry at index ${i} in config.json should be an object, will not parse`);
-                    return acc;
-                }
-                return acc.concat(curr);
-            }, []);
-            for (const c of validMainConfigs) {
-                const {name = 'unnamed'} = c;
-                configs.push({...c,
-                    name,
-                    source: 'config.json',
-                    configureAs: 'client', //override user value
-                });
-            }
-        }
-
-        for (const clientType of this.clientTypes) {
-            let defaultConfigureAs = 'client';
-            switch (clientType) {
-                case 'maloja':
-                    // env builder for single user mode
-                    const url = process.env.MALOJA_URL;
-                    const apiKey = process.env.MALOJA_API_KEY;
-                    if (url !== undefined || apiKey !== undefined) {
-                        configs.push({
-                            type: 'maloja',
-                            name: 'unnamed',
-                            source: 'ENV',
-                            mode: 'single',
-                            data: {
-                                url,
-                                apiKey
-                            }
-                        })
-                    }
-                    break;
-                case 'lastfm':
-                    const lfm = {
-                        apiKey: process.env.LASTFM_API_KEY,
-                        secret: process.env.LASTFM_SECRET,
-                        redirectUri: process.env.LASTFM_REDIRECT_URI,
-                        session: process.env.LASTFM_SESSION,
-                    };
-                    if (!Object.values(lfm).every(x => x === undefined)) {
-                        configs.push({
-                            type: 'lastfm',
-                            name: 'unnamed',
-                            source: 'ENV',
-                            mode: 'single',
-                            data: lfm
-                        })
-                    }
-                    break;
-                default:
-                    break;
-            }
-            let rawClientConfigs;
-            try {
-                rawClientConfigs = await readJson(`${this.configDir}/${clientType}.json`, {throwOnNotFound: false});
-            } catch (e) {
-                this.logger.error(`${clientType}.json config file could not be parsed`);
-                continue;
-            }
-            if (rawClientConfigs !== undefined) {
-                let clientConfigs = [];
-                if (Array.isArray(rawClientConfigs)) {
-                    clientConfigs = rawClientConfigs;
-                } else if(rawClientConfigs === null) {
-                    this.logger.error(`${clientType}.json contained no data`);
-                    continue;
-                } else if (typeof rawClientConfigs === 'object') {
-                    // backwards compatibility, assuming its single-user mode
-                    this.logger.warn(`DEPRECATED: Starting in 0.4 configurations in all [type].json files (${clientType}.json) must be in an array.`);
-                    if (rawClientConfigs.data === undefined) {
-                        clientConfigs = [{data: rawClientConfigs, mode: 'single', name: 'unnamed'}];
-                    } else {
-                        clientConfigs = [rawClientConfigs];
-                    }
-                } else {
-                    this.logger.error(`All top level data from ${clientType}.json must be an array of objects, will not parse configs from file`);
-                    continue;
-                }
-                for (const [i,m] of clientConfigs.entries()) {
-                    if(m === null) {
-                        this.logger.error(`The config entry at index ${i} from ${clientType}.json is null`);
-                        continue;
-                    }
-                    if (typeof m !== 'object') {
-                        this.logger.error(`The config entry at index ${i} from ${clientType}.json was not an object, skipping`, m);
-                        continue;
-                    }
-                    const {configureAs = defaultConfigureAs} = m;
-                    if(configureAs === 'client') {
-                        m.source = `${clientType}.json`;
-                        m.type = clientType;
-                        configs.push(m);
-                    }
-                }
-            }
-        }
-
-        // we have all possible client configurations so we'll check they are minimally valid
-        const validConfigs = configs.reduce((acc, c) => {
-            const isValid = isValidConfigStructure(c, {type: true, data: true});
-            if (isValid !== true) {
-                this.logger.error(`Client config from ${c.source} with name [${c.name || 'unnamed'}] of type [${c.type || 'unknown'}] will not be used because it has structural errors: ${isValid.join(' | ')}`);
-                return acc;
-            }
-            return acc.concat(c);
-        }, []);
-
-        // all client configs are minimally valid
-        // now check that names are unique
-        const nameGroupedConfigs = validConfigs.reduce((acc, curr) => {
-            const {name = 'unnamed'} = curr;
-            const {[name]: n = []} = acc;
-            return {...acc, [name]: [...n, curr]};
-        }, {});
-        let noConflictConfigs = [];
-        for (const [name, configs] of Object.entries(nameGroupedConfigs)) {
-            if (configs.length > 1) {
-                const sources = configs.map(c => `Config object from ${c.source} of type [${c.type}]`);
-                this.logger.error(`The following clients will not be built because of config naming conflicts (they have the same name of "${name}"): 
-${sources.join('\n')}`);
-                if (name === 'unnamed') {
-                    this.logger.info('HINT: "unnamed" configs occur when using ENVs, if a multi-user mode config does not have a "name" property, or if a config is built in single-user mode');
-                }
-            } else {
-                noConflictConfigs = [...noConflictConfigs, ...configs];
-            }
-        }
-
-        // finally! all configs are valid, structurally, and can now be passed to addClient
-        // just need to re-map unnnamed to default
-        const finalConfigs = noConflictConfigs.map(({name = 'unnamed', ...x}) => ({
-            ...x,
-            name
-        }));
-        for (const c of finalConfigs) {
-            try {
-                await this.addClient(c, clientDefaults);
-            } catch(e) {
-                this.logger.error(`Client ${c.name} was not added because it had unrecoverable errors`);
-                this.logger.error(e);
-            }
-        }
-    }
-
-    addClient = async (clientConfig, defaults = {}) => {
-        const isValidConfig = isValidConfigStructure(clientConfig, {name: true, data: true, type: true});
-        if (isValidConfig !== true) {
-            throw new Error(`Config object from ${clientConfig.source || 'unknown'} with name [${clientConfig.name || 'unnamed'}] of type [${clientConfig.type || 'unknown'}] has errors: ${isValidConfig.join(' | ')}`)
-        }
-        const {type, name, data: d = {}} = clientConfig;
-        // add defaults
-        const data = {...defaults, ...d};
-        let newClient;
-        this.logger.debug(`(${name}) Constructing ${type} client...`);
-        switch (type) {
-            case 'maloja':
-                newClient = new MalojaScrobbler(name, data);
-                break;
-            case 'lastfm':
-                newClient = new LastfmScrobbler(name, {...data, configDir: this.configDir});
-                break;
-            default:
-                break;
-        }
-
-        if(newClient === undefined) {
-            // really shouldn't get here!
-            throw new Error(`Client of type ${type} was not recognized??`);
-        }
-        if(newClient.initialized === false) {
-            this.logger.debug(`(${name}) Attempting ${type} initialization...`);
-            if (await newClient.initialize() === false) {
-                this.logger.error(`(${name}) ${type} client failed to initialize. Client needs to be successfully initialized before scrobbling.`);
-            } else {
-                this.logger.info(`(${name}) ${type} client initialized`);
-            }
-        }
-        if(newClient.requiresAuth && !newClient.authed) {
-            this.logger.debug(`(${name}) Checking ${type} client auth...`);
-            let success;
-            try {
-                success = await newClient.testAuth();
-            } catch (e) {
-                success = false;
-            }
-            if(!success) {
-                this.logger.warn(`(${name}) ${type} client auth failed.`);
-            } else {
-                this.logger.warn(`(${name}) ${type} client auth OK`);
-            }
-        }
-        this.clients.push(newClient);
-    }
-
-    /**
-     * @param {*} data
-     * @param {{scrobbleFrom, scrobbleTo, forceRefresh: boolean}|{scrobbleFrom, scrobbleTo}} options
-     * @returns {Array}
-     */
-    scrobble = async (data, options = {}) => {
-        const playObjs = Array.isArray(data) ? data : [data];
-        const {
-            forceRefresh = false,
-            checkTime = dayjs(),
-            scrobbleTo = [],
-            scrobbleFrom = 'source',
-        } = options;
-
-        const tracksScrobbled = [];
-
-        if (this.clients.length === 0) {
-            this.logger.warn('Cannot scrobble! No clients are configured.');
-        }
-
-        for (const client of this.clients) {
-            if (scrobbleTo.length > 0 && !scrobbleTo.includes(client.name)) {
-                this.logger.debug(`Client '${client.name}' was filtered out by '${scrobbleFrom}'`);
-                continue;
-            }
-            if(client.initialized === false) {
-                this.logger.warn(`Cannot scrobble to Client '${client.name}' because it is not yet initialized`);
-                continue;
-            }
-            if(client.requiresAuthInteraction === true && !client.authed) {
-                this.logger.warn(`Cannot scrobble to Client '${client.name}' because user interaction is required for authentication`);
-                continue;
-            }
-
-                if (forceRefresh || client.scrobblesLastCheckedAt().unix() < checkTime.unix()) {
-                    try {
-                        await client.refreshScrobbles();
-                    } catch(e) {
-                        this.logger.error(`Encountered error while refreshing scrobbles for ${client.name}`);
-                        this.logger.error(e);
-                    }
-                }
-                for (const playObj of playObjs) {
-                    try {
-                        const {
-                            meta: {
-                                newFromSource = false,
-                            } = {}
-                        } = playObj;
-                        if (client.timeFrameIsValid(playObj, newFromSource) && !client.alreadyScrobbled(playObj, newFromSource)) {
-                            await client.scrobble(playObj)
-                            client.tracksScrobbled++;
-                            // since this is what we return to the source only add to tracksScrobbled if not already in array
-                            // (source should only know that a track was scrobbled (binary) -- doesn't care if it was scrobbled more than once
-                            if(!tracksScrobbled.some(x => playObjDataMatch(x, playObj) && x.data.playDate === playObj.data.playDate)) {
-                                tracksScrobbled.push(playObj);
-                            }
-                        }
-                    } catch(e) {
-                        this.logger.error(`Encountered error while in scrobble loop for ${client.name}`);
-                        this.logger.error(e);
-                        // for now just stop scrobbling plays for this client and move on. the client should deal with logging the issue
-                        if(e.continueScrobbling !== true) {
-                            break;
-                        }
-                    }
-                }
-        }
-        return tracksScrobbled;
-    }
-}

cliff.toml

@@ -0,0 +1,67 @@
+# configuration file for git-cliff (0.1.0)
+
+[changelog]
+# changelog header
+header = """
+# Changelog
+All notable changes to this project will be documented in this file.\n
+"""
+# template for the changelog body
+# https://tera.netlify.app/docs/#introduction
+body = """
+{% if version %}\
+    ## [{{ version | replace(from="v", to="") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}\
+    ## [unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | upper_first }}
+    {% for commit in commits
+    | filter(attribute="scope")
+    | sort(attribute="scope") %}
+        - *({{commit.scope}})* {{ commit.message | upper_first }}
+        {%- if commit.breaking %}
+        {% raw %}  {% endraw %}- **BREAKING**: {{commit.breaking_description}}
+        {%- endif -%}
+    {%- endfor -%}
+    {%- for commit in commits %}
+        {%- if commit.scope -%}
+        {% else -%}
+            - *(No Category)* {{ commit.message | upper_first }}
+            {% if commit.breaking -%}
+            {% raw %}  {% endraw %}- **BREAKING**: {{commit.breaking_description}}
+            {% endif -%}
+        {% endif -%}
+    {% endfor -%}
+{% endfor %}
+"""
+# remove the leading and trailing whitespaces from the template
+trim = true
+# changelog footer
+footer = """
+<!-- generated by git-cliff -->
+"""
+
+[git]
+# allow only conventional commits
+# https://www.conventionalcommits.org
+conventional_commits = true
+# regex for parsing and grouping commits
+commit_parsers = [
+    { message = "^feat", group = "Features"},
+    { message = "^fix", group = "Bug Fixes"},
+    { message = "^doc", group = "Documentation"},
+    { message = "^perf", group = "Performance"},
+    { message = "^refactor", group = "Refactor"},
+    { message = "^style", group = "Styling"},
+    { message = "^test", group = "Testing"},
+    { message = "^chore\\(release\\): prepare for", skip = true},
+    { message = "^chore", group = "Miscellaneous Tasks"},
+    { body = ".*security", group = "Security"},
+]
+# filter out the commits that are not matched by commit parsers
+filter_commits = false
+# glob pattern for matching git tags
+tag_pattern = "[0-9]*"
+# regex for skipping tags
+skip_tags = "v0.1.0-beta.1"

config/README.md

@@ -0,0 +1,12 @@
+These are **example configurations** for all Source/Client types and AIO config.
+
+These can be used as-is by renaming them to `.json` and filling or replacing sample data.
+
+For docker installations these examples are copied to your configuration directory on first-time use.
+
+These are **NOT** exhaustive examples. You should consult the  **configuration** documentation and the **schema explorer links** for each source/config type to see a complete list of options and descriptions for all properties.
+
+Documentation at
+
+* [internal docs](../docsite/docs/configuration/configuration.mdx)
+* External Link: https://foxxmd.github.io/multi-scrobbler/docs/configuration

config/chromecast.json.example

@@ -0,0 +1,11 @@
+[
+  {
+    "name": "MyCast",
+    "data": {
+      "blacklistedDevices": [],
+      "whitelistedDevices": [],
+      "blacklistedApps": [],
+      "whitelistedApps": []
+    }
+  }
+]

config/config.json.example

@@ -1,32 +1,70 @@
 {
+  "debugMode": false,
+  "disableWeb": false,
   "sourceDefaults": {
-    "maxPollRetries": 0,          // optional, default # of automatic polling restarts on error. can be overridden by property in individual config
-    "maxRequestRetries": 1,       // optional, default # of http request retries a source can make before error is thrown. can be overridden by property in individual config
-    "retryMultiplier": 1.5,       // optional, default retry delay multiplier (retry attempt * multiplier = # of seconds to wait before retrying). can be overridden by property in individual config
+    "logPayload": false,
+    "logFilterFailure": "warn",
+    "logPlayerState": false,
+    "scrobbleThresholds": {
+      "duration": 30,
+      "percent": 50
+    },
+    "maxPollRetries": 1,
+    "maxRequestRetries": 1,
+    "retryMultiplier": 1.5
   },
   "clientDefaults": {
-    "maxRequestRetries": 1,       // optional, default # of http request retries a client can make before error is thrown. can be overridden by property in individual config
-    "retryMultiplier": 1.5,       // optional, default retry delay multiplier (retry attempt * multiplier = # of seconds to wait before retrying). can be overridden by property in individual config
+    "maxRequestRetries": 1,
+    "retryMultiplier": 1.5
   },
   "sources": [
     {
-      "type": "spotify",          // required, source type
-      "clients": ["myConfig"],    // optional, a list of Client config names this Source should scrobble to. Using an empty list or not including this property will make this Source scrobble to all Clients.
-      "name": "mySpotifySource",  // optional, friendly name for the log
-      "data": {                   // required, the data for your config
-        "clientId": "example",
-        //...
+      "type": "spotify",
+      "enable": true,
+      "clients": ["myConfig"],
+      "name": "mySpotifySource",
+      "data": {
+        "clientId": "a89cba1569901a0671d5a9875fed4be1",
+        "clientSecret": "ec42e09d5ae0ee0f0816ca151008412a",
+        "redirectUri": "http://localhost:9078/callback"
       }
     }
   ],
   "clients": [
     {
-      "type": "maloja",           // required, Client type
-      "name": "myConfig",         // required, a name to identifier your Client
-      "data": {                   // required, the data for your config
-        "url": "http://example.com",
-        //...
+      "type": "maloja",
+      "enable": true,
+      "name": "myConfig",
+      "data": {
+        "url": "http://localhost:42010",
+        "apiKey": "myMalojaKey"
+      }
+    }
+  ],
+  "webhooks": [
+    {
+      "name": "FirstGotifyServer",
+      "type": "gotify",
+      "url": "http://localhost:8070",
+      "token": "MyGotifyToken",
+      "priorities": {
+        "info": 5,
+        "warn": 7,
+        "error": 10
       }
     },
+    {
+      "type": "ntfy",
+      "name": "MyNtfyFriendlyNameForLogs",
+      "url": "http://localhost:9991",
+      "topic": "MyMultiScrobblerTopic",
+      "username": "Optional",
+      "password": "Optional",
+      "priorities": {
+        "info": 3,
+        "warn": 4,
+        "error": 5
+      }
+    }
   ]
 }

config/deezer.json.example

@@ -0,0 +1,13 @@
+[
+  {
+    "name": "FoxxMDeezer",
+    "enable": true,
+    "clients": [],
+    "data": {
+      "clientId": "a89cba1569901a0671d5a9875fed4be1",
+      "clientSecret": "ec42e09d5ae0ee0f0816ca151008412a",
+      "redirectUri": "http://localhost:9078/deezer/callback",
+      "interval": 60
+    }
+  }
+]

config/jellyfin.json.example

@@ -1,10 +1,15 @@
 [
   {
-    "name": "default",                                        // optional, friendly name for logs
-    "clients": [],                                            // optional, list of scrobble clients (by config name) that this source should scrobble to. Using an empty list or not including this property will make this source scrobble to all clients.
+    "name": "MyJellyfin",
+    "enable": true,
+    "clients": [],
     "data": {
-      "users": ["FoxxMD"],                                     // optional, list of users to scrobble tracks for
-      "servers": ["myServer","anotherServer"]                 // optional, list of servers to scrobble tracks from
+      "users": ["FoxxMD"],
+      "servers": ["myServer","anotherServer"]
+    },
+    "options": {
+      "logPayload": false,
+      "logFilterFailure": "warn"
     }
   }
 ]

config/jriver.json.example

@@ -0,0 +1,11 @@
+[
+  {
+    "name": "MyJriver",
+    "enable": true,
+    "data": {
+      "url": "0.0.0.0",
+      "username": "auser",
+      "password": "apassword"
+    }
+  }
+]

config/kodi.json.example

@@ -0,0 +1,11 @@
+[
+  {
+    "name": "MyKodi",
+    "enable": true,
+    "data": {
+      "url": "http://localhost:8080/jsonrpc",
+      "username": "myUser",
+      "password": "myPassword"
+    }
+  }
+]

config/lastfm.json.example

@@ -1,16 +1,12 @@
 [
   {
-    "name": "myLastFm",                                          // [As Client/Source] required if configured as "client", a name to identify your Client/Source
-    "configureAs": "client",                                     // optional and default to "client", set to "source" to use this configuration as a Source
-    "clients": [],                                               // [As Source] optional, list of scrobble Clients (by config name) that this Source should scrobble to. Using an empty list or not including this property will make this Source scrobble to all Clients.
+    "name": "myLastFm",
+    "enable": true,
+    "configureAs": "client",
     "data": {
-      "apiKey": "string",                                        // required, Lastfm api key
-      "secret": "string",                                        // required, Lastfm shared secret
-      "session": "string",                                       // optional, session id returned from a complete auth flow.
-                                                                 //   if not specified will be generated during authentication
-      "redirectUri": "http://localhost:9078/lastfm/callback"     // optional, if not different than this default
-                                                                 //   callback for auth. Must have "lastfm/callback" in the url somewhere
-      // ALSO see config.json.example for default properties that can be overridden here (in clientDefaults)
+      "apiKey": "a89cba1569901a0671d5a9875fed4be1",
+      "secret": "ec42e09d5ae0ee0f0816ca151008412a",
+      "redirectUri": "http://localhost:9078/lastfm/callback"
     }
   }
 ]

config/listenbrainz.json.example

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

config/maloja.json.example

@@ -1,10 +1,10 @@
 [
   {
-    "name": "myMaloja",            // required, a name to identify your Client
+    "name": "myMaloja",
+    "enable": true,
     "data": {
-      "url": "https://domain.tld", // required, the base url of your maloja installation
-      "apiKey": "string"           // required, your maloja api key
-      // ALSO see config.json.example for default properties that can be overridden here (in clientDefaults)
+      "url": "http://localhost:42010",
+      "apiKey": "myMalojaKey"
     }
   }
 ]

config/mopidy.json.example

@@ -0,0 +1,12 @@
+[
+  {
+    "name": "MyMopidy",
+    "enable": true,
+    "data": {
+      "url": "localhost",
+      "uriBlacklist": [],
+      "uriWhitelist": [],
+      "albumBlacklist": []
+    }
+  }
+]

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/mpris.json.example

@@ -0,0 +1,10 @@
+[
+  {
+    "name": "ubuntu",
+    "enable": true,
+    "data": {
+      "whitelist": ["vlc", "mpd"],
+      "blacklist": ["spotify"]
+    }
+  }
+]

config/musikcube.json.example

@@ -0,0 +1,11 @@
+[
+  {
+    "type": "musikcube",
+    "enable": true,
+    "name": "musikcube",
+    "data": {
+      "url": "ws://localhost:7905",
+      "password": "MY_PASSWORD"
+    }
+  }
+]

config/plex.json.example

@@ -1,11 +1,15 @@
 [
   {
-    "name": "default",                                        // optional, friendly name for logs
-    "clients": [],                                            // optional, list of scrobble clients (by config name) that this source should scrobble to. Using an empty list or not including this property will make this source scrobble to all clients.
+    "name": "MyPlex",
+    "enable": true,
+    "clients": [],
     "data": {
-      "user": ["username@gmail.com","anotherUser@gmail.com"], // optional, list of users to scrobble tracks for
-      "libraries": ["music","my podcasts"],                   // optional, list of libraries to scrobble tracks from
-      "servers": ["myServer","anotherServer"]                 // optional, list of servers to scrobble tracks from
+      "user": ["username@gmail.com","anotherUser@gmail.com"],
+      "libraries": ["music","my podcasts"],
+      "servers": ["myServer","anotherServer"],
+      "options": {
+        "logFilterFailure": "warn"
+      }
     }
   }
 ]

config/spotify.json.example

@@ -1,15 +1,13 @@
 [
   {
-    "name": "default",                                // optional, friendly name for logs
-    "clients": [],                                    // optional, list of scrobble clients (by config name) that this source should scrobble to. Using an empty list or not including this property will make this source scrobble to all clients.
+    "name": "MySpotify",
+    "enable": true,
+    "clients": [],
     "data": {
-      "clientId": "string",                           // spotify client id -- required if not providing access token
-      "clientSecret": "string",                       // spotify client secret -- required if not providing access token
-      "accessToken": "string",                        // spotify access token -- required if not providing client id/secret
-      "refreshToken": "string",                       // spotify refresh token -- recommended to provide if not providing client id/secret
-      "redirectUri": "http://localhost:9078/callback",// spotify redirect URI -- required only if not the default shown here. URI must end in "callback"
-      "interval": 60,                                 // optional, how long to wait before calling spotify for new tracks
-      // ALSO see config.json.example for default properties that can be overridden here (in sourceDefaults)
+      "clientId": "a89cba1569901a0671d5a9875fed4be1",
+      "clientSecret": "ec42e09d5ae0ee0f0816ca151008412a",
+      "redirectUri": "http://localhost:9078/callback",
+      "interval": 60
     }
   }
 ]

config/subsonic.json.example

@@ -1,11 +1,11 @@
 [
   {
-    "name": "default",                        // optional, friendly name for logs
+    "name": "MySubsonic",
+    "enable": true,
     "data": {
-      "url": "http://localhost:4040/airsonic",// required, the url you would visit to listen to music on the web
-      "user": "yourUser",                     // required, username to login with
-      "password": "yourPassword",             // required, password to login with
-      // ALSO see config.json.example for default properties that can be overridden here (in sourceDefaults)
+      "url": "http://localhost:4040/airsonic",
+      "user": "yourUser",
+      "password": "yourPassword"
     }
   }
 ]

config/tautulli.json.example

@@ -1,11 +1,15 @@
 [
   {
-    "name": "default",                                        // optional, friendly name for logs
-    "clients": [],                                            // optional, list of scrobble clients (by config name) that this source should scrobble to. Using an empty list or not including this property will make this source scrobble to all clients.
+    "name": "MyTautuilli",
+    "enable": true,
+    "clients": [],
     "data": {
-      "user": ["username@gmail.com","anotherUser@gmail.com"], // optional, list of users to scrobble tracks for
-      "libraries": ["music","my podcasts"],                   // optional, list of libraries to scrobble tracks from
-      "servers": ["myServer","anotherServer"]                 // optional, list of servers to scrobble tracks from
+      "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

@@ -0,0 +1,10 @@
+[
+  {
+    "name": "MyWebScrobbler",
+    "data": {
+      "slug": null,
+      "whitelist": [],
+      "blacklist": []
+    }
+  }
+]

config/ytmusic.json.example

@@ -0,0 +1,11 @@
+[
+  {
+    "name": "MyYTMusic",
+    "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"
+    }
+  }
+]

docker-compose.yml

@@ -0,0 +1,26 @@
+version: '3.7'
+
+services:
+  multi-scrobbler:
+    image: foxxmd/multi-scrobbler
+    container_name: multi-scrobbler
+    environment:
+      - TZ=Etc/GMT # Specify timezone from TZ Database name found here https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+      #- SPOTIFY_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:
+      - /path_on_host/multi-scrobbler-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/root/etc/s6-overlay/s6-rc.d/init-ms-config/run

@@ -0,0 +1,33 @@
+#!/usr/bin/with-contenv bash
+
+# used https://github.com/linuxserver/docker-plex as a template
+
+POPULATE_EXAMPLES=false
+
+echo "-------------------------------------"
+echo -e "Setting up multi-scrobbler config directory based on CONFIG_DIR env: ${CONFIG_DIR}\n"
+
+# make config folder if it does not exist
+if [ ! -d "${CONFIG_DIR}" ]; then
+  echo "Directory does not exist! Creating..."
+  POPULATE_EXAMPLES=true
+  mkdir -p "${CONFIG_DIR}"
+else
+  if [ "$(ls -A ${CONFIG_DIR})" ]; then
+       echo "Directory is not empty, not creating examples."
+    else
+      POPULATE_EXAMPLES=true
+    fi
+fi
+
+# add example configs
+if [ "$POPULATE_EXAMPLES" = true ]; then
+  echo "Directory is empty, adding examples..."
+  cp -r /app/config/. "${CONFIG_DIR}"/
+fi
+
+# permissions
+echo "chown'ing directory to ensure correct permissions."
+chown -R abc:abc "${CONFIG_DIR}"
+echo "Done!"
+echo -e "-------------------------------------\n"

docker/root/etc/s6-overlay/s6-rc.d/init-ms-config/type

@@ -0,0 +1 @@
+oneshot

docker/root/etc/s6-overlay/s6-rc.d/init-ms-config/up

@@ -0,0 +1 @@
+/etc/s6-overlay/s6-rc.d/init-ms-config/run

docker/root/etc/s6-overlay/s6-rc.d/svc-node/run

@@ -0,0 +1,10 @@
+#!/usr/bin/with-contenv bash
+
+# used https://github.com/linuxserver/docker-wikijs/blob/master/root/etc/s6-overlay/s6-rc.d/svc-wikijs/run as a template
+
+# NODE_ARGS can be passed by ENV in docker command like "docker run foxxmd/multi-scrobbler -e NODE_ARGS=--optimize_for_size"
+echo -e "\nmulti-scrobbler is starting!"
+export NODE_ENV=production
+cd /app || exit
+exec \
+	  s6-setuidgid abc /usr/bin/node $NODE_ARGS /app/node_modules/.bin/tsx /app/src/backend/index.ts

docker/root/etc/s6-overlay/s6-rc.d/svc-node/type

@@ -0,0 +1 @@
+longrun

docs/configuration.md

@@ -1,219 +0,0 @@
-# General
-
-General configuration options. These must be set through environmental variables because they affect initial startup of
-the app. **These variables are also available to Docker containers.**
-
-| Environmental Variable | Required? |   Default    |                                        Description                                        |
-|----------------------------|-----------|--------------|-------------------------------------------------------------------------------------------|
-| `CONFIG_DIR`               |         No | `CWD/config` | Directory to look for all other configuration files                                       |
-| `LOG_PATH`                 |         No | `CWD/logs`   | If `false` no logs will be written. If `string` will be the directory logs are written to |
-| `PORT`                     |         No | 9078         | Port to run web server on                                                                 |
-
-**The app must have permission to write to `CONFIG_DIR` in order to store the current spotify access token.**
-
-
-# Sources and (Scrobble) Clients
-
-The app has two types of configurations:
-
-* **Sources** -- Where plays are parsed from
-* **Clients** -- Scrobble clients that plays are scrobbled to
-
-All configurations can be configured through:
-* environmental variables
-* individual **json** files for each source/client type found in the `CONFIG_DIR` directory IE `config/spotify.json`
-* or through the main `config.json` (also found in `CONFIG_DIR` directory) using the `clients` or `sources` property under `data`:
-
-```json5
-// in config.json
-{
-  //...
-  "sources": [
-    {
-      "name": "myConfig",
-      "type": "spotify",
-      "clients": [
-        "myMalojaClient"
-      ],
-      "data": {
-        "clientId": "anExample"
-        //...
-      }
-    }
-  ]
-}
-```
-
-See [config.json.example](../config/config.json.example) for a short example of this or check out [the kitchen sink example](kitchensink.md).
-
-### ENV-Based or JSON-Based?
-
-multi-scrobbler can be configured differently depending on how you will use it. See which use-case fits you the best and then use that approach when setting up each configuration:
-
-#### ENV-Based (Single User)
-
-* You are the only person for whom the application is scrobbling
-* You may have many sources (Plex, Spotify, Tautulli...) but you only have one of each type of source
-* You have only one scrobble client
-* **Easier for small setups. Difficult for larger, multi-sourced setups (may want to switch to json)**
-* **Will not work for multi-user setups**
-
-#### JSON-Based (Multi User)
-
-* You are a single user but want to set up many sources
-* You want to use multi-scrobbler to scrobble for yourself and others IE family, friends, etc.
-* You may have many of each type of **Source** you want to scrobble from IE 2x Plex accounts, 3x Spotify accounts, 1x
-  Funkwhale...
-* You have more than one scrobble **Client** you want to scrobble to IE multiple Maloja servers, one for each person
-* You want only some **Sources** to scrobble to some **Clients** IE Fred's Spotify account scrobbles to Fred's Maloja
-  server, but not Mary's Maloja server
-
-Note: While you may mix and match configuration approaches it is recommended to **only use ENV-based configs if you are
-doing everything in ENV-based configurations.**
-
-# Sources
-
-## [Spotify](https://www.spotify.com)
-
-To access your Spotify history you must [register an application](https://developer.spotify.com/dashboard) to get a
-Client ID/Secret. Make sure to also whitelist your redirect URI in the application settings.
-
-### ENV-Based
-
-| Environmental Variable     | Required? |            Default             |                    Description                     |
-|----------------------------|-----------|----------------------------------|----------------------------------------------------|
-| `SPOTIFY_CLIENT_ID`        | Yes       |                                  |                                                    |
-| `SPOTIFY_CLIENT_SECRET`    | Yes       |                                  |                                                    |
-| `SPOTIFY_ACCESS_TOKEN`     | No         |                                  | Must include either this token or client id/secret |
-| `SPOTIFY_REFRESH_TOKEN`    | No         |                                  | If using access token this is also recommended      |
-| `SPOTIFY_REDIRECT_URI`     | No         | `http://localhost:{PORT}/callback` | URI must end in `callback`                         |
-
-### JSON-Based
-
-See [`spotify.json.example`](../config/spotify.json.example)
-
-## [Plex](https://plex.tv)
-
-Check the [instructions](plex.md) on how to setup a [webhooks](https://support.plex.tv/articles/115002267687-webhooks) to scrobble your plays.
-
-### ENV-Based
-
-| Environmental Variable | Required | Default |                   Description                   |
-|------------------------|----------|---------|-------------------------------------------------|
-| `PLEX_USER`              |        No |         | The a comma-delimited list of usernames to scrobble tracks for. No usernames specified means all tracks by all users will be scrobbled. |
-
-### JSON-Based
-
-See [`plex.json.example`](../config/plex.json.example)
-
-## [Tautulli](https://tautulli.com)
-
-Check the [instructions](plex.md) on how to setup a notification agent.
-
-### ENV-Based
-
-| Environmental Variable | Required | Default |                   Description                   |
-|------------------------|----------|---------|-------------------------------------------------|
-| `TAUTULLI_USER`              |        No |         | The a comma-delimited list of usernames to scrobble tracks for. No usernames specified means all tracks by all users will be scrobbled. |
-
-### JSON-Based
-
-See [`tautulli.json.example`](../config/tautulli.json.example)
-
-## [Subsonic](http://www.subsonic.org/)
-
-Can use this source for any application that implements the [Subsonic API](http://www.subsonic.org/pages/api.jsp) (such as [Airsonic](https://airsonic.github.io/))
-
-**Known Issues:**
-* "Time played at" is somewhat inaccurate since the api only reports "played X minutes ago" so...
-  * All scrobble times are therefore "on the minute" and you may experience occasional duplicate scrobbles
-  * "played X minutes ago" sometimes is also not reported correctly
-* Multiple artists are reported as one value and cannot be separated
-* If using [Airsonic Advanced](https://github.com/airsonic-advanced/airsonic-advanced) the password used (under **Credentials**) must be **Decodable**  
-
-### ENV-Based
-
-| Environmental Variable     | Required? |            Default             |                    Description                     |
-|----------------------------|-----------|----------------------------------|----------------------------------------------------|
-| `SUBSONIC_USER`        | Yes       |                                  |                                                    |
-| `SUBSONIC_PASSWORD`    | Yes       |                                  |                                                    |
-| `SUBSONIC_URL`     | Yes         |                                  | Base url of your subsonic-api server |
-
-### JSON-Based
-
-See [`subsonic.json.example`](../config/subsonic.json.example)
-
-## [Jellyfin](https://jellyfin.org/)
-
-Must be using Jellyfin 10.7 or greater
-
-* Add the [Webhook Plugin](https://github.com/crobibero/jellyfin-plugin-webhook) repository to your plugins, then restart your server
-* In the Webhook settings:
-  * `Add Generic Destination`
-  * In the new `Generic` dropdown:
-    * Webhook Url: `http://localhost:9078/jellyfin`
-    * Notification Type: `Playback Progress`
-    * Item Type: `Songs`
-    * Check `Send All Properties`
-  * Save
-
-### ENV-Based
-
-| Environmental Variable | Required? | Default | Description                                                       |
-|------------------------|-----------|---------|-------------------------------------------------------------------|
-| `JELLYFIN_USER`        |           |         | Comma-separated list of usernames (from Jellyfin) to scrobble for |
-| `JELLYFIN_SERVER`      |           |         | Comma-separated list of Jellyfin server names to scrobble from    |
-
-### JSON-Based
-
-See [`jellyfin.json.example`](../config/jellyfin.json.example)
-
-## [Last.fm (Source)](https://www.last.fm)
-
-See the [Last.fm (Client)](#lastfm) setup for registration instructions.
-
-### ENV-Based
-
-No support for ENV based for Last.fm as a client (only source)
-
-### JSON-Based
-
-See [`lastfm.json.example`](../config/lastfm.json.example), change `configureAs` to `source`.
-
-# Clients
-
-## [Maloja](https://github.com/krateng/maloja)
-
-### ENV-Based
-
-| Environmental Variable | Required? | Default |          Description          |
-|----------------------------|-----------|---------|-------------------------------|
-| `MALOJA_URL`               | Yes       |         | Base URL of your installation |
-| `MALOJA_API_KEY`           | Yes       |         | Api Key                       |
-
-### JSON-Based
-
-See [`maloja.json.example`](../config/maloja.json.example)
-
-## [Last.fm](https://www.last.fm)
-
-[Register for an API account here.](https://www.last.fm/api/account/create)
-
-The Callback URL is actually specified by multi-scrobbler but to keep things consistent you should use
-```
-http://localhost:9078/lastfm/callback
-```
-or replace `localhost:9078` with your own base URL
-
-### ENV-Based
-
-| Environmental Variable | Required? | Default |          Description          |
-|----------------------------|-----------|---------|-------------------------------|
-| `LASTFM_API_KEY`           | Yes       |         | Api Key from your API Account |
-| `LASTFM_SECRET`            | Yes       |         | Shared secret from your API Account |
-| `LASTFM_REDIRECT_URI`      | No        | `http://localhost:{PORT}/lastfm/callback`        | Url to use for authentication. Must include `lastfm/callback` somewhere in it |
-| `LASTFM_SESSION`           | No        |         | Session id. Will be generated by authentication flow if not provided.                       |
-
-### JSON-Based
-
-See [`lastfm.json.example`](../config/lastfm.json.example)

docsite/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docsite/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docsite/babel.config.js

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

docsite/docs/FAQ.md

@@ -0,0 +1,203 @@
+---
+toc_min_heading_level: 2
+toc_max_heading_level: 5
+---
+
+## Connection Issues
+
+### Plex/Tautulli/Jellyfin/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.
+
+multi-scrobbler will log information about any server that connects to it for these services. In the logs it looks something like this:
+
+```
+2023-02-22T10:55:56-05:00 info   : [Ingress - Plex  ] Received request from a new remote address: ::ffff:192.168.0.140 (UA: PlexMediaServer/1.24.5.5173-8dcc73a59)
+2023-02-22T10:55:56-05:00 info   : [Ingress - Plex  ] ::ffff:192.168.0.140 (UA: PlexMediaServer/1.24.5.5173-8dcc73a59) Received valid data from server examplePlex for the first time.
+2023-02-22T10:55:56-05:00 warn   : [Plex Request    ] Received valid Plex webhook payload but no Plex sources are configured
+```
+It also logs if a server tries to connect to a URL that it does not recognize:
+```
+2023-02-22T11:16:12-05:00 debug  : [App             ] Server received POST request from ::ffff:192.168.0.140 (UA: PlexMediaServer/1.24.5.5173-8dcc73a59) to unknown route: /plkex
+```
+**So, if you do not see either of these in your logs then Plex/Tautulli/Jellyfin/Webscrobbler is not able to connect to your multi-scrobbler instance at all.**
+
+This is not something multi-scrobbler can fix and means you have an issue in your network.
+
+#### Troubleshooting
+
+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.
+
+##### Check Host name and URL
+
+The URLs examples in the [configuration](configuration/configuration.mdx) documentation assume you are running Plex/Tautulli/Jellyfin/Webscrobbler on the same server as multi-scrobbler. If these are not the same machine then you need to determine the IP address or domain name that multi-scrobbler is reachable at and use that instead of `localhost` when configuring these sources. **This is likely the same host name that you would use to access the web interface for multi-scrobbler.**
+
+EX `http://localhost:9078/plex` -> `http://192.168.0.140:9078/plex`
+
+##### Check Firewall and Port Forwarding
+
+If the machine multi-scrobbler is running on has a firewall ensure that port **9078** is open. Or if it is in another network entirely make sure your router is forwarding this port and it is open to the correct machine.
+
+##### Check Source Service Logs
+
+Plex/Tautulli/Jellyfin all have logs that will log if they cannot connect to multi-scrobbler. Check these for further information.
+
+###### Plex
+
+Settings -> Manage -> Console
+
+###### Tautulli
+
+Check the command-line output of the application or docker logs.
+
+###### Jellyfin
+
+Administration -> Dashboard -> Advanced -> Logs
+
+###### Webscrobbler
+
+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
+
+Make sure you have 
+* [Configured the webhook plugin correctly](configuration/configuration.mdx#jellyfin)
+  * Checked the **Send All Properties(ignores template)** option in the webhook settings and **Saved**
+
+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
+    }
+  }
+]
+```
+
+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
+
+If you experience issues trying to scrobble with Jellyfin and find this in your MS logs
+
+```
+[API] Jellyfin is not sending a request with valid headers...
+```
+
+A workaround that may fix this:
+
+* In Webhook settings:
+  * [In the webhook you have already configured...](configuration/configuration.mdx#jellyfin)
+    * Add Request Header...
+      * **Key:** `Content-Type`
+      * **Value:** `application/json`
+  * Then Save
+
+### Spotify/Deezer/LastFM won't authenticate
+
+Ensure any **client id** or **secrets** are correct in your configuration.
+
+The callback/redirect URL for these services must be:
+
+* the same address you would use to access the multi-scrobbler web interface
+  * the web-interface must be accessible from the browser you are completing authentication from.
+
+If multi-scrobbler is not running on the same machine your browser is on then the default/example addresses (`http://localhost...`) **will not work.** You must determine the address you can reach the web interface at (such as `http://192.168.0.140:9078`) then use that in place of `localhost` in the callback URLs.
+
+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
+
+The Youtube Music library relies on scraping the YTM site (pretending to be a browser) by using cookies/auth from your actual 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.
+
+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 access. [Follow the YTM instructions to retrieve a new set of cookies for multi-scrobbler]((configuration/configuration.mdx#youtube-music)) and then restart MS to potentially resolve the problem. See [this issue](https://github.com/FoxxMD/multi-scrobbler/issues/158) for further discussion of the problem.
+
+## Configuration Issues
+
+### Config could not be parsed
+
+If you see something like this in your logs:
+
+```
+2023-02-19T10:05:42-06:00 warn   : [App] App config file exists but could not be parsed!
+2023-02-19T10:05:42-06:00 error  : [App] Exited with uncaught error
+2023-02-19T10:05:42-06:00 error  : [App] Error: config.json could not be parsed
+```
+
+It means the JSON in your configuration file is not valid. Copy and paste your configuration into a site like [JSONLint](https://jsonlint.com/) to find out where errors you have and fix them.
+
+## Scrobbling Issues
+
+### Last.fm does not scrobble tracks with multiple artists correctly
+
+This is a limitation of the [Last.fm API](https://www.last.fm/api/show/track.scrobble) where the **artist** field is only one string and Last.fm does not recognize (play well) with "combined" artists.
+
+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
+
+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)
+
+### 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.
+
+To diagnose these issues you [**must enable payload logging**](configuration/configuration.mdx#cast-troubleshooting) for your google cast Source, run MS, and then include logs with this output from that run. Without the raw data logged from your cast device it will be nearly impossible to resolve your issue.
+
+### Google Cast device does not track media
+
+It is likely the app playing on the cast device is incorrectly reporting the media type as **not music**. 
+
+MS logs will tell you what type the media is reported as with lines like:
+
+```
+My Artist - Example Track has 'unknown' media type and allowUnknownMedia=false, will not track
+```
+
+Refer to [Allow Unknown Media Type](configuration/configuration.mdx#allow-unknown-media-type) section to fix this
+
+```
+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 scrobbles
+
+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).
+
+In order 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.
+
+See [this issue](https://github.com/FoxxMD/multi-scrobbler/issues/156#issuecomment-2312533486) for further discussion and a more detailed explanation of why this is happening and how multi-scrobbler compensates for it.

docsite/docs/configuration/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Configuration",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Configuring Multi-Scrobbler and examples"
+  }
+}

docsite/docs/configuration/kitchensink.md

@@ -1,3 +1,8 @@
+---
+sidebar_position: 3
+title: Kitchen Sink
+---
+
 # Example Config using all Possible Features
 
 Scenario: 
@@ -6,17 +11,17 @@ Scenario:
 * Each person has their own Maloja server
 * Each person has their own Spotify account
 * You have your own Airsonic (subsonic) server you to scrobble from
+* You have your own Youtube Music account you want to scrobble from
 * Mary has her own Last.fm account she also wants to scrobble to
 * Fred has his own Spotify application and provides you with just his access and refresh token because he doesn't trust you (wtf Fred)
 * Fred has a Plex server and wants to scrobble everything he plays
 * Mary uses Fred's Plex server but only wants to scrobble her plays from the `podcast` library
 * The three of you have a shared library on Plex called `party` that you only play when you are hanging out. You want plays from that library to be scrobbled to everyone's servers.
+* Fred also has his own Jellyfin server and wants to scrobble everything he plays
 
 ### All-in-one Config
 
-Using just one config file located at `CONFIG_DIR/config.json`:
-
-```json5
+```json5 title="CONFIG_DIR/config.json"
 {
   "sourceDefaults": {
     "maxPollRetries": 0,          // optional, default # of automatic polling restarts on error. can be overridden by property in individual config
@@ -35,6 +40,8 @@ Using just one config file located at `CONFIG_DIR/config.json`:
       "data": {
         "clientId": "foxxSpotifyAppId", 
         "clientSecret": "foxxSpotifyAppSecret",
+      },
+      "options": {
         "maxRequestRetries": 2,  // override default max retries because spotify can...spotty
       }
     },
@@ -82,6 +89,14 @@ Using just one config file located at `CONFIG_DIR/config.json`:
         "libraries": ["party"],
       }
     },
+    {
+      "type": "jellyfin",
+      "name": "FredJelly",
+      // omitting clients (or making it empty) will make this Source scrobble to all Clients
+      "data": {
+        "user": ["fred@email.com"]
+      }
+    },
     {
       "type": "subsonic",
       "name": "foxxAirsonic",
@@ -92,6 +107,15 @@ Using just one config file located at `CONFIG_DIR/config.json`:
         "url": "https://airsonic.foxx.example"
       }
     },
+    {
+      "type": "ytmusic",
+      "name": "foxxYoutube",
+      "clients": ["foxxMaloja"],
+      "data": {
+        "cookie": "__Secure-3PAPISID=3AxsXpy0MKGu75Qb/AkISXGqOnSDn1jEKn; DEVICE_INFO=ChxOekU0Tmpjek5EWTBPRGd3TlRBMk16QXpNdz09EJbS8Z0GGJbS8Z0G; ...",
+        "authUser": 1
+      }
+    },
   ],
   "clients": [
     {
@@ -124,6 +148,7 @@ Using just one config file located at `CONFIG_DIR/config.json`:
       "data": {
         "apiKey": "maryApiKey",
         "secret": "marySecret",
+        "redirectUri": "http://localhost:9078/lastfm/callback"
       }
     }
   ]
@@ -133,9 +158,7 @@ Using just one config file located at `CONFIG_DIR/config.json`:
 
 ### Separate JSON files
 
-In `CONFIG_DIR/spotify.json`:
-
-```json5
+```json5 title="CONFIG_DIR/spotify.json"
 [
   {
     // may omit 'type' property since app knows this is file is for spotify configs
@@ -143,7 +166,7 @@ In `CONFIG_DIR/spotify.json`:
     "clients": ["foxxMaloja"],
     "data": {
       "clientId": "foxxSpotifyAppId",
-      "clientSecret": "foxxSpotifyAppSecret",
+      "clientSecret": "foxxSpotifyAppSecret"
     }
   },
   {
@@ -151,7 +174,7 @@ In `CONFIG_DIR/spotify.json`:
     "clients": ["maryMaloja"],
     "data": {
       "clientId": "foxxSpotifyAppId",
-      "clientSecret": "foxxSpotifyAppSecret",
+      "clientSecret": "foxxSpotifyAppSecret"
     }
   },
   {
@@ -160,15 +183,13 @@ In `CONFIG_DIR/spotify.json`:
     "data": {
       "accessToken": "fredsToken",
       "refreshToken": "fredsRefreshToken",
-      "interval": 120,
+      "interval": 120
     }
   },
 ]
 ```
 
-In `CONFIG_DIR/plex.json`
-
-```json5
+```json5 title="CONFIG_DIR/plex.json"
 [
   {
     "name": "fredPlex",
@@ -188,15 +209,38 @@ In `CONFIG_DIR/plex.json`
   {
     "name": "partyPlex",
     "data": {
-      "libraries": ["party"],
+      "libraries": ["party"]
     }
   }
 ]
 ```
 
-In `CONFIG_DIR/maloja.json`:
+```json5 title="CONFIG_DIR/jellyfin.json"
+[
+  {
+    "name": "FredJelly",
+    "data": {
+      "user": ["fred@email.com"]
+    }
+  }
+]
+```
 
-```json5
+```json5 title="CONFIG_DIR/ytmusic.json"
+[
+  {
+    "type": "ytmusic",
+    "name": "foxxYoutube",
+    "clients": ["foxxMaloja"],
+    "data": {
+      "cookie": "__Secure-3PAPISID=3AxsXpy0MKGu75Qb/AkISXGqOnSDn1jEKn; DEVICE_INFO=ChxOekU0Tmpjek5EWTBPRGd3TlRBMk16QXpNdz09EJbS8Z0GGJbS8Z0G; ...",
+      "authUser": 1
+    }
+  }
+]
+```
+
+```json5 title="CONFIG_DIR/maloja.json"
 [
   {
     "name": "foxxMaloja",
@@ -222,15 +266,14 @@ In `CONFIG_DIR/maloja.json`:
 ]
 ```
 
-In `CONFIG_DIR/lastfm.json`:
-
-```json5
+```json5 title="CONFIG_DIR/lastfm.json"
 [
   {
     "name": "maryLFM",
     "data": {
       "apiKey": "maryApiKey",
       "secret": "marySecret",
+      "redirectUri": "http://localhost:9078/lastfm/callback"
     }
   }
 ]

docsite/docs/configuration/plex.md

@@ -1,3 +1,8 @@
+---
+sidebar_position: 2
+title: Plex/Tautulli
+---
+
 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)
@@ -40,8 +45,17 @@ Expand the **Watched** dropdown and add the following code block to the **JSON D
 "album_name": "{album_name}",
 "media_type": "{media_type}",
 "title":  "{title}",
-"duration": "{duration}",
-"username": "{username}"
+"duration": "{duration_sec}",
+"username": "{username}",
+"server": "{server_name}",
+"version": "{server_version}",
+"library": "{library_name}",
+"player": "{player}",
+"device": "{device}",
+"platform": "{platform}",
+"action": "{action}",
+"machine_id": "{machine_id}",
+"session_key": "{session_key}"
 }
 ```
 

docsite/docs/configuration/transforms.mdx

@@ -0,0 +1,320 @@
+---
+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)
+
+## 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>

docsite/docs/development/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Development",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Developing for Multi-Scrobbler and tutorials"
+  }
+}

docsite/docs/development/dev-client.md

@@ -0,0 +1,8 @@
+---
+toc_min_heading_level: 2
+toc_max_heading_level: 5
+sidebar_position: 3
+title: Client Development/Tutorial
+---
+
+To do...

docsite/docs/development/dev-common.md

@@ -0,0 +1,168 @@
+---
+toc_min_heading_level: 2
+toc_max_heading_level: 5
+sidebar_position: 1
+title: Common Development
+description: Start here for MS development
+---
+
+# Development
+
+## Architecture
+
+Multi-scrobbler is written entirely in [Typescript](https://www.typescriptlang.org/). It consists of a backend and frontend. The backend handles all Source/Client logic, mounts web server endpoints that listen for Auth callbacks and Source ingress using [expressjs](https://expressjs.com/), and  serves the frontend. The frontend is a standalone [Vitejs](https://vitejs.dev/) app that communicates via API to the backend in order to render the dashboard.
+
+## 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.
+
+
+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
+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.
+
+## Common Development
+
+:::info
+
+In this document, when referring to aspects of Sources and Clients that are shared between both, the Source/Client will be referred to as a **Component.**
+
+:::
+
+A Component is composed of two parts:
+
+* Typescript interfaces describing structure of configuration for that Component
+* A concrete class inheriting from a common "startup" abstract class that enforces how the Component is built and operates
+
+In both parts Source/Clients share some common properties/behavior before diverging in how they operate.
+
+### 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):
+
+```ts
+interface MyConfig {
+  name: string
+  data?: object
+  options?: object
+}
+```
+
+* `data` contains data that is required for a Component to operate such as credentials, callback urls, api keys, endpoints, etc...
+* `options` are **optional** settings that can be used to fine-tune the usage of the Component but are not required or do not majorly affect behavior. EX additional logging toggles
+
+### 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...
+
+#### Stages
+
+Stages below are invoked in the order listed. All stages are asynchronous to allow fetching network requests or reading files.
+
+The stage function (described in each stage below) should return a value or throw:
+
+* return `null` if the stage is not required
+* return `true` if the stage succeeded
+* return a `string` if the stage succeeded and you wish to append a result to the log output for this stage
+* throw an `Exception` if the stage failed for any reason and the Component should not continue to run/start up
+
+##### Stage: Build Data
+
+This stage should be used to validate user configuration, parse any additional data from async sources (file, network), and finalize the shape of any configuration/data needed for the Component to operate.
+
+:::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.
+
+::::
+
+<details>
+
+<summary>Examples</summary>
+
+* Parse a full URL like `http://SOME_IP:7000/subfolder/api` from user config containing a base url like `data.baseUrl: 'SOME_IP'` and then store this in the class config
+* Validate that config `data` contains required properties `user` `password` `salt`
+* Read stored credentials from `${this.configDir}/currentCreds-MySource-${name}.json`;
+
+</details>
+
+##### Stage: Check Connection
+
+This stage is used to validate that MS can communicate with the service the Component is interacting with. This stage is invoked on MS startup as well as any time the Component tries to restart after a failure.
+
+If the Component depends on **ingress** (like Jellyfin/Plex webhook) this stage is not necessary.
+
+:::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.
+
+::::
+
+<details>
+
+<summary>Examples</summary>
+
+* Make a [`request`](https://nodejs.org/docs/latest-v18.x/api/http.html#httprequesturl-options-callback) to the service's server to ensure it is accessible
+* Open a websocket connection and check for a ping-pong
+
+</details>
+
+##### Stage: Test Auth
+
+MS determines if Auth is required for a Component based on two class properties. You should set these properties during `constructor` initialization for your Component class:
+
+* `requiresAuth` - (default `false`) Set to `true` if MS should check/test Auth for this Component
+* `requiresAuthInteraction` - (default `false`) Set to `true` if user interaction is required to complete auth IE user needs to visit a callback URL
+
+If the Component requires authentication in order to communicate with a service then any required data should be built in this stage and a request made to the service to ensure the authentication data is valid.
+
+This stage should return:
+
+* `true` if auth succeeded
+* `false` if auth failed without unexpected errors 
+  * IE the authentication data is not valid and requires user interaction to resolve the failure
+* throw an exception if network failure or unexpected error occurred
+
+You _should_ attempt to re-authenticate, if possible. Only throw an exception or return `false` if there is no way to recover from an authentication failure.
+
+:::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.
+
+::::
+
+<details>
+
+<summary>Examples</summary>
+
+* Generate a Bearer Token for Basic Auth from user/password given in config and store in class properties
+* Make a request to a known endpoint with Authorization token from read credentials file to see if succeeds or returns 403
+* Catch a 403 and attempt to reauthenticate at an auth endpoint with user/password given in config
+
+</details>
+
+### Play Object
+
+The **PlayObject** is the standard data structure MS uses to store listen (track) information and data required for scrobbling. It consists of:
+
+* Track Data -- a standard format for storing track, artists, album, track duration, the date the track was played at, etc...
+* Listen Metadata -- Optional but useful data related to the specific play or specifics about the Source/Client context for this play such as
+  * Platform specific ID, web URL to track, device/user ID that played this track, etc...
+
+Both Sources and Clients use the **PlayObject** interface. When a Component receives track info from its corresponding service it must transform this data into a PlayObject before it can be interacted with.
+
+For more refer to the TS documentation for `PlayObject` or [`AmbPlayObject`](https://github.com/FoxxMD/multi-scrobbler/blob/master/src/core/Atomic.ts#L141) in your project
+
+## Creating Clients and Sources
+
+* [Source Development and Tutorial](dev-source.md)
+* [Client Development and Tutorial](dev-client.md)

docsite/docs/development/dev-source.md

@@ -0,0 +1,552 @@
+---
+toc_min_heading_level: 2
+toc_max_heading_level: 5
+sidebar_position: 2
+title: Source Development/Tutorial
+---
+
+This document will provide a step-by-step guide for creating a (trivial) new Source in MS alongside describing what aspects of the Source need to be implemented based on the service you use. Before using this document you should review [Common Development](dev-common.md#common-development).
+
+## Scenario
+
+You are the developer of a fancy, new self-hosted web-based media player called **Cool Player.** Cool Player has a slick interface and many bells and whistles, but most importantly it has an API. The API:
+
+* Has an unauthenticated health endpoint at `/api/health` that returns `200` if the service is running properly
+* Has authenticated endpoints that require a user-generated token in the header `Authorization MY_TOKEN`
+  * Has a `/api/recent` endpoint that lists recently played tracks with a timestamp
+  * Has a `/api/now-playing` endpoint that returns information about the state of the player like current track, player position in the track, etc...
+* Cool Player is by default accessed on port `6969`
+* Your personal instance of Cool Player is hosted at `http://192.168.0.100:6969` and the api is accessed at `http://192.168.0.100:6969/api`
+
+Because there is an API that MS can actively read this will be a **polling** Source where MS sends requests to Cool Player to get scrobble information -- as opposed to an **ingress** Source like Jellyfin/Plex that uses webhooks from the service to send data to MS.
+
+## Minimal Implementation
+
+### Define and Implement Config
+
+We will create a new config interface for Cool Player using the [Common Config](dev-common.md#config) and tell MS it is a valid config that can be used.
+
+Create a new file for your config:
+
+```ts title="/src/backend/common/infrastructure/config/source/coolplayer.ts"
+import { PollingOptions } from "../common.js";
+import { CommonSourceConfig, CommonSourceData } from "./index.js";
+
+// all of the required data for the Build Data and Test Auth stages (from Common Development docs)
+// should go here
+export interface CoolPlayerSourceData extends CommonSourceData, PollingOptions {
+// remember to annotation your properties!
+
+  /**
+   * The user-generated token for Cool Player auth created in Cool Player -> Settings -> User -> Tokens
+   *
+   * @example f243331e-cf5b-49d7-846b-0845bdc965b4
+   * */
+  token: string
+  /**
+   * The host and port where Cool Player is hosted
+   *
+   * @example http://192.168.0.100:6969
+   * */
+  baseUrl: string
+}
+
+export interface CoolPlayerSourceConfig extends CommonSourceConfig {
+  data: CoolPlayerSourceData
+}
+
+export interface CoolPlayerSourceAIOConfig extends CoolPlayerSourceConfig {
+  // when using the all-in-one 'config.json' this is how users will identify this source
+  type: 'coolplayer'
+}
+```
+
+Add the new interface to the list of valid interfaces for sources:
+
+```ts title="src/backend/common/infrastructure/config/source/sources.ts"
+import { ChromecastSourceAIOConfig, ChromecastSourceConfig } from "./chromecast.js";
+// ...
+// highlight-next-line
+import { CoolPlayerSourceAIOConfig, CoolPlayerSourceConfig } from "./coolplayer.js";
+
+export type SourceConfig =
+        SpotifySourceConfig
+        // ...
+        // highlight-next-line
+        | CoolPlayerSourceConfig;
+
+export type SourceAIOConfig =
+        SpotifySourceAIOConfig
+        // ...
+        // highlight-next-line
+        | CoolPlayerSourceAIOConfig;
+```
+
+Finally, add the source type identifier to the list of valid identifiers
+
+```ts title="src/backend/common/infrastructure/Atomic.ts"
+export type SourceType =
+    'spotify'
+    // ...
+    // highlight-next-line
+    | 'coolplayer';
+
+export const sourceTypes: SourceType[] = [
+    'spotify',
+    // ...
+    // highlight-next-line
+    'coolplayer'
+];
+```
+
+Now we will create a new Source inheriting from [`AbstractComponent`](dev-common.md#concrete-class) that:
+
+* accepts our config interface
+* implements a function to transform CoolPlayer's track data into a [**PlayObject**](dev-common.md#play-object)
+* implements required [stages](dev-common.md#stages)
+* implements required methods to current player state and/or now playing track
+
+### Create CoolPlayer Source
+
+First we create a new Source called `CoolPlayerSource` and setup our constructor to accept the config and [specify Auth behavior.](dev-common.md#stage-test-auth)
+
+```ts title="src/backend/sources/SpotifySource.ts"
+import { CoolPlayerSourceConfig } from "../common/infrastructure/config/source/coolplayer.js";
+import MemorySource from "./MemorySource.js";
+import {
+  InternalConfig,
+} from "../common/infrastructure/Atomic.js";
+
+// MemorySource is the base class used for polling-type Sources
+export default class CoolPlayerSource extends MemorySource {
+
+  // type hints for TS to know what the base class config looks like
+  declare config: CoolPlayerSourceConfig;
+
+  constructor(name: any, config: CoolPlayerSourceConfig, internal: InternalConfig, emitter: EventEmitter) {
+    super('coolplayer', name, config, internal, emitter);
+
+    // Cool Player required authentication
+    this.requiresAuth = true;
+    // but does not require user interaction for auth to work
+    this.requiresAuthInteraction = false;
+    // tells MS this is a Source that can be activity monitored through API
+    this.canPoll = true;
+  }
+}
+```
+
+### Initialize Source from Config
+
+When MS starts it reads all configs and determines which Source to build based on the configs found. We need to tell it to build a `CoolPlayerSource` when a `coolplayer` config type is found.
+
+We modify `ScrobbleSources.ts` to add `CoolPlayerSource` as an option:
+
+```ts title="src/backend/sources/ScrobbleSources.ts"
+// ...
+import { CoolPlayerSource, CoolPlayerData } from "./CoolPlayerSource.js";
+
+export default class ScrobbleSources {
+  // ...
+  buildSourcesFromConfig = async (additionalConfigs: ParsedConfig[] = []) => {
+    // ...
+
+    // if CoolPlayerSource should be able to be built from ENVs only 
+    // then add it as a case statement here
+    for (const sourceType of sourceTypes) {
+      switch (sourceType) {
+              // ...
+        case 'musikcube':
+          // ...
+          break;
+              // highlight-start
+        case 'coolplayer':
+          const cp = {
+            baseUrl: process.env.COOL_URL,
+            token: process.env.COOL_TOKEN
+          }
+          if (!Object.values(cp).every(x => x === undefined)) {
+            configs.push({
+              type: 'coolplayer',
+              name: 'unnamed',
+              source: 'ENV',
+              mode: 'single',
+              configureAs: defaultConfigureAs,
+              data: cp as CoolPlayerData
+            });
+          }
+          break;
+              // highlight-end
+        default:
+          break;
+      }
+    }
+  }
+
+  // ...
+
+  // (required) create new CoolPlayerSource if source config type is 'coolplayer'
+  addSource = async (clientConfig: ParsedConfig, defaults: SourceDefaults = {}) => {
+    // ...
+    let newSource: AbstractSource;
+    switch (type) {
+      // ...
+      case 'musikcube':
+        // ...
+        break;
+            // highlight-start
+      case 'coolplayer':
+        newSource = await new CoolPlayerSource(name, compositeConfig as CoolPlayerSourceConfig, internal, this.emitter);
+        break;
+            // highlight-end
+      default:
+        break;
+    }
+  }
+}
+```
+
+### Implement Play Object Transform
+
+Now we will create a static function that is used to take the track data returned from Cool Player's API and return a standard [`PlayObject`.](dev-common.md#play-object)
+
+```ts title="src/backend/sources/CoolPlayerSource.ts"
+import dayjs from "dayjs";
+import {
+  FormatPlayObjectOptions,
+} from "../common/infrastructure/Atomic.js";
+import { PlayObject } from "../../core/Atomic.js";
+
+export default class CoolPlayerSource extends MemorySource {
+  // ...
+
+  // 'obj' should ideally be a real TS interface
+  // if CoolPlayer has a ts/js client we would use that otherwise
+  // we should build our own interfaces to represent track data from Cool Player's API
+  static formatPlayObj(obj: any, options: FormatPlayObjectOptions = {}): PlayObject {
+    const {
+      trackName,
+      artistName,
+      albumName,
+      duration,
+      playedAt,
+    } = obj;
+
+    return {
+      data: {
+        artists: [artistName],
+        album: albumName,
+        track: trackName,
+        // assuming seconds
+        duration,
+        // assuming playedAt is an ISO8601 timestamp
+        playDate: dayjs(playedAt)
+      },
+      meta: {
+        source: 'CoolPlayer'
+      }
+    }
+  }
+}
+```
+
+### Implement Stages
+
+Next we will implement the [Stages](dev-common.md#stages) required to get CoolPlayerSource running.
+
+#### Build Data
+
+First we implement the [Build Data Stage](dev-common.md#stage-build-data). We will check that the `token` and `baseUrl` properties have been provided by the user. Additionally, we will parse the baseUrl and add default ports/prefix.
+
+```ts title="src/backend/sources/CoolPlayerSource.ts"
+import { URL } from "url";
+// ...
+
+export default class CoolPlayerSource extends MemorySource {
+
+  baseUrl!: URL;
+
+  // ...
+
+  static parseConnectionUrl(val: string) {
+    const normal = normalizeUrl(val, {removeTrailingSlash: false, normalizeProtocol: true})
+    const url = new URL(normal);
+
+    if (url.port === null || url.port === '') {
+      url.port = '6969';
+    }
+    if (url.pathname === '/') {
+      url.pathname = '/api/';
+    }
+    return url;
+  }
+
+  protected async doBuildInitData(): Promise<true | string | undefined> {
+    const {
+      token,
+      baseUrl
+    } = this.config;
+    if (token === null || token === undefined || (typeof token === 'string' && token.trim() === '')) {
+      throw new Error(`'token' must be defined`);
+    }
+
+    if (baseUrl === null || baseUrl === undefined || (typeof baseUrl === 'string' && baseUrl.trim() === '')) {
+      throw new Error(`'baseUrl' must be defined`);
+    }
+    try {
+      this.baseUrl = CoolPlayerSource.parseConnectionUrl(baseUrl);
+    } catch (e) {
+      throw new Error(`Could not parse baseUrl: ${baseUrl}`, {cause: e});
+    }
+
+    this.logger.verbose(`Config URL: ${baseUrl} => Normalized: '${this.url.toString()}'`);
+    return true;
+  }
+}
+```
+
+#### Check Connection
+
+Second we will implement the [Check Connection Stage](dev-common.md#stage-check-connection):
+
+```ts title="src/backend/sources/CoolPlayerSource.ts"
+import request from 'superagent';
+import { UpstreamError } from "../common/errors/UpstreamError.js";
+// ...
+export default class CoolPlayerSource extends MemorySource {
+
+  // ...
+
+  protected async doCheckConnection(): Promise<true | string | undefined> {
+    try {
+      const resp = await request.get(`${this.baseUrl}/health`);
+      return true;
+      // if /health returned version info we could instead read response and return a string with version info for visibility to the user
+      // return `Cool Player Version: ${resp.body.version}`;
+    } catch (e) {
+      throw e;
+    }
+  }
+}
+```
+
+#### Test Auth
+
+Finally, we will implement [Auth Test Stage](dev-common.md#stage-test-auth):
+
+```ts title="src/backend/sources/CoolPlayerSource.ts"
+import request from 'superagent';
+import { UpstreamError } from "../common/errors/UpstreamError.js";
+// ...
+export default class CoolPlayerSource extends MemorySource {
+
+  // ...
+
+  doAuthentication = async () => {
+    try {
+      const resp = await request
+              .get(`${this.baseUrl}/recent`)
+              .set('Authorization', `Token ${this.config.token}`);
+      return true;
+    } catch (e) {
+      // if Cool Player returned an error as json we could parse it from error body and throw new Error with the message
+      throw e;
+    }
+  }
+}
+```
+
+### Implement Polling
+
+The majority of Sources MS monitors primarily operate as a source of truth for a **music player** rather than a **played music history.** Only Listenbrainz and Last.fm operate as a source of music history.
+
+To this end, MS implements a [state machine](https://www.freecodecamp.org/news/state-machines-basics-of-computer-science-d42855debc66/) that emulates the behavior of a music player in order to keep track of when a song you are listening to should be scrobbled. It does this by monitoring the "currently playing" track reported by a Source's service, with varying degrees of accuracy depending on what information is returned from the service. The state machine is implemented in `MemorySource` which our `CoolPlayerSource` inherits from.
+
+For a polling Source to work properly we need to implement a function, [`getRecentlyPlayed`](https://github.com/FoxxMD/multi-scrobbler/blob/master/src/backend/sources/AbstractSource.ts#L92), that returns PlayObjects that are "newly" played. These are then checked against previously "discovered" plays and their timestamp to determine if they should be surfaced to Clients to scrobble.
+
+To take advantage of the `MemorySource` state machine we will additionally use [`processRecentPlays`](https://github.com/FoxxMD/multi-scrobbler/blob/master/src/backend/sources/MemorySource.ts#L113) from `MemorySource` inside `getRecentlyPlayed`. We pass track and/or player state returned from the Source service to `processRecentPlayers`. It then takes care of deriving Source player state based on how this data changes over time. The advantage to using `processRecentPlays` is that our Source service does not necessarily need to pass any player information -- as long as the track info has a **duration** we can more-or-less determine if it has been played long enough to scrobble.
+
+```ts title="src/backend/sources/CoolPlayerSource.ts"
+import request from 'superagent';
+import {
+  SourceData,
+  PlayerStateData,
+  SINGLE_USER_PLATFORM_ID
+} from "../common/infrastructure/Atomic.js";
+// ...
+export default class CoolPlayerSource extends MemorySource {
+
+  // ...
+
+  protected async getRecentlyPlayed(options: RecentlyPlayedOptions = {}): Promise<PlayObject[]> {
+    const plays: SourceData[] = [];
+    try {
+      // currently playing tracks/player state data
+      const resp = await request
+              .get(`${this.baseUrl}/now-playing`)
+              .set('Authorization', `Token ${this.config.token}`);
+      const {
+        body: {
+          playerState, // 'playing' or 'stopped' or 'paused'...
+          position, // number of seconds into the track IE at position 48 -> ( 0:48/3:56 in player UI )
+          play: { /* track data */}
+        }
+      } = resp;
+
+      // transform into standard player state data
+      const playerData: PlayerStateData = {
+        platformId: SINGLE_USER_PLATFORM_ID,
+        play: CoolPlayerSource.formatPlayObj(play),
+        position
+      };
+
+      // if Cool Player does return player state we can also push a regular PlayObject to this list
+      plays.push(playerData);
+    } catch (e) {
+      throw e;
+    }
+
+    // process player state through state machine
+    // if the track changes or player state changes
+    // and currently played track has been listened to long enough to be scrobbled it will return in newPlays
+    const newPlays = this.processRecentPlays(plays);
+
+    // finally, we return new plays and MS checks to see if they have been previously seen 
+    // before signalling to Clients that they can be scrobbled
+    return newPlays;
+  }
+}
+```
+
+Congratulations! Your `CoolPlayerSource` has been minimally implemented and can now be used in multi-scrobbler.
+
+## Further Implementation
+
+### Backlog
+
+To have your Source try to scrobble "missed" tracks when MS starts up the Source's service must be able to provide:
+
+* track information
+* timestamp of when the track was played
+
+In your Source implement [`getBackloggedPlays`](https://github.com/FoxxMD/multi-scrobbler/blob/master/src/backend/sources/AbstractSource.ts#L235) and set setting in constructor indicating it has backlogging capabilities:
+
+```ts title="src/backend/sources/CoolPlayerSource.ts"
+import request from 'superagent';
+import {
+  PlayObject,
+} from "../common/infrastructure/Atomic.js";
+// ...
+export default class CoolPlayerSource extends MemorySource {
+
+  constructor(/* ... */) {
+    super(/* ... */);
+    // ...
+
+    // tell MS it should try to get backlogged tracks on startup
+    this.canBacklog = true;
+  }
+
+  // ...
+
+  protected getBackloggedPlays = async (options: RecentlyPlayedOptions): Promise<PlayObject[]> => {
+    try {
+      const resp = await request
+              .get(`${this.baseUrl}/recent`)
+              .set('Authorization', `Token ${this.config.token}`);
+
+      // assuming list from body looks like track info returned in 
+      // "Implement Play Object Transform" section
+      const {
+        body = []
+      } = resp;
+
+      return body.map(x => CoolPlayerSource.formatPlayObj(x));
+    } catch (e) {
+      throw new Error('Error occurred while getting recently played', {cause: e});
+    }
+
+  }
+}
+```
+
+### Other Source Types
+
+There are some scenarios where polling and/or state machine is not the right tool to handle determining if incoming data should be scrobbled:
+
+* The Source service handles scrobble threshold internally, the data being received should always be scrobbled (WebScrobbler, Plex, Tautulli, Listenbrainz, Last.fm)
+* You prefer to handle the scrobble determination yourself
+
+#### Music History Source
+
+If the Source is still polling but the track returned should always be scrobbled if not already seen IE the Source service is a **music history source** (Listenbrainz, Last.fm), rather than a music player, then simply indicate to MS the source of truth type by setting it in the constructor. The state machine will always return a track if it is new and not seen, regardless of how recently it was seen:
+
+
+```ts title="src/backend/sources/CoolPlayerSource.ts"
+import { SOURCE_SOT } from "../../core/Atomic.js";
+// ...
+export default class CoolPlayerSource extends MemorySource {
+
+  constructor(/* ... */) {
+    super(/* ... */);
+    // ...
+
+    // tell MS it should immediately scrobble any new, unseen tracks from the upstream service
+    this.playerSourceOfTruth = SOURCE_SOT.HISTORY;
+  }
+}
+```
+
+#### Non-Polling Source
+
+**Ingress** Sources (like Plex, Tautulli, Webscrobbler, Jellyfin) do not having a polling mechanism because the upstream service contacts MS when there is an event, rather than MS contacting the upstream service.
+
+For these Sources you will need to implement endpoints in `src/service/api.ts` and corresponding files. See the existing Sources in the project as references for how to do this. 
+
+You may still wish to use the state machine `MemorySource` (like Jellyfin) if the events received are not "scrobble" events but instead of implementing `getRecentlyPlayed` you will implement your own function in your Source class, like `handle()`, that receives data and then uses `processRecentPlays`.
+
+After new plays have been determined see the next section for how to scrobble...
+
+#### Basic Source
+
+At the core of a Source that implements `AbstractSource`'s functionality is the ability to **Discover** and **Scrobble** plays. 
+
+These functions are not seen in the MVP `CoolPlayerSource` because they are automatically done by the polling functionality after being returned from `getRecentlyPlayed`.
+
+##### Discovery
+
+A Source keeps track of all the "plays" that are determined to be valid for scrobbling. When a play is valid it is checked to see if it has already been "discovered" by comparing the track info and timestamp of the play against already discovered plays. This prevents duplicate scrobbling by using the Source's own data and simplifies scrobbling for Sources by allowing your implementation to "always" ingest track data without having to worry about whether its new or not -- `AbstractSource` and `discover()` will take care of that for you.
+
+```ts title="src/backend/sources/MyBasicSource.ts"
+export default class MyBasicSource extends AbstractSource {
+  handle(somePlay: PlayObject) {
+    // if the track is "new" and not seen before it is returned in the discovered list
+    // we then know it is OK to be sent to Clients for scrobbling
+    const discovered: PlayObject[] = this.discover([somePlay]);
+  }
+}
+```
+
+This additionally will be surfaced to the user in the Dashboard in the "Tracks Discovered" page.
+
+##### Scrobbling
+
+After a play is verified to be discovered we can then scrobble it. This will emit the plays to the ScrobbleClients service which then disseminates the play to all Clients that were configured to listen in the Source's config.
+
+```ts title="src/backend/sources/MyBasicSource.ts"
+export default class MyBasicSourceSource extends AbstractSource {
+  handle(somePlay: PlayObject) {
+    const discovered: PlayObject[] = this.discover([somePlay]);
+    // emit plays that can be scrobbled by clients
+    this.scrobble(discovered);
+  }
+}
+```
+
+If your service only emits an event when a play is scrobbled you can _technically_ skip using `discover()` but it is good practice to use it unless you have a very good reason not to.
+
+:::note
+
+Using `scrobble()` does not guarantee a track is actually scrobbled! The Scrobble Clients also check the play against their own "recently scrobbled" list to prevent duplicates.
+
+:::

docsite/docs/development/flatpak.md

@@ -0,0 +1,104 @@
+---
+toc_min_heading_level: 2
+toc_max_heading_level: 5
+sidebar_position: 4
+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
+
+### Flatpak and flatpak-builder
+
+Install [Flatpak](https://flatpak.org/setup/)
+
+Install [flatpak-builder](https://docs.flatpak.org/en/latest/first-build.html#building-your-first-flatpak)
+
+#### [flatpak-node-generator](https://github.com/flatpak/flatpak-builder-tools/tree/master/node)
+
+Requires python 3.7+, [pip](https://pip.pypa.io/en/stable/)/[pipx](https://pypa.github.io/pipx/)
+
+## Update Project source
+
+Set the `branch` `tag` or `commit` to use for MS in the `source` section of [`io.github.foxxmd.multiscrobbler.yml`](https://github.com/FoxxMD/multi-scrobbler/blob/master/flatpak/io.github.foxxmd.multiscrobbler.yml)
+
+## Generate Sources and Build
+
+### Use Setup Script
+
+A convenience bash script is provided that automates generating offline sources and building the flatpak app for you. This is the recommend method to use.
+
+Located in the project at [`flatpak/setup.sh`](https://github.com/FoxxMD/multi-scrobbler/blob/master/flatpak/setup.sh), run it from the `flatpak` directory with this syntax:
+
+```shell
+./setup.sh -o -b /path/to/flatpak/build/dir
+```
+
+```
+Args:
+
+-o => Delete and overwrite any existing generated sources
+-b => The absolute path to the directory that should be used for flatpak build/artifacts. If not defined will use `CWD/build`
+-y => Proceed without confirming settings
+```
+
+### Manual Setup
+
+If you cannot use `setup.sh` follow the below to manually generate sources and build the flatpak app:
+
+<details>
+
+<summary>Instructions</summary>
+
+#### Use `flatpak-node-generator` to generate sources
+
+First, [make sure `node_modules` is deleted or empty](https://github.com/flatpak/flatpak-builder-tools/issues/354#issuecomment-1478518442) for both the project and `docsite` directories.
+
+Then, from MS project root:
+
+```shell title="PROJECT_DIR"
+flatpak-node-generator npm package-lock.json
+```
+
+Move `generated-sources.json` into `PROJECT_DIR/flatpak` and rename `generated-sources.0.json`
+
+Then, generate `docsite` sources:
+
+```shell title="PROJECT_DIR"
+flatpak-node-generator npm docsite/package-lock.json
+```
+
+Move `generated-sources.json` into `PROJECT_DIR/flatpak` and rename `generated-sources.1.json`
+
+#### Build flatpak
+
+In the below command replace `/home/yourUser/multi-scrobbler-flatpak` with a directory to use for storing flatpak build/artifacts.
+
+```shell title="PROJECT_DIR/flatpak"
+flatpak-builder --repo=/home/yourUser/multi-scrobbler-flatpak/repo --state-dir=/home/yourUser/multi-scrobbler-flatpak/state /home/yourUser/multi-scrobbler-flatpak/build io.github.foxxmd.multiscrobbler.yml --force-clean
+```
+
+:::info
+
+Append `--install --user` to the above command to have the app installed immediately.
+
+::::
+
+</details>
+
+
+# Run App
+
+If built with `--install --user` (default when using `setup.sh`) you can now run MS using the command
+
+```shell
+flatpak run -u io.github.foxxmd.multiscrobbler
+```

docsite/docs/installation/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Installation",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Way to install Multi-Scrobbler"
+  }
+}

docsite/docs/installation/installation.mdx

@@ -0,0 +1,344 @@
+---
+sidebar_position: 1
+title: 'Overview'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+:::tip
+
+For the difference between **ENV** and **File** examples in this document see [Configuration Types](../configuration/configuration.mdx#configuration-types).
+
+:::
+
+## Local Installation
+
+After installation see [service.md](service.md) to configure multi-scrobbler to run automatically in the background.
+
+### Nodejs
+
+Clone this repository somewhere and then install from the working directory
+
+```shell
+git clone https://github.com/FoxxMD/multi-scrobbler.git .
+cd multi-scrobbler
+nvm use # optional, to set correct Node version
+npm install
+npm run docs:install && npm run build
+npm run start
+```
+
+#### Rollup build error
+
+During building if you encounter an error like: `Your current platform "XXX" and architecture "XXX" combination is not yet supported by the native Rollup build.`
+
+Modify `overrides` in `package.json` to use `@rollup/wasm-node` as a drop-in replacement for rollup:
+
+```json
+"overrides": {
+  "spotify-web-api-node": {
+    "superagent": "$superagent"
+  }
+  "vite": {
+    "rollup": "npm:@rollup/wasm-node@^4.9.6"
+  }
+}
+```
+
+See [this issue](https://github.com/FoxxMD/multi-scrobbler/issues/135#issuecomment-1927080260) for more detail.
+
+#### Usage Examples
+
+<Tabs groupId="configType" queryString>
+<TabItem value="env" label="ENV">
+```shell
+SPOTIFY_CLIENT_ID=yourId SPOTIFY_CLIENT_SECRET=yourSecret MALOJA_URL="http://domain.tld" node src/index.js
+```
+</TabItem>
+<TabItem value="file" label="File">
+
+<details>
+    <summary>`./config/config.json`</summary>
+
+    ```json title="./config/config.json"
+    {
+        "sources": [
+            {
+                "type": "spotify",
+                "clients": ["myConfig"],
+                "name": "mySpotifySource",
+                "data": {
+                    "clientId": "a89cba1569901a0671d5a9875fed4be1",
+                    "clientSecret": "ec42e09d5ae0ee0f0816ca151008412a",
+                 }
+            }
+        ],
+        "clients": [
+            {
+                "type": "maloja",
+                "name": "myConfig",
+                "data": {
+                    "url": "http://localhost:42010",
+                    "apiKey": "myMalojaKey"
+                }
+            }
+        ],
+    }
+    ```
+
+</details>
+
+```shell
+npm run start
+```
+</TabItem>
+</Tabs>
+
+:::tip
+
+The web UI and API is served on port `9078`. This can be modified using the `PORT` environmental variable.
+
+:::
+
+### 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:
+
+* 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
+
+::::
+
+#### Usage Examples
+
+<Tabs groupId="configType" queryString>
+    <TabItem value="env" label="ENV">
+        There are a few [options for running flatpak applications with temporary or permanent environmental variables.](https://ardasevinc.dev/launch-flatpak-apps-with-custom-args-and-environment-variables)
+
+        ```shell
+        flatpak run --env=SPOTIFY_CLIENT_ID=yourId --envSPOTIFY_CLIENT_SECRET=yourSecret --env=MALOJA_URL="http://domain.tld" io.github.foxxmd.multiscrobbler
+        ```
+    </TabItem>
+    <TabItem value="file" label="File">
+        The config directory for multi-scrobbler as a flatpak can be found under `/home/YourUser/.var/app/io.github.foxxmd.multiscrobbler/config`
+
+        ```shell
+        flatpak run io.github.foxxmd.multiscrobbler
+        ```
+    </TabItem>
+</Tabs>
+
+## Docker
+
+Cross-platform images are built for x86 (Intel/AMD) and ARM64 (IE Raspberry Pi)
+
+:::info[Available Images]
+
+<Tabs>
+    <TabItem value="docker" label="Dockerhub">
+        [Repository Page](https://hub.docker.com/r/foxxmd/multi-scrobbler)
+        ```
+        docker.io/foxxmd/multi-scrobbler:latest
+        ```
+    </TabItem>
+    <TabItem value="ghcr" label="Github Packages">
+        [Repository Page](https://github.com/FoxxMD/multi-scrobbler/pkgs/container/multi-scrobbler)
+        ```
+        ghcr.io/foxxmd/multi-scrobbler:latest
+        ```
+    </TabItem>
+</Tabs>
+
+:::
+
+Or use the provided [docker-compose.yml](../../../docker-compose.yml) after modifying it to fit your configuration.
+
+Recommended configuration steps for docker or docker-compose usage:
+
+#### Storage
+
+You **should** bind a host directory into the container for storing configurations and credentials. Otherwise, these will be lost when the container is updated.
+
+<details>
+
+<summary>Example</summary>
+
+<Tabs groupId="runType" queryString>
+    <TabItem value="docker" label="Docker">
+        [Using `-v` method for docker](https://docs.docker.com/storage/bind-mounts/#start-a-container-with-a-bind-mount):
+        ```shell
+        docker run ... -v "$(pwd)/config:/config" foxxmd/multi-scrobbler
+        ```
+    </TabItem>
+    <TabItem value="docker-compose" label="Docker Compose">
+        [Using docker-compose](https://docs.docker.com/compose/compose-file/compose-file-v3/#short-syntax-3):
+
+        ```yaml title="docker-compose.yml"
+        services:
+          multi-scrobbler:
+            # ...
+            volumes:
+              - "./config:/config"
+        ```
+    </TabItem>
+</Tabs>
+
+</details>
+
+#### Networking
+
+If you are using a [bridge network](https://www.appsdeveloperblog.com/docker-networking-bridging-host-and-overlay/) (default docker setup) you **must** map a port to the container in order to access the dashboard and use MS with some sources (Plex, Jellyfin). The default container port is `9078`.
+
+<details>
+
+    <summary>Example</summary>
+
+<Tabs groupId="runType" queryString>
+    <TabItem value="docker" label="Docker">
+        [Docker `run` publish options](https://docs.docker.com/engine/reference/commandline/run/#publish):
+        ```shell
+        docker run ... -p 9078:9078 foxxmd/multi-scrobbler
+        ```
+    </TabItem>
+    <TabItem value="docker-compose" label="Docker Compose">
+        [docker-compose](https://docs.docker.com/compose/compose-file/compose-file-v3/#short-syntax-1):
+
+        ```yaml title="docker-compose.yml"
+        services:
+          multi-scrobbler:
+            # ...
+            ports:
+              - "9078:9078"
+        ```
+    </TabItem>
+</Tabs>
+
+</details>
+
+##### Base URL
+
+Optionally, when
+
+* using a [Source or Client](../configuration/configuration.mdx) that has a "Redirect URI" that you have not explicitly defined
+* and
+  * using a bridge network or
+  * installing MS on a different machine than the one used to view the dashboard
+
+set the [Base URL](../configuration/configuration.mdx#base-url) as the IP of the host machine. (This is the IP you would use to view the dashboard in a browser)
+
+<details>
+
+    <summary>Example</summary>
+
+<Tabs groupId="runType" queryString>
+    <TabItem value="docker" label="Docker">
+        ```shell
+        docker run ... -e BASE_URL="http://hostMachineIP" foxxmd/multi-scrobbler
+        ```
+    </TabItem>
+    <TabItem value="docker-compose" label="Docker Compose">
+        [docker-compose](https://docs.docker.com/compose/compose-file/compose-file-v3/#short-syntax-1):
+
+        ```yaml title="docker-compose.yml"
+        services:
+          multi-scrobbler:
+            # ...
+            environment:
+              - BASE_URL="http://hostMachineIP"
+        ```
+    </TabItem>
+</Tabs>
+
+</details>
+
+#### Other
+
+* (Optionally) set the [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for the container using the environmental variable `TZ` ([docker](https://docs.docker.com/engine/reference/commandline/run/#env)) ([docker-compose](https://docs.docker.com/compose/compose-file/compose-file-v3/#environment))
+
+### Linux Host
+
+::::info
+
+:::note
+
+If you are using [rootless containers with Podman](https://developers.redhat.com/blog/2020/09/25/rootless-containers-with-podman-the-basics#why_podman_) or are running docker on MacOS/Windows this **DOES NOT** apply to you.
+
+:::
+
+If you are running Docker on a **Linux Host** you must specify `user:group` permissions of the user who owns the **configuration directory** on the host to avoid [docker file permission problems.](https://ikriv.com/blog/?p=4698) These can be specified using the [environmental variables **PUID** and **PGID**.](https://docs.linuxserver.io/general/understanding-puid-and-pgid)
+
+To get the UID and GID for the current user run these commands from a terminal:
+
+* `id -u` -- prints UID
+* `id -g` -- prints GID
+
+::::
+
+### Docker Usage Example
+
+:::tip
+
+See the [**Quick Start Guide**](../quickstart.mdx) for another guided docker-compose example
+
+:::
+
+The example scenario:
+
+* [Spotify **Source**](../configuration/configuration.mdx#spotify)
+* [Maloja **Client**](../configuration/configuration.mdx#maloja)
+* Serving app on port `9078`
+* Docker container located on a different IP (`192.168.0.100`) so use [Base URL](../configuration/configuration.mdx#base-url)
+* Config/data directory on host machine in a directory next to `docker-compose.yml`
+* Linux uid/gid is `1000:1000`
+
+<Tabs groupId="runType" queryString>
+    <TabItem value="docker" label="Docker">
+        <Tabs groupId="configType" queryString>
+            <TabItem value="env" label="ENV">
+                ```bash
+                docker run -e "SPOTIFY_CLIENT_ID=yourId" -e "SPOTIFY_CLIENT_SECRET=yourSecret" -e "BASE_URL=192.168.0.100" -e "MALOJA_URL=http://domain.tld" -e "MALOJA_API_KEY=1234" -e "PUID=1000" -e "PGID=1000" -p 9078:9078 -v /home/myUser/ms:/config foxxmd/multi-scrobbler
+                ```
+            </TabItem>
+            <TabItem value="file" label="File">
+                ```bash
+                docker run -e "PUID=1000" -e "PGID=1000" -e "BASE_URL=192.168.0.100" -p 9078:9078 -v "$(pwd)/config:/config" foxxmd/multi-scrobbler
+                ```
+            </TabItem>
+        </Tabs>
+    </TabItem>
+    <TabItem value="docker-compose" label="Docker Compose">
+        See [`docker-compose.yml`](../../../docker-compose.yml) file for more options and annotations.
+
+        ```yaml title="docker-compose.yml"
+        services:
+            multi-scrobbler:
+                image: foxxmd/multi-scrobbler
+                container_name: multi-scrobbler
+                environment:
+                    - TZ=Etc/GMT # Specify timezone from TZ Database name found here https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+                    - SPOTIFY_CLIENT_ID=yourId
+                    - SPOTIFY_CLIENT_SECRET=yourSecret
+                    - BASE_URL="http://192.168.0.100:9078"
+                    - MALOJA_URL=http://domain.tld:42010
+                    - MALOJA_API_KEY=1234
+                    - PUID=1000
+                    - PGID=1000
+                volumes:
+                    - "./config:/config"
+                ports:
+                    - "9078:9078"
+                restart: unless-stopped
+        ```
+    </TabItem>
+</Tabs>
+
+

docsite/docs/installation/service.md

@@ -0,0 +1,73 @@
+---
+sidebar_position: 2
+title: 'As a Service'
+---
+
+If you have multi-scrobbler installed [locally](installation.mdx#nodejs) you can enable it to run as a background service when you login.
+
+Before running as a service you should run it at least once in the foreground to ensure it can start up correctly!
+
+# [Systemd](https://systemd.io/)
+
+Systemd is system and service manager that is used by [most popular linux distros](https://en.wikipedia.org/wiki/Systemd#Adoption) including [Ubuntu](https://wiki.ubuntu.com/SystemdForUpstartUsers), [Fedora](https://docs.fedoraproject.org/en-US/quick-docs/understanding-and-administering-systemd/), Pop!_OS, [Debian](https://wiki.debian.org/systemd), and [Arch](https://wiki.archlinux.org/title/systemd).
+
+This setup will create a [user service](https://wiki.archlinux.org/title/systemd/User) that runs on login.
+
+## Create A Unit File
+
+Create a new service file for multi-scrobbler under your HOME config:
+
+```bash
+mkdir -p ~/.config/systemd/user
+touch ~/.config/systemd/user/multi-scrobbler.service
+```
+
+In a text editor add contents below to the file you created, `multi-scrobbler.service`:
+
+```ini
+[Unit]
+Description=multi-scrobbler
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=flatpak run io.github.multiscrobbler
+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:
+
+```bash
+systemctl daemon-reload
+systemctl --user enable multi-scrobbler.service
+systemctl --user start multi-scrobbler.service
+```
+
+This will
+
+* scan for new services and pickup our multi-scrobbler user service
+* enable the service to run at login automatically
+* start the service now
+
+# Other Service Methods
+
+Open a PR if you would like to document setting up multi-scrobbler for other service managers!

docsite/docs/quickstart.mdx

@@ -0,0 +1,165 @@
+---
+title: 'Quickstart'
+sidebar_position: 1
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+This guide will get you up and running with multi-scrobbler using [Docker](https://www.docker.com/) and [`docker compose`](https://docs.docker.com/compose/). At the end of the guide you will have:
+
+* the dashboard served on port `9078` of a host machine which has an IP of `192.168.0.100`
+* data saved to the same directory as the `docker-compose.yml` file
+* multi-scrobbler monitoring [Spotify](./configuration/configuration.mdx#spotify) and/or [Jellyfin](./configuration/configuration.mdx#jellyfin) for listening activity
+* multi-scrobbler scrobbling to [Lastfm](./configuration/configuration.mdx#lastfm) and/or [Maloja](./configuration/configuration.mdx#maloja)
+
+:::note
+
+If the multi-scrobbler container is on the same machine you will be viewing the dashboard from (IE `localhost`) you can remove and ignore `BASE_URL` usage below. Additionally, replace usage of `192.168.0.100` with `localhost`.
+
+:::
+
+## Create Docker Compose File
+
+Create a new folder for multi-scrobbler related data and then create `docker-compose.yml` with this content:
+
+```yaml title="~/msData/docker-compose.yml"
+services:
+  multi-scrobbler:
+    image: foxxmd/multi-scrobbler
+    container_name: multi-scrobbler
+    environment:
+      - TZ=Etc/GMT # Specify timezone from TZ Database name found here https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+      - BASE_URL="http://192.168.0.100:9078"
+      # all Environmental Variables in below examples go here!
+
+    volumes:
+      - "./config:/config"
+    ports:
+      - "9078:9078"
+    restart: unless-stopped
+```
+
+## Setup Sources
+
+**Sources** are the services multi-scrobbler monitors to look for listening activity.
+
+<Tabs>
+    <TabItem value="jellyfin" label="Jellyfin">
+        Follow the Jellyfin configuration [instructions for setting up a **webhook**.](./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)
+
+        ```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
+        ```
+    </TabItem>
+    <TabItem value="spotify" label="Spotify">
+        To access your Spotify activity you must [register a Spotify application](https://developer.spotify.com/dashboard) to get a
+        **Client ID/Secret**.
+
+        When creating the application add this to **Redirect URIs**
+
+        ```
+        http://192.168.0.100:9078/callback
+        ```
+
+        After the application is created add these values to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)
+
+        ```yaml title="~/msData/docker-compose.yml"
+        - SPOTIFY_CLIENT_ID=yourClientId
+        - SPOTIFY_CLIENT_SECRET=yourClientSecret
+        ```
+
+        Later, after [starting multi-scrobbler](#start-multi-scrobbler), visit the dashboard at `http://192.168.0.100:9078` and click **(Re)authenticate** on the Spotify card to authorize multi-scrobbler to use your account. Monitoring will begin automatically after authorization is complete.
+    </TabItem>
+</Tabs>
+
+## Setup Clients
+
+**Clients** are services that store scrobbles. Multi-scrobbler will scrobble all listening activity from the **Sources** you configured to all **Clients** you configure here.
+
+<Tabs>
+    <TabItem value="maloja" label="Maloja">
+        Setup a [Maloja server](https://github.com/krateng/maloja?tab=readme-ov-file#how-to-install) if you have not already done this.
+
+        <details>
+
+            <summary>Maloja Setup Intructions</summary>
+
+            Using Maloja's example `docker-compose.yml`:
+
+            ```yaml reference title="~/malojaData/docker-compose.yml"
+            https://github.com/krateng/maloja/blob/master/example-compose.yml
+            ```
+
+            Uncomment `environment` and add `MALOJA_FORCE_PASSWORD=CHANGE_ME` to set an admin password
+
+            Start the container:
+
+            ```shell title="~/malojaData"
+            docker compose up -d
+            ```
+        </details>
+
+        * Navigate to the Admin Panel (Cog in upper-right corner) -> API Keys (or at http://192.168.0.100:42010/admin_apikeys)
+          * Create a **New Key** and then copy the generated key value
+
+        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_API_KEY=myApiKey
+        ```
+    </TabItem>
+    <TabItem value="lastfm" label="Last.fm">
+        [Register for an API account at Last.fm.](https://www.last.fm/api/account/create)
+
+        Use the following for **Callback URL**:
+
+        ```
+        http://192.168.0.100:9078/lastfm/callback
+        ```
+
+        After account creation use the displayed information and 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"
+        - LASTFM_API_KEY=myApiKey
+        - LASTFM_SECRET=myApiSecret
+        ```
+    </TabItem>
+</Tabs>
+
+## Start Multi-Scrobbler
+
+:::tip
+
+If you are running your multi-scrobbler container on a Linux host see [these instructions for setting proper file permissions.](./installation/installation.mdx#linux-host)
+
+:::
+
+From the same directory as the [`docker-compose.yml` you created earlier](#create-docker-compose-file) start the container:
+
+```shell title="~/msData"
+docker compose up -d
+```
+
+You're done! Multi-scrobbler is now running. It will monitor the sources you configured and scrobble to clients you set up.
+
+Visit `http://192.168.0.100:9078` to see the dashboard where
+
+* configured Sources/Clients
+  * show current status and authentication options
+  * display statistics about discovered/scrobbled tracks and Now Playing status
+* a real-time log shows multi-scrobbler's activity
+
+## Next Steps
+
+* See more advanced docker options as well as other install methods in the [**Installation**](./installation/installation.mdx#docker) docs
+* Review the [**Configuration**](./configuration/configuration.mdx) docs
+  * Learn about how to configure multi-scrobbler using files for more complicated Source/Client scenarios
+  * See all available Sources/Clients alongside configuration examples
+  * Learn how to set up [notification webhooks](./configuration/configuration.mdx#webhook-configurations)
+  * Check out the [kitchensink example](./configuration/kitchensink.md)
+* Consult the [**FAQ**](./FAQ.md) for solutions to common problems

docsite/docusaurus.config.ts

@@ -0,0 +1,185 @@
+import type * as Preset from '@docusaurus/preset-classic';
+import type { Config } from '@docusaurus/types';
+import * as themes from 'prism-react-renderer';
+//import sidebars from './sidebars';
+
+const config: Config = {
+  title: 'Multi-Scrobbler',
+  tagline: 'Scrobble all the things',
+  favicon: 'img/favicon.ico',
+
+  // Set the production url of your site here
+  url: 'https://foxxmd.github.io',
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: process.env.DOCS_BASE !== undefined && process.env.DOCS_BASE !== '' ? process.env.DOCS_BASE : '/docs',
+
+  // GitHub pages deployment config.
+  // If you aren't using GitHub pages, you don't need these.
+  organizationName: 'foxxmd', // Usually your GitHub org/user name.
+  projectName: 'multi-scrobbler', // Usually your repo name.
+
+  trailingSlash: false,
+
+  onBrokenLinks: 'warn',
+  onBrokenMarkdownLinks: 'warn',
+
+  // Even if you don't use internalization, you can use this field to set useful
+  // metadata like html lang. For example, if your site is Chinese, you may want
+  // to replace "en" with "zh-Hans".
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+  scripts: [
+  ],
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: './sidebars.ts',
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          editUrl:
+            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
+        },
+        // blog: {
+        //   showReadingTime: true,
+        //   // Please change this to your repo.
+        //   // Remove this to remove the "edit this page" links.
+        //   editUrl:
+        //     'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
+        // },
+        blog: false,
+
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+  themes: [
+      "docusaurus-json-schema-plugin",
+    [
+      "@easyops-cn/docusaurus-search-local",
+      /** @type {import("@easyops-cn/docusaurus-search-local").PluginOptions} */
+      {
+        // ... Your options.
+        // `hashed` is recommended as long-term-cache of index file is possible.
+        hashed: true,
+        indexBlog: false,
+        // For Docs using Chinese, The `language` is recommended to set to:
+        // ```
+        // language: ["en", "zh"],
+        // ```
+      },
+    ],
+    'docusaurus-theme-github-codeblock'
+  ],
+  plugins: [
+  ],
+  themeConfig:
+    {
+      // Replace with your project's social card
+      image: 'img/docusaurus-social-card.jpg',
+      navbar: {
+        title: 'Multi-Scrobbler',
+        logo: {
+          alt: 'Logo',
+          src: 'img/icon.svg',
+        },
+        items: [
+          {
+            type: 'docSidebar',
+            sidebarId: 'tutorialSidebar',
+            position: 'left',
+            label: 'Docs',
+          },
+          {
+            to: 'playground',
+            position: 'left',
+            label: 'Config Playground',
+          },
+          {
+            href: 'https://github.com/foxxmd/multi-scrobbler',
+            label: 'GitHub',
+            position: 'right',
+          },
+          {
+            href: 'https://foxxmd.github.io/multi-scrobbler/',
+            label: 'Website',
+            position: 'right',
+          },
+        ],
+      },
+      footer: {
+        style: 'dark',
+        links: [
+          {
+            title: 'Docs',
+            items: [
+              {
+                label: 'Overview',
+                to: '/',
+              },
+              {
+                label: 'Installation',
+                to: 'docs/installation',
+              },
+              {
+                label: 'Configuration',
+                to: 'docs/configuration',
+              },
+              {
+                label: 'Development',
+                to: 'docs/development/dev-common',
+              },
+            ],
+          },
+          {
+            title: 'More',
+            items: [
+              {
+                label: 'GitHub',
+                href: 'https://github.com/foxxmd/multi-scrobbler',
+              },
+              {
+                label: 'Website',
+                href: 'https://foxxmd.github.io/multi-scrobbler/',
+              },
+            ],
+          },
+        ],
+        copyright: `Copyright © ${new Date().getFullYear()} Multi-Scrobbler. Built with Docusaurus.`,
+      },
+      prism: {
+        theme: themes.themes.github,
+        darkTheme: themes.themes.dracula,
+        additionalLanguages: ['json','json5','typescript', 'docker', 'bash', 'ini']
+      },
+      colorMode: {
+        defaultMode: 'dark',
+        disableSwitch: false,
+        respectPrefersColorScheme: false,
+      },
+      codeblock: {
+        showGithubLink: true,
+        githubLinkLabel: 'View on GitHub',
+        showRunmeLink: false,
+        runmeLinkLabel: 'Checkout via Runme'
+      }
+    } satisfies Preset.ThemeConfig,
+};
+
+if (process.env.ANALYTICS !== undefined && process.env.ANALYTICS !== '') {
+  const script = {
+    src: process.env.ANALYTICS,
+  }
+  if (process.env.ANALYTICS_DOMAIN !== undefined && process.env.ANALYTICS_DOMAIN !== '') {
+    script['data-domain'] = process.env.ANALYTICS_DOMAIN;
+  }
+  config.scripts.push(script)
+}
+
+export default config;

docsite/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "my-website",
+  "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",
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "@docusaurus/core": "^3.4.0",
+    "@docusaurus/preset-classic": "^3.4.0",
+    "@easyops-cn/docusaurus-search-local": "^0.44.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",
+    "micromark-extension-directive": "^3.0.1",
+    "prism-react-renderer": "^2.3.0",
+    "raw-loader": "^4.0.2",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "^3.4.0",
+    "@docusaurus/tsconfig": "^3.4.0",
+    "@docusaurus/types": "^3.4.0",
+    "@types/react": "^18.2.29",
+    "typescript": "~5.2.2"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
+    ]
+  },
+  "engines": {
+    "node": ">=18.0"
+  }
+}

docsite/sidebars.ts

@@ -0,0 +1,39 @@
+import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
+
+/**
+ * Creating a sidebar enables you to:
+ - create an ordered group of docs
+ - render a sidebar for each doc of that group
+ - provide next/previous navigation
+
+ The sidebars can be generated from the filesystem, or explicitly defined here.
+
+ Create as many sidebars as you want.
+ */
+
+const sidebars: SidebarsConfig = {
+  // By default, Docusaurus generates a sidebar from the docs folder structure
+  tutorialSidebar: [
+      {type: 'autogenerated', dirName: '.'},
+    {
+      type: "link",
+      label: "Config Playground",
+      href: "/playground"
+    }
+  ],
+
+  // But you can create a sidebar manually
+  /*
+  tutorialSidebar: [
+    'intro',
+    'hello',
+    {
+      type: 'category',
+      label: 'Tutorial',
+      items: ['tutorial-basics/create-a-document'],
+    },
+  ],
+   */
+};
+
+export default sidebars;

docsite/src/components/AIOExample.tsx

@@ -0,0 +1,50 @@
+import React, { Fragment } from "react"
+import CodeBlock from '@theme/CodeBlock';
+import Admonition from '@theme/Admonition';
+import ErrorBoundary from "@docusaurus/ErrorBoundary"
+import Error from "@theme/Error"
+import { Simulate } from "react-dom/test-utils";
+import error = Simulate.error;
+
+export interface AIOProps {
+    data: string
+    client?: boolean
+    name: string
+}
+
+const AIOExample = (props: AIOProps) => {
+    const {
+        data,
+        name,
+        client = false
+    } = props;
+
+    let configObj;
+    // eslint-disable-next-line prefer-const
+    try {
+        configObj = JSON.parse(data);
+    } catch (e) {
+        console.error(e);
+        return <Admonition type="danger" title="Unexpected Error">
+            <p>Example component crashed because of error!</p>
+            <CodeBlock>{e.message}</CodeBlock>
+        </Admonition>
+    }
+    configObj[0].type = name;
+    const configType = client ? 'clients' : 'sources';
+
+    const aio = {[configType]: configObj};
+    return <CodeBlock title="CONFIG_DIR/config.json" language="json5">{JSON.stringify(aio, null, 2)}</CodeBlock>
+}
+
+const WrappedAIOExample = (props: AIOProps) => {
+    return <ErrorBoundary
+        fallback={({error}) => (
+            <div>
+                <p>Example component crashed because of error: {error.message}.</p>
+            </div>
+        )}
+    ><AIOExample {...props} /></ErrorBoundary>
+}
+
+export default WrappedAIOExample;

docsite/src/components/JSONSchemaData.tsx

@@ -0,0 +1,44 @@
+import React from "react"
+import BrowserOnly from "@docusaurus/BrowserOnly"
+import { useColorMode } from "@docusaurus/theme-common"
+
+import JSONSchemaEditor from "@theme/JSONSchemaEditor"
+// Context
+import { usePlaygroundContext } from "@site/src/contexts/PlaygroundContext"
+
+// Common stringify of the JSON
+const STRINGIFY_JSON = (json: unknown) => JSON.stringify(json, null, "\t")
+
+function JSONSchemaDataInner(): JSX.Element {
+    const {
+        state: { userSchema, editorRef, data: value },
+        updateState,
+    } = usePlaygroundContext()
+
+    const { colorMode } = useColorMode()
+
+    return (
+        <div style={{ boxSizing: "border-box", width: "50%" }}>
+            <JSONSchemaEditor
+                value={value}
+                schema={userSchema}
+                theme={colorMode === "dark" ? "vs-dark" : "vs"}
+                editorDidMount={(editor) => {
+                    updateState({ editorRef: editor })
+                }}
+                height={"70vh"}
+                key={STRINGIFY_JSON(userSchema)}
+            />
+        </div>
+    )
+}
+
+export default function JSONSchemaDataComponent(): JSX.Element {
+    return (
+        <BrowserOnly fallback={<div>Loading...</div>}>
+            {() => {
+                return <JSONSchemaDataInner />
+            }}
+        </BrowserOnly>
+    )
+}

docsite/src/components/PlaygroundInner.tsx

@@ -0,0 +1,59 @@
+import React from "react"
+import BrowserOnly from "@docusaurus/BrowserOnly"
+
+import Schema from "@site/static/aio.json";
+import ConfigExample from "@site/static/configExample.json";
+import JSONSchemaViewer from "@theme/JSONSchemaViewer"
+import JSONSchemaEditor from "@theme/JSONSchemaEditor";
+import {useColorMode} from "@docusaurus/theme-common";
+const STRINGIFY_JSON = (json: unknown) => JSON.stringify(json, null, "\t")
+
+// based on https://github.com/jy95/docusaurus-json-schema-plugin/blob/main/testsite/src/components/PlaygroundInner.tsx
+function PlaygroundInner(): JSX.Element {
+
+    const { colorMode } = useColorMode()
+
+    return (
+        <div
+            style={{
+                display: "flex",
+                flexDirection: "column",
+                overflowY: "hidden",
+                overflowX: "hidden",
+            }}
+        >
+            <div
+                style={{
+                    display: "flex",
+                    flexDirection: "row",
+                    justifyContent: "space-between",
+                }}
+            >
+                <div style={{width: '50%'}}>
+                <JSONSchemaViewer
+                    schema={Schema}
+                    showExamples={true}
+                />
+                </div>
+                <div style={{ boxSizing: "border-box", width: "50%" }}>
+                <JSONSchemaEditor
+                    value={STRINGIFY_JSON(ConfigExample)}
+                    theme={colorMode === "dark" ? "vs-dark" : "vs"}
+                    schema={Schema}
+                    height={"70vh"}
+                />
+                </div>
+            </div>
+        </div>
+    )
+}
+
+export default function PlaygroundComponent(): JSX.Element {
+    return (
+        <BrowserOnly fallback={<div>Loading...</div>}>
+            {() => {
+                return <PlaygroundInner />
+            }}
+        </BrowserOnly>
+    )
+}

docsite/src/components/SchemaLink.tsx

@@ -0,0 +1,27 @@
+import React, {PropsWithChildren, Fragment} from "react"
+
+export interface SchemaLinkProps {
+    objectName: string
+    lower?: boolean
+    client?: boolean
+}
+
+const sourceURL = 'https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fmaster%2Fsrc%2Fbackend%2Fcommon%2Fschema%2Fsource.json';
+const clientURL = 'https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fmaster%2Fsrc%2Fbackend%2Fcommon%2Fschema%2Fclient.json';
+
+const SchemaLink = (props: PropsWithChildren<SchemaLinkProps>) => {
+    const {
+        children,
+        lower,
+        client = false
+    } = props;
+    let content = children;
+    if(content === undefined) {
+        content = <Fragment>{lower ? 'explore' : 'Explore'} the schema with an example and live editor/validator</Fragment>
+    }
+    const definition = `https://json-schema.app/view/%23/%23%2Fdefinitions%2F${props.objectName}`;
+    const url = client ? clientURL : sourceURL;
+ return <a target="_blank" href={`${definition}?url=${url}`}>{content}</a>
+}
+
+export default SchemaLink;

docsite/src/contexts/PlaygroundContext.tsx

@@ -0,0 +1,50 @@
+import { useContext, createContext } from "react"
+
+// Type I need for useRef
+import type { MonacoEditorTypes } from "@theme/MonacoEditor"
+
+export type State = {
+    // The full schema
+    // We might need to scope it with a JSON Pointer
+    fullSchema: unknown
+    // The current schema displayed (after the json pointer)
+    userSchema: unknown
+    // The current json pointer
+    jsonPointer: string
+    // Schema editor ref
+    schemaRef: undefined | MonacoEditorTypes.IStandaloneCodeEditor
+    // Data editor ref
+    editorRef: undefined | MonacoEditorTypes.IStandaloneCodeEditor
+    // Data on the data editor
+    // When using "Infer schema from data", it would be annoying to lose our written
+    data: string
+    // Errors in schema
+    schemaErrors: MonacoEditorTypes.IMarkerData[]
+    // Errors in data
+    dataErrors: MonacoEditorTypes.IMarkerData[]
+}
+
+export type Playground = {
+    // state
+    state: State
+    // update function
+    updateState: (_: Partial<State>) => void
+}
+
+export const PlaygroundContext = createContext<Playground>({
+    state: {
+        fullSchema: {},
+        userSchema: {},
+        jsonPointer: "",
+        data: "{}",
+        schemaRef: undefined,
+        editorRef: undefined,
+        schemaErrors: [],
+        dataErrors: [],
+    },
+    updateState: () => {},
+})
+
+export const usePlaygroundContext = () => useContext(PlaygroundContext)
+
+export const PlaygroundContextProvider = PlaygroundContext.Provider

docsite/src/css/custom.css

@@ -0,0 +1,30 @@
+/**
+ * Any CSS included here will be global. The classic template
+ * bundles Infima by default. Infima is a CSS framework designed to
+ * work well for content-centric websites.
+ */
+
+/* You can override the default Infima variables here. */
+:root {
+  --ifm-color-primary: #2e8555;
+  --ifm-color-primary-dark: #29784c;
+  --ifm-color-primary-darker: #277148;
+  --ifm-color-primary-darkest: #205d3b;
+  --ifm-color-primary-light: #33925d;
+  --ifm-color-primary-lighter: #359962;
+  --ifm-color-primary-lightest: #3cad6e;
+  --ifm-code-font-size: 95%;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
+}
+
+/* For readability concerns, you should choose a lighter palette in dark mode. */
+[data-theme='dark'] {
+  --ifm-color-primary: #25c2a0;
+  --ifm-color-primary-dark: #21af90;
+  --ifm-color-primary-darker: #1fa588;
+  --ifm-color-primary-darkest: #1a8870;
+  --ifm-color-primary-light: #29d5b0;
+  --ifm-color-primary-lighter: #32d8b4;
+  --ifm-color-primary-lightest: #4fddbf;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
+}