Merge branch 'develop'

https://github.com/flathub/flathub/pull/4002#pullrequestreview-1355412003

.dockerignore

@@ -4,10 +4,14 @@ npm-debug.log
 Dockerfile
 .dockerignore
 .gitignore
+.github
 .git
-config/currentCreds.json
 *.log
-config/maloja.json
-config/spotify.json
-config/config.json
+.idea
+config/*.json
+config/*.bak
 /docs
+/logs
+.flatpak-builder
+flatpak/generated-sources.json
+flatpak/.flatpak-builder

.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/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/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/workflows/dockerhub.yml

@@ -17,18 +17,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out the repo
-        uses: actions/checkout@v2
-      
+        uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b
+
       - name: Log in to Docker Hub
         if: github.event_name != 'pull_request'
-        uses: docker/login-action@f054a8b539a109f9f41c372932f1ae047eff08c9
+        uses: docker/login-action@dd4fa0671be5250ee6f50aedf4cb05514abda2c7
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
       
       - name: Extract metadata (tags, labels) for Docker
         id: meta
-        uses: docker/metadata-action@v3
+        uses: docker/metadata-action@f2a13332ac1ce8c0a71aeac48a150dbb1838ab67
         with:
           images: foxxmd/multi-scrobbler
           # generate Docker tags based on the following events/attributes
@@ -38,12 +38,18 @@ jobs:
             type=semver,pattern={{version}}
           flavor: |
             latest=false
-      
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@27d0a4f181a40b142cce983c5393082c365d1480
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@94ab11c41e45d028884a99163086648e898eed25
+
       - name: Build and push Docker image
-        uses: docker/build-push-action@v2
+        uses: docker/build-push-action@ac9327eae2b366085ac7f6a2d02df8aa8ead720a
         with:
           context: .
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-
+          platforms: linux/amd64,linux/arm64,linux/arm/v7

.gitignore

@@ -117,6 +117,13 @@ dist
 .yarn/install-state.gz
 .pnp.*
 
-*.json
+config/*.json
 *.txt
 .idea/
+
+src/**/**.js
+src/**/**.js.map
+
+*.bak
+.flatpak-builder
+flatpak/generated-sources.json

.nvmrc

@@ -1 +1 @@
-"lts/fermium"
+lts/hydrogen

Dockerfile

@@ -1,35 +1,54 @@
-FROM node:fermium-alpine3.10
+FROM lsiobase/alpine:3.17 as base
 
 ENV TZ=Etc/GMT
 
+RUN \
+  echo "**** install build packages ****" && \
+  apk add --no-cache \
+    alpine-base \
+    git \
+    nodejs \
+    npm \
+    openssh && \
+  echo "**** cleanup ****" && \
+  rm -rf \
+    /root/.cache \
+    /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 NPM dependencies and install
+COPY --chown=abc:abc package*.json ./
+COPY --chown=abc:abc tsconfig.json .
 
-COPY --chown=node:node . .
+RUN npm install
 
-ENV NPM_CONFIG_LOGLEVEL debug
+COPY --chown=abc:abc . /app
 
-ARG config_dir=/home/node/config
-RUN mkdir -p $config_dir
-VOLUME $config_dir
-ENV CONFIG_DIR=$config_dir
+RUN npm run build && rm -rf node_modules
 
-ARG log_dir=/home/node/logs
-RUN mkdir -p $log_dir
-VOLUME $log_dir
-ENV LOG_DIR=$log_dir
+FROM base as app
+
+COPY --from=build --chown=abc:abc /app /app
+
+ENV NODE_ENV="production"
+
+RUN npm install --omit=dev \
+    && npm cache clean --force \
+    && chown abc:abc node_modules \
+    && rm -rf node_modules/ts-node \
+    && rm -rf node_modules/typescript
 
 ARG webPort=9078
 ENV PORT=$webPort
 EXPOSE $PORT
-
-CMD [ "node", "index.js" ]

README.md

@@ -4,93 +4,93 @@
 [![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)
 
-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!)
+<img src="/assets/icon.png" align="right"
+alt="multi-scrobbler logo" width="180" height="180">
 
-* Supports scrobbling for many sources
+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](/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)
+  * [Youtube Music](/docs/configuration.md#youtube-music)
   * [Last.fm](/docs/configuration.md#lastfm-source)
+  * [ListenBrainz](/docs/configuration.md#listenbrainz--source-)
   * [Deezer](/docs/configuration.md#deezer)
-* Supports scrobbling to many clients
+  * [MPRIS (Linux Desktop)](/docs/configuration.md#mpris)
+  * [Mopidy](/docs/configuration.md#mopidy)
+  * [JRiver](/docs/configuration.md#jriver)
+  * [Kodi](/docs/configuration.md#kodi)
+* Supports scrobbling to many **Clients**
   * [Maloja](/docs/configuration.md#maloja)
   * [Last.fm](/docs/configuration.md#lastfm)
+  * [ListenBrainz](/docs/configuration.md#listenbrainz)
+* Monitor status of Sources and Clients using [webhooks (Gotify or Ntfy)](/docs/configuration.md#webhook-configurations) or [healthcheck endpoint](/docs/configuration.md#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
 * Smart handling of credentials (persistent, authorization through app)
 * Easy configuration through ENVs or JSON
-* Built for Docker and unattended use!
+* Install using [Docker images for x86/ARM](/docs/installation.md#docker), [flatpak](/docs/installation.md#flatpak), or [locally with NodeJS](/docs/installation.md#nodejs)
 
 **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**](/docs/configuration.md#lastfm--source-) or [Listenbrainz as a **Source**](/docs/configuration.md#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.
+
 ## Installation
 
+[See the **Installation** documentation](/docs/installation.md)
 
-### 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](/docs/configuration.md)
 
 ## 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](/docs/FAQ.md) before creating an issue!
 
 ## License
 

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');
-    }
-}

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: #231f20;
+      }
+    </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,156 +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;
-        this.ready = true;
-        return this.initialized;
-    }
-
-    // default init function, should be overridden if auth stage is required
-    testAuth = async () => {
-        return this.authed;
-    }
-
-    isReady = async () => {
-        return this.initialized && (!this.requiresAuth || (this.requiresAuth && 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,316 +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;
-    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,484 +0,0 @@
-import AbstractScrobbleClient from "./AbstractScrobbleClient.js";
-import request from 'superagent';
-import dayjs from 'dayjs';
-import compareVersions from 'compare-versions';
-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;
-    ready = false;
-    serverVersion;
-
-    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(`Communication test not OK! HTTP Status => Expected: 200 | Received: ${statusCode}`);
-                return false;
-            }
-
-            this.logger.info('Communication test 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. multi-scrobbler will most likely not work with this server.');
-            } else {
-                this.logger.info(`Maloja Server Version: ${versionstring}`);
-                this.serverVersion = versionstring;
-                if(compareVersions(versionstring, '2.7.0') < 0) {
-                    this.logger.warn('Maloja Server Version is less than 2.7, please upgrade to ensure compatibility');
-                }
-            }
-            return true;
-        } catch (e) {
-            this.logger.error('Communication test failed');
-            this.logger.error(e);
-            return false;
-        }
-    }
-
-    testHealth = async () => {
-
-        const {url} = this.config;
-        try {
-            const serverInfoResp = await this.callApi(request.get(`${url}/apis/mlj_1/serverinfo`), {maxRequestRetries: 0});
-            const {
-                statusCode,
-                body: {
-                    db_status: {
-                        healthy = false,
-                        rebuildinprogress = false,
-                        complete = false,
-                    }
-                } = {},
-            } = serverInfoResp;
-
-            if (statusCode >= 300) {
-                return [false, `Server responded with NOT OK status: ${statusCode}`];
-            }
-
-            if(rebuildinprogress) {
-                return [false, 'Server is rebuilding database'];
-            }
-
-            if(!healthy) {
-                return [false, 'Server responded that it is not healthy'];
-            }
-
-            return [true];
-        } catch (e) {
-            this.logger.error('Unexpected error encountered while testing server health');
-            this.logger.error(e);
-            throw e;
-        }
-    }
-
-    initialize = async () => {
-        // just checking that we can get a connection
-        this.initialized = await this.testConnection();
-        return this.initialized;
-    }
-
-    testAuth = async () => {
-
-        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) {
-            if(e.status === 403) {
-                // may be an older version that doesn't support auth readiness before db upgrade
-                // and if it was before api was accessible during db build then test would fail during testConnection()
-                if(compareVersions(this.serverVersion, '2.12.19') < 0) {
-                    if(!(await this.isReady())) {
-                        this.logger.error(`Could not test auth because server is not ready`);
-                        this.authed = false;
-                        return this.authed;
-                    }
-                }
-            }
-            this.logger.error('Auth test failed');
-            this.logger.error(e);
-            this.authed = false;
-        }
-        return this.authed;
-    }
-
-    isReady = async () => {
-        if (this.ready) {
-            return this.ready;
-        }
-
-        try {
-            const [isHealthy, status] = await this.testHealth();
-            if (!isHealthy) {
-                this.logger.error(`Server is not ready: ${status}`);
-                this.ready = false;
-                return this.ready;
-            }
-            this.logger.info('Server reported database is built and status is healthy');
-            this.ready = true;
-            return this.ready;
-        } catch (e) {
-            this.logger.error(`Testing server health failed due to an unexpected error`);
-            this.ready = false;
-            return this.ready;
-        }
-    }
-
-    refreshScrobbles = async () => {
-        if (this.refreshEnabled) {
-            this.logger.debug('Refreshing recent scrobbles');
-            debugger;
-            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;
-    }
-}

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](/docs/configuration.md)
+* External Link: https://github.com/FoxxMD/multi-scrobbler/blob/master/docs/configuration.md

config/config.json.example

@@ -1,32 +1,59 @@
 {
   "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
+    "maxPollRetries": 0,
+    "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",
+      "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",
+      "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

@@ -1,14 +1,12 @@
 [
   {
     "name": "FoxxMDeezer",
-    "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.
+    "clients": [],
     "data": {
-      "clientId": "string",                                  // deezer APPLICATION ID -- required if not providing access token
-      "clientSecret": "string",                              // deezer SECRET KEY -- required if not providing access token
-      "accessToken": "string",                               // deezer access token -- required if not providing client id/secret
-      "redirectUri": "http://localhost:9078/deezer/callback",// deezer redirect URI -- required only if not the default shown here. URI must end in "deezer/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/deezer/callback",
+      "interval": 60
     }
   }
 ]

config/jellyfin.json.example

@@ -1,10 +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": "MyJellyfin",
+    "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
+      }
     }
   }
 ]

config/jriver.json.example

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

config/kodi.json.example

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

config/lastfm.json.example

@@ -1,16 +1,11 @@
 [
   {
-    "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",
+    "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,10 @@
+[
+  {
+    "name": "brainz",
+    "configureAs": "client"
+    "data": {
+      "token": "029b081ba-9156-4pe7-88e5-3be671f5ea2b",
+      "username": "FoxxMD"
+    }
+  }
+]

config/maloja.json.example

@@ -1,10 +1,9 @@
 [
   {
-    "name": "myMaloja",            // required, a name to identify your Client
+    "name": "myMaloja",
     "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,11 @@
+[
+  {
+    "name": "MyMopidy",
+    "data": {
+      "url": "localhost",
+      "uriBlacklist": [],
+      "uriWhitelist": [],
+      "albumBlacklist": []
+    }
+  }
+]

config/mpris.json.example

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

config/plex.json.example

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

config/spotify.json.example

@@ -1,15 +1,12 @@
 [
   {
-    "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",
+    "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,10 @@
 [
   {
-    "name": "default",                        // optional, friendly name for logs
+    "name": "MySubsonic",
     "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,11 @@
 [
   {
-    "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",
+    "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"]
     }
   }
 ]

config/ytmusic.json.example

@@ -0,0 +1,10 @@
+[
+  {
+    "name": "MyYTMusic",
+    "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,19 @@
+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
+  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 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,8 @@
+#!/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!"
+exec \
+	  s6-setuidgid abc /usr/bin/node $NODE_ARGS /app/src/index.js run

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

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

docs/FAQ.md

@@ -0,0 +1,122 @@
+* [Connection Issues](#connection-issues)
+  * [Plex/Tautulli/Jellyfin don't connect](#plextautullijellyfin-dont-connect)
+  * [Jellyfin has warnings about undefined or missing data](#jellyfin-has-warnings-about-undefined-or-missing-data)
+  * [Spotify/Deezer/LastFM won't authenticate](#spotifydeezerlastfm-wont-authenticate)
+* [Configuration Issues](#configuration-issues)
+  * [Config could not be parsed](#config-could-not-be-parsed)
+
+# Connection Issues
+
+## Plex/Tautulli/Jellyfin don't connect
+
+These three [sources](/README.md#source) are **ingress-based** which means that multi-scrobbler waits for the Plex/Tautulli/Jellyfin server to contact multi-scrobbler, as opposed to multi-scrobbler contacting the server.
+
+multi-scrobbler will log information about any server that connects to it for these three 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 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](/docs/configuration.md) documentation assume you are running Plex/Tautulli/Jellyfin 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
+
+## Jellyfin has warnings about undefined or missing data
+
+Make sure you have 
+* [Configured the webhook plugin correctly](/docs/configuration.md#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.
+
+
+## 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`
+
+# 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.

docs/configuration.md

@@ -1,28 +1,89 @@
-# General
+* [Configuration Overview](#configuration-overview)
+  * [ENV-Based Configuration](#env-based-configuration)
+  * [File-Based Configuration](#file-based-configuration)
+    * [All-in-One File Configuration](#all-in-one-file-configuration)
+    * [Specific File Configuration](#specific-file-configuration)
+* [Source Configurations](#source-configurations)
+  * [Spotify](#spotify)
+  * [Plex](#plex)
+  * [Tautulli](#tautulli)
+  * [Subsonic](#subsonic)
+  * [Jellyfin](#jellyfin)
+  * [Last.fm (Source)](#lastfm--source-)
+  * [Listenbrainz (Source)](#listenbrainz--source-)
+  * [Deezer](#deezer)
+  * [Youtube Music](#youtube-music)
+  * [MPRIS (Linux Desktop)](#mpris)
+  * [Mopidy](#mopidy)
+  * [JRiver](#jriver)
+  * [Kodi](#kodi)
+* [Client Configurations](#client-configurations)
+  * [Maloja](#maloja)
+  * [Last.fm](#lastfm)
+  * [Listenbrainz](#listenbrainz)
+* [Monitoring](#monitoring)
+  * [Webhooks](#webhook-configurations)
+  * [Health Endpoint](#health-endpoint)
 
-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.**
+# Configuration Overview
 
-| 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                                                                 |
+[**Sources** and **Clients**](/README.md#how-does-multi-scrobbler-ms-work) are configured using environmental (ENV) variables and/or json files.
 
-**The app must have permission to write to `CONFIG_DIR` in order to store the current spotify access token.**
+**MS will parse configuration from both configuration types.** You can mix and match configurations but it is generally better to stick to one or the other.
 
+TIP: Check the [**FAQ**](/docs/FAQ.md) if you have any issues after configuration!
 
-# Sources and (Scrobble) Clients
+## ENV-Based Configuration
 
-The app has two types of configurations:
+This is done by passing environmental variables and so does not require any files to run MS.
 
-* **Sources** -- Where plays are parsed from
-* **Clients** -- Scrobble clients that plays are scrobbled to
+* Using a docker container EX `docker run -e "SPOTIFY_CLIENT_ID=yourId" -e "SPOTIFY_CLIENT_SECRET=yourSecret" ...`
+* Using a local installations by exporting variables before running MS EX `SPOTIFY_CLIENT_ID=yourId SPOTIFY_CLIENT_SECRET=yourSecret node index.js`
 
-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`:
+Use ENV-based configuration if:
+
+* You are the only person for whom MS is scrobbling for
+* You have a very simple setup for MS such as one scrobble [Client](/README.md#client) and one [Source](/README.md#source) IE Plex -> Maloja
+
+## File-Based Configuration
+
+MS will parse configuration files located in the directory specified by the `CONFIG_DIR` environmental variable. This variable defaults to:
+
+* Local installation -> `PROJECT_DIR/config`
+* Docker -> `/config` (in the container) -- see the [install docs](/docs/installation.md#docker) for how to configure this correctly
+
+Use File-based configuration if:
+
+* You have many [Sources](/README.md#source)
+* You 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
+* 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
+
+File-based configurations located in the `CONFIG_DIR` directory can be parsed from
+
+* an **all-in-one** config file named `config.json` that contains information for all Sources and Clients and/or
+* many **specific** files named based on the client/source to configure IE `plex.json` `spotify.json`
+
+There are **example configurations** for all Source/Client types and AIO config located in the [/config](/config) directory of this project. These can be used as-is by renaming them to `.json`.
+For docker installations these examples are copied to your configuration directory on first-time use.
+
+There is also a [**kitchensink example**](/docs/kitchensink.md) that provides examples of using all sources/clients in a complex configuration.
+
+### All-in-One File Configuration
+
+[**Explore the schema for this configuration, along with an example generator and validator, here**](https://json-schema.app/view/%23?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Faio.json)
+
+Example directory structure:
+
+```
+/CONFIG_DIR
+  config.json
+```
+
+<details>
+<summary>Config Example</summary>
 
 ```json5
 // in config.json
@@ -40,38 +101,68 @@ All configurations can be configured through:
         //...
       }
     }
+  ],
+  "clients": [
+    {
+      "name": "myFirstMalojaClient",
+      "type": "maloja",
+      "data": {
+        "url": "http://myMalojaServer.example",
+        // ...
+      }
+    }
   ]
 }
 ```
 
-See [config.json.example](../config/config.json.example) for a short example of this or check out [the kitchen sink example](kitchensink.md).
+</details>
 
-### ENV-Based or JSON-Based?
+`config.json` can also be used to set default behavior for all sources/clients using `sourceDefaults` and `clientDefaults` properties.
 
-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:
+See [config.json.example](/config/config.json.example) for an annotated example or check out [the kitchen sink example](kitchensink.md).
 
-#### ENV-Based (Single User)
+### Specific File Configuration
 
-* 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**
+Each file is named by the **type** of the Client/Source found in below sections. Each file as an **array** of that type of Client/Source.
 
-#### JSON-Based (Multi User)
+Example directory structure:
 
-* 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
+```
+/CONFIG_DIR
+  plex.json
+  spotify.json
+  maloja.json
+```
 
-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.**
+<details>
+<summary>Config Example</summary>
 
-# Sources
+```json5
+// in maloja.json
+[
+  {
+    "name": "myFirstMalojaClient",
+    "data": {
+      "url": "http://myMalojaServer.example",
+      "apiKey": "myKey"
+    }
+  },
+  {
+    "name": "mySecondMalojaClient",
+    "data": {
+      "url": "http://my2ndMalojaServer.example",
+      "apiKey": "myKey"
+    }
+  }
+]
+
+```
+
+</details>
+
+See the [/config](/config) directory of this project for examples of each type of config file or reference specific files below.
+
+# Source Configurations
 
 ## [Spotify](https://www.spotify.com)
 
@@ -80,17 +171,15 @@ Client ID/Secret. Make sure to also whitelist your redirect URI in the applicati
 
 ### ENV-Based
 
-| Environmental Variable     | Required? |            Default             |                    Description                     |
+| 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`                         |
+| `SPOTIFY_REDIRECT_URI`     | No         | `http://localhost:9078/callback` | URI must end in `callback`                         |
 
-### JSON-Based
+### File-Based
 
-See [`spotify.json.example`](../config/spotify.json.example)
+See [`spotify.json.example`](/config/spotify.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23/%23%2Fdefinitions%2FSpotifySourceConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fsource.json)
 
 ## [Plex](https://plex.tv)
 
@@ -102,9 +191,9 @@ Check the [instructions](plex.md) on how to setup a [webhooks](https://support.p
 |------------------------|----------|---------|-------------------------------------------------|
 | `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
+### File-Based
 
-See [`plex.json.example`](../config/plex.json.example)
+See [`plex.json.example`](/config/plex.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23/%23%2Fdefinitions%2FPlexSourceConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fsource.json)
 
 ## [Tautulli](https://tautulli.com)
 
@@ -116,9 +205,9 @@ Check the [instructions](plex.md) on how to setup a notification agent.
 |------------------------|----------|---------|-------------------------------------------------|
 | `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
+### File-Based
 
-See [`tautulli.json.example`](../config/tautulli.json.example)
+See [`tautulli.json.example`](/config/tautulli.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23/%23%2Fdefinitions%2FTautulliSourceConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fsource.json)
 
 ## [Subsonic](http://www.subsonic.org/)
 
@@ -139,16 +228,19 @@ Can use this source for any application that implements the [Subsonic API](http:
 | `SUBSONIC_PASSWORD`    | Yes       |                                  |                                                    |
 | `SUBSONIC_URL`     | Yes         |                                  | Base url of your subsonic-api server |
 
-### JSON-Based
+### File-Based
 
-See [`subsonic.json.example`](../config/subsonic.json.example)
+See [`subsonic.json.example`](/config/subsonic.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23/%23%2Fdefinitions%2FSubSonicSourceConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fsource.json)
 
 ## [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:
+* In the Jellyfin desktop web UI Navigate to -> Administration -> Dashboard -> Plugins -> Catalog
+  * Under Notifications -> **Webhook** -> Install, then restart your server
+* Navigate back to -> Administration -> Dashboard -> Plugins -> My Plugins -> Webhook
+  * Click "..." -> Settings
+* In Webhook settings:
   * `Add Generic Destination`
   * In the new `Generic` dropdown:
     * Webhook Url: `http://localhost:9078/jellyfin`
@@ -164,21 +256,35 @@ Must be using Jellyfin 10.7 or greater
 | `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
+### File-Based
 
-See [`jellyfin.json.example`](../config/jellyfin.json.example)
+See [`jellyfin.json.example`](/config/jellyfin.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23/%23%2Fdefinitions%2FJellySourceConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fsource.json)
 
 ## [Last.fm (Source)](https://www.last.fm)
 
-See the [Last.fm (Client)](#lastfm) setup for registration instructions.
+See the [Last.fm (Client)](#lastfm) setup for registration instructions. You may need to disable "Hide recent listening information" on your [privacy page](https://www.last.fm/settings/privacy) for this to work.
 
 ### ENV-Based
 
 No support for ENV based for Last.fm as a client (only source)
 
-### JSON-Based
+### File-Based
 
-See [`lastfm.json.example`](../config/lastfm.json.example), change `configureAs` to `source`.
+See [`lastfm.json.example`](/config/lastfm.json.example), change `configureAs` to `source`. Or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23/%23%2Fdefinitions%2FLastfmSourceConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fsource.json)
+
+## [Listenbrainz (Source)](https://listenbrainz.org)
+
+You will need to run your own Listenbrainz server or have an account [on the official instance](https://listenbrainz.org/login/)
+
+On your [profile page](https://listenbrainz.org/profile/) find your **User Token** to use in the configuration.
+
+**NOTE:** You cannot use ENV variables shown in the [Listenbrainz Client config](#listenbrainz) -- multi-scrobbler assumes Listenbrainz ENVs are always used for the **client** configuration. You must use the file-based config from below to setup Listenbrainz as a Source.
+
+### File-Based
+
+See [`listenbrainz.json.example`](/config/listenbrainz.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23%2Fdefinitions%2FListenBrainzSourceConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fsource.json)
+
+**Change `configureAs` to `source`**
 
 ## [Deezer](https://deezer.com/)
 
@@ -194,24 +300,308 @@ After application creation you should have credentials displayed in the "My Apps
 * **Secret Key**
 * **Redirect URL** (if not the default)
 
-### If no access token is provided...
+**If no access token is provided...**
 
 After starting multi-scrobbler with credentials in-place open the dashboard (`http://localhost:9078`) and find your Deezer source. Click **(Re)authenticate and (re)start polling** to start the login process. After login is complete polling will begin automatically.
 
 ### ENV-Based
 
-| Environmental Variable     | Required? |            Default             |                    Description                     |
-|----------------------------|-----------|----------------------------------|----------------------------------------------------|
-| `DEEZER_CLIENT_ID`        | Yes       |                                  |  Your **Application ID**                            |
-| `DEEZER_CLIENT_SECRET`    | Yes       |                                  |  Your **Secret Key**                                |
-| `DEEZER_ACCESS_TOKEN`     | No         |                                  | Must include either this token or client id/secret |
-| `DEEZER_REDIRECT_URI`     | No         | `http://localhost:{PORT}/deezer/callback` | URI must end in `deezer/callback`         |
+| Environmental Variable     | Required? | Default                                 |                    Description                     |
+|----------------------------|-----------|-----------------------------------------|----------------------------------------------------|
+| `DEEZER_CLIENT_ID`        | Yes       |                                         |  Your **Application ID**                            |
+| `DEEZER_CLIENT_SECRET`    | Yes       |                                         |  Your **Secret Key**                                |
+| `DEEZER_REDIRECT_URI`     | No         | `http://localhost:9078/deezer/callback` | URI must end in `deezer/callback`         |
 
-### JSON-Based
+### File-Based
 
-See [`deezer.json.example`](../config/deezer.json.example)
+See [`deezer.json.example`](/config/deezer.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23/%23%2Fdefinitions%2FDeezerSourceConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fsource.json)
 
-# Clients
+## [Youtube Music](https://music.youtube.com)
+
+Credentials for YT Music are obtained from a browser request to https://music.youtube.com **once you are logged in.** [Specific requirements are here and summarized below:](https://github.com/nickp10/youtube-music-ts-api/blob/master/DOCUMENTATION.md#authenticate)
+
+* Open a new tab
+* Open the developer tools (Ctrl-Shift-I) and select the “Network” tab 
+* Go to https://music.youtube.com and ensure you are logged in 
+
+Then...
+
+1. Find and select an authenticated POST request. The simplest way is to filter by /browse using the search bar of the developer tools. If you don’t see the request, try scrolling down a bit or clicking on the library button in the top bar.
+2. **Make sure **Headers** pane is selected and open
+3. In the **Request Headers** section find and copy the **entire value** found after `Cookie:` and use this as the `cookie` value in your multi-scrobbler config
+4. If present, in the **Request Headers** section find and copy the number found in `X-google-AuthUser` and use this as the value for `authUser` in your multi-scrobbler config
+
+![Google Headers](/docs/google-header.jpg)
+
+NOTES:
+
+* YT Music authentication is "browser based" which means your credentials may expire after a (long?) period of time OR if you log out of https://music.youtube.com. In the event this happens just repeat the steps above to get new credentials.
+* Communication to YT Music is **unofficial** and not supported or endorsed by Google. This means that **this integration may stop working at any time** if Google decides to change how YT Music works in the browser.
+
+### File-Based
+
+See [`ytmusic.json.example`](/config/ytmusic.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23/%23%2Fdefinitions%2FYTMusicSourceConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fsource.json)
+
+## [MPRIS](https://specifications.freedesktop.org/mpris-spec/latest/)
+
+MPRIS is a standard interface for communicating with Music Players on **linux operating systems.**
+
+If you run Linux and have a notification tray that shows what media you are listening to, you likely have access to MPRIS.
+
+![Notification Tray](/assets/mpris.jpg)
+
+multi-scrobbler can listen to this interface and scrobble tracks played by **any media player** that communicates to the operating system with MPRIS.
+
+**NOTE:** multi-scrobbler needs to be running as a [**Local Installation**](/docs/installation.md#local) in order to use MPRIS. This cannot be used from docker.
+
+### ENV-Based
+
+| Environmental Variable | Required? | Default | Description                                                                      |
+|------------------------|-----------|---------|----------------------------------------------------------------------------------|
+| MPRIS_ENABLE           | No        |         | Use MPRIS as a Source (useful when you don't need any other options)             |
+| MPRIS_BLACKLIST        | No        |         | Comma-delimited list of player names not to scrobble from                        |
+| MPRIS_WHITELIST        | No        |         | Comma-delimited list of players names to ONLY scrobble from. Overrides blacklist |
+
+### File-Based
+
+See [`mpris.json.example`](/config/mpris.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23%2Fdefinitions%2FMPRISSourceConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fsource.json)
+
+## [Mopidy](https://mopidy.com/)
+
+Mopidy is a headless music server that supports playing music from many [standard and non-standard sources such as Pandora, Bandcamp, and Tunein.](https://mopidy.com/ext/)
+
+multi-scrobbler can scrobble tracks played from any Mopidy backend source, regardless of where you listen to them.
+
+### File-Based
+
+See [`mopidy.json.example`](/config/mopidy.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23%2Fdefinitions%2FMopidySourceConfig/%23%2Fdefinitions%2FMopidyData?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fsource.json)
+
+Configuration Options:
+
+##### `url`
+
+The URL used to connect to the Mopidy server. You MUST have [Mopidy-HTTP extension](https://mopidy.com/ext/http) enabled.
+
+If no `url` is provided a default is used which assumes Mopidy is installed on the same server as multi-scrobbler: `ws://localhost:6680/mopidy/ws/`
+
+Make sure the hostname and port number match what is found in the Mopidy configuration file `mopidy.conf`:
+
+```
+...
+
+[http]
+hostname = localhost
+port = 6680
+
+...
+```
+
+The URL used to connect ultimately must be formed like this: `[protocol]://[hostname]:[port]/[path]`
+If any part of this URL is missing multi-scrobbler will use a default value, for your convenience. This also means that if any part of your URL is **not** standard you must explicitly define it.
+
+Part => Default Value
+
+* Protocol => `ws://`
+* Hostname => `localhost`
+* Port => `6680`
+* Path => `/mopidy/ws/`
+
+<details>
+<summary>URL Transform Examples</summary>
+
+```json
+{
+  "url": "mopidy.mydomain.com"
+}
+```
+
+MS transforms this to: `ws://mopidy.mydomain.com:6680/mopidy/ws/`
+
+```json
+{
+  "url": "192.168.0.101:3456"
+}
+```
+
+MS transforms this to: `ws://192.168.0.101:3456/mopidy/ws/`
+
+```json
+{
+  "url": "mopidy.mydomain.com:80/MOPWS"
+}
+```
+
+MS transforms this to: `ws://mopidy.mydomain.com:80/MOPWS`
+
+</details>
+
+
+#### URI Blacklist/Whitelist
+
+If you wish to disallow or only allow scrobbling from some sources played through Mopidy you can specify these using `uriBlacklist` or `uriWhitelist` in your config. multi-scrobbler will check the list to see if any string matches the START of the `uri` on a track. If whitelist is used then blacklist is ignored. All strings are case-insensitive.
+
+EX:
+
+```json
+{
+  "uriBlacklist": ["soundcloud"]
+}
+```
+
+Will prevent multi-scrobbler from scrobbling any Mopidy track that start with a `uri` like `soundcloud:song:MySong-1234`
+
+#### Album Blacklist
+
+For certain sources (Soundcloud) Mopidy does not have all track info (Album) and will instead use "Soundcloud" as the Album name. You can prevent multi-scrobbler from using this bad Album data by adding the fake Album name to this list. Multi-scrobbler will still scrobble the track, just without the bad data. All strings are case-insensitive.
+
+EX:
+
+```json
+{
+  "albumBlacklist": ["SoundCloud", "Mixcloud"]
+}
+```
+
+If a track would be scrobbled like `Album: Soundcloud, Track: My Cool Track, Artist: A Cool Artist` 
+then multi-scrobbler will instead scrobble  `Track: My Cool Track, Artist: A Cool Artist`
+
+## [JRiver](https://jriver.com/)
+
+In order for multi-scrobbler to communicate with JRiver you must have [Web Server Interface](https://wiki.jriver.com/index.php/Web_Service_Interface#Documentation_of_Functions) enabled. This can can be in the JRiver GUI:
+
+* Tools -> Options -> Media Network
+  * Check `Use Media Network to share this library...`
+  * If you have `Authentication` checked you will need to provide the **Username** and **Password** in the ENV/File configuration below.
+
+#### URL
+
+If you do not provide a URL then a default is used which assumes JRiver is installed on the same server as multi-scrobbler: `http://localhost:52199/MCWS/v1/`
+
+* Make sure the port number matches what is found in `Advanced` section in the [Media Network](#jriver) options.
+* If your installation is on the same machine but you cannot connect using `localhost` try `0.0.0.0` instead.
+
+The URL used to connect ultimately must be formed like this: `[protocol]://[hostname]:[port]/[path]`
+If any part of this URL is missing multi-scrobbler will use a default value, for your convenience. This also means that if any part of your URL is **not** standard you must explicitly define it.
+
+Part => Default Value
+
+* Protocol => `http://`
+* Hostname => `localhost`
+* Port => `52199`
+* Path => `/MCWS/v1/`
+
+<details>
+<summary>URL Transform Examples</summary>
+
+```json
+{
+  "url": "jriver.mydomain.com"
+}
+```
+
+MS transforms this to: `http://jriver.mydomain.com:52199/MCWS/v1/`
+
+```json
+{
+  "url": "192.168.0.101:3456"
+}
+```
+
+MS transforms this to: `http://192.168.0.101:3456/MCWS/v1/`
+
+```json
+{
+  "url": "mydomain.com:80/jriverReverse/MCWS/v1/"
+}
+```
+
+MS transforms this to: `http://mydomain.com:80/jriverReverse/MCWS/v1/`
+
+</details>
+
+### ENV-Based
+
+
+| Environmental Variable | Required |             Default             |                  Description                   |
+|------------------------|----------|---------------------------------|------------------------------------------------|
+| JRIVER_URL             | Yes      | http://localhost:52199/MCWS/v1/ | The URL of the JRiver server                   |
+| JRIVER_USERNAME        | No       |                                 | If authentication is enabled, the username set |
+| JRIVER_PASSWORD        | No       |                                 | If authenticated is enabled, the password set  |
+
+
+### File-Based
+
+See [`jriver.json.example`](/config/jriver.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23%2Fdefinitions%2FJRiverSourceConfig/%23%2Fdefinitions%2FJRiverData?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fsource.json)
+
+## [Kodi](https://kodi.tv/)
+
+In order for multi-scrobbler to communicate with Kodi you must have the [Web Interface](https://kodi.wiki/view/Web_interface) enabled. This can can be in the Kodi GUI:
+
+* Settings -> Services -> Control
+  * Check `Allow remote control via HTTP`
+  * Ensure you have a **Username** and **Password** set, you will need to provide them in the ENV/File configuration below.
+
+#### URL
+
+If you do not provide a URL then a default is used which assumes Kodi is installed on the same server as multi-scrobbler: `http://localhost:8080/jsonrpc`
+
+* Make sure the port number matches what is found in **Port** in the [Control](#kodi) section mentioned above.
+* If your installation is on the same machine but you cannot connect using `localhost` try `0.0.0.0` instead.
+
+The URL used to connect ultimately must be formed like this: `[protocol]://[hostname]:[port]/[path]`
+If any part of this URL is missing multi-scrobbler will use a default value, for your convenience. This also means that if any part of your URL is **not** standard you must explicitly define it.
+
+Part => Default Value
+
+* Protocol => `http://`
+* Hostname => `localhost`
+* Port => `8080`
+* Path => `/jsonrpc`
+
+<details>
+<summary>URL Transform Examples</summary>
+
+```json
+{
+  "url": "kodi.mydomain.com"
+}
+```
+
+MS transforms this to: `http://kodi.mydomain.com:8080/jsonrpc`
+
+```json
+{
+  "url": "192.168.0.101:3456"
+}
+```
+
+MS transforms this to: `http://192.168.0.101:3456/jsonprc`
+
+```json
+{
+  "url": "mydomain.com:80/kodiReverse/jsonrpc"
+}
+```
+
+MS transforms this to: `http://mydomain.com:80/kodiReverse/jsonrpc`
+
+</details>
+
+### ENV-Based
+
+
+| Environmental Variable | Required | Default                       | Description                |
+|------------------------|----------|-------------------------------|----------------------------|
+| KODI_URL               | Yes      | http://localhost:8080/jsonrpc | The URL of the Kodi server |
+| KODI_USERNAME          | No       |                               | The username set           |
+| KODI_PASSWORD          | No       |                               | The password set           |
+
+
+### File-Based
+
+See [`kodi.json.example`](/config/kodi.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23%2Fdefinitions%2FKodiSourceConfig/%23%2Fdefinitions%2FKodiData?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fsource.json)
+
+# Client Configurations
 
 ## [Maloja](https://github.com/krateng/maloja)
 
@@ -222,9 +612,9 @@ See [`deezer.json.example`](../config/deezer.json.example)
 | `MALOJA_URL`               | Yes       |         | Base URL of your installation |
 | `MALOJA_API_KEY`           | Yes       |         | Api Key                       |
 
-### JSON-Based
+### File-Based
 
-See [`maloja.json.example`](../config/maloja.json.example)
+See [`maloja.json.example`](/config/maloja.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23/%23%2Fdefinitions%2FMalojaClientConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fclient.json)
 
 ## [Last.fm](https://www.last.fm)
 
@@ -238,13 +628,134 @@ 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.                       |
+| 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:9078/lastfm/callback` | Url to use for authentication. Must include `lastfm/callback` somewhere in it |
+| `LASTFM_SESSION`           | No        |                                         | Session id. Will be generated by authentication flow if not provided.                       |
 
-### JSON-Based
+### File-Based
 
-See [`lastfm.json.example`](../config/lastfm.json.example)
+See [`lastfm.json.example`](/config/lastfm.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23/%23%2Fdefinitions%2FLastfmClientConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fclient.json)
+
+## [Listenbrainz](https://listenbrainz.org)
+
+You will need to run your own Listenbrainz server or have an account [on the official instance](https://listenbrainz.org/login/)
+
+On your [profile page](https://listenbrainz.org/profile/) find your **User Token** to use in the configuration.
+
+### ENV-Based
+
+
+| Environmental Variable | Required? |            Default            |           Description           |
+|------------------------|-----------|-------------------------------|---------------------------------|
+| LZ_TOKEN               | Yes       |                               | User token from your LZ profile |
+| LZ_USER                | Yes       |                               | Your LZ username                |
+| LZ_URL                 | No        | https://api.listenbrainz.org/ | The base URL for the LZ server  |
+
+### File-Based
+
+See [`listenbrainz.json.example`](/config/listenbrainz.json.example) or [explore the schema with an example and live editor/validator](https://json-schema.app/view/%23%2Fdefinitions%2FListenBrainzClientConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Fclient.json)
+
+# Monitoring
+
+multi-scrobbler supports some common webhooks and a healthcheck endpoint in order to monitor Sources and Clients for errors.
+
+## Webhook Configurations
+
+Webhooks will **push** a notification to your configured servers on these events:
+
+* Source polling started 
+* Source polling retry
+* Source polling stopped on error 
+* Scrobble client scrobble failure
+
+Webhooks are configured in the main [config.json](#all-in-one-file-configuration) file under the `webhook` top-level property. Multiple webhooks may be configured for each webhook type. EX:
+
+```json
+{
+  "sources": [
+    ...
+  ],
+  "clients": [
+    ...
+  ],
+  "webhooks": [
+    {
+      "name": "FirstGotifyServer",
+      "type": "gotify",
+      "url": "http://192.168.0.100:8070",
+      "token": "abcd"
+    }, 
+    {
+      "name": "SecondGotifyServer",
+      "type": "gotify",
+      ...
+    },
+    {
+      "name": "NtfyServerOne",
+      "type": "ntfy",
+      ...
+    },
+    ...
+  ]
+}
+```
+
+### [Gotify](https://gotify.net/)
+
+Refer to the [config schema for GotifyConfig](https://json-schema.app/view/%23/%23%2Fdefinitions%2FGotifyConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Faio.json)
+
+multi-scrobbler optionally supports setting message notification priority via `info` `warn` and `error` mappings.
+
+EX
+
+```json
+{
+  "type": "gotify",
+  "name": "MyGotifyFriendlyNameForLogs",
+  "url": "http://192.168.0.100:8070",
+  "token": "AQZI58fA.rfSZbm",
+  "priorities": {
+    "info": 5,
+    "warn": 7,
+    "error": 10
+  }
+}
+```
+
+### [Ntfy](https://ntfy.sh/)
+
+Refer to the [config schema for NtfyConfig](https://json-schema.app/view/%23/%23%2Fdefinitions%2FNtfyConfig?url=https%3A%2F%2Fraw.githubusercontent.com%2FFoxxMD%2Fmulti-scrobbler%2Fdevelop%2Fsrc%2Fcommon%2Fschema%2Faio.json)
+
+multi-scrobbler optionally supports setting message notification priority via `info` `warn` and `error` mappings.
+
+EX
+
+```json
+{
+  "type": "ntfy",
+  "name": "MyNtfyFriendlyNameForLogs",
+  "url": "http://192.168.0.100:9991",
+  "topic": "RvOwKJ1XtIVMXGLR",
+  "username": "Optional",
+  "password": "Optional",
+  "priorities": {
+    "info": 3,
+    "warn": 4,
+    "error": 5
+  }
+}
+```
+
+## Health Endpoint
+
+An endpoint for monitoring the health of sources/clients is available at GET `http://YourMultiScrobblerDomain/health`
+
+* Returns `200 OK` when **everything** is working or `500 Internal Server Error` if **anything** is not 
+* The plain url (`/health`) aggregates status of **all clients/sources** -- so any failing client/source will make status return 500 
+  * Use query params `type` or `name` to restrict client/sources aggregated IE `/health?type=spotify` or `/health?name=MyMaloja`
+* On 500 the response returns a JSON payload with `messages` array that describes any issues
+  * For any clients/sources that require authentication `/health` will return 500 if they are **not authenticated** 
+  * For sources that poll (spotify, yt music, subsonic) `/health` will 500 if they are **not polling**

docs/installation.md

@@ -0,0 +1,112 @@
+# Installation
+
+# Local
+
+After installation see [service.md](/docs/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 build
+npm start
+```
+
+### Usage Examples
+
+* The web UI is served on port `9078`. This can be modified using the `PORT` environmental variable.
+
+#### Using [file-based](/docs/configuration.md#file-based-configuration) configuration
+
+```shell
+npm start
+```
+
+#### Using [env-based](/docs/configuration.md#env-based-configuration) configuration
+
+```shell
+SPOTIFY_CLIENT_ID=yourId SPOTIFY_CLIENT_SECRET=yourSecret MALOJA_URL="http://domain.tld" node src/index.js
+```
+
+## Flatpak
+
+You must have [Flatpak](https://flatpak.org/) installed on your system.
+
+```shell
+flatpak install flathub io.github.foxxmd.multiscrobbler
+```
+
+### Usage Examples
+
+#### Using [file-based](/docs/configuration.md#file-based-configuration) configuration
+
+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.multiscrobbler
+```
+
+#### Using [env-based](/docs/configuration.md#env-based-configuration) configuration
+
+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
+```
+
+# [Docker](https://hub.docker.com/r/foxxmd/multi-scrobbler)
+
+Cross-platform images are built for x86 (Intel/AMD) and ARM (IE Raspberry Pi)
+
+```
+foxxmd/multi-scrobbler:latest
+```
+
+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:
+
+* If you must **bind a host directory into the container for storing configurations and credentials:**
+    * [Using `-v` method for docker](https://docs.docker.com/storage/bind-mounts/#start-a-container-with-a-bind-mount): `-v /path/on/host/config:/config`
+    * [Using docker-compose](https://docs.docker.com/compose/compose-file/compose-file-v3/#short-syntax-3): `- /path/on/host/config:/config`
+* (Optionally) map the web UI port in the container **9078** to the host
+    * With [docker](https://docs.docker.com/engine/reference/commandline/run/#publish): `-p 9078:9078` (first port is the port on the host to use)
+    * With [docker-compose](https://docs.docker.com/compose/compose-file/compose-file-v3/#short-syntax-1): `- "9078:9078"`
+* (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
+
+If you are
+
+* using [rootless containers with Podman](https://developers.redhat.com/blog/2020/09/25/rootless-containers-with-podman-the-basics#why_podman_)
+* running docker on MacOS or 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 Examples
+
+### Using [env-based](/docs/configuration.md#env-based-configuration) configuration
+
+```bash
+docker run -e "SPOTIFY_CLIENT_ID=yourId" -e "SPOTIFY_CLIENT_SECRET=yourSecret" -e "MALOJA_URL=http://domain.tld" -e "MALOJA_API_KEY=1234" -e "PUID=1000" -e "PGID=1000" -p 9078:9078 -v /path/on/host/config:/config foxxmd/multi-scrobbler
+```
+
+### Using [file-based](/docs/configuration.md#file-based-configuration) configuration
+
+```bash
+docker run -e "PUID=1000" -e "PGID=1000" -p 9078:9078 -v /path/on/host/config:/config foxxmd/multi-scrobbler
+```
+
+See the [docker-compose.yml](/docker-compose.yml) file for how to use with docker-compose.

docs/kitchensink.md

@@ -6,11 +6,13 @@ 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
 
@@ -82,6 +84,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 +102,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 +143,7 @@ Using just one config file located at `CONFIG_DIR/config.json`:
       "data": {
         "apiKey": "maryApiKey",
         "secret": "marySecret",
+        "redirectUri": "http://localhost:9078/lastfm/callback"
       }
     }
   ]
@@ -143,7 +163,7 @@ In `CONFIG_DIR/spotify.json`:
     "clients": ["foxxMaloja"],
     "data": {
       "clientId": "foxxSpotifyAppId",
-      "clientSecret": "foxxSpotifyAppSecret",
+      "clientSecret": "foxxSpotifyAppSecret"
     }
   },
   {
@@ -151,7 +171,7 @@ In `CONFIG_DIR/spotify.json`:
     "clients": ["maryMaloja"],
     "data": {
       "clientId": "foxxSpotifyAppId",
-      "clientSecret": "foxxSpotifyAppSecret",
+      "clientSecret": "foxxSpotifyAppSecret"
     }
   },
   {
@@ -160,7 +180,7 @@ In `CONFIG_DIR/spotify.json`:
     "data": {
       "accessToken": "fredsToken",
       "refreshToken": "fredsRefreshToken",
-      "interval": 120,
+      "interval": 120
     }
   },
 ]
@@ -188,7 +208,36 @@ In `CONFIG_DIR/plex.json`
   {
     "name": "partyPlex",
     "data": {
-      "libraries": ["party"],
+      "libraries": ["party"]
+    }
+  }
+]
+```
+
+In `CONFIG_DIR/jellyfin.json`
+
+```json5
+[
+  {
+    "name": "FredJelly",
+    "data": {
+      "user": ["fred@email.com"]
+    }
+  }
+]
+```
+
+In `CONFIG_DIR/ytmusic.json`
+
+```json5
+[
+  {
+    "type": "ytmusic",
+    "name": "foxxYoutube",
+    "clients": ["foxxMaloja"],
+    "data": {
+      "cookie": "__Secure-3PAPISID=3AxsXpy0MKGu75Qb/AkISXGqOnSDn1jEKn; DEVICE_INFO=ChxOekU0Tmpjek5EWTBPRGd3TlRBMk16QXpNdz09EJbS8Z0GGJbS8Z0G; ...",
+      "authUser": 1
     }
   }
 ]
@@ -231,6 +280,7 @@ In `CONFIG_DIR/lastfm.json`:
     "data": {
       "apiKey": "maryApiKey",
       "secret": "marySecret",
+      "redirectUri": "http://localhost:9078/lastfm/callback"
     }
   }
 ]

docs/plex.md

@@ -40,8 +40,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}"
 }
 ```
 

docs/service.md

@@ -0,0 +1,68 @@
+If you have multi-scrobbler installed [locally](/docs/installation.md#local) 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:
+
+```console
+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](/docs/installation.md#flatpak)
+
+### Node.js Installs
+
+If you are running multi-scrobbler directly with [nodejs from a clone repository directory](/docs/installation.md#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:
+
+```console
+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!

flatpak/README.md

@@ -0,0 +1,41 @@
+NOTE: This steps are for building the flatpak entirely locally, from source. If you want to install the application normally then [get it through flathub](/docs/installation.md#flatpak)
+
+Flatpak build is a little convoluted until someone sets me straight...
+
+# 1. 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/)
+
+# 2. Update Project source
+
+Set the `branch` `tag` or `commit` to use for MS in the `git` source in [`io.github.foxxmd.multiscrobbler.yml`](/flatpak/io.github.foxxmd.multiscrobbler.yml)
+
+# 3. 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)
+
+Then, from MS project root:
+
+```
+flatpak-node-generator npm package-lock.json
+```
+
+Move `generated-sources.json` into [`/flatpak`](/flatpak)
+
+# 4. Build flatpak
+
+From MS project root:
+
+```console
+cd flatpak
+flatpak-builder --repo=/home/yourUser/multi-scrobbler-repo /home/yourUser/multi-scrobbler-build io.github.foxxmd.multiscrobbler.yml --force-clean
+```
+Add `--install --user` to have the app installed immediately.

flatpak/defaultConfig.json

@@ -0,0 +1,5 @@
+{
+  "logging": {
+    "file": false
+  }
+}

flatpak/io.github.foxxmd.multiscrobbler.desktop

@@ -0,0 +1,10 @@
+[Desktop Entry]
+Type=Application
+Name=multi-scrobbler
+Comment=Scrobbles music from multiple sources to multiple clients
+Icon=io.github.foxxmd.multiscrobbler
+TryExec=multiscrobbler
+Exec=multiscrobbler
+Terminal=true
+Categories=Utility;Music;ConsoleOnly;
+X-Flatpak=io.github.foxxmd.multiscrobbler

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

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<component type="console-application">
+    <id>io.github.foxxmd.multiscrobbler</id>
+    <provides>
+        <id>io.github.foxxmd.multiscrobbler.desktop</id>
+    </provides>
+    <launchable type="desktop-id">io.github.foxxmd.multiscrobbler.desktop</launchable>
+    <name>multi-scrobbler</name>
+    <summary>Scrobbles music from many sources to many clients</summary>
+    <url type="homepage">https://github.com/FoxxMD/multi-scrobbler</url>
+    <url type="help">https://github.com/FoxxMD/multi-scrobbler/blob/flatpak-clean/docs/configuration.md</url>
+    <metadata_license>MIT</metadata_license>
+    <project_license>MIT</project_license>
+    <description>
+        <p>
+            Track your music listening history from many different sources:
+        </p>
+        <ul>
+            <li>Spotify</li>
+            <li>Plex (Tautulli)</li>
+            <li>Any subsonic-based music player (Airsonic)</li>
+            <li>Jellyfin</li>
+            <li>Mopidy</li>
+            <li>Deezer</li>
+            <li>JRiver</li>
+            <li>Kodi</li>
+            <li>MPRIS (linux desktop)</li>
+        </ul>
+        <p>and consolidate your listens (scrobbles) into one or more scrobbling servers/services:</p>
+        <ul>
+            <li>Maloja</li>
+            <li>Last.fm</li>
+            <li>Listenbrainz</li>
+        </ul>
+        <p>multi-scrobbler requires some configuration before use. Please visit the website or help links below to get started.</p>
+    </description>
+    <screenshots>
+        <screenshot type="default">
+            <caption>Browser-based UI</caption>
+            <image type="source">https://raw.githubusercontent.com/FoxxMD/multi-scrobbler/7b0f5801a1aa728986f440f4c67fe158cecd763d/assets/status-ui.jpg</image>
+        </screenshot>
+    </screenshots>
+    <releases>
+        <release version="0.4.4" date="2023-03-20"/>
+    </releases>
+    <categories>
+        <category>Utility</category>
+        <category>Music</category>
+        <category>ConsoleOnly</category>
+    </categories>
+    <content_rating type="oars-1.0">
+        <content_attribute id="language-profanity">mild</content_attribute>
+    </content_rating>
+</component>

flatpak/io.github.foxxmd.multiscrobbler.yml

@@ -0,0 +1,76 @@
+app-id: io.github.foxxmd.multiscrobbler
+runtime: org.freedesktop.Platform
+runtime-version: '22.08'
+sdk: org.freedesktop.Sdk
+command: multiscrobbler
+finish-args:
+  - --share=network
+  # used for access to MPRIS in order to scrobble
+  - --own-name=org.mpris.MediaPlayer2.*
+sdk-extensions:
+  - org.freedesktop.Sdk.Extension.node18
+modules:
+  - name: multiscrobbler
+    buildsystem: simple
+    build-options:
+      append-path: /usr/lib/sdk/node18/bin
+      env:
+        XDG_CACHE_HOME: /run/build/multiscrobbler/flatpak-node/cache
+        npm_config_cache: /run/build/multiscrobbler/flatpak-node/npm-cache
+        npm_config_nodedir: /usr/lib/sdk/node18
+        npm_config_offline: 'true'
+    build-commands:
+      # install npm dependencies
+      - npm install --offline
+
+      # build app
+      - npm run build
+
+      # makes node and npm available
+      - mkdir -p /app/bin /app/lib /app/lib/src
+      - cp -a /usr/lib/sdk/node18/bin/{node,npm} /app/bin
+      - cp -a /usr/lib/sdk/node18/lib/* /app/lib
+      - rm -r /app/lib/node_modules/npm/{docs,man}
+
+      # remove dev dependencies
+      - npm prune --production
+
+      # copy node_modules needed to run app
+      - cp -r node_modules/* /app/lib/node_modules
+
+      # delete typescript files (not needed for running app)
+      - find src/ -name "*.ts" -type f -delete
+
+      # copy app files to runtime dir
+      - cp -r src/* /app/lib/src
+      - cp -r config /app/lib/config
+      - cp flatpak/defaultConfig.json /app/lib/config/config.json
+
+      - install -Dm644 flatpak/${FLATPAK_ID}.desktop /app/share/applications/${FLATPAK_ID}.desktop
+      - install -Dm644 flatpak/icon.png /app/share/icons/hicolor/512x512/apps/${FLATPAK_ID}.png
+      - install -Dm644 flatpak/${FLATPAK_ID}.metainfo.xml /app/share/metainfo/${FLATPAK_ID}.metainfo.xml
+
+      - install -Dm755 ../run.sh /app/bin/multiscrobbler
+    subdir: main
+    sources:
+      - type: git
+        url: https://github.com/FoxxMD/multi-scrobbler
+        commit: 9a578e54a89f87c82ff811bb04257c9b641b199a
+        dest: main
+      # Wrapper to launch the app
+      - type: script
+        dest-filename: run.sh
+        commands:
+          # Run config check and copy examples + default config (disable file logging)
+          - |
+            echo -e "Checking CONFIG_DIR for existing configs: ${XDG_CONFIG_HOME}"
+            if [ "$(ls -A ${XDG_CONFIG_HOME})" ]; then
+              echo "Directory is not empty! Will not add default config/examples"
+            else
+              echo "Directory is empty! Adding default config/examples"
+              cp -r /app/lib/config/. "${XDG_CONFIG_HOME}"/
+              #cp /app/lib/defaultConfig.json $XDG_CONFIG_HOME/config.json
+            fi
+          - cd /app/lib && CONFIG_DIR=$XDG_CONFIG_HOME IS_LOCAL=true node src/index.js
+
+      - generated-sources.json

package.json

@@ -1,15 +1,28 @@
 {
   "name": "multi-scrobbler",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "scrobble plays from multiple sources to multiple clients",
-  "type": "module",
-  "main": "index.js",
+  "main": "src/index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "tsc",
+    "start": "node src/index.js",
+    "schema": "npm run -s schema-aio & npm run -s schema-source & npm run -s schema-client & npm run -s schema-aiosource & npm run -s schema-aioclient",
+    "schema-client": "typescript-json-schema tsconfig.json ClientConfig --out src/common/schema/client.json --required --tsNodeRegister --refs --validationKeywords deprecationMessage",
+    "schema-source": "typescript-json-schema tsconfig.json SourceConfig --out src/common/schema/source.json --required --tsNodeRegister --refs --validationKeywords deprecationMessage",
+    "schema-aio": "typescript-json-schema tsconfig.json AIOConfig --out src/common/schema/aio.json --required --tsNodeRegister --refs --validationKeywords deprecationMessage",
+    "schema-aiosource": "typescript-json-schema tsconfig.json AIOSourceConfig --out src/common/schema/aio-source.json --required --tsNodeRegister --refs --validationKeywords deprecationMessage",
+    "schema-aioclient": "typescript-json-schema tsconfig.json AIOClientConfig --out src/common/schema/aio-client.json --required --tsNodeRegister --refs --validationKeywords deprecationMessage"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/common/infrastructure/typings/lastfm-node-client.d.ts",
+      "import": "./src/index.js"
+    }
   },
   "engines": {
-    "node": ">=14.0.0",
-    "npm": ">=6.0.0"
+    "node": ">=18.0.0",
+    "npm": ">=9.1.0"
   },
   "repository": {
     "type": "git",
@@ -23,21 +36,65 @@
   "homepage": "https://github.com/FoxxMD/multi-scrobbler#readme",
   "dependencies": {
     "@awaitjs/express": "^0.6.3",
+    "@foxxmd/winston": "3.3.31",
+    "@kenyip/backoff-strategies": "^1.0.4",
+    "ajv": "^7.2.4",
     "body-parser": "^1.19.0",
     "compare-versions": "^4.1.2",
+    "concat-stream": "^2.0.0",
     "dayjs": "^1.10.4",
+    "dbus-next": "^0.10.2",
     "ejs": "^3.1.6",
+    "es6-error": "^4.1.1",
     "express": "^4.17.1",
     "express-session": "^1.17.2",
+    "fixed-size-list": "^0.3.0",
+    "formidable": "^2.1",
+    "gotify": "^1.1.0",
+    "iti": "^0.6.0",
+    "json5": "^2.2.3",
+    "kodi-api": "^0.2.1",
     "lastfm-node-client": "^2.2.0",
-    "multer": "^1.4.2",
-    "passport": "^0.5.0",
+    "mopidy": "^1.3.0",
+    "normalize-url": "^6.1.0",
+    "ntfy": "^1.0.5",
+    "p-event": "^4.2.0",
+    "passport": "^0.6.0",
     "passport-deezer": "^0.2.0",
+    "pony-cause": "^1.1.1",
     "safe-stable-stringify": "^1.1.1",
-    "socket.io": "^4.1.3",
+    "socket.io": "^4.6.1",
     "spotify-web-api-node": "^5.0.2",
-    "superagent": "^6.1.0",
-    "winston": "^3.3.3",
-    "winston-daily-rotate-file": "^4.5.0"
+    "superagent": "^8.0.9",
+    "triple-beam": "^1.3.0",
+    "winston-daily-rotate-file": "^4.5.0",
+    "winston-duplex": "0.1.3",
+    "winston-null": "^2.0.0",
+    "winston-transport": "^4.4.0",
+    "xml2js": "^0.4.23",
+    "youtube-music-ts-api": "^1.4.1"
+  },
+  "devDependencies": {
+    "@tsconfig/node18": "^1.0.1",
+    "@types/concat-stream": "^2.0.0",
+    "@types/express": "^4.17.13",
+    "@types/express-session": "^1.17.4",
+    "@types/formidable": "^2.0.5",
+    "@types/node": "^18.0.0",
+    "@types/passport": "^1.0.12",
+    "@types/spotify-web-api-node": "^5.0.7",
+    "@types/superagent": "^4.1.16",
+    "@types/triple-beam": "^1.3.2",
+    "@types/xml2js": "^0.4.11",
+    "ts-essentials": "^9.1.2",
+    "ts-node": "^10.7.0",
+    "tsconfig-paths": "^3.13.0",
+    "typescript": "^4.9.5",
+    "typescript-json-schema": "~0.55"
+  },
+  "overrides": {
+    "spotify-web-api-node": {
+      "superagent": "$superagent"
+    }
   }
 }

sources/AbstractSource.js

@@ -1,205 +0,0 @@
-import dayjs from "dayjs";
-import {buildTrackString, capitalize, createLabelledLogger, sleep} from "../utils.js";
-
-export default class AbstractSource {
-
-    name;
-    type;
-    identifier;
-
-    config;
-    clients;
-    logger;
-    instantiatedAt;
-    initialized = false;
-    requiresAuth = false;
-    requiresAuthInteraction = false;
-    authed = false;
-
-    canPoll = false;
-    polling = false;
-    pollRetries = 0;
-    tracksDiscovered = 0;
-
-    constructor(type, name, config = {}, clients = []) {
-        this.type = type;
-        this.name = name;
-        this.identifier = `Source - ${capitalize(this.type)} - ${name}`;
-        this.logger = createLabelledLogger(this.identifier, this.identifier);
-        this.config = config;
-        this.clients = clients;
-        this.instantiatedAt = dayjs();
-    }
-
-    // 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;
-    }
-
-    getRecentlyPlayed = async (options = {}) => {
-        return [];
-    }
-
-    // by default if the track was recently played it is valid
-    // this is useful for sources where the track doesn't have complete information like Subsonic
-    // TODO make this more descriptive? or move it elsewhere
-    recentlyPlayedTrackIsValid = (playObj) => {
-        return true;
-    }
-
-    poll = async (allClients) => {
-        await this.startPolling(allClients);
-    }
-
-    startPolling = async (allClients) => {
-        if(this.requiresAuthInteraction && !this.authed) {
-            this.logger.error('Cannot start polling because user interaction is required for authentication');
-            return;
-        }
-        // reset poll attempts if already previously run
-        this.pollRetries = 0;
-
-        const {
-            maxPollRetries = 0,
-            retryMultiplier = 1.5,
-        } = this.config;
-
-        // can't have negative retries!
-        const maxRetries = Math.max(0, maxPollRetries);
-
-        while (this.pollRetries <= maxRetries) {
-            try {
-                await this.doPolling(allClients);
-            } catch (e) {
-                if (this.pollRetries < maxRetries) {
-                    const delayFor = (this.pollRetries + 1) * retryMultiplier;
-                    this.logger.info(`Poll reties (${this.pollRetries}) less than max poll retries (${maxRetries}), restarting polling after ${delayFor} second delay...`);
-                    await sleep((delayFor) * 1000);
-                } else {
-                    this.logger.warn(`Poll retries (${this.pollRetries}) equal to max poll retries (${maxRetries}), stopping polling!`);
-                }
-                this.pollRetries++;
-            }
-        }
-    }
-
-    /**
-     * @param {ScrobbleClients} allClients
-     */
-    doPolling = async (allClients) => {
-        if (this.polling === true) {
-            return;
-        }
-        this.logger.info('Polling started');
-        let lastTrackPlayedAt = this.instantiatedAt;
-        let checkCount = 0;
-        let checksOverThreshold = 0;
-        try {
-            this.polling = true;
-            while (true) {
-                if(this.polling === false) {
-                    this.logger.info('Stopped polling due to user input');
-                    break;
-                }
-                let playObjs = [];
-                this.logger.debug('Refreshing recently played')
-                playObjs = await this.getRecentlyPlayed({formatted: true});
-                checkCount++;
-                let newTracksFound = false;
-                let closeToInterval = false;
-                const now = dayjs();
-
-                const playInfo = playObjs.reduce((acc, playObj) => {
-                    if(this.recentlyPlayedTrackIsValid(playObj)) {
-                        const {data: {playDate} = {}} = playObj;
-                        if (playDate.unix() > lastTrackPlayedAt.unix()) {
-                            newTracksFound = true;
-                            this.logger.info(`New Track => ${buildTrackString(playObj)}`);
-
-                            if (closeToInterval === false) {
-                                closeToInterval = Math.abs(now.unix() - playDate.unix()) < 5;
-                            }
-
-                            return {
-                                plays: [...acc.plays, {...playObj, meta: {...playObj.meta, newFromSource: true}}],
-                                lastTrackPlayedAt: playDate
-                            }
-                        }
-                        return {
-                            ...acc,
-                            plays: [...acc.plays, playObj]
-                        }
-                    }
-                    return acc;
-                }, {plays: [], lastTrackPlayedAt});
-                playObjs = playInfo.plays;
-                lastTrackPlayedAt = playInfo.lastTrackPlayedAt;
-
-                if (closeToInterval) {
-                    // because the interval check was so close to the play date we are going to delay client calls for a few secs
-                    // this way we don't accidentally scrobble ahead of any other clients (we always want to be behind so we can check for dups)
-                    // additionally -- it should be ok to have this in the for loop because played_at will only decrease (be further in the past) so we should only hit this once, hopefully
-                    this.logger.info('Track is close to polling interval! Delaying scrobble clients refresh by 10 seconds so other clients have time to scrobble first');
-                    await sleep(10 * 1000);
-                }
-
-                if (newTracksFound === false) {
-                    if (playObjs.length === 0) {
-                        this.logger.debug(`No new tracks found and no tracks returned from API`);
-                    } else {
-                        this.logger.debug(`No new tracks found. Newest track returned was ${buildTrackString(playObjs.slice(-1)[0])}`);
-                    }
-                } else {
-                    checkCount = 0;
-                    checksOverThreshold = 0;
-                }
-
-                let scrobbleResult = [];
-
-                if(playObjs.length > 0) {
-                    // use the source instantiation time or the last track play time to determine if we should refresh clients...
-                    // we only need to refresh clients when the source has "newer" information otherwise we're just refreshing clients for no reason
-                    scrobbleResult = await allClients.scrobble(playObjs, {
-                        checkTime: lastTrackPlayedAt.add(2, 's'),
-                        forceRefresh: closeToInterval,
-                        scrobbleFrom: this.identifier,
-                        scrobbleTo: this.clients
-                    });
-                }
-
-                if (scrobbleResult.length > 0) {
-                    checkCount = 0;
-                    this.tracksDiscovered += scrobbleResult.length;
-                }
-
-                const {interval = 30, checkActiveFor = 300, maxSleep = 300} = this.config;
-
-                let sleepTime = interval;
-                // don't need to do back off calc if interval is 5 minutes or greater since its already pretty light on API calls
-                // and don't want to back off if we just started the app
-                const activeThreshold = lastTrackPlayedAt.add(checkActiveFor, 's');
-                if (activeThreshold.isBefore(dayjs()) && sleepTime < 300) {
-                    checksOverThreshold++;
-                    const backoffMultiplier = Math.min(checksOverThreshold, 1000) * 1.5;
-                    sleepTime = Math.min(interval * backoffMultiplier, maxSleep);
-                }
-
-                // sleep for interval
-                this.logger.debug(`Sleeping for ${sleepTime}s`);
-                await sleep(sleepTime * 1000);
-
-            }
-        } catch (e) {
-            this.logger.error('Error occurred while polling');
-            this.logger.error(e);
-            this.polling = false;
-            throw e;
-        }
-    }
-}

sources/JellyfinSource.js

@@ -1,165 +0,0 @@
-import MemorySource from "./MemorySource.js";
-import dayjs from "dayjs";
-import {buildTrackString} from "../utils.js";
-
-
-export default class JellyfinSource extends MemorySource {
-    users;
-    servers;
-
-    constructor(name, config, clients, type = 'jellyfin') {
-        super(type, name, config, clients);
-        const {users, servers} = config
-
-        if (users === undefined || users === null) {
-            this.users = undefined;
-        } else {
-            if (!Array.isArray(users)) {
-                this.users = [users];
-            } else {
-                this.users = users;
-            }
-            this.users = this.users.map(x => x.toLocaleLowerCase())
-        }
-
-        if (servers === undefined || servers === null) {
-            this.servers = undefined;
-        } else {
-            if (!Array.isArray(servers)) {
-                this.servers = [servers];
-            } else {
-                this.servers = servers;
-            }
-            this.servers = this.servers.map(x => x.toLocaleLowerCase())
-        }
-
-        if (users === undefined && servers === undefined) {
-            this.logger.warn('Initializing, but with no filters! All tracks from all users on all servers will be scrobbled.');
-        } else {
-            this.logger.info(`Initializing with the following filters => Users: ${this.users === undefined ? 'N/A' : this.users.join(', ')} | Servers: ${this.servers === undefined ? 'N/A' : this.servers.join(', ')}`);
-        }
-        this.initialized = true;
-    }
-
-    static formatPlayObj(obj, newFromSource = false) {
-        const {
-            ServerId,
-            ServerName,
-            Username,
-            UserId,
-            NotificationType,
-            UtcTimestamp,
-            Album,
-            Artist,
-            Name,
-            RunTime,
-            ItemId,
-            ItemType,
-        } = obj;
-
-        const parsedRuntime = RunTime.split(':');
-        const dur = dayjs.duration({
-            hours: Number.parseInt(parsedRuntime[0]),
-            minutes: Number.parseInt(parsedRuntime[1]),
-            seconds: Number.parseInt(parsedRuntime[2])
-        });
-
-        return {
-            data: {
-                artists: [Artist],
-                album: Album,
-                track: Name,
-                duration: dur.as('seconds'),
-                playDate: dayjs(),
-            },
-            meta: {
-                event: NotificationType,
-                mediaType: ItemType,
-                sourceId: ItemId,
-                user: Username,
-                server: ServerName,
-                source: 'Jellyfin',
-                newFromSource,
-            }
-        }
-    }
-
-    isValidEvent = (playObj) => {
-        const {
-            meta: {
-                mediaType, event, user, server
-            },
-            data: {
-                artists,
-                track,
-            } = {}
-        } = playObj;
-
-        if (this.users !== undefined) {
-            if (user === undefined) {
-                this.logger.warn(`Config defined users but payload contained no user info${hint}`);
-            } else if (!this.users.includes(user.toLocaleLowerCase())) {
-                this.logger.debug(`Will not scrobble event because author was not an allowed user: ${user}`, {
-                    artists,
-                    track
-                })
-                return false;
-            }
-        }
-
-        if (event !== undefined && !['PlaybackProgress','PlaybackStarted'].includes(event)) {
-            this.logger.debug(`Will not scrobble event because it is not media.scrobble (${event})`, {
-                artists,
-                track
-            })
-            return false;
-        }
-
-        if (mediaType !== 'Audio') {
-            this.logger.debug(`Will not scrobble event because media type was not 'Audio' (${mediaType})`, {
-                artists,
-                track
-            });
-            return false;
-        }
-
-        if (this.servers !== undefined && !this.servers.includes(server.toLocaleLowerCase())) {
-            this.logger.debug(`Will not scrobble event because server was not on allowed list: ${server}`, {
-                artists,
-                track
-            })
-            return false;
-        }
-
-        return true;
-    }
-
-    getRecentlyPlayed = async (options = {}) => {
-        return this.statefulRecentlyPlayed;
-    }
-
-    handle = async (playObj, allClients) => {
-        if (!this.isValidEvent(playObj)) {
-            return;
-        }
-
-        const newPlays = this.processRecentPlays([playObj]);
-
-        for(const p of newPlays) {
-            this.logger.info(`New Track => ${buildTrackString(p)}`);
-        }
-
-        if(newPlays.length > 0) {
-            const recent = await this.getRecentlyPlayed();
-            const newestPlay = recent[recent.length - 1];
-            try {
-                await allClients.scrobble(newPlays, {scrobbleTo: this.clients, scrobbleFrom: this.identifier, checkTime: newestPlay.data.playDate});
-                // only gets hit if we scrobbled ok
-                this.tracksDiscovered++;
-            } catch (e) {
-                this.logger.error('Encountered error while scrobbling')
-                this.logger.error(e)
-            }
-        }
-    }
-}

sources/MemorySource.js

@@ -1,76 +0,0 @@
-import AbstractSource from "./AbstractSource.js";
-import {playObjDataMatch, sortByPlayDate, buildTrackString} from "../utils.js";
-import dayjs from "dayjs";
-
-export default class MemorySource extends AbstractSource {
-    /*
-    * MemorySource uses its own state to maintain a list of recently played tracks and determine if a track if valid.
-    * This is necessary for any source that
-    *  * doesn't have its own source of truth for "recently played" or
-    *  * that does not return "started at" and "duration" timestamps for recent plays or
-    *  * where these timestamps don't have enough granularity (IE second accuracy)
-    * such as subsonic and jellyfin */
-
-    statefulRecentlyPlayed = [];
-    candidateRecentlyPlayed = [];
-
-    processRecentPlays = (plays) => {
-
-        let newStatefulPlays = [];
-        // first format new plays with locked play date
-        const lockedPlays = plays.map((p) => {
-                    const {data: {playDate, ...restData}, ...rest} = p;
-                    return {data: {...restData, playDate: dayjs()}, ...rest};
-        })
-        // if no candidates exist new plays are new candidates
-        if(this.candidateRecentlyPlayed.length === 0) {
-            this.candidateRecentlyPlayed = lockedPlays;
-        } else {
-            // otherwise determine new tracks (not found in prior candidates)
-            const newTracks = lockedPlays.filter(x => this.candidateRecentlyPlayed.every(y => !playObjDataMatch(y, x)));
-            // filter prior candidates based on new recently played
-            this.candidateRecentlyPlayed = this.candidateRecentlyPlayed.filter(x => lockedPlays.some(y => playObjDataMatch(x, y)));
-            // and then combine still playing with new tracks
-            this.candidateRecentlyPlayed = this.candidateRecentlyPlayed.concat(newTracks);
-            this.candidateRecentlyPlayed.sort(sortByPlayDate);
-
-            for(const candidate of this.candidateRecentlyPlayed) {
-                const {data: {playDate, track}} = candidate;
-                if(playDate.isBefore(dayjs().subtract(30, 's'))) {
-                    // a prior candidate has been playing for more than 30 seconds, time to check statefuls
-
-                    const matchingRecent = this.statefulRecentlyPlayed.find(x => playObjDataMatch(x, candidate));
-                    let stPrefix = `(Stateful Play) ${buildTrackString(candidate, {include: ['artist', 'track']})}`;
-                    if(matchingRecent === undefined) {
-                        this.logger.debug(`${stPrefix} added after being seen for 30 seconds and not matching any prior plays`);
-                        newStatefulPlays.push(candidate);
-                        this.statefulRecentlyPlayed.push(candidate);
-                    } else {
-                        const {data: { playDate, duration }} = candidate;
-                        const {data: { playDate: rplayDate }} = matchingRecent;
-                        if(!playDate.isSame(rplayDate)) {
-                            if(duration !== undefined) {
-                                if(playDate.isAfter(rplayDate.add(duration, 's'))) {
-                                    this.logger.debug(`${stPrefix} added after being seen for 30 seconds and having a different timestamp than a prior play`);
-                                    newStatefulPlays.push(candidate);
-                                    this.statefulRecentlyPlayed.push(candidate);
-                                }
-                            } else if(!playObjDataMatch(this.statefulRecentlyPlayed[0], candidate)) {
-                                // if most recent stateful play is not this track we'll add it
-                                this.logger.debug(`${stPrefix} added after being seen for 30 seconds. Matched other recent play but could not determine time frame due to missing duration. Allowed due to not being last played track.`);
-                                newStatefulPlays.push(candidate);
-                                this.statefulRecentlyPlayed.push(candidate);
-                            }
-                        }
-                    }
-                }
-            }
-            this.statefulRecentlyPlayed.sort(sortByPlayDate);
-        }
-        return newStatefulPlays;
-    }
-
-    recentlyPlayedTrackIsValid = (playObj) => {
-        return playObj.data.playDate.isBefore(dayjs().subtract(30, 's'));
-    }
-}

sources/PlexSource.js

@@ -1,175 +0,0 @@
-import dayjs from "dayjs";import LastFm from "lastfm-node-client";
-import LastfmScrobbler from '../clients/LastfmScrobbler.js';
-import {buildTrackString} from "../utils.js";
-import AbstractSource from "./AbstractSource.js";
-
-export default class PlexSource extends AbstractSource {
-    users;
-    libraries;
-    servers;
-
-    constructor(name, config, clients, type = 'plex') {
-        super(type, name, config, clients);
-        const {user, libraries, servers} = config
-
-        if (user === undefined || user === null) {
-            this.users = undefined;
-        } else {
-            if (!Array.isArray(user)) {
-                this.users = [user];
-            } else {
-                this.users = user;
-            }
-            this.users = this.users.map(x => x.toLocaleLowerCase())
-        }
-
-        if (libraries === undefined || libraries === null) {
-            this.libraries = undefined;
-        } else {
-            if (!Array.isArray(libraries)) {
-                this.libraries = [libraries];
-            } else {
-                this.libraries = libraries;
-            }
-            this.libraries = this.libraries.map(x => x.toLocaleLowerCase())
-        }
-
-        if (servers === undefined || servers === null) {
-            this.servers = undefined;
-        } else {
-            if (!Array.isArray(servers)) {
-                this.servers = [servers];
-            } else {
-                this.servers = servers;
-            }
-            this.servers = this.servers.map(x => x.toLocaleLowerCase())
-        }
-
-        if (user === undefined && libraries === undefined && servers === undefined) {
-            this.logger.warn('Initializing, but with no filters! All tracks from all users on all servers and libraries will be scrobbled.');
-        } else {
-            this.logger.info(`Initializing with the following filters => Users: ${this.users === undefined ? 'N/A' : this.users.join(', ')} | Libraries: ${this.libraries === undefined ? 'N/A' : this.libraries.join(', ')} | Servers: ${this.servers === undefined ? 'N/A' : this.servers.join(', ')}`);
-        }
-        this.initialized = true;
-    }
-
-    static formatPlayObj(obj, newFromSource = false) {
-        const {
-            event,
-            Account: {
-                title: user,
-            } = {},
-            Metadata: {
-                type,
-                title: track,
-                parentTitle: album,
-                grandparentTitle: artist,
-                librarySectionTitle: library
-            } = {},
-            Server: {
-                title: server
-            } = {},
-        } = obj;
-        return {
-            data: {
-                artists: [artist],
-                album,
-                track,
-                playDate: dayjs(),
-            },
-            meta: {
-                event,
-                mediaType: type,
-                user,
-                library,
-                server,
-                source: 'Plex',
-                newFromSource,
-            }
-        }
-    }
-
-    isValidEvent = (playObj) => {
-        const {
-            meta: {
-                mediaType, event, user, library, server
-            },
-            data: {
-                artists,
-                track,
-            } = {}
-        } = playObj;
-
-        const hint = this.type === 'tautulli' ? ' (Check notification agent json data configuration)' : '';
-
-        if (this.users !== undefined) {
-            if (user === undefined) {
-                this.logger.warn(`Config defined users but payload contained no user info${hint}`);
-            } else if (!this.users.includes(user.toLocaleLowerCase())) {
-                this.logger.debug(`Will not scrobble event because author was not an allowed user: ${user}`, {
-                    artists,
-                    track
-                })
-                return false;
-            }
-        }
-
-        if (event !== undefined && event !== 'media.scrobble') {
-            this.logger.debug(`Will not scrobble event because it is not media.scrobble (${event})`, {
-                artists,
-                track
-            })
-            return false;
-        }
-
-        if (mediaType !== 'track') {
-            this.logger.debug(`Will not scrobble event because media type was not a track (${mediaType})`, {
-                artists,
-                track
-            });
-            return false;
-        }
-
-        if (this.libraries !== undefined) {
-            if (library === undefined) {
-                this.logger.warn(`Config defined libraries but payload contained no library info${hint}`);
-            } else if (!this.libraries.includes(library.toLocaleLowerCase())) {
-                this.logger.debug(`Will not scrobble event because library was not on allowed list: ${library}`, {
-                    artists,
-                    track
-                })
-                return false;
-            }
-        }
-
-        if (this.servers !== undefined) {
-            if (server === undefined) {
-                this.logger.warn(`Config defined server but payload contained no server info${hint}`);
-            } else if (!this.servers.includes(server.toLocaleLowerCase())) {
-                this.logger.debug(`Will not scrobble event because server was not on allowed list: ${server}`, {
-                    artists,
-                    track
-                })
-                return false;
-            }
-        }
-
-        return true;
-    }
-
-    handle = async (playObj, allClients) => {
-        if (!this.isValidEvent(playObj)) {
-            return;
-        }
-
-        this.logger.info(`New Track => ${buildTrackString(playObj)}`);
-        try {
-            await allClients.scrobble(playObj, {scrobbleTo: this.clients, scrobbleFrom: this.identifier});
-            // only gets hit if we scrobbled ok
-            this.tracksDiscovered++;
-        } catch (e) {
-            this.logger.error('Encountered error while scrobbling')
-            this.logger.error(e)
-        }
-    }
-}

sources/ScrobbleSources.js

@@ -1,343 +0,0 @@
-import {createLabelledLogger, isValidConfigStructure, readJson} from "../utils.js";
-import SpotifySource from "./SpotifySource.js";
-import PlexSource from "./PlexSource.js";
-import TautulliSource from "./TautulliSource.js";
-import {SubsonicSource} from "./SubsonicSource.js";
-import JellyfinSource from "./JellyfinSource.js";
-import LastfmSource from "./LastfmSource.js";
-import DeezerSource from "./DeezerSource.js";
-
-export default class ScrobbleSources {
-
-    sources = [];
-    logger;
-    configDir;
-    localUrl;
-
-    sourceTypes = ['spotify', 'plex', 'tautulli', 'subsonic', 'jellyfin', 'lastfm', 'deezer'];
-
-    constructor(localUrl, configDir = process.cwd()) {
-        this.configDir = configDir;
-        this.localUrl = localUrl;
-        this.logger = createLabelledLogger('sources', 'Sources');
-    }
-
-    getByName = (name) => {
-        return this.sources.find(x => x.name === name);
-    }
-
-    getByType = (type) => {
-        return this.sources.filter(x => x.type === type);
-    }
-
-    getByNameAndType = (name, type) => {
-        return this.sources.find(x => x.name === name && x.type === type);
-    }
-
-    buildSourcesFromConfig = async (additionalConfigs = []) => {
-        let configs = additionalConfigs;
-
-        let configFile;
-        try {
-            configFile = await readJson(`${this.configDir}/config.json`, {throwOnNotFound: false});
-        } catch (e) {
-            throw new Error('config.json could not be parsed');
-        }
-        let sourceDefaults = {};
-        if (configFile !== undefined) {
-            const {
-                sources: mainConfigSourcesConfigs = [],
-                sourceDefaults: sd = {},
-            } = configFile;
-            sourceDefaults = sd;
-            const validMainConfigs = mainConfigSourcesConfigs.reduce((acc, curr, i) => {
-                if(curr === null) {
-                    this.logger.error(`The source 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 source 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: 'source' // override user value
-                });
-            }
-        }
-
-        for (let sourceType of this.sourceTypes) {
-            let defaultConfigureAs = 'source';
-            // env builder for single user mode
-            switch (sourceType) {
-                case 'spotify':
-                    const s = {
-                        accessToken: process.env.SPOTIFY_ACCESS_TOKEN,
-                        clientId: process.env.SPOTIFY_CLIENT_ID,
-                        clientSecret: process.env.SPOTIFY_CLIENT_SECRET,
-                        redirectUri: process.env.SPOTIFY_REDIRECT_URI,
-                        refreshToken: process.env.SPOTIFY_REFRESH_TOKEN,
-                    };
-                    if (!Object.values(s).every(x => x === undefined)) {
-                        configs.push({
-                            type: 'spotify',
-                            name: 'unnamed',
-                            source: 'ENV',
-                            mode: 'single',
-                            data: s
-                        })
-                    }
-                    break;
-                case 'tautulli':
-                    const t = {
-                        // support this for now
-                        user: process.env.TAUTULLI_USER || process.env.PLEX_USER
-                    };
-                    if (!Object.values(t).every(x => x === undefined)) {
-                        configs.push({
-                            type: 'tautulli',
-                            name: 'unnamed',
-                            source: 'ENV',
-                            mode: 'single',
-                            data: t
-                        })
-                    }
-                    break;
-                case 'plex':
-                    const p = {
-                        user: process.env.PLEX_USER
-                    };
-                    if (!Object.values(p).every(x => x === undefined)) {
-                        configs.push({
-                            type: 'plex',
-                            name: 'unnamed',
-                            source: 'ENV',
-                            mode: 'single',
-                            data: p
-                        })
-                    }
-                    break;
-                case 'subsonic':
-                    const sub = {
-                        user: process.env.SUBSONIC_USER,
-                        password: process.env.SUBSONIC_PASSWORD,
-                        url: process.env.SUBSONIC_URL,
-                    };
-                    if (!Object.values(sub).every(x => x === undefined)) {
-                        configs.push({
-                            type: 'subsonic',
-                            name: 'unnamed',
-                            source: 'ENV',
-                            mode: 'single',
-                            data: sub
-                        })
-                    }
-                    break;
-                case 'jellyfin':
-                    const j = {
-                        user: process.env.JELLYFIN_USER,
-                        server: process.env.JELLYFIN_SERVER,
-                    };
-                    if (!Object.values(j).every(x => x === undefined)) {
-                        configs.push({
-                            type: 'jellyfin',
-                            name: 'unnamed',
-                            source: 'ENV',
-                            mode: 'single',
-                            data: j
-                        })
-                    }
-                    break;
-                case 'lastfm':
-                    // sane default for lastfm is that user want to scrobble TO it, not FROM it -- this is also existing behavior
-                    defaultConfigureAs = 'client';
-                    break;
-                case 'deezer':
-                    const d = {
-                        clientId: process.env.DEEZER_APP_ID,
-                        clientSecret: process.env.DEEZER_SECRET_KEY,
-                        redirectUri: process.env.DEEZER_REDIRECT_URI,
-                        accessToken: process.env.DEEZER_ACCESS_TOKEN,
-                    };
-                    break;
-                default:
-                    break;
-            }
-            let rawSourceConfigs;
-            try {
-                rawSourceConfigs = await readJson(`${this.configDir}/${sourceType}.json`, {throwOnNotFound: false});
-            } catch (e) {
-                this.logger.error(`${sourceType}.json config file could not be parsed`);
-                continue;
-            }
-            if (rawSourceConfigs !== undefined) {
-                let sourceConfigs = [];
-                if (Array.isArray(rawSourceConfigs)) {
-                    sourceConfigs = rawSourceConfigs;
-                } else if (rawSourceConfigs === null) {
-                    this.logger.error(`${sourceType}.json contained no data`);
-                    continue;
-                } else if (typeof rawSourceConfigs === 'object') {
-                    // backwards compatibility, assuming its single-user mode
-                    this.logger.warn(`DEPRECATED: Starting in 0.4 configurations in all [type].json files (${sourceType}.json) must be in an array.`);
-                    if (rawSourceConfigs.data === undefined) {
-                        sourceConfigs = [{data: rawSourceConfigs, mode: 'single', name: 'unnamed'}];
-                    } else {
-                        sourceConfigs = [rawSourceConfigs];
-                    }
-                } else {
-                    this.logger.error(`All top level data from ${sourceType}.json must be an array of objects, will not parse configs from file`);
-                    continue;
-                }
-                for (const [i,m] of sourceConfigs.entries()) {
-                    if(m === null) {
-                        this.logger.error(`The config entry at index ${i} from ${sourceType}.json is null`);
-                        continue;
-                    }
-                    if (typeof m !== 'object') {
-                        this.logger.error(`The config entry at index ${i} from ${sourceType}.json was not an object, skipping`, m);
-                        continue;
-                    }
-                    const {configureAs = defaultConfigureAs} = m;
-                    if(configureAs === 'source') {
-                        m.source = `${sourceType}.json`;
-                        m.type = sourceType;
-                        configs.push(m);
-                    }
-                }
-            }
-        }
-
-        // we have all possible 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(`Source 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);
-        }, []);
-
-        // finally! all configs are valid, structurally, and can now be passed to addClient
-        // do a last check that names (within each type) are unique and warn if not, but add anyways
-        const typeGroupedConfigs = validConfigs.reduce((acc, curr) => {
-            const {type} = curr;
-            const {[type]: t = []} = acc;
-            return {...acc, [type]: [...t, curr]};
-        }, {});
-        // only need to warn if dup names PER TYPE
-        for (const [type, typedConfigs] of Object.entries(typeGroupedConfigs)) {
-            const nameGroupedConfigs = typedConfigs.reduce((acc, curr) => {
-                const {name = 'unnamed'} = curr;
-                const {[name]: n = []} = acc;
-                return {...acc, [name]: [...n, curr]};
-            }, {});
-            for (const [name, namedConfigs] of Object.entries(nameGroupedConfigs)) {
-                let tempNamedConfigs = namedConfigs;
-                const hasDups = namedConfigs.length > 1;
-                if (hasDups) {
-                    const sources = namedConfigs.map(c => `Config object from ${c.source} of type [${c.type}]`);
-                    this.logger.warn(`Source configs have naming conflicts -- the following configs have the same name "${name}":\n\n${sources.join('\n')}\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');
-                    }
-                }
-                tempNamedConfigs = tempNamedConfigs.map(({name = 'unnamed', ...x}, i) => ({
-                    ...x,
-                    name: hasDups ? `${name}${i + 1}` : name
-                }));
-                for (const c of tempNamedConfigs) {
-                    try {
-                        await this.addSource(c, sourceDefaults);
-                    } catch(e) {
-                        this.logger.error(`Source ${c.name} of type ${c.type} was not added because of unrecoverable errors`);
-                        this.logger.error(e);
-                    }
-                }
-            }
-        }
-    }
-
-    addSource = 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, clients = [], data: d = {}} = clientConfig;
-        // add defaults
-        const data = {...defaults, ...d};
-        this.logger.debug(`(${name}) Constructing ${type} source`);
-        let newSource;
-        switch (type) {
-            case 'spotify':
-                newSource = new SpotifySource(name, {
-                    ...data,
-                    localUrl: this.localUrl,
-                    configDir: this.configDir
-                }, clients);
-                break;
-            case 'plex':
-                newSource = await new PlexSource(name, data, clients);
-                break;
-            case 'tautulli':
-                newSource = await new TautulliSource(name, data, clients);
-                break;
-            case 'subsonic':
-                newSource = new SubsonicSource(name, data, clients);
-                break;
-            case 'jellyfin':
-                newSource = await new JellyfinSource(name, data, clients);
-                break;
-            case 'lastfm':
-                newSource = await new LastfmSource(name, {...data, configDir: this.configDir}, clients);
-                break;
-            case 'deezer':
-                newSource = await new DeezerSource(name, {
-                    ...data,
-                    localUrl: this.localUrl,
-                    configDir: this.configDir
-                }, clients);
-                break;
-            default:
-                break;
-        }
-
-        if(newSource === undefined) {
-            // really shouldn't get here!
-            throw new Error(`Source of type ${type} was not recognized??`);
-        }
-        if(newSource.initialized === false) {
-            this.logger.debug(`(${name}) Attempting ${type} initialization...`);
-            if (await newSource.initialize() === false) {
-                this.logger.error(`(${name}) ${type} source failed to initialize. Source needs to be successfully initialized before activity capture can begin.`);
-                return;
-            } else {
-                this.logger.info(`(${name}) ${type} source initialized`);
-            }
-        } else {
-            this.logger.info(`(${name}) ${type} source initialized`);
-        }
-
-        if(newSource.requiresAuth && !newSource.authed) {
-            this.logger.debug(`(${name}) Checking ${type} source auth...`);
-            let success;
-            try {
-                success = await newSource.testAuth();
-            } catch (e) {
-                success = false;
-            }
-            if(!success) {
-                this.logger.warn(`(${name}) ${type} source auth failed.`);
-            } else {
-                this.logger.info(`(${name}) ${type} source auth OK`);
-            }
-        }
-
-        this.sources.push(newSource);
-    }
-}

sources/SpotifySource.js

@@ -1,254 +0,0 @@
-import dayjs from "dayjs";
-import {
-    readJson,
-    writeFile,
-    sortByPlayDate, sleep, parseRetryAfterSecsFromObj,
-} from "../utils.js";
-import SpotifyWebApi from "spotify-web-api-node";
-import AbstractSource from "./AbstractSource.js";
-
-const scopes = ['user-read-recently-played', 'user-read-currently-playing'];
-const state = 'random';
-
-export default class SpotifySource extends AbstractSource {
-
-    spotifyApi;
-    localUrl;
-    workingCredsPath;
-    configDir;
-
-    requiresAuth = true;
-    requiresAuthInteraction = true;
-
-    constructor(name, config = {}, clients = []) {
-        super('spotify', name, config, clients);
-        const {
-            localUrl,
-            configDir,
-            interval = 60,
-        } = config;
-
-        if (interval < 15) {
-            this.logger.warn('Interval should be above 30 seconds...😬');
-        }
-
-        this.config.interval = interval;
-
-        this.configDir = configDir;
-        this.workingCredsPath = `${configDir}/currentCreds-${name}.json`;
-        this.localUrl = localUrl;
-        this.canPoll = true;
-    }
-
-    static formatPlayObj(obj, newFromSource = false) {
-        const {
-            track: {
-                artists = [],
-                name,
-                id,
-                duration_ms,
-                album: {
-                    name: albumName,
-                } = {},
-                external_urls: {
-                    spotify,
-                } = {}
-            } = {},
-            played_at
-        } = obj;
-        //let artistString = artists.reduce((acc, curr) => acc.concat(curr.name), []).join(',');
-        return {
-            data: {
-                artists: artists.map(x => x.name),
-                album: albumName,
-                track: name,
-                duration: duration_ms / 1000,
-                playDate: dayjs(played_at),
-            },
-            meta: {
-                trackLength: duration_ms / 1000,
-                source: 'Spotify',
-                sourceId: id,
-                newFromSource,
-                url: {
-                    web: spotify
-                }
-            }
-        }
-    }
-
-    buildSpotifyApi = async () => {
-
-        let spotifyCreds = {};
-        try {
-            spotifyCreds = await readJson(this.workingCredsPath, {throwOnNotFound: false});
-        } catch (e) {
-            this.logger.warn('Current spotify credentials file exists but could not be parsed', { path: this.workingCredsPath });
-        }
-
-        const {
-            accessToken,
-            clientId,
-            clientSecret,
-            redirectUri,
-            refreshToken,
-        } = this.config || {};
-
-        const rdUri = redirectUri || `${this.localUrl}/callback`;
-
-
-        const {token = accessToken, refreshToken: rt = refreshToken} = spotifyCreds || {};
-
-        const apiConfig = {
-            clientId,
-            clientSecret,
-            accessToken: token,
-            refreshToken: rt,
-        }
-
-        if (Object.values(apiConfig).every(x => x === undefined)) {
-            this.logger.info('No values found for Spotify configuration, skipping initialization');
-            return;
-        }
-        apiConfig.redirectUri = rdUri;
-
-        const validationErrors = [];
-
-        if (token === undefined) {
-            if (clientId === undefined) {
-                validationErrors.push('clientId must be defined when access token is not present');
-            }
-            if (clientSecret === undefined) {
-                validationErrors.push('clientSecret must be defined when access token is not present');
-            }
-            if (rdUri === undefined) {
-                validationErrors.push('redirectUri must be defined when access token is not present');
-            }
-            if (validationErrors.length !== 0) {
-                validationErrors.unshift('no access token is defined');
-            }
-        } else if (rt === undefined && (
-            clientId === undefined ||
-            clientSecret === undefined ||
-            rdUri === undefined
-        )) {
-            this.logger.warn('Access token is present but no refresh token is defined and remaining configuration is not sufficient to re-authorize. Without a refresh token API calls will fail after current token is expired.');
-        }
-
-        if (validationErrors.length !== 0) {
-            this.logger.warn(`Configuration was not valid:\*${validationErrors.join('\n')}`);
-            throw new Error('Failed to initialize a Spotify source');
-        }
-
-        this.spotifyApi = new SpotifyWebApi(apiConfig);
-    }
-
-    initialize = async () => {
-        if(this.spotifyApi === undefined) {
-            await this.buildSpotifyApi();
-        }
-        this.initialized = true;
-        return this.initialized;
-    }
-
-    testAuth = async () => {
-        try {
-            await this.callApi((api => api.getMe()));
-            this.authed = true;
-        } catch (e) {
-            this.logger.error('Could not successfully communicate with Spotify API');
-            this.authed = false;
-        }
-        return this.authed;
-    }
-
-    createAuthUrl = () => {
-        return this.spotifyApi.createAuthorizeURL(scopes, this.name);
-    }
-
-    handleAuthCodeCallback = async ({error, code}) => {
-        if (error === undefined) {
-            const tokenResponse = await this.spotifyApi.authorizationCodeGrant(code);
-            this.spotifyApi.setAccessToken(tokenResponse.body['access_token']);
-            this.spotifyApi.setRefreshToken(tokenResponse.body['refresh_token']);
-            await writeFile(this.workingCredsPath, JSON.stringify({
-                token: tokenResponse.body['access_token'],
-                refreshToken: tokenResponse.body['refresh_token']
-            }));
-            this.logger.info('Got token from code grant authorization!');
-            return true;
-        } else {
-            this.logger.warn('Callback contained an error! User may have denied access?')
-            this.logger.error(error);
-            return error;
-        }
-    }
-
-    getRecentlyPlayed = async (options = {}) => {
-        const {limit = 20, formatted = false} = options;
-        const func = api => api.getMyRecentlyPlayedTracks({
-            limit
-        });
-        const result = await this.callApi(func);
-        if (formatted === true) {
-            return result.body.items.map(x => SpotifySource.formatPlayObj(x)).sort(sortByPlayDate);
-        }
-        return result;
-    }
-
-    callApi = async (func, retries = 0) => {
-        const {
-            maxRequestRetries = 1,
-            retryMultiplier = 2,
-        } = this.config;
-        try {
-            return await func(this.spotifyApi);
-        } catch (e) {
-            if (e.statusCode === 401) {
-                if (this.spotifyApi.getRefreshToken() === undefined) {
-                    throw new Error('Access token was not valid and no refresh token was present')
-                }
-                this.logger.debug('Access token was not valid, attempting to refresh');
-
-                const tokenResponse = await this.spotifyApi.refreshAccessToken();
-                const {
-                    body: {
-                        access_token,
-                        // spotify may return a new refresh token
-                        // if it doesn't then continue to use the last refresh token we received
-                        refresh_token = this.spotifyApi.getRefreshToken(),
-                    } = {}
-                } = tokenResponse;
-                this.spotifyApi.setAccessToken(access_token);
-                await writeFile(this.workingCredsPath, JSON.stringify({
-                    token: access_token,
-                    refreshToken: refresh_token,
-                }));
-                try {
-                    return await func(this.spotifyApi);
-                } catch (ee) {
-                    this.logger.error('Refreshing access token encountered an error');
-                    this.logger.error(ee, {label: 'Spotify'});
-                    throw ee;
-                }
-            } else if(maxRequestRetries > retries) {
-                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 this.callApi(func, retries + 1);
-            } else {
-                this.logger.error(`Request failed on retry (${retries}) with no more retries permitted (max ${maxRequestRetries})`);
-                this.logger.error(e, {label: 'Spotify'});
-                throw e;
-            }
-        }
-    }
-
-    poll = async (allClients) => {
-        if (this.spotifyApi === undefined) {
-            this.logger.warn('Cannot poll spotify without valid credentials configuration')
-            return;
-        }
-        await this.startPolling(allClients);
-    }
-}

sources/TautulliSource.js

@@ -1,47 +0,0 @@
-import dayjs from "dayjs";
-import PlexSource from "./PlexSource.js";
-
-export default class TautulliSource extends PlexSource {
-
-    constructor(name, config, clients) {
-        super(name, config, clients, 'tautulli');
-    }
-
-    static formatPlayObj(obj, newFromSource = false) {
-        const {
-            artist_name,
-            track_name,
-            track_artist,
-            album_name,
-            media_type,
-            title,
-            library_name,
-            server,
-            duration,
-            username,
-        } = obj;
-        let artists = [artist_name];
-        if (track_artist !== undefined && track_artist !== artist_name) {
-            artists.push(track_artist);
-        }
-        return {
-            data: {
-                artists,
-                album: album_name,
-                track: track_name,
-                duration,
-                playDate: dayjs(),
-            },
-            meta: {
-                title,
-                library: library_name,
-                server,
-                mediaType: media_type,
-                user: username,
-                trackLength: duration,
-                source: 'Tautulli',
-                newFromSource,
-            }
-        }
-    }
-}

src/apis/AbstractApiClient.ts

@@ -0,0 +1,31 @@
+import {capitalize, mergeArr} from "../utils.js";
+import {Logger} from '@foxxmd/winston';
+import {FormatPlayObjectOptions, PlayObject} from "../common/infrastructure/Atomic.js";
+import winston from '@foxxmd/winston';
+
+export default abstract class AbstractApiClient {
+    name: string;
+    type: string;
+    initialized: boolean = false;
+
+    config: object;
+    options: object;
+    logger: Logger;
+
+    client: any;
+    workingCredsPath?: string;
+    redirectUri?: string;
+
+    constructor(type: any, name: any, config = {}, options = {}) {
+        this.type = type;
+        this.name = name;
+        const identifier = `API - ${capitalize(this.type)} - ${name}`;
+        this.logger = winston.loggers.get('app').child({labels: [identifier]}, mergeArr);
+        this.config = config;
+        this.options = options;
+    }
+
+    static formatPlayObj = (obj: any, options: FormatPlayObjectOptions): PlayObject => {
+        throw new Error('should be overridden');
+    }
+}

src/apis/JRiverApiClient.ts

@@ -0,0 +1,167 @@
+import AbstractApiClient from "./AbstractApiClient.js";
+import {JRiverData} from "../common/infrastructure/config/source/jriver.js";
+import request, {Request, Response} from 'superagent';
+import xml2js from 'xml2js';
+import {ErrorWithCause} from "pony-cause";
+
+const parser = new xml2js.Parser({'async': true});
+
+export const PLAYER_STATE: Record<string, PLAYER_STATE> = {
+    STOPPED: '0',
+    PAUSED: '1',
+    PLAYING: '2'
+}
+
+export type PLAYER_STATE = '0' | '1' | '2';
+
+interface JRiverResponseItem {
+    _: string
+    $: {
+        Name: string
+    }
+}
+
+interface JRiverResponse {
+    Response: {
+        '$': {
+            Status: string
+        },
+        Item: JRiverResponseItem[]
+    }
+}
+
+export interface JRiverTransformedResponse<T> {
+    status: string
+    data?: T
+}
+
+export interface Alive {
+    RuntimeGUID: string
+    LibraryVersion: string
+    ProgramName: string
+    ProgramVersion: string
+    FriendlyName: string
+    AccessKey: string
+    ProductVersion: string
+    Platform: string
+}
+// state 0 = nothing?
+// 2 = playing
+// 1 = paused
+
+export interface Authenticate {
+    Token: string
+    ReadOnly: number
+    PreLicensed: boolean
+}
+
+export interface Info {
+    ZoneID: string
+    ZoneName: string
+    State: PLAYER_STATE
+    PositionMS: number
+    DurationMS: number
+    Artist: string
+    Album: string
+    Name: string
+    Status: string
+    FileKey: string
+}
+
+export interface Zones {
+    NumberZones: number
+    CurrentZoneID: string
+    CurrentZoneIndex: string
+}
+
+const jriverResponseTransform = <T>(val: JRiverResponse): JRiverTransformedResponse<T> => {
+    const status = val.Response.$.Status;
+    const items = val.Response.Item === undefined ? undefined : val.Response.Item.map(x => {
+        return [x.$.Name, x._];
+    });
+    return {
+        status,
+        data: items.reduce((acc, curr) => {
+            acc[curr[0]] = curr[1];
+            return acc;
+        }, {}) as T
+    };
+}
+
+export class JRiverApiClient extends AbstractApiClient {
+
+    declare config: JRiverData
+
+    url: string;
+
+    token?: string;
+
+    constructor(name: any, config: JRiverData, options = {}) {
+        super('JRiver', name, config, options);
+        const {
+            url = 'http://localhost:52199/MCWS/v1/'
+        } = config;
+        this.url = url;
+    }
+
+    callApi = async <T>(req: Request, retries = 0): Promise<Response & {body: T}> => {
+        const {
+            maxRequestRetries = 2,
+            retryMultiplier = 1.5
+        } = this.config;
+
+        if (this.token !== undefined) {
+            req.query({token: this.token});
+        }
+
+        try {
+            const resp = await req as Response;
+            if (resp.text !== '') {
+                const rawBody = await parser.parseStringPromise(resp.text);
+                resp.body = <T>jriverResponseTransform(rawBody);
+            }
+            return resp;
+        } catch (e) {
+            throw e;
+        }
+    }
+
+    testConnection = async () => {
+        try {
+            const resp = await this.callApi<Alive>(request.get(`${this.url}Alive`));
+            const {body: { data } = {}} = resp;
+            this.logger.verbose(`Found ${data.ProgramName} ${data.ProgramVersion} (${data.FriendlyName})`);
+            return true;
+        } catch (e) {
+            this.logger.error(new ErrorWithCause('Could not communicate with JRiver server. Verify your server URL is correct.', {cause: e}));
+            return false;
+        }
+    }
+
+    testAuth = async () => {
+        try {
+            let req = request.get(`${this.url}Authenticate`);
+            if (this.config.username !== undefined) {
+                req.auth(this.config.username, this.config.password);
+            }
+            const resp = await this.callApi<Authenticate>(req);
+            this.token = resp.body.data.Token;
+            return true;
+        } catch (e) {
+            let msg = 'Authentication failed.';
+            if(this.config.username === undefined || this.config.password === undefined) {
+                msg = 'Authentication failed. No username/password was provided in config! Did you mean to do this?';
+            }
+            this.logger.error(new ErrorWithCause(msg, {cause: e}));
+            return false;
+        }
+    }
+
+    getInfo = async (zoneId: string = '-1') => {
+        return await this.callApi<Info>(request.get(`${this.url}Playback/Info`).query({Zone: zoneId}));
+    }
+
+    getZones = async () => {
+        return await this.callApi<Zones>(request.get(`${this.url}Playback/Zones`));
+    }
+}

src/apis/KodiApiClient.ts

@@ -0,0 +1,187 @@
+import AbstractApiClient from "./AbstractApiClient.js";
+import {ErrorWithCause} from "pony-cause";
+import {KodiData} from "../common/infrastructure/config/source/kodi.js";
+import { KodiClient } from 'kodi-api'
+import normalizeUrl from "normalize-url";
+import {URL} from "url";
+import {RecentlyPlayedOptions} from "../sources/AbstractSource.js";
+import {FormatPlayObjectOptions, PlayObject} from "../common/infrastructure/Atomic.js";
+import dayjs from "dayjs";
+
+interface KodiDuration {
+    hours: number
+    milliseconds: number
+    minutes: number
+    seconds: number
+}
+interface ActivePlayer {
+    playerid: number
+    playertype: string
+    type: string
+}
+
+interface PlayerInfo {
+    position: -1 | 0
+    time: KodiDuration
+    totaltime: KodiDuration
+    type: string
+}
+
+interface PlayerItem {
+    album: string
+    albumartist: string[]
+    artist: string[]
+    duration: number
+    id: number
+    label: string
+    title: string
+    type: string
+}
+
+export class KodiApiClient extends AbstractApiClient {
+
+    declare config: KodiData
+
+    url: URL;
+
+    token?: string;
+
+    client: KodiClient;
+
+    constructor(name: any, config: KodiData, options = {}) {
+        super('Kodi', name, config, options);
+        const {
+            url = 'http://localhost:8080/jsonrpc'
+        } = config;
+        this.url = KodiApiClient.parseConnectionUrl('http://localhost:8080');
+        const auth = new Buffer(`${config.username}:${config.password}`).toString('base64');
+        this.client = new KodiClient({
+            clientType: this.url.protocol.replace(':', '') as ('http' | 'https'),
+            //parameterMode: 'object',
+            clientOptions: {
+                host: this.url.hostname,
+                port: this.url.port,
+                path: this.url.pathname,
+                headers: {
+                    Authorization: `Basic ${auth}`
+                },
+            }
+        });
+    }
+
+    static parseConnectionUrl(val: string) {
+        const normal = normalizeUrl(val, {removeTrailingSlash: true, normalizeProtocol: true})
+        const url = new URL(normal);
+
+        if (url.port === null || url.port === '') {
+            url.port = '8080';
+        }
+        if (url.pathname === '/') {
+            url.pathname = '/jsonrpc';
+        } else if (url.pathname === '/jsonrpc/') {
+            url.pathname = '/jsonrpc';
+        }
+        return url;
+    }
+
+    static formatPlayObj(obj: (PlayerItem & Partial<PlayerInfo> & { playerid?: number }), options: FormatPlayObjectOptions = {}): PlayObject {
+        const {newFromSource = true} = options;
+
+        const {
+            album: albumVal,
+            albumartist,
+            artist: artistVal,
+            duration,
+            id,
+            title,
+            time,
+            playerid,
+        } = obj;
+
+        let artists = artistVal === null || artistVal === undefined ? [] : artistVal;
+        let album = albumVal === null || albumVal === '' ? undefined : albumVal;
+        const trackProgressPosition = time !== undefined ? Math.round(dayjs.duration(time).asSeconds()) : undefined;
+
+        return {
+            data: {
+                track: title,
+                album: album,
+                artists,
+                duration,
+                playDate: dayjs()
+            },
+            meta: {
+                source: 'kodi',
+                trackId: id.toString(),
+                newFromSource,
+                trackProgressPosition,
+                deviceId: playerid !== undefined ? `Player${playerid}` : undefined,
+            }
+        }
+    }
+
+    testConnection = async () => {
+        return true;
+    }
+
+    testAuth = async () => {
+        try {
+
+            await this.client.connect();
+            // https://kodi.wiki/view/JSON-RPC_API/v12#JSONRPC.Version
+            const jsonInfo = await this.client.JSONRPC.Version();
+
+            // https://kodi.wiki/view/JSON-RPC_API/v12#Application.GetProperties
+            const applicationInfo = await this.client.Application.GetProperties(['version']);
+
+            this.logger.info(`Found Kodi v${applicationInfo.version.major}.${applicationInfo.version.minor} (JSONRPC v${jsonInfo.version.major}.${jsonInfo.version.minor})`);
+            return true;
+        } catch (e) {
+            let msg = 'Authentication failed.';
+            if(this.config.username === undefined || this.config.password === undefined) {
+                msg = 'Authentication failed. No username/password was provided in config! Did you mean to do this?';
+            }
+            this.logger.error(new ErrorWithCause(msg, {cause: e}));
+            return false;
+        }
+    }
+
+    getPlayerInfo = async (id: number): Promise<PlayerInfo> => {
+        // https://kodi.wiki/view/JSON-RPC_API/v12#Player.GetProperties
+        // @ts-ignore
+        const playerInfo = await this.client.Player.GetProperties(0, ["position","type","time","totaltime"])
+        return playerInfo;
+    }
+
+    getPlayerItem = async (id: number): Promise<{item: PlayerItem}> => {
+        // https://kodi.wiki/view/JSON-RPC_API/v12#Player.GetItem
+        // @ts-ignore
+        const itemInfo = await this.client.Player.GetItem(0, ["title","artist","album","albumartist","starttime","endtime","duration","streamdetails","uniqueid"]);
+        return itemInfo as {item: PlayerItem};
+    }
+
+    getActivePlayers = async (): Promise<ActivePlayer[]> => {
+        // https://kodi.wiki/view/JSON-RPC_API/v12#Player.GetActivePlayers
+        const players = await this.client.Player.GetActivePlayers();
+        return players as ActivePlayer[];
+    }
+
+    getRecentlyPlayed = async (options: RecentlyPlayedOptions = {}): Promise<PlayObject[]> => {
+        const active = await this.getActivePlayers();
+        if(active.length === 0) {
+            return [];
+        }
+        // get first active playing audio
+        const audioActive = active.find(x => x.type === 'audio');
+        if(audioActive === undefined) {
+            return [];
+        }
+        const playerInfo = await this.getPlayerInfo(audioActive.playerid);
+
+        const itemInfo = await this.getPlayerItem(audioActive.playerid);
+
+        const play = KodiApiClient.formatPlayObj({...itemInfo.item, ...playerInfo, ...audioActive});
+
+        return [play];
+    }
+}

src/apis/LastfmApiClient.ts

@@ -1,7 +1,9 @@
-import LastFm from "lastfm-node-client";
+import LastFm, {AuthGetSessionResponse, TrackObject, UserGetInfoResponse} from "lastfm-node-client";
 import AbstractApiClient from "./AbstractApiClient.js";
 import dayjs from "dayjs";
 import {readJson, sleep, writeFile} from "../utils.js";
+import {FormatPlayObjectOptions, PlayObject} from "../common/infrastructure/Atomic.js";
+import {LastfmData} from "../common/infrastructure/config/client/lastfm.js";
 
 const badErrors = [
     'api key suspended',
@@ -19,9 +21,10 @@ const retryErrors = [
 
 export default class LastfmApiClient extends AbstractApiClient {
 
-    user;
+    user?: string;
+    declare config: LastfmData;
 
-    constructor(name, config = {}, options = {}) {
+    constructor(name: any, config: Partial<LastfmData> & {configDir: string}, options = {}) {
         super('lastfm', name, config, options);
         const {redirectUri, apiKey, secret, session, configDir} = config;
         this.redirectUri = `${redirectUri}?state=${name}`;
@@ -29,13 +32,12 @@ export default class LastfmApiClient extends AbstractApiClient {
             this.logger.warn("'apiKey' not found in config!");
         }
         this.workingCredsPath = `${configDir}/currentCreds-lastfm-${name}.json`;
-        this.client = new LastFm(apiKey, secret, session);
+        this.client = new LastFm(apiKey as string, secret, session);
     }
 
-    static formatPlayObj = obj => {
+    static formatPlayObj = (obj: TrackObject, options: FormatPlayObjectOptions = {}): PlayObject => {
         const {
             artist: {
-                // last.fm doesn't seem consistent with which of these properties it returns...
                 '#text': artists,
                 name: artistName,
             },
@@ -45,6 +47,7 @@ export default class LastfmApiClient extends AbstractApiClient {
             },
             duration,
             date: {
+                // @ts-ignore
                 uts: time,
             } = {},
             '@attr': {
@@ -57,7 +60,7 @@ export default class LastfmApiClient extends AbstractApiClient {
         let artistStrings = artists !== undefined ? artists.split(',') : [artistName];
         return {
             data: {
-                artists: [...new Set(artistStrings)],
+                artists: [...new Set(artistStrings)] as string[],
                 track: title,
                 album,
                 duration,
@@ -74,22 +77,22 @@ export default class LastfmApiClient extends AbstractApiClient {
         }
     }
 
-    callApi = async (func, retries = 0) => {
+    callApi = async <T>(func: any, retries = 0): Promise<T> => {
         const {
             maxRequestRetries = 2,
             retryMultiplier = 1.5
         } = this.config;
 
         try {
-            return await func(this.client);
+            return await func(this.client) as T;
         } 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) {
+            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);
@@ -109,8 +112,8 @@ export default class LastfmApiClient extends AbstractApiClient {
         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});
+    authenticate = async (token: any) => {
+        const sessionRes: AuthGetSessionResponse = await this.client.authGetSession({token});
         const {
             session: {
                 key: sessionKey,
@@ -145,7 +148,7 @@ export default class LastfmApiClient extends AbstractApiClient {
             return false;
         }
         try {
-            const infoResp = await this.callApi(client => client.userGetInfo());
+            const infoResp = await this.callApi<UserGetInfoResponse>((client: any) => client.userGetInfo());
             const {
                 user: {
                     name,

src/apis/ListenbrainzApiClient.ts

@@ -0,0 +1,271 @@
+import AbstractApiClient from "./AbstractApiClient.js";
+import request, {Request} from 'superagent';
+import {ListenBrainzClientData} from "../common/infrastructure/config/client/listenbrainz.js";
+import {FormatPlayObjectOptions, PlayObject} from "../common/infrastructure/Atomic.js";
+import dayjs from "dayjs";
+
+
+export interface ArtistMBIDMapping {
+    artist_credit_name: string
+    artist_mbid: string
+    join_phrase: string
+}
+
+export interface MinimumTrack {
+    artist_name: string;
+    track_name: string;
+    release_name?: string;
+}
+
+export interface AdditionalTrackInfo {
+    artist_mbids?: string[]
+    release_mbid?: string
+    release_group_mbid?: string
+    recording_mbid?: string
+    submission_client?: string
+    submission_client_version?: string
+    spotify_id?: string
+    media_player?: string
+    media_player_version?: string
+
+    music_service?: string
+    music_service_name?: string
+    origin_url?: string
+    tags?: string[]
+    duration?: number
+
+    duration_ms?: number
+    track_mbid?: string
+    work_mbids?: string[]
+}
+
+export interface Track {
+    artist_name: string;
+    track_name: string;
+    release_name?: string;
+    artist_mbids?: string[];
+    artist_msid?: string;
+    recording_mbid?: string;
+    release_mbid?: string;
+    release_msid?: string;
+    tags?: string[];
+
+    duration?: number
+}
+
+export interface AdditionalTrackInfoResponse extends AdditionalTrackInfo {
+    recording_msid?: string
+}
+
+export interface TrackPayload extends MinimumTrack {
+    additional_info?: AdditionalTrackInfo
+}
+
+export interface ListenPayload {
+    listened_at: Date | number;
+    recording_msid?: string;
+    track_metadata: TrackPayload;
+}
+
+export interface SubmitPayload {
+    listen_type: 'single',
+    payload: [ListenPayload]
+}
+
+export interface TrackResponse extends MinimumTrack {
+    duration: number
+    additional_info: AdditionalTrackInfoResponse
+    mbid_mapping: {
+        artist_mbids?: string[]
+        artists?: ArtistMBIDMapping[]
+        caa_id?: number
+        caa_release_mbid?: string
+        recording_mbid?: string
+        release_mbid?: string
+    }
+}
+
+export interface ListensResponse {
+    count: number;
+    listens: ListenResponse[];
+}
+
+export interface ListenResponse {
+
+    inserted_at: number
+    listened_at: number;
+    recording_msid?: string;
+    track_metadata: TrackResponse;
+}
+
+export class ListenbrainzApiClient extends AbstractApiClient {
+
+    declare config: ListenBrainzClientData;
+    url: string;
+
+    constructor(name: any, config: ListenBrainzClientData, options = {}) {
+        super('ListenBrainz', name, config, options);
+        const {
+            url = 'https://api.listenbrainz.org/'
+        } = config;
+        this.url = url;
+    }
+
+
+    callApi = async <T>(req: Request, retries = 0): Promise<T> => {
+        const {
+            maxRequestRetries = 2,
+            retryMultiplier = 1.5
+        } = this.config;
+
+        try {
+            req.set('Authorization', `Token ${this.config.token}`);
+            return await req as T;
+        } catch (e) {
+            const {
+                message,
+            } = e;
+            throw e;
+        }
+    }
+
+    testConnection = async () => {
+        try {
+            const resp = await this.callApi(request.get(this.url))
+            return true;
+        } catch (e) {
+            if(e.status === 410) {
+                return true;
+            }
+            return false;
+        }
+    }
+
+    testAuth = async () => {
+        try {
+            const resp = await this.callApi(request.get(`${this.url}1/validate-token`));
+            return true;
+        } catch (e) {
+            return false;
+        }
+    }
+
+    getUserListens = async (maxTracks: number, user?: string): Promise<ListensResponse> => {
+        try {
+
+            const resp = await this.callApi(request
+                .get(`${this.url}1/user/${user ?? this.config.username}/listens`)
+                // this endpoint can take forever, sometimes, and we want to make sure we timeout in a reasonable amount of time for polling sources to continue trying to scrobble
+                .timeout({
+                    response: 15000, // wait 15 seconds before timeout if server doesn't response at all
+                    deadline: 30000 // wait 30 seconds overall for request to complete
+                })
+                .query({
+                    count: maxTracks
+                }));
+            const {body: {payload}} = resp as any;
+            return payload as ListensResponse;
+        } catch (e) {
+            throw e;
+        }
+    }
+
+    getRecentlyPlayed = async (maxTracks: number, user?: string): Promise<PlayObject[]> => {
+        try {
+            const resp = await this.getUserListens(maxTracks, user);
+            return resp.listens.map(x => ListenbrainzApiClient.listenResponseToPlay(x));
+        } catch (e) {
+            this.logger.error(`Error encountered while getting User listens | Error =>  ${e.message}`);
+            return [];
+        }
+    }
+
+    submitListen = async (play: PlayObject) => {
+        try {
+            const listenPayload: SubmitPayload = {listen_type: 'single', payload: [ListenbrainzApiClient.playToListenPayload(play)]};
+            await this.callApi(request.post(`${this.url}1/submit-listens`).type('json').send(listenPayload));
+            return listenPayload;
+        } catch (e) {
+            throw e;
+        }
+    }
+
+    static playToListenPayload = (play: PlayObject): ListenPayload => {
+        const {
+            data: {
+                meta: {
+                    brainz = {}
+                } = {}
+            }
+        } = play;
+        return {
+            listened_at: (play.data.playDate ?? dayjs()).unix(),
+            track_metadata: {
+                artist_name: play.data.artists[0],
+                track_name: play.data.track,
+                additional_info: {
+                    duration: play.data.duration !== undefined ? Math.round(play.data.duration) : undefined,
+                    track_mbid: brainz.track,
+                    artist_mbids: brainz.artist !== undefined ? [brainz.artist] : undefined,
+                    release_mbid: brainz.album,
+                    release_group_mbid: brainz.releaseGroup
+                }
+            }
+        }
+    }
+
+    static listenResponseToPlay = (listen: ListenResponse): PlayObject => {
+        const {
+            listened_at,
+            recording_msid,
+            track_metadata: {
+                track_name,
+                artist_name,
+                release_name,
+                duration,
+                additional_info: {
+                    recording_msid: aRecordingMsid,
+                    recording_mbid: aRecordingMbid,
+                    duration: aDuration,
+                    duration_ms: aDurationMs,
+                } = {},
+                mbid_mapping: {
+                    artists: artistMappings = [],
+                    recording_mbid: mRecordingMbid
+                } = {}
+            } = {}
+        } = listen;
+
+        const playId = recording_msid ?? aRecordingMsid;
+        const trackId = aRecordingMbid ?? mRecordingMbid;
+        let dur = duration ?? aDuration;
+        if (dur === undefined && aDurationMs !== undefined) {
+            dur = Math.round(aDurationMs / 1000);
+        }
+
+        let artists: string[] = [artist_name];
+        if (artistMappings.length > 0) {
+            const secondaryArtists = artistMappings.filter(x => x.artist_credit_name !== artist_name);
+            artists = artists.concat(secondaryArtists.map(x => x.artist_credit_name));
+        }
+
+        return {
+            data: {
+                playDate: dayjs.unix(listened_at),
+                track: track_name,
+                artists: artists,
+                album: release_name,
+                duration: dur
+            },
+            meta: {
+                source: 'listenbrainz',
+                trackId,
+                playId
+            }
+        }
+    }
+
+    static formatPlayObj = (obj: any, options: FormatPlayObjectOptions): PlayObject => {
+        return ListenbrainzApiClient.listenResponseToPlay(obj);
+    }
+}

src/clients/AbstractScrobbleClient.ts

@@ -0,0 +1,368 @@
+import dayjs, {Dayjs} from "dayjs";
+import {
+    buildTrackString,
+    capitalize, closePlayDate,
+    mergeArr,
+    playObjDataMatch, setIntersection,
+    truncateStringToLength
+} from "../utils.js";
+import {
+    ClientType, FormatPlayObjectOptions,
+    INITIALIZED,
+    INITIALIZING,
+    InitState,
+    NOT_INITIALIZED,
+    PlayObject, ScrobbledPlayObject, TrackStringOptions
+} from "../common/infrastructure/Atomic.js";
+import winston, {Logger} from '@foxxmd/winston';
+import {CommonClientConfig} from "../common/infrastructure/config/client/index.js";
+import {ClientConfig} from "../common/infrastructure/config/client/clients.js";
+import {Notifiers} from "../notifier/Notifiers.js";
+import {FixedSizeList} from 'fixed-size-list';
+
+export default abstract class AbstractScrobbleClient {
+
+    name: string;
+    type: ClientType;
+
+    #initState: InitState = NOT_INITIALIZED;
+
+    protected MAX_STORED_SCROBBLES = 40;
+
+    requiresAuth: boolean = false;
+    requiresAuthInteraction: boolean = false;
+    authed: boolean = false;
+
+    recentScrobbles: PlayObject[] = [];
+    scrobbledPlayObjs: FixedSizeList<ScrobbledPlayObject>;
+    newestScrobbleTime?: Dayjs
+    oldestScrobbleTime?: Dayjs
+    tracksScrobbled: number = 0;
+
+    lastScrobbleCheck: Dayjs = dayjs(0)
+    refreshEnabled: boolean;
+    checkExistingScrobbles: boolean;
+    verboseOptions;
+
+    config: CommonClientConfig;
+    logger: Logger;
+
+    notifier: Notifiers;
+
+    constructor(type: any, name: any, config: CommonClientConfig, notifier: Notifiers, logger: Logger) {
+        this.type = type;
+        this.name = name;
+        const identifier = `${capitalize(this.type)} - ${name}`;
+        this.logger = logger.child({labels: [identifier]}, mergeArr);
+        this.notifier = notifier;
+
+        this.scrobbledPlayObjs = new FixedSizeList<ScrobbledPlayObject>(this.MAX_STORED_SCROBBLES);
+
+        const {
+            data: {
+                options: {
+                    refreshEnabled = true,
+                    checkExistingScrobbles = true,
+                    verbose = {},
+                } = {},
+            },
+        } = config;
+        this.config = config;
+        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
+            }
+        };
+    }
+
+    get initialized() {
+        return this.#initState === INITIALIZED;
+    }
+
+   set initialized(val) {
+        // @ts-expect-error TS(2367): This condition will always return 'false' since th... Remove this comment to see the full error message
+        if(val === INITIALIZING) {
+            this.#initState = INITIALIZING;
+        // @ts-expect-error TS(2367): This condition will always return 'false' since th... Remove this comment to see the full error message
+        } else if(val === true || val === INITIALIZED) {
+            this.#initState = INITIALIZED;
+        } else {
+            this.#initState = NOT_INITIALIZED;
+        }
+   }
+
+   get initializing() {
+        return this.#initState === INITIALIZING;
+   }
+
+    // default init function, should be overridden if init stage is required
+    initialize = async () => {
+        this.initialized = true;
+        return true;
+    }
+
+    // default init function, should be overridden if auth stage is required
+    testAuth = async () => {
+        return this.authed;
+    }
+
+    isReady = async () => {
+        return this.initialized && (!this.requiresAuth || (this.requiresAuth && this.authed));
+    }
+
+    refreshScrobbles = async () => {
+        this.logger.debug('Scrobbler does not have refresh function implemented!');
+    }
+
+    alreadyScrobbled = async (playObj: PlayObject, log = false) => {
+        this.logger.debug('Scrobbler does not have alreadyScrobbled check implemented!');
+        return false;
+    }
+
+    scrobblesLastCheckedAt = () => {
+        return this.lastScrobbleCheck;
+    }
+
+    formatPlayObj = (obj: any, options: FormatPlayObjectOptions = {}) => {
+        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: PlayObject) => {
+
+        if(this.oldestScrobbleTime === undefined) {
+            return [true, ''];
+        }
+
+        const {
+            data: {
+                playDate,
+            } = {},
+        } = playObj;
+        const validTime = playDate.isAfter(this.oldestScrobbleTime);
+        let log = '';
+        if (!validTime) {
+            const dur = dayjs.duration(Math.abs(playDate.diff(this.oldestScrobbleTime))).humanize(false);
+            log = `occurred ${dur} before the oldest scrobble returned by this client (${this.oldestScrobbleTime.format()})`;
+        }
+        return [validTime, log]
+    }
+
+    addScrobbledTrack = (playObj: PlayObject, scrobbledPlay: PlayObject) => {
+        this.scrobbledPlayObjs.add({play: playObj, scrobble: scrobbledPlay});
+    }
+
+    filterScrobbledTracks = () => {
+        this.scrobbledPlayObjs = new FixedSizeList<ScrobbledPlayObject>(this.MAX_STORED_SCROBBLES, this.scrobbledPlayObjs.data.filter(x => this.timeFrameIsValid(x.play)[0])) ;
+    }
+
+    cleanSourceSearchTitle = (playObj: PlayObject) => {
+        const {
+            data: {
+                track,
+            } = {},
+        } = playObj;
+
+        return track.toLocaleLowerCase().trim();
+    };
+
+    findExistingSubmittedPlayObj = (playObj: PlayObject): ([undefined, undefined] | [ScrobbledPlayObject, ScrobbledPlayObject[]]) => {
+        const {
+            data: {
+                playDate
+            } = {},
+            meta: {
+                source,
+            } = {}
+        } = playObj;
+
+        const dtInvariantMatches = this.scrobbledPlayObjs.data.filter(x => playObjDataMatch(playObj, x.play));
+
+        if (dtInvariantMatches.length === 0) {
+            return [undefined, undefined];
+        }
+
+        const matchPlayDate = dtInvariantMatches.find((x: ScrobbledPlayObject) => {
+            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];
+    }
+
+    protected compareExistingScrobbleTime = (existing: PlayObject, candidate: PlayObject): [boolean, boolean?] => {
+        let closeTime = closePlayDate(existing, candidate);
+        let fuzzyTime = false;
+        if(!closeTime) {
+            fuzzyTime = closePlayDate(existing, candidate, {fuzzyDuration: true});
+        }
+        return [closeTime, fuzzyTime];
+    }
+    protected compareExistingScrobbleTitle = (existing: PlayObject, candidate: PlayObject): number => {
+
+        const {
+            data: {
+                track: scrobbleTitle,
+            } = {},
+        } = existing;
+
+        let cleanSourceTitle = this.cleanSourceSearchTitle(candidate);
+
+        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: any) => x !== ''));
+        const commonTerms = setIntersection(new Set(lowerScrobbleTitle.split(' ')), sourceTitleTerms);
+
+        titleMatch = commonTerms.size / sourceTitleTerms.size;
+        return titleMatch;
+    }
+
+    protected compareExistingScrobbleArtist = (existing: PlayObject, candidate: PlayObject): number => {
+        const {
+            data: {
+                artists: sourceArtists = [],
+            } = {},
+        } = candidate;
+        const {
+            data: {
+                artists = [],
+            } = {},
+        } = candidate;
+        let artistMatch;
+        const lowerSourceArtists = sourceArtists.map((x: any) => x.toLocaleLowerCase());
+        const lowerScrobbleArtists = artists.map(x => x.toLocaleLowerCase());
+        artistMatch = setIntersection(new Set(lowerScrobbleArtists), new Set(lowerSourceArtists)).size / artists.length;
+
+        return artistMatch;
+    }
+
+    existingScrobble = async (playObj: PlayObject) => {
+        const tr = truncateStringToLength(27);
+        const scoreTrackOpts: TrackStringOptions = {include: ['track', 'time'], transformers: {track: (t: any) => 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: number, breakdowns: string[], scrobble?: PlayObject} = {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 (existingScrobble === undefined) {
+
+            // 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;
+            }
+
+            // 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;
+
+            // 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 [closeTime, fuzzyTime = false] = this.compareExistingScrobbleTime(x, playObj);
+
+                const titleMatch = this.compareExistingScrobbleTitle(x, playObj);
+
+                const artistMatch = this.compareExistingScrobbleArtist(x, playObj);
+
+                const artistScore = .2 * artistMatch;
+                const titleScore = .3 * titleMatch;
+                const timeScore = .5 * (closeTime ? 1 : (fuzzyTime ? 0.5 : 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;
+    }
+}

src/clients/LastfmScrobbler.ts

@@ -0,0 +1,206 @@
+import AbstractScrobbleClient from "./AbstractScrobbleClient.js";
+import dayjs from 'dayjs';
+
+import {
+    buildTrackString, capitalize,
+    playObjDataMatch, removeUndefinedKeys,
+    setIntersection, sleep,
+    sortByOldestPlayDate,
+    truncateStringToLength,
+} from "../utils.js";
+import LastfmApiClient from "../apis/LastfmApiClient.js";
+import {
+    FormatPlayObjectOptions,
+    INITIALIZING,
+    PlayObject, ScrobbledPlayObject,
+    TrackStringOptions
+} from "../common/infrastructure/Atomic.js";
+import {LastfmClientConfig} from "../common/infrastructure/config/client/lastfm.js";
+import {TrackScrobbleResponse, UserGetRecentTracksResponse} from "lastfm-node-client";
+import {Notifiers} from "../notifier/Notifiers.js";
+import {Logger} from '@foxxmd/winston';
+
+export default class LastfmScrobbler extends AbstractScrobbleClient {
+
+    api: LastfmApiClient;
+    requiresAuth = true;
+    requiresAuthInteraction = true;
+
+    declare config: LastfmClientConfig;
+
+    constructor(name: any, config: LastfmClientConfig, options = {}, notifier: Notifiers, logger: Logger) {
+        super('lastfm', name, config, notifier, logger);
+        // @ts-ignore
+        this.api = new LastfmApiClient(name, config.data, options)
+    }
+
+    formatPlayObj = (obj: any, options: FormatPlayObjectOptions = {}) => LastfmApiClient.formatPlayObj(obj, options);
+
+    initialize = async () => {
+        // @ts-expect-error TS(2322): Type 'number' is not assignable to type 'boolean'.
+        this.initialized = INITIALIZING;
+        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<UserGetRecentTracksResponse>((client: any) => client.userGetRecentTracks({user: this.api.user, limit: this.MAX_STORED_SCROBBLES, extended: true}));
+            const {
+                recenttracks: {
+                    track: list = [],
+                }
+            } = resp;
+            this.recentScrobbles = list.reduce((acc: any, x: any) => {
+                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(sortByOldestPlayDate);
+            this.logger.debug(`Found ${this.recentScrobbles.length} recent scrobbles`);
+            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.filterScrobbledTracks();
+            }
+        }
+        this.lastScrobbleCheck = dayjs();
+    }
+
+    cleanSourceSearchTitle = (playObj: PlayObject) => {
+        const {
+            data: {
+                track,
+            } = {},
+        } = playObj;
+        return track.toLocaleLowerCase().trim();
+    }
+
+    alreadyScrobbled = async (playObj: PlayObject, log = false) => {
+        return await this.existingScrobble(playObj) !== undefined;
+    }
+
+    scrobble = async (playObj: PlayObject) => {
+        const {
+            data: {
+                artists,
+                album,
+                track,
+                duration,
+                playDate
+            } = {},
+            data = {},
+            meta: {
+                source,
+                newFromSource = false,
+            } = {}
+        } = playObj;
+
+        const sType = newFromSource ? 'New' : 'Backlog';
+
+        const rawPayload = {
+            artist: artists.join(', '),
+            duration,
+            track,
+            album,
+            timestamp: playDate.unix(),
+        };
+        // 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
+        const scrobblePayload = removeUndefinedKeys(rawPayload);
+
+        try {
+            const response = await this.api.callApi<TrackScrobbleResponse>((client: any) => client.trackScrobble(
+                scrobblePayload));
+            const {
+                scrobbles: {
+                    '@attr': {
+                        accepted = 0,
+                        ignored = 0,
+                        code = undefined,
+                    } = {},
+                    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, this.formatPlayObj({...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) {
+                await this.notifier.notify({title: `Client - ${capitalize(this.type)} - ${this.name} - Scrobble Error`, message: `Failed to scrobble => ${buildTrackString(playObj)} | Error: Service ignored this scrobble 😬 => (Code ${ignoreCode}) ${(ignoreMsg === '' ? '(No error message returned)' : ignoreMsg)}`, priority: 'warn'});
+                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`, {payload: scrobblePayload});
+            }
+
+            // 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) {
+            await this.notifier.notify({title: `Client - ${capitalize(this.type)} - ${this.name} - Scrobble Error`, message: `Failed to scrobble => ${buildTrackString(playObj)} | Error: ${e.message}`, priority: 'error'});
+            this.logger.error(`Scrobble Error (${sType})`, {playInfo: buildTrackString(playObj), payload: scrobblePayload});
+            throw e;
+        } finally {
+            this.logger.debug('Raw Payload: ', rawPayload);
+        }
+
+        return true;
+    }
+}

src/clients/ListenbrainzScrobbler.ts

@@ -0,0 +1,130 @@
+import dayjs from 'dayjs';
+
+import AbstractScrobbleClient from "./AbstractScrobbleClient.js";
+import {
+    buildTrackString, capitalize,
+    playObjDataMatch, removeUndefinedKeys,
+    setIntersection, sleep,
+    sortByOldestPlayDate,
+    truncateStringToLength,
+} from "../utils.js";
+import LastfmApiClient from "../apis/LastfmApiClient.js";
+import {
+    FormatPlayObjectOptions,
+    INITIALIZING,
+    PlayObject,
+    TrackStringOptions
+} from "../common/infrastructure/Atomic.js";
+import {Notifiers} from "../notifier/Notifiers.js";
+import {Logger} from '@foxxmd/winston';
+import {ListenBrainzClientConfig} from "../common/infrastructure/config/client/listenbrainz.js";
+import {ListenbrainzApiClient} from "../apis/ListenbrainzApiClient.js";
+
+export default class ListenbrainzScrobbler extends AbstractScrobbleClient {
+
+    api: ListenbrainzApiClient;
+    requiresAuth = true;
+    requiresAuthInteraction = false;
+
+    declare config: ListenBrainzClientConfig;
+
+    constructor(name: any, config: ListenBrainzClientConfig, options = {}, notifier: Notifiers, logger: Logger) {
+        super('listenbrainz', name, config, notifier, logger);
+        this.api = new ListenbrainzApiClient(name, config.data);
+    }
+
+    formatPlayObj = (obj: any, options: FormatPlayObjectOptions = {}) => ListenbrainzApiClient.formatPlayObj(obj, options);
+
+    initialize = async () => {
+        // @ts-expect-error TS(2322): Type 'number' is not assignable to type 'boolean'.
+        this.initialized = INITIALIZING;
+        if(this.config.data.token === undefined) {
+            this.logger.error('Must provide a User Token');
+            this.initialized = false;
+        } else {
+            try {
+                await this.api.testConnection();
+                this.initialized = true;
+            } catch (e) {
+                this.logger.error(e);
+                this.initialized = false;
+            }
+        }
+        return this.initialized;
+    }
+
+    testAuth = async () => {
+
+        try {
+            this.authed = await this.api.testAuth();
+        } catch (e) {
+            this.logger.error('Could not successfully communicate with Listenbrainz 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.getRecentlyPlayed(this.MAX_STORED_SCROBBLES);
+            this.logger.debug(`Found ${resp.length} recent scrobbles`);
+            this.recentScrobbles = resp.sort(sortByOldestPlayDate);
+            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.filterScrobbledTracks();
+            }
+        }
+        this.lastScrobbleCheck = dayjs();
+    }
+
+    alreadyScrobbled = async (playObj: PlayObject, log = false) => {
+        return await this.existingScrobble(playObj) !== undefined;
+    }
+
+    scrobble = async (playObj: PlayObject) => {
+        const {
+            meta: {
+                source,
+                newFromSource = false,
+            } = {}
+        } = playObj;
+
+        let rawPayload = {listen_type: 'single', payload: [ListenbrainzApiClient.playToListenPayload(playObj)]};
+
+        try {
+            const resp = await this.api.submitListen(playObj);
+            rawPayload = resp;
+            this.addScrobbledTrack(playObj, playObj);
+            if (newFromSource) {
+                this.logger.info(`Scrobbled (New)     => (${source}) ${buildTrackString(playObj)}`);
+            } else {
+                this.logger.info(`Scrobbled (Backlog) => (${source}) ${buildTrackString(playObj)}`);
+            }
+
+            // 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) {
+            let message = e.message;
+            if(e.response !== undefined) {
+                if(e.response.body !== undefined) {
+                    message = e.response.body.messsage;
+                } else if(e.response.text !== undefined) {
+                    message = e.response.text;
+                }
+            }
+            await this.notifier.notify({title: `Client - ${capitalize(this.type)} - ${this.name} - Scrobble Error`, message: `Failed to scrobble => ${buildTrackString(playObj)} | Error: ${message}`, priority: 'error'});
+            this.logger.error(`Failed to scrobble => ${message}`, {payload: rawPayload});
+            throw e;
+        } finally {
+            this.logger.debug(`Raw Payload:`, {rawPayload});
+        }
+
+        return true;
+    }
+}

src/clients/MalojaScrobbler.ts

@@ -0,0 +1,455 @@
+import AbstractScrobbleClient from "./AbstractScrobbleClient.js";
+import request from 'superagent';
+import dayjs from 'dayjs';
+import compareVersions from 'compare-versions';
+import {
+    buildTrackString,
+    playObjDataMatch,
+    setIntersection,
+    sleep,
+    sortByOldestPlayDate,
+    truncateStringToLength,
+    parseRetryAfterSecsFromObj, capitalize, closePlayDate
+} from "../utils.js";
+import {
+    FormatPlayObjectOptions,
+    INITIALIZING,
+    MalojaScrobbleData,
+    MalojaScrobbleRequestData,
+    MalojaScrobbleV2RequestData,
+    MalojaScrobbleV3RequestData,
+    MalojaV2ScrobbleData,
+    MalojaV3ScrobbleData,
+    PlayObject,
+    TrackStringOptions
+} from "../common/infrastructure/Atomic.js";
+import {MalojaClientConfig} from "../common/infrastructure/config/client/maloja.js";
+import {Notifiers} from "../notifier/Notifiers.js";
+import {Logger} from '@foxxmd/winston';
+
+const feat = ["ft.", "ft", "feat.", "feat", "featuring", "Ft.", "Ft", "Feat.", "Feat", "Featuring"];
+
+export default class MalojaScrobbler extends AbstractScrobbleClient {
+
+    requiresAuth = true;
+    serverIsHealthy = false;
+    serverVersion: any;
+
+    declare config: MalojaClientConfig
+
+    constructor(name: any, config: MalojaClientConfig, notifier: Notifiers, logger: Logger) {
+        super('maloja', name, config, notifier, logger);
+        const {url, apiKey} = config.data;
+        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: MalojaScrobbleData, options: FormatPlayObjectOptions = {}): PlayObject {
+        let artists,
+            title,
+            album,
+            duration,
+            time;
+
+        const {serverVersion} = options;
+
+        if(serverVersion === undefined || compareVersions(serverVersion, '3.0.0') >= 0) {
+            // scrobble data structure changed for v3
+            const {
+                // when the track was scrobbled
+                time: mTime,
+                track: {
+                    artists: mArtists,
+                    title: mTitle,
+                    album: {
+                        name: mAlbum,
+                        artists: albumArtists
+                    } = {},
+                    // length of the track
+                    length: mLength,
+                } = {},
+                // how long the track was listened to before it was scrobbled
+                duration: mDuration,
+            } = obj as MalojaV3ScrobbleData;
+            artists = mArtists;
+            time = mTime;
+            title = mTitle;
+            duration = mLength;
+            album = mAlbum;
+        } else {
+            // scrobble data structure for v2 and below
+            const {
+                artists: mArtists,
+                title: mTitle,
+                album: mAlbum,
+                duration: mDuration,
+                time: mTime,
+            } = obj as MalojaV2ScrobbleData;
+            artists = mArtists;
+            title = mTitle;
+            album = mAlbum;
+            duration = mDuration;
+            time = mTime;
+        }
+        let artistStrings = artists.reduce((acc: any, curr: any) => {
+            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)] as string[],
+                track: title,
+                album,
+                duration,
+                playDate: dayjs.unix(time),
+            },
+            meta: {
+                source: 'Maloja',
+            }
+        }
+    }
+
+    formatPlayObj = (obj: any, options: FormatPlayObjectOptions = {}) => MalojaScrobbler.formatPlayObj(obj, {serverVersion: this.serverVersion});
+
+    callApi = async (req: any, retries = 0) => {
+        const {
+            maxRequestRetries = 1,
+            retryMultiplier = 1.5
+        } = this.config.data;
+
+        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: {
+                    // @ts-expect-error TS(2525): Initializer provides no value for this binding ele... Remove this comment to see the full error message
+                    status,
+                    // @ts-expect-error TS(2525): Initializer provides no value for this binding ele... Remove this comment to see the full error message
+                    body,
+                    // @ts-expect-error TS(2525): Initializer provides no value for this binding ele... Remove this comment to see the full error message
+                    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.data;
+        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(`Communication test not OK! HTTP Status => Expected: 200 | Received: ${statusCode}`);
+                return false;
+            }
+
+            this.logger.info('Communication test 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. multi-scrobbler will most likely not work with this server.');
+            } else {
+                this.logger.info(`Maloja Server Version: ${versionstring}`);
+                this.serverVersion = versionstring;
+                if(compareVersions(versionstring, '2.7.0') < 0) {
+                    this.logger.warn('Maloja Server Version is less than 2.7, please upgrade to ensure compatibility');
+                }
+            }
+            return true;
+        } catch (e) {
+            this.logger.error('Communication test failed');
+            this.logger.error(e);
+            return false;
+        }
+    }
+
+    testHealth = async () => {
+
+        const {url} = this.config.data;
+        try {
+            const serverInfoResp = await this.callApi(request.get(`${url}/apis/mlj_1/serverinfo`), 0);
+            const {
+                statusCode,
+                body: {
+                    // @ts-expect-error TS(2525): Initializer provides no value for this binding ele... Remove this comment to see the full error message
+                    db_status: {
+                        healthy = false,
+                        rebuildinprogress = false,
+                        complete = false,
+                    }
+                } = {},
+            } = serverInfoResp;
+
+            if (statusCode >= 300) {
+                return [false, `Server responded with NOT OK status: ${statusCode}`];
+            }
+
+            if(rebuildinprogress) {
+                return [false, 'Server is rebuilding database'];
+            }
+
+            if(!healthy) {
+                return [false, 'Server responded that it is not healthy'];
+            }
+
+            return [true];
+        } catch (e) {
+            this.logger.error('Unexpected error encountered while testing server health');
+            this.logger.error(e);
+            throw e;
+        }
+    }
+
+    initialize = async () => {
+        // just checking that we can get a connection
+        // @ts-expect-error TS(2322): Type 'number' is not assignable to type 'boolean'.
+        this.initialized = INITIALIZING;
+        this.initialized = await this.testConnection();
+        return this.initialized;
+    }
+
+    testAuth = async () => {
+
+        const {url, apiKey} = this.config.data;
+        try {
+            const resp = await this.callApi(request
+                .get(`${url}/apis/mlj_1/test`)
+                .query({key: apiKey}));
+
+            const {
+                status,
+                body: {
+                    // @ts-expect-error TS(2525): Initializer provides no value for this binding ele... Remove this comment to see the full error message
+                    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) {
+            if(e.status === 403) {
+                // may be an older version that doesn't support auth readiness before db upgrade
+                // and if it was before api was accessible during db build then test would fail during testConnection()
+                if(compareVersions(this.serverVersion, '2.12.19') < 0) {
+                    if(!(await this.isReady())) {
+                        this.logger.error(`Could not test auth because server is not ready`);
+                        this.authed = false;
+                        return this.authed;
+                    }
+                }
+            }
+            this.logger.error('Auth test failed');
+            this.logger.error(e);
+            this.authed = false;
+        }
+        return this.authed;
+    }
+
+    isReady = async () => {
+        if (this.serverIsHealthy) {
+            return true;
+        }
+
+        try {
+            const [isHealthy, status] = await this.testHealth();
+            if (!isHealthy) {
+                this.logger.error(`Server is not ready: ${status}`);
+                this.serverIsHealthy = false;
+            } else {
+                this.logger.info('Server reported database is built and status is healthy');
+                this.serverIsHealthy = true;
+            }
+        } catch (e) {
+            this.logger.error(`Testing server health failed due to an unexpected error`);
+            this.serverIsHealthy = false;
+        }
+        return this.serverIsHealthy
+    }
+
+    refreshScrobbles = async () => {
+        if (this.refreshEnabled) {
+            this.logger.debug('Refreshing recent scrobbles');
+            const {url} = this.config.data;
+            const resp = await this.callApi(request.get(`${url}/apis/mlj_1/scrobbles?max=${this.MAX_STORED_SCROBBLES}`));
+            const {
+                body: {
+                    list = [],
+                } = {},
+            } = resp;
+            this.logger.debug(`Found ${list.length} recent scrobbles`);
+            this.recentScrobbles = list.map((x: any) => this.formatPlayObj(x)).sort(sortByOldestPlayDate);
+            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.filterScrobbledTracks();
+            }
+        }
+        this.lastScrobbleCheck = dayjs();
+    }
+
+    cleanSourceSearchTitle = (playObj: PlayObject) => {
+        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: any) => x.toLocaleLowerCase());
+        lowerTitle = lowerArtists.reduce((acc: any, curr: any) => acc.replace(curr, ''), lowerTitle);
+
+        // remove any whitespace in parenthesis
+        lowerTitle = lowerTitle.replace("\\s+(?=[^()]*\\))", '')
+            // replace parenthesis
+            .replace('()', '')
+            .replace('( )', '')
+            .trim();
+
+        return lowerTitle;
+    }
+
+    alreadyScrobbled = async (playObj: any, log = false) => {
+        return await this.existingScrobble(playObj) !== undefined;
+    }
+
+    scrobble = async (playObj: PlayObject) => {
+        const {url, apiKey} = this.config.data;
+
+        const {
+            data: {
+                artists,
+                album,
+                track,
+                duration,
+                playDate
+            } = {},
+            meta: {
+                source,
+                newFromSource = false,
+            } = {}
+        } = playObj;
+
+        const sType = newFromSource ? 'New' : 'Backlog';
+
+        const scrobbleData: MalojaScrobbleRequestData = {
+            title: track,
+            album,
+            key: apiKey,
+            time: playDate.unix(),
+            // https://github.com/FoxxMD/multi-scrobbler/issues/42#issuecomment-1100184135
+            length: duration,
+        };
+
+        try {
+            // 3.0.3 has a BC for something (maybe seconds => length ?) -- see #42 in repo
+            if(this.serverVersion === undefined || compareVersions(this.serverVersion, '3.0.2') > 0) {
+                (scrobbleData as MalojaScrobbleV3RequestData).artists = artists;
+            } else {
+                // maloja seems to detect this deliminator much better than commas
+                // also less likely artist has a forward slash in their name than a comma
+                (scrobbleData as MalojaScrobbleV2RequestData).artist = artists.join(' / ');
+            }
+
+            const response = await this.callApi(request.post(`${url}/apis/mlj_1/newscrobble`)
+                .type('json')
+                .send(scrobbleData));
+
+            let scrobbleResponse = {};
+
+            if(this.serverVersion === undefined || compareVersions(this.serverVersion, '3.0.0') >= 0) {
+                const {
+                    body: {
+                    // @ts-expect-error TS(2525): Initializer provides no value for this binding ele... Remove this comment to see the full error message
+                    track,
+                } = {}
+                } = response;
+                scrobbleResponse = {
+                    time: playDate.unix(),
+                    track: {
+                        ...track,
+                        length: duration
+                    },
+                }
+                if(album !== undefined) {
+                    const {
+                        album: malojaAlbum = {},
+                    } = track;
+                    // @ts-expect-error TS(2339): Property 'track' does not exist on type '{}'.
+                    scrobbleResponse.track.album = {
+                        ...malojaAlbum,
+                        name: album
+                    }
+                }
+            } else {
+                const {body: {
+                    // @ts-expect-error TS(2525): Initializer provides no value for this binding ele... Remove this comment to see the full error message
+                    track: {
+                        time: mTime = playDate.unix(),
+                        duration: mDuration = duration,
+                        album: mAlbum = album,
+                        ...rest
+                    }
+                } = {}} = response;
+                scrobbleResponse = {...rest, album: mAlbum, time: mTime, duration: mDuration};
+            }
+            this.addScrobbledTrack(playObj, this.formatPlayObj(scrobbleResponse));
+            if (newFromSource) {
+                this.logger.info(`Scrobbled (New)     => (${source}) ${buildTrackString(playObj)}`);
+            } else {
+                this.logger.info(`Scrobbled (Backlog) => (${source}) ${buildTrackString(playObj)}`);
+            }
+        } catch (e) {
+            await this.notifier.notify({title: `Client - ${capitalize(this.type)} - ${this.name} - Scrobble Error`, message: `Failed to scrobble => ${buildTrackString(playObj)} | Error: ${e.message}`, priority: 'error'});
+            this.logger.error(`Scrobble Error (${sType})`, {playInfo: buildTrackString(playObj), payload: scrobbleData});
+            throw e;
+        } finally {
+            this.logger.debug('Raw Payload:', scrobbleData);
+        }
+
+        return true;
+    }
+}

src/clients/ScrobbleClients.ts

@@ -1,37 +1,89 @@
-import dayjs from "dayjs";
+import dayjs, {Dayjs} from "dayjs";
 import {
-    createLabelledLogger,
-    isValidConfigStructure,
+    buildTrackString,
+    createAjvFactory,
+    mergeArr,
     playObjDataMatch,
     readJson,
-    returnDuplicateStrings
+    returnDuplicateStrings, validateJson
 } from "../utils.js";
 import MalojaScrobbler from "./MalojaScrobbler.js";
 import LastfmScrobbler from "./LastfmScrobbler.js";
+import {clientTypes, ConfigMeta, PlayObject} from "../common/infrastructure/Atomic.js";
+import {AIOConfig} from "../common/infrastructure/config/aioConfig.js";
+import * as aioSchema from '../common/schema/aio-client.json';
+import * as clientSchema from '../common/schema/client.json';
+import {ClientAIOConfig, ClientConfig} from "../common/infrastructure/config/client/clients.js";
+import {MalojaClientConfig} from "../common/infrastructure/config/client/maloja.js";
+import {LastfmClientConfig} from "../common/infrastructure/config/client/lastfm.js";
+import {Notifiers} from "../notifier/Notifiers.js";
+import AbstractScrobbleClient from "./AbstractScrobbleClient.js";
+import {EventEmitter} from "events";
+import winston from '@foxxmd/winston';
+import ListenbrainzScrobbler from "./ListenbrainzScrobbler.js";
+import {ListenBrainzClientConfig} from "../common/infrastructure/config/client/listenbrainz.js";
+import {ErrorWithCause} from "pony-cause";
+
+type groupedNamedConfigs = {[key: string]: ParsedConfig[]};
+
+type ParsedConfig = ClientAIOConfig & ConfigMeta;
 
 export default class ScrobbleClients {
 
-    clients = [];
+    /** @type AbstractScrobbleClient[] */
+    clients: (MalojaScrobbler | LastfmScrobbler)[] = [];
     logger;
     configDir;
 
-    clientTypes = ['maloja','lastfm'];
+    emitter: EventEmitter;
 
-    constructor(configDir) {
+    sourceEmitter: EventEmitter;
+
+    constructor(emitter: EventEmitter, sourceEmitter: EventEmitter, configDir: any) {
+        this.emitter = emitter;
+        this.sourceEmitter = sourceEmitter;
         this.configDir = configDir;
-        this.logger = createLabelledLogger('scrobblers', 'Scrobblers');
+        this.logger = winston.loggers.get('app').child({labels: ['Scrobblers']}, mergeArr);
+
+        this.sourceEmitter.on('scrobble', async (payload: { data: (PlayObject | PlayObject[]), options: { forceRefresh?: boolean, checkTime?: Dayjs, scrobbleTo?: string[], scrobbleFrom?: string } }) => {
+            await this.scrobble(payload.data, payload.options);
+        });
     }
 
-    getByName = (name) => {
+    getByName = (name: any) => {
         return this.clients.find(x => x.name === name);
     }
 
-    getByType = (type) => {
+    getByType = (type: any) => {
         return this.clients.filter(x => x.type === type);
     }
 
-    buildClientsFromConfig = async () => {
-        let configs = [];
+    async getStatusSummary(type?: string, name?: string): Promise<[boolean, string[]]> {
+        let clients: AbstractScrobbleClient[];
+
+        const messages: string[] = [];
+        let clientsReady = true;
+
+        if(type !== undefined) {
+            clients = this.getByType(type);
+        } else if(name !== undefined) {
+            clients = [this.getByName(name)];
+        } else {
+            clients = this.clients;
+        }
+
+        for(const client of clients) {
+            if(!await client.isReady()) {
+                clientsReady = false;
+                messages.push(`Client ${client.type} - ${client.name} is not ready.`);
+            }
+        }
+
+        return [clientsReady, messages];
+    }
+
+    buildClientsFromConfig = async (notifier: Notifiers) => {
+        let configs: ParsedConfig[] = [];
 
         let configFile;
         try {
@@ -42,23 +94,24 @@ export default class ScrobbleClients {
         }
         let clientDefaults = {};
         if (configFile !== undefined) {
+            const aioConfig = validateJson<AIOConfig>(configFile, aioSchema, this.logger);
             const {
                 clients: mainConfigClientConfigs = [],
                 clientDefaults: cd = {},
-            } = configFile;
+            } = aioConfig;
             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 validMainConfigs = mainConfigClientConfigs.reduce((acc: any, curr: any, i: any) => {
+            //     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 mainConfigClientConfigs) {
                 const {name = 'unnamed'} = c;
                 configs.push({...c,
                     name,
@@ -68,7 +121,7 @@ export default class ScrobbleClients {
             }
         }
 
-        for (const clientType of this.clientTypes) {
+        for (const clientType of clientTypes) {
             let defaultConfigureAs = 'client';
             switch (clientType) {
                 case 'maloja':
@@ -78,11 +131,13 @@ export default class ScrobbleClients {
                     if (url !== undefined || apiKey !== undefined) {
                         configs.push({
                             type: 'maloja',
-                            name: 'unnamed',
+                            name: 'unnamed-mlj',
                             source: 'ENV',
                             mode: 'single',
+                            configureAs: 'client',
                             data: {
                                 url,
+                                // @ts-ignore
                                 apiKey
                             }
                         })
@@ -98,13 +153,33 @@ export default class ScrobbleClients {
                     if (!Object.values(lfm).every(x => x === undefined)) {
                         configs.push({
                             type: 'lastfm',
-                            name: 'unnamed',
+                            name: 'unnamed-lfm',
                             source: 'ENV',
                             mode: 'single',
+                            configureAs: 'client',
+                            // @ts-ignore
                             data: lfm
                         })
                     }
                     break;
+                case 'listenbrainz':
+                    const lz = {
+                        url: process.env.LZ_URL,
+                        token: process.env.LZ_TOKEN,
+                        username: process.env.LZ_USER
+                    };
+                    if (!Object.values(lz).every(x => x === undefined)) {
+                        configs.push({
+                            type: 'listenbrainz',
+                            name: 'unnamed-lz',
+                            source: 'ENV',
+                            mode: 'single',
+                            configureAs: 'client',
+                            // @ts-ignore
+                            data: lz
+                        })
+                    }
+                    break;
                 default:
                     break;
             }
@@ -116,25 +191,36 @@ export default class ScrobbleClients {
                 continue;
             }
             if (rawClientConfigs !== undefined) {
-                let clientConfigs = [];
+                let clientConfigs: ParsedConfig[] = [];
                 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 if(typeof rawClientConfigs === 'object') {
+                    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`);
+                    this.logger.error(`All top level data from ${clientType}.json must be an object or an array of objects, will not parse configs from file`);
                     continue;
                 }
-                for (const [i,m] of clientConfigs.entries()) {
+                for(const [i,rawConf] of rawClientConfigs.entries()) {
+                    try {
+                        const validConfig = validateJson<ClientConfig>(rawConf, clientSchema, this.logger);
+                        // @ts-ignore
+                        const {configureAs = defaultConfigureAs} = validConfig;
+                        if (configureAs === 'client') {
+                            const parsedConfig: ParsedConfig = {
+                                ...rawConf,
+                                source: `${clientType}.json`,
+                                type: clientType
+                            }
+                            configs.push(parsedConfig);
+                        }
+                    } catch (e: any) {
+                        this.logger.error(`The config entry at index ${i} from ${clientType}.json was not valid`);
+                    }
+                }
+/*                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;
@@ -149,31 +235,31 @@ export default class ScrobbleClients {
                         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 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 nameGroupedConfigs = configs.reduce((acc: groupedNamedConfigs, curr: ParsedConfig) => {
             const {name = 'unnamed'} = curr;
             const {[name]: n = []} = acc;
             return {...acc, [name]: [...n, curr]};
         }, {});
-        let noConflictConfigs = [];
+        let noConflictConfigs: ParsedConfig[] = [];
         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}]`);
+                const sources = configs.map((c: any) => `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') {
@@ -186,13 +272,13 @@ ${sources.join('\n')}`);
 
         // 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}) => ({
+        const finalConfigs: ParsedConfig[] = noConflictConfigs.map(({name = 'unnamed', ...x}) => ({
             ...x,
             name
         }));
         for (const c of finalConfigs) {
             try {
-                await this.addClient(c, clientDefaults);
+                await this.addClient(c, clientDefaults, notifier);
             } catch(e) {
                 this.logger.error(`Client ${c.name} was not added because it had unrecoverable errors`);
                 this.logger.error(e);
@@ -200,22 +286,25 @@ ${sources.join('\n')}`);
         }
     }
 
-    addClient = async (clientConfig, defaults = {}) => {
-        const isValidConfig = isValidConfigStructure(clientConfig, {name: true, data: true, type: true});
+    addClient = async (clientConfig: ParsedConfig, defaults = {}, notifier: Notifiers) => {
+/*        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...`);
+        this.logger.debug(`Constructing ${type} (${name}) client...`);
         switch (type) {
             case 'maloja':
-                newClient = new MalojaScrobbler(name, data);
+                newClient = new MalojaScrobbler(name, ({...clientConfig, data} as unknown as MalojaClientConfig), notifier, this.logger);
                 break;
             case 'lastfm':
-                newClient = new LastfmScrobbler(name, {...data, configDir: this.configDir});
+                newClient = new LastfmScrobbler(name, {...clientConfig, data: {configDir: this.configDir, ...data} } as unknown as LastfmClientConfig, {}, notifier, this.logger);
+                break;
+            case 'listenbrainz':
+                newClient = new ListenbrainzScrobbler(name, {...clientConfig, data: {configDir: this.configDir, ...data} } as unknown as ListenBrainzClientConfig, {}, notifier, this.logger);
                 break;
             default:
                 break;
@@ -226,15 +315,15 @@ ${sources.join('\n')}`);
             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.`);
+            this.logger.debug(`Attempting ${type} (${name}) initialization...`);
+            if ((await newClient.initialize()) === false) {
+                this.logger.error(`${type} (${name}) client failed to initialize. Client needs to be successfully initialized before scrobbling.`);
             } else {
-                this.logger.info(`(${name}) ${type} client initialized`);
+                this.logger.info(`${type} (${name}) client initialized`);
             }
         }
         if(newClient.requiresAuth && !newClient.authed) {
-            this.logger.debug(`(${name}) Checking ${type} client auth...`);
+            this.logger.debug(`Checking ${type} (${name}) client auth...`);
             let success;
             try {
                 success = await newClient.testAuth();
@@ -242,9 +331,9 @@ ${sources.join('\n')}`);
                 success = false;
             }
             if(!success) {
-                this.logger.warn(`(${name}) ${type} client auth failed.`);
+                this.logger.warn(`${type} (${name}) client auth failed.`);
             } else {
-                this.logger.warn(`(${name}) ${type} client auth OK`);
+                this.logger.info(`${type} (${name}) client auth OK`);
             }
         }
         this.clients.push(newClient);
@@ -255,7 +344,7 @@ ${sources.join('\n')}`);
      * @param {{scrobbleFrom, scrobbleTo, forceRefresh: boolean}|{scrobbleFrom, scrobbleTo}} options
      * @returns {Array}
      */
-    scrobble = async (data, options = {}) => {
+    scrobble = async (data: (PlayObject | PlayObject[]), options: {forceRefresh?: boolean, checkTime?: Dayjs, scrobbleTo?: string[], scrobbleFrom?: string} = {}) => {
         const playObjs = Array.isArray(data) ? data : [data];
         const {
             forceRefresh = false,
@@ -264,7 +353,7 @@ ${sources.join('\n')}`);
             scrobbleFrom = 'source',
         } = options;
 
-        const tracksScrobbled = [];
+        const tracksScrobbled: any = [];
 
         if (this.clients.length === 0) {
             this.logger.warn('Cannot scrobble! No clients are configured.');
@@ -272,26 +361,32 @@ ${sources.join('\n')}`);
 
         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}'`);
+                client.logger.debug(`Client was filtered out by Source '${scrobbleFrom}'`);
                 continue;
             }
-            if(client.initialized === false) {
-                this.logger.warn(`Cannot scrobble to Client '${client.name}' because it is not yet initialized`);
-                continue;
+            if(!client.initialized) {
+                if(client.initializing) {
+                    client.logger.warn(`Cannot scrobble because it is still initializing`);
+                    continue;
+                }
+                if(!(await client.initialize())) {
+                    client.logger.warn(`Cannot scrobble because it could not be initialized`);
+                    continue;
+                }
             }
 
             if(client.requiresAuth && !client.authed) {
                 if (client.requiresAuthInteraction) {
-                    this.logger.warn(`Cannot scrobble to Client '${client.name}' because user interaction is required for authentication`);
+                    client.logger.warn(`Cannot scrobble because user interaction is required for authentication`);
                     continue;
                 } else if (!(await client.testAuth())) {
-                    this.logger.warn(`Cannot scrobble to Client '${client.name}' because auth test failed`);
+                    client.logger.warn(`Cannot scrobble because auth test failed`);
                     continue;
                 }
             }
 
             if(!(await client.isReady())) {
-                this.logger.warn(`Cannot scrobble to Client '${client.name}' because it is not ready`);
+                client.logger.warn(`Cannot scrobble because it is not ready`);
                 continue;
             }
 
@@ -299,7 +394,7 @@ ${sources.join('\n')}`);
                 try {
                     await client.refreshScrobbles();
                 } catch(e) {
-                    this.logger.error(`Encountered error while refreshing scrobbles for ${client.name}`);
+                    client.logger.error(`Encountered error while refreshing scrobbles`);
                     this.logger.error(e);
                 }
             }
@@ -310,7 +405,8 @@ ${sources.join('\n')}`);
                             newFromSource = false,
                         } = {}
                     } = playObj;
-                    if (client.timeFrameIsValid(playObj, newFromSource) && !client.alreadyScrobbled(playObj, newFromSource)) {
+                    const [timeFrameValid, timeFrameValidLog] = client.timeFrameIsValid(playObj);
+                    if (timeFrameValid && !(await client.alreadyScrobbled(playObj))) {
                         await client.scrobble(playObj)
                         client.tracksScrobbled++;
                         // since this is what we return to the source only add to tracksScrobbled if not already in array
@@ -318,10 +414,13 @@ ${sources.join('\n')}`);
                         if(!tracksScrobbled.some(x => playObjDataMatch(x, playObj) && x.data.playDate === playObj.data.playDate)) {
                             tracksScrobbled.push(playObj);
                         }
+                    } else {
+                        if(!timeFrameValid) {
+                            client.logger.debug(`Will not scrobble ${buildTrackString(playObj)} from Source '${scrobbleFrom}' because it ${timeFrameValidLog}`);
+                        }
                     }
                 } catch(e) {
-                    this.logger.error(`Encountered error while in scrobble loop for ${client.name}`);
-                    this.logger.error(e);
+                    client.logger.error(new ErrorWithCause(`Encountered error while in scrobble loop`, {cause: 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;

src/common/index.ts

@@ -0,0 +1,8 @@
+import * as path from 'path';
+//import {fileURLToPath} from "url";
+
+//const __filename = fileURLToPath(import.meta.url);
+//const __dirname = path.dirname(__filename);
+
+export const projectDir = path.resolve(__dirname, '../../');
+export const configDir: string = path.resolve(projectDir, './config');

src/common/infrastructure/Atomic.ts

@@ -0,0 +1,267 @@
+import {Dayjs} from "dayjs";
+import {FixedSizeList} from 'fixed-size-list';
+import {MESSAGE} from 'triple-beam';
+import {Logger} from '@foxxmd/winston';
+
+export type SourceType = 'spotify' | 'plex' | 'tautulli' | 'subsonic' | 'jellyfin' | 'lastfm' | 'deezer' | 'ytmusic' | 'mpris' | 'mopidy' | 'listenbrainz' | 'jriver' | 'kodi';
+export const sourceTypes: SourceType[] = ['spotify', 'plex', 'tautulli', 'subsonic', 'jellyfin', 'lastfm', 'deezer', 'ytmusic', 'mpris', 'mopidy', 'listenbrainz', 'jriver', 'kodi'];
+
+export const lowGranularitySources: SourceType[] = ['subsonic','ytmusic'];
+
+export type ClientType = 'maloja' | 'lastfm' | 'listenbrainz';
+export const clientTypes: ClientType[] = ['maloja', 'lastfm', 'listenbrainz'];
+
+export type InitState = 0 | 1 | 2;
+export const NOT_INITIALIZED: InitState = 0;
+export const INITIALIZING: InitState = 1;
+export const INITIALIZED: InitState = 2;
+export const initStates: InitState[] = [NOT_INITIALIZED, INITIALIZING, INITIALIZED];
+
+export type ReadyState = 0 | 1 | 2;
+export const NOT_READY: ReadyState = 0;
+export const GETTING_READY: ReadyState = 1;
+export const READY: ReadyState = 2;
+export const readyStates: ReadyState[] = [NOT_READY, GETTING_READY, READY];
+
+export interface InternalConfig {
+    localUrl: string
+    configDir: string
+
+    logger: Logger
+}
+
+export interface ConfigMeta {
+    source: string
+    mode?: string
+    configureAs: string
+}
+
+export interface PlayData {
+    artists?: string[]
+    album?: string
+    track?: string
+    /**
+     * The length of the track, in seconds
+     * */
+    duration?: number
+    /**
+     * The date the track was played at
+     * */
+    playDate?: Dayjs
+
+    meta?: {
+        brainz?: {
+            artist?: string
+            albumArtist?: string
+            album?: string
+            track?: string
+            releaseGroup?: string
+        }
+    }
+}
+
+export interface PlayMeta {
+    source?: string
+
+    /**
+     * Specifies from what facet/data from the source this play was parsed from IE history, now playing, etc...
+     * */
+    parsedFrom?: string
+    /**
+     * Unique ID for this track, given by the Source
+     * */
+    trackId?: string
+
+    /**
+     * Atomic ID for this instance of played tracked IE a unique ID for "this track played at this time"
+     * */
+    playId?: string
+    newFromSource?: boolean
+    url?: {
+        web: string
+        [key: string]: string
+    }
+    user?: string
+    mediaType?: string
+    server?: string
+    library?: string
+    /**
+     * The position the "player" is at in the track at the time the play was reported, in seconds
+     * */
+    trackProgressPosition?: number
+    /**
+     * A unique identifier for the device playing this track
+     * */
+    deviceId?: string
+
+    [key: string]: any
+}
+
+export interface PlayObject {
+    data: PlayData,
+    meta: PlayMeta
+}
+
+export interface FormatPlayObjectOptions {
+    newFromSource?: boolean
+    parsedFrom?: string
+
+    [key: string]: any
+}
+
+export interface ProgressAwarePlayObject extends PlayObject {
+    meta: PlayMeta & {
+        initialTrackProgressPosition?: number
+    }
+}
+
+export type GroupedPlays = Map<string, ProgressAwarePlayObject[]>;
+
+export type GroupedFixedPlays = Map<string, FixedSizeList<ProgressAwarePlayObject>>;
+
+export interface TrackStringOptions {
+    include?: ('time' | 'artist' | 'track' | 'timeFromNow' | 'trackId')[]
+    transformers?: {
+        artists?: (a: string[]) => string
+        track?: (t: string) => string
+        time?: (t: Dayjs) => string
+        timeFromNow?: (t: Dayjs) => string
+    }
+}
+
+export interface ScrobbledPlayObject {
+    play: PlayObject
+    scrobble: PlayObject
+}
+
+export interface MalojaV2ScrobbleData {
+    artists: string[]
+    title: string
+    album: string
+    /**
+     * Length of the track
+     * */
+    duration: number
+    /**
+     * unix timestamp (seconds) scrobble was made at
+     * */
+    time: number
+}
+
+export interface MalojaV3ScrobbleData {
+    /**
+     * unix timestamp (seconds) scrobble was made at
+     * */
+    time: number
+    track: {
+        artists: string[]
+        title: string
+        album?: {
+            name: string
+            artists: string[]
+        }
+        /**
+         * length of the track
+         * */
+        length: number
+    }
+    /**
+     * how long the track was listened to before it was scrobbled
+     * */
+    duration: number
+}
+
+export type MalojaScrobbleData = MalojaV2ScrobbleData | MalojaV3ScrobbleData;
+
+export interface MalojaScrobbleRequestData {
+    key: string
+    title: string
+    album: string
+    time: number
+    length: number
+}
+
+export interface MalojaScrobbleV2RequestData extends MalojaScrobbleRequestData {
+    artist: string
+}
+
+export interface MalojaScrobbleV3RequestData extends MalojaScrobbleRequestData {
+    artists: string[]
+}
+
+export interface RemoteIdentityParts {
+    host: string,
+    proxy: string | undefined,
+    agent: string | undefined
+}
+
+export type LogLevel = "error" | "warn" | "info" | "verbose" | "debug";
+export const logLevels = ['error', 'warn', 'info', 'verbose', 'debug'];
+
+export interface LogConfig {
+    level?: string
+    file?: string | false
+    stream?: string
+    console?: string
+}
+
+export interface LogOptions {
+    /**
+     *  Specify the minimum log level for all log outputs without their own level specified.
+     *
+     *  Defaults to env `LOG_LEVEL` or `info` if not specified.
+     *
+     *  @default 'info'
+     * */
+    level?: LogLevel
+    /**
+     * Specify the minimum log level to output to rotating files. If `false` no log files will be created.
+     * */
+    file?: LogLevel | false
+    /**
+     * Specify the minimum log level streamed to the UI
+     * */
+    stream?: LogLevel
+    /**
+     * Specify the minimum log level streamed to the console (or docker container)
+     * */
+    console?: LogLevel
+}
+
+export const asLogOptions = (obj: LogConfig = {}): obj is LogOptions => {
+    return Object.entries(obj).every(([key,  val]) => {
+        if(key !== 'file') {
+            return val === undefined || logLevels.includes(val.toLocaleLowerCase());
+        }
+        return val === undefined || val === false || logLevels.includes(val.toLocaleLowerCase());
+    });
+}
+
+export interface LogInfo {
+    message: string
+    [MESSAGE]: string,
+    level: string
+    timestamp: string
+    labels?: string[]
+    transport?: string[]
+}
+
+// https://stackoverflow.com/questions/40510611/typescript-interface-require-one-of-two-properties-to-exist#comment116238286_49725198
+export type RequireAtLeastOne<T, R extends keyof T = keyof T> = Omit<T, R> & {   [ P in R ] : Required<Pick<T, P>> & Partial<Omit<T, P>> }[R];
+
+export const DEFAULT_SCROBBLE_DURATION_THRESHOLD: number = 30;
+
+export interface ScrobbleThresholdResult {
+    passes: boolean
+    duration: {
+        passes?: boolean
+        value?: number
+        threshold?: number
+    }
+    percent: {
+        passes?: boolean
+        value?: number
+        threshold?: number
+    }
+
+}

src/common/infrastructure/config/aioConfig.ts

@@ -0,0 +1,41 @@
+import {ScrobbleThresholds, SourceRetryOptions} from "./source/index.js";
+import {RequestRetryOptions} from "./common.js";
+import {SourceAIOConfig} from "./source/sources.js";
+import {ClientAIOConfig} from "./client/clients.js";
+import {WebhookConfig} from "./health/webhooks.js";
+import {LogOptions} from "../Atomic.js";
+
+export interface AIOConfig {
+    sourceDefaults?: SourceRetryOptions &
+        {
+            /**
+             * Set thresholds for when multi-scrobbler should consider a tracked play to be "scrobbable". If both duration and percent are defined then if either condition is met the track is scrobbled.
+             * */
+            scrobbleThresholds?: ScrobbleThresholds
+        }
+    clientDefaults?: RequestRetryOptions
+    sources?: SourceAIOConfig[]
+    clients?: ClientAIOConfig[]
+
+    webhooks?: WebhookConfig[]
+
+    /**
+     * Set the port the multi-scrobbler UI will be served from
+     *
+     * @default 9078
+     * @examples [9078]
+     * */
+    port?: number
+
+    logging?: LogOptions
+}
+
+export interface AIOClientConfig {
+    clientDefaults?: RequestRetryOptions
+    clients?: ClientAIOConfig[]
+}
+
+export interface AIOSourceConfig {
+    sourceDefaults?: SourceRetryOptions
+    sources?: SourceAIOConfig[]
+}

src/common/infrastructure/config/client/clients.ts

@@ -0,0 +1,7 @@
+import {MalojaClientAIOConfig, MalojaClientConfig} from "./maloja.js";
+import {LastfmClientAIOConfig, LastfmClientConfig} from "./lastfm.js";
+import {ListenBrainzClientAIOConfig, ListenBrainzClientConfig} from "./listenbrainz.js";
+
+export type ClientConfig = MalojaClientConfig | LastfmClientConfig | ListenBrainzClientConfig;
+
+export type ClientAIOConfig = MalojaClientAIOConfig | LastfmClientAIOConfig | ListenBrainzClientAIOConfig;

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

@@ -0,0 +1,80 @@
+import {CommonConfig, CommonData} from "../common.js";
+
+/**
+ * Scrobble matching (between new source track and existing client scrobbles) logging options. Used for debugging.
+ * */
+export interface MatchLoggingOptions {
+    /**
+     * Log to DEBUG when a new track does NOT match an existing scrobble
+     *
+     * @default false
+     * @examples [false]
+     * */
+    onNoMatch?: boolean
+    /**
+     * Log to DEBUG when a new track DOES match an existing scrobble
+     *
+     * @default false
+     * @examples [false]
+     * */
+    onMatch?: boolean
+    /**
+     * Include confidence breakdowns in track match logging, if applicable
+     *
+     * @default false
+     * @examples [false]
+     * */
+    confidenceBreakdown?: boolean
+}
+
+export interface CommonClientData extends CommonData {
+    /**
+     * default # of http request retries a client can make before error is thrown.
+     *
+     * @default 1
+     * @examples [1]
+     * */
+    maxRequestRetries?: number
+    /**
+     * default retry delay multiplier (retry attempt * multiplier = # of seconds to wait before retrying).
+     *
+     * @default 1.5
+     * @examples [1.5]
+     * */
+    retryMultiplier?: number
+
+    options?: {
+        /**
+         * Try to get fresh scrobble history from client when tracks to be scrobbled are newer than the last scrobble found in client history
+         * @default true
+         * @examples [true]
+         * */
+        refreshEnabled?: boolean
+        /**
+         * Check client for an existing scrobble at the same recorded time as the "new" track to be scrobbled. If an existing scrobble is found this track is not track scrobbled.
+         * @default true
+         * @examples [true]
+         * */
+        checkExistingScrobbles?: boolean
+        /**
+        * Options used for increasing verbosity of logging in MS (used for debugging)
+        * */
+        verbose?: {
+
+            match?: MatchLoggingOptions
+        }
+    }
+}
+
+export interface CommonClientConfig extends CommonConfig {
+    /**
+     * Unique identifier for this client. Used with sources to restrict where scrobbles are sent.
+     *
+     * @examples ["MyConfig"]
+     * */
+    name: string
+    /**
+     * Specific data required to configure this client
+     * */
+    data?: CommonClientData
+}

src/common/infrastructure/config/client/lastfm.ts

@@ -0,0 +1,43 @@
+import {CommonClientConfig, CommonClientData} from "./index.js";
+import {RequestRetryOptions} from "../common.js";
+
+export interface LastfmData extends RequestRetryOptions {
+    /**
+     * API Key generated from Last.fm account
+     *
+     * @examples ["787c921a2a2ab42320831aba0c8f2fc2"]
+     * */
+    apiKey: string
+    /**
+     * Secret generated from Last.fm account
+     *
+     * @examples ["ec42e09d5ae0ee0f0816ca151008412a"]
+     * */
+    secret: string
+    /**
+     * Optional session id returned from a completed auth flow
+     * */
+    session?: string
+    /**
+     * Optional URI to use for callback. Specify this if callback should be different than the default. MUST have "lastfm/callback" in the URL somewhere.
+     *
+     * @default "http://localhost:9078/lastfm/callback"
+     * @examples ["http://localhost:9078/lastfm/callback"]
+     * */
+    redirectUri?: string
+}
+
+export interface LastfmClientConfig extends CommonClientConfig {
+    /**
+     * Should always be `client` when using LastFM as a client
+     *
+     * @default client
+     * @examples ["client"]
+     * */
+    configureAs?: 'client' | 'source'
+    data: CommonClientData & LastfmData
+}
+
+export interface LastfmClientAIOConfig extends LastfmClientConfig {
+    type: 'lastfm'
+}

src/common/infrastructure/config/client/listenbrainz.ts

@@ -0,0 +1,40 @@
+import {CommonClientConfig, CommonClientData} from "./index.js";
+import {RequestRetryOptions} from "../common.js";
+
+export interface ListenBrainzData extends RequestRetryOptions{
+    /**
+     * URL for the ListenBrainz server, if not using the default
+     *
+     * @examples ["https://api.listenbrainz.org/"]
+     * @default "https://api.listenbrainz.org/"
+     * */
+    url?: string
+    /**
+     * User token for the user to scrobble for
+     *
+     * @examples ["6794186bf-1157-4de6-80e5-uvb411f3ea2b"]
+     * */
+    token: string
+
+    /**
+     * Username of the user to scrobble for
+     * */
+    username: string
+}
+
+export interface ListenBrainzClientData extends ListenBrainzData, CommonClientData {}
+
+export interface ListenBrainzClientConfig extends CommonClientConfig {
+    /**
+     * Should always be `client` when using Listenbrainz as a client
+     *
+     * @default client
+     * @examples ["client"]
+     * */
+    configureAs?: 'client' | 'source'
+    data: ListenBrainzClientData
+}
+
+export interface ListenBrainzClientAIOConfig extends ListenBrainzClientConfig {
+    type: 'listenbrainz'
+}

src/common/infrastructure/config/client/maloja.ts

@@ -0,0 +1,25 @@
+import {CommonClientConfig, CommonClientData} from "./index.js";
+import {RequestRetryOptions} from "../common.js";
+
+export interface MalojaClientData extends RequestRetryOptions, CommonClientData {
+    /**
+     * URL for maloja server
+     *
+     * @examples ["http://localhost:42010"]
+     * */
+    url: string
+    /**
+     * API Key for Maloja server
+     *
+     * @examples ["myApiKey"]
+     * */
+    apiKey: string
+}
+
+export interface MalojaClientConfig extends CommonClientConfig {
+    data: MalojaClientData
+}
+
+export interface MalojaClientAIOConfig extends MalojaClientConfig {
+    type: 'maloja'
+}

src/common/infrastructure/config/common.ts

@@ -0,0 +1,45 @@
+export interface CommonConfig {
+    name?: string
+    data?: CommonData
+}
+
+export interface CommonData {
+    [key: string]: any
+    options?: Record<string, any>
+}
+
+export interface RequestRetryOptions {
+    /**
+     * default # of http request retries a source can make before error is thrown
+     *
+     * @default 1
+     * @examples [1]
+     * */
+    maxRequestRetries?: number
+    /**
+     * default retry delay multiplier (retry attempt * multiplier = # of seconds to wait before retrying)
+     *
+     * @default 1.5
+     * @examples [1.5]
+     * */
+    retryMultiplier?: number
+}
+
+export interface PollingOptions {
+
+    /**
+     * How long to wait before polling the source API for new tracks (in seconds)
+     *
+     * @default 30
+     * @examples [30]
+     * */
+    interval?: number
+
+    /**
+     * When there has been no new activity from the Source API multi-scrobbler will gradually increase the wait time between polling up to this value (in seconds)
+     *
+     * @default 60
+     * @examples [60]
+     * */
+    maxInterval?: number
+}

src/common/infrastructure/config/health/webhooks.ts

@@ -0,0 +1,93 @@
+export interface WebhookPayload {
+    title?: string
+    message: string
+    priority: 'info' | 'warn' | 'error'
+}
+
+export interface PrioritiesConfig {
+    /**
+     * @examples [5]
+     * */
+    info: number
+    /**
+     * @examples [7]
+     * */
+    warn: number
+    /**
+     * @examples [10]
+     * */
+    error: number
+}
+
+export interface CommonWebhookConfig {
+    /**
+     * Webhook type. Valid values are:
+     *
+     * * gotify
+     * * ntfy
+     *
+     * @examples ["gotify"]
+     * */
+    type: 'gotify' | 'ntfy'
+    /**
+     * A friendly name used to identify webhook config in logs
+     * */
+    name?: string
+}
+
+export interface GotifyConfig extends CommonWebhookConfig {
+    /**
+     * The URL of the Gotify server. Same URL that would be used to reach the Gotify UI
+     *
+     * @examples ["http://192.168.0.100:8078"]
+     * */
+    url: string
+    /**
+     * The token created for this Application in Gotify
+     *
+     * @examples ["AQZI58fA.rfSZbm"]
+     * */
+    token: string
+    /**
+     * Priority of messages
+     *
+     * * Info -> 5
+     * * Warn -> 7
+     * * Error -> 10
+     * */
+    priorities?: PrioritiesConfig
+}
+
+export interface NtfyConfig extends CommonWebhookConfig {
+    /**
+     * The URL of the Ntfy server
+     *
+     * @examples ["http://192.168.0.100:8078"]
+     * */
+    url: string
+
+    /**
+     * The topic mutli-scrobbler should POST to
+     * */
+    topic: string
+
+    /**
+     * Required if topic is protected
+     * */
+    username?: string
+    /**
+     * Required if topic is protected
+     * */
+    password?: string
+
+    /**
+     * Priority of messages
+     *
+     * * Info -> 3
+     * * Warn -> 4
+     * * Error -> 5
+     * */
+    priorities?: PrioritiesConfig
+}
+
+export type WebhookConfig = GotifyConfig | NtfyConfig;

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

@@ -0,0 +1,37 @@
+import {CommonSourceConfig, CommonSourceData} from "./index.js";
+
+export interface DeezerData extends CommonSourceData {
+    /**
+     * deezer client id
+     *
+     * @examples ["a89cba1569901a0671d5a9875fed4be1"]
+     * */
+    clientId: string
+    /**
+     * deezer client secret
+     *
+     * @examples ["ec42e09d5ae0ee0f0816ca151008412a"]
+     * */
+    clientSecret: string
+    /**
+     * deezer redirect URI -- required only if not the default shown here. URI must end in "callback"
+     *
+     * @default "http://localhost:9078/deezer/callback"
+     * @examples ["http://localhost:9078/deezer/callback"]
+     * */
+    redirectUri: string
+    /**
+     * optional, how long to wait before calling spotify for new tracks (in seconds)
+     *
+     * @default 60
+     * @examples [60]
+     * */
+    interval?: number
+}
+export interface DeezerSourceConfig extends CommonSourceConfig {
+    data: DeezerData
+}
+
+export interface DeezerSourceAIOConfig extends DeezerSourceConfig {
+    type: 'deezer'
+}

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

@@ -0,0 +1,49 @@
+import {CommonConfig, CommonData, RequestRetryOptions} from "../common.js";
+
+export interface SourceRetryOptions extends RequestRetryOptions {
+    /**
+     * default # of automatic polling restarts on error
+     *
+     * @default 5
+     * @examples [5]
+     * */
+    maxPollRetries?: number
+}
+
+export interface ScrobbleThresholds {
+    /**
+     * The number of seconds before a track should be considered scrobbled.
+     *
+     * @default 30
+     * @examples [30]
+     * */
+    duration?: number
+    /**
+     * The percentage of a track that should have been seen played before it should be scrobbled. Only used if the Source provides information about how long the track is.
+     *
+     * NOTE: This should be used with care when the Source is a "polling" type (has an 'interval' property). If the track is short and the interval is too high MS may ignore the track if percentage is high because it had not "seen" the track for long enough from first discovery, even if you have been playing the track for longer.
+     * */
+    percent?: number
+}
+
+export interface CommonSourceData extends CommonData, SourceRetryOptions {
+    /**
+     * Set thresholds for when multi-scrobbler should consider a tracked play to be "scrobbable". If both duration and percent are defined then if either condition is met the track is scrobbled.
+     * */
+    scrobbleThresholds?: ScrobbleThresholds
+}
+
+export interface CommonSourceConfig extends CommonConfig {
+    /**
+     * Unique identifier for this source.
+     * */
+    name?: string
+    /**
+     * Restrict scrobbling tracks played from this source to Clients with names from this list. If list is empty is not present Source scrobbles to all configured Clients.
+     *
+     * @examples [["MyMalojaConfigName","MyLastFMConfigName"]]
+     * */
+    clients?: string[]
+    data?: CommonSourceData
+}
+

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

@@ -0,0 +1,41 @@
+import {CommonSourceConfig, CommonSourceData} from "./index.js";
+
+export interface JellyData extends CommonSourceData {
+    /**
+     * optional list of users to scrobble tracks from
+     *
+     * If none are provided tracks from all users will be scrobbled
+     *
+     * @examples [["MyUser1","MyUser2"]]
+     * */
+    users?: string | string[]
+    /**
+     * optional list of servers to scrobble tracks from
+     *
+     * If none are provided tracks from all servers will be scrobbled
+     *
+     * @examples [["MyServerName1"]]
+     * */
+    servers?: string | string[]
+
+    /**
+     * Additional options for jellyfin logging and tuning
+     * */
+    options?: {
+        /**
+         * Log raw Jellyfin webhook payload to debug
+         *
+         * @default false
+         * @examples [false]
+         * */
+        logPayload?: boolean
+    }
+}
+
+export interface JellySourceConfig extends CommonSourceConfig {
+    data: JellyData
+}
+
+export interface JellySourceAIOConfig extends JellySourceConfig {
+    type: 'jellyfin'
+}

src/common/infrastructure/config/source/jriver.ts

@@ -0,0 +1,41 @@
+import {CommonSourceConfig, CommonSourceData} from "./index.js";
+import {PollingOptions} from "../common.js";
+
+export interface JRiverData extends CommonSourceData, PollingOptions {
+    /**
+     * URL of the JRiver HTTP server to connect to
+     *
+     * multi-scrobbler connects to the Web Service Interface endpoint that ultimately looks like this => `http://yourDomain:52199/MCWS/v1/`
+     *
+     * The URL you provide here will have all parts not explicitly defined filled in for you so if these are not the default you must define them.
+     *
+     * Parts => [default value]
+     *
+     * * Protocol => `http://`
+     * * Hostname => `localhost`
+     * * Port => `52199`
+     * * Path => `/MCWS/v1/`
+     *
+     *
+     * @examples ["http://localhost:52199/MCWS/v1/"]
+     * @default "http://localhost:52199/MCWS/v1/"
+     * */
+    url: string
+
+    /**
+     * If you have enabled authentication, the username you set
+     * */
+    username?: string
+
+    /**
+     * If you have enabled authentication, the password you set
+     * */
+    password?: string
+}
+export interface JRiverSourceConfig extends CommonSourceConfig {
+    data: JRiverData
+}
+
+export interface JRiverSourceAIOConfig extends JRiverSourceConfig {
+    type: 'jriver'
+}

src/common/infrastructure/config/source/kodi.ts

@@ -0,0 +1,42 @@
+import {CommonSourceConfig, CommonSourceData} from "./index.js";
+import {PollingOptions} from "../common.js";
+
+
+export interface KodiData extends CommonSourceData, PollingOptions {
+    /**
+     * URL of the Kodi HTTP server to connect to
+     *
+     * multi-scrobbler connects to the Web Service Interface endpoint that ultimately looks like this => `http://yourDomain:8080/jsonrpc`
+     *
+     * The URL you provide here will have all parts not explicitly defined filled in for you so if these are not the default you must define them.
+     *
+     * Parts => [default value]
+     *
+     * * Protocol => `http://`
+     * * Hostname => `localhost`
+     * * Port => `8080`
+     * * Path => `/jsonrpc`
+     *
+     *
+     * @examples ["http://localhost:8080/jsonrpc"]
+     * @default "http://localhost:8080/jsonrpc"
+     * */
+    url: string
+
+    /**
+     * The username set for Remote Control via Web Sever
+     * */
+    username: string
+
+    /**
+     * The password set for Remote Control via Web Sever
+     * */
+    password: string
+}
+export interface KodiSourceConfig extends CommonSourceConfig {
+    data: KodiData
+}
+
+export interface KodiSourceAIOConfig extends KodiSourceConfig {
+    type: 'kodi'
+}

src/common/infrastructure/config/source/lastfm.ts

@@ -0,0 +1,19 @@
+import {LastfmData} from "../client/lastfm.js";
+import {CommonSourceConfig, CommonSourceData} from "./index.js";
+
+export interface LastFmSourceData extends CommonSourceData, LastfmData{}
+
+export interface LastfmSourceConfig extends CommonSourceConfig {
+    /**
+     * When used in `lastfm.config` this tells multi-scrobbler whether to use this data to configure a source or client.
+     *
+     * @default source
+     * @examples ["source"]
+     * */
+    configureAs?: 'source'
+    data: LastFmSourceData
+}
+
+export interface LastFmSouceAIOConfig extends LastfmSourceConfig {
+    type: 'lastfm'
+}

src/common/infrastructure/config/source/listenbrainz.ts

@@ -0,0 +1,20 @@
+import {CommonSourceConfig, CommonSourceData} from "./index.js";
+import {ListenBrainzData} from "../client/listenbrainz.js";
+
+export interface ListenBrainzSourceData extends ListenBrainzData, CommonSourceData {
+}
+
+export interface ListenBrainzSourceConfig extends CommonSourceConfig {
+    /**
+     * When used in `listenbrainz.config` this tells multi-scrobbler whether to use this data to configure a source or client.
+     *
+     * @default source
+     * @examples ["source"]
+     * */
+    configureAs?: 'source'
+    data: ListenBrainzSourceData
+}
+
+export interface ListenBrainzSourceAIOConfig extends ListenBrainzSourceConfig {
+    type: 'listenbrainz'
+}

src/common/infrastructure/config/source/mopidy.ts

@@ -0,0 +1,76 @@
+import {CommonSourceConfig, CommonSourceData} from "./index.js";
+import {PollingOptions} from "../common.js";
+
+export interface MopidyData extends CommonSourceData, PollingOptions {
+    /**
+     * URL of the Mopidy HTTP server to connect to
+     *
+     * You MUST have Mopidy-HTTP extension enabled: https://mopidy.com/ext/http
+     *
+     * multi-scrobbler connects to the WebSocket endpoint that ultimately looks like this => `ws://localhost:6680/mopidy/ws/`
+     *
+     * The URL you provide here will have all parts not explicitly defined filled in for you so if these are not the default you must define them.
+     *
+     * Parts => [default value]
+     *
+     * * Protocol => `ws://`
+     * * Hostname => `localhost`
+     * * Port => `6680`
+     * * Path => `/mopidy/ws/`
+     *
+     *
+     * @examples ["ws://localhost:6680/mopidy/ws/"]
+     * @default "ws://localhost:6680/mopidy/ws/"
+     * */
+    url?: string
+
+    /**
+     * Do not scrobble tracks whose URI STARTS WITH any of these strings, case-insensitive
+     *
+     * EX: Don't scrobble tracks from soundcloud by adding 'soundcloud' to this list.
+     *
+     * List is ignored if uriWhitelist is used.
+     * */
+    uriBlacklist?: string[]
+
+    /**
+     * Only scrobble tracks whose URI STARTS WITH any of these strings, case-insensitive
+     *
+     * EX: Only scrobble tracks from soundcloud by adding 'soundcloud' to this list.
+     *
+     * */
+    uriWhitelist?: string[]
+
+    /**
+     * Remove album data that matches any case-insensitive string from this list when scrobbling,
+     *
+     * For certain sources (Soundcloud) Mopidy does not have all track info (Album) and will instead use "Soundcloud" as the Album name. You can prevent multi-scrobbler from using this bad Album data by adding the fake name to this list. Multi-scrobbler will still scrobble the track, just without the bad data.
+     *
+     * @examples [["Soundcloud", "Mixcloud"]]
+     * @default ["Soundcloud"]
+     * */
+    albumBlacklist?: string[]
+
+    /**
+     * How long to wait before polling the source API for new tracks (in seconds)
+     *
+     * @default 10
+     * @examples [10]
+     * */
+    interval?: number
+
+    /**
+     * When there has been no new activity from the Source API multi-scrobbler will gradually increase the wait time between polling up to this value (in seconds)
+     *
+     * @default 30
+     * @examples [30]
+     * */
+    maxInterval?: number
+}
+export interface MopidySourceConfig extends CommonSourceConfig {
+    data: MopidyData
+}
+
+export interface MopidySourceAIOConfig extends MopidySourceConfig {
+    type: 'mopidy'
+}

src/common/infrastructure/config/source/mpris.ts

@@ -0,0 +1,55 @@
+import {CommonSourceConfig, CommonSourceData} from "./index.js";
+
+export const PLAYBACK_STATUS_PLAYING = 'Playing';
+export const PLAYBACK_STATUS_PAUSED = 'Paused';
+export const PLAYBACK_STATUS_STOPPED = 'Stopped';
+
+export type PlaybackStatus = 'Playing' | 'Paused' | 'Stopped';
+
+export const MPRIS_IFACE = 'org.mpris.MediaPlayer2.Player';
+export const MPRIS_PATH = '/org/mpris/MediaPlayer2';
+export const PROPERTIES_IFACE = 'org.freedesktop.DBus.Properties';
+
+export interface MPRISMetadata {
+    trackid?: string
+    length?: number
+    artUrl?: string
+    album?: string
+    albumArtist?: string[]
+    artist?: string[]
+    title?: string
+    url?: string
+}
+
+export interface PlayerInfo {
+    name: string
+    status: PlaybackStatus
+    position?: number
+    metadata: MPRISMetadata
+}
+
+export interface MPRISData extends CommonSourceData {
+    /**
+     * DO NOT scrobble from any players that START WITH these values, case-insensitive
+     *
+     * @examples [["spotify","vlc"]]
+     * */
+    blacklist?: string | string[]
+
+    /**
+     * ONLY from any players that START WITH these values, case-insensitive
+     *
+     * If whitelist is present then blacklist is ignored
+     *
+     * @examples [["spotify","vlc"]]
+     * */
+    whitelist?: string | string[]
+}
+
+export interface MPRISSourceConfig extends CommonSourceConfig {
+    data: MPRISData
+}
+
+export interface MPRISSourceAIOConfig extends MPRISSourceConfig {
+    type: 'mpris'
+}

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

@@ -0,0 +1,36 @@
+import {CommonSourceConfig, CommonSourceData} from "./index.js";
+
+export interface PlexSourceData extends CommonSourceData {
+    /**
+     * optional list of users to scrobble tracks from
+     *
+     * If none are provided tracks from all users will be scrobbled
+     *
+     * @examples [["MyUser1", "MyUser2"]]
+     * */
+    user?: string | string[]
+    /**
+     * optional list of libraries to scrobble tracks from
+     *
+     * If none are provided tracks from all libraries will be scrobbled
+     *
+     * @examples [["Audio","Music"]]
+     * */
+    libraries?: string | string[]
+    /**
+     * optional list of servers to scrobble tracks from
+     *
+     * If none are provided tracks from all servers will be scrobbled
+     *
+     * @examples [["MyServerName"]]
+     * */
+    servers?: string | string[]
+}
+
+export interface PlexSourceConfig extends CommonSourceConfig {
+    data: PlexSourceData
+}
+
+export interface PlexSourceAIOConfig extends PlexSourceConfig {
+    type: 'plex'
+}

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

@@ -0,0 +1,17 @@
+import {SpotifySourceAIOConfig, SpotifySourceConfig} from "./spotify.js";
+import {PlexSourceAIOConfig, PlexSourceConfig} from "./plex.js";
+import {TautulliSourceAIOConfig, TautulliSourceConfig} from "./tautulli.js";
+import {DeezerSourceAIOConfig, DeezerSourceConfig} from "./deezer.js";
+import {SubsonicSourceAIOConfig, SubSonicSourceConfig} from "./subsonic.js";
+import {JellySourceAIOConfig, JellySourceConfig} from "./jellyfin.js";
+import {LastFmSouceAIOConfig, LastfmSourceConfig} from "./lastfm.js";
+import {YTMusicSourceAIOConfig, YTMusicSourceConfig} from "./ytmusic.js";
+import {MPRISSourceAIOConfig, MPRISSourceConfig} from "./mpris.js";
+import {MopidySourceAIOConfig, MopidySourceConfig} from "./mopidy.js";
+import {ListenBrainzSourceAIOConfig, ListenBrainzSourceConfig} from "./listenbrainz.js";
+import {JRiverSourceAIOConfig, JRiverSourceConfig} from "./jriver.js";
+import {KodiSourceAIOConfig, KodiSourceConfig} from "./kodi.js";
+
+export type SourceConfig = SpotifySourceConfig | PlexSourceConfig | TautulliSourceConfig | DeezerSourceConfig | SubSonicSourceConfig | JellySourceConfig | LastfmSourceConfig | YTMusicSourceConfig | MPRISSourceConfig | MopidySourceConfig | ListenBrainzSourceConfig | JRiverSourceConfig | KodiSourceConfig;
+
+export type SourceAIOConfig = SpotifySourceAIOConfig | PlexSourceAIOConfig | TautulliSourceAIOConfig | DeezerSourceAIOConfig | SubsonicSourceAIOConfig | JellySourceAIOConfig | LastFmSouceAIOConfig | YTMusicSourceAIOConfig | MPRISSourceAIOConfig | MopidySourceAIOConfig | ListenBrainzSourceAIOConfig | JRiverSourceAIOConfig | KodiSourceAIOConfig;

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

@@ -0,0 +1,46 @@
+import {CommonSourceConfig, CommonSourceData} from "./index.js";
+import {PollingOptions} from "../common.js";
+
+export interface SpotifySourceData extends CommonSourceData, PollingOptions {
+    /**
+     * spotify client id
+     *
+     * @examples ["787c921a2a2ab42320831aba0c8f2fc2"]
+     * */
+    clientId: string
+    /**
+     * spotify client secret
+     *
+     * @examples ["ec42e09d5ae0ee0f0816ca151008412a"]
+     * */
+    clientSecret: string
+    /**
+     * spotify redirect URI -- required only if not the default shown here. URI must end in "callback"
+     *
+     * @default "http://localhost:9078/callback"
+     * @examples ["http://localhost:9078/callback"]
+     * */
+    redirectUri: string
+    /**
+     * How long to wait before polling the source API for new tracks (in seconds)
+     *
+     * It is unlikely you should need to change this unless you scrobble many very short tracks often
+     *
+     * Reading:
+     * * https://developer.spotify.com/documentation/web-api/guides/rate-limits/
+     * * https://medium.com/mendix/limiting-your-amount-of-calls-in-mendix-most-of-the-time-rest-835dde55b10e
+     *   * The rate limit is ~180 req/min
+     *
+     * @default 30
+     * @examples [30]
+     * */
+    interval?: number
+}
+
+export interface SpotifySourceConfig extends CommonSourceConfig {
+    data: SpotifySourceData
+}
+
+export interface SpotifySourceAIOConfig extends SpotifySourceConfig {
+    type: 'spotify'
+}

src/common/infrastructure/config/source/subsonic.ts

@@ -0,0 +1,47 @@
+import {CommonSourceConfig, CommonSourceData} from "./index.js";
+import {PollingOptions} from "../common.js";
+
+export interface SubsonicData extends CommonSourceData, PollingOptions {
+    /**
+     * URL of the subsonic media server to query
+     *
+     * @examples ["http://airsonic.local"]
+     * */
+    url: string
+    /**
+     * Username to login to the server with
+     *
+     * @example ["MyUser"]
+     * */
+    user: string
+
+    /**
+    * Password for the user to login to the server with
+     *
+     * @examples ["MyPassword"]
+    * */
+    password: string
+
+    /**
+     * How long to wait before polling the source API for new tracks (in seconds)
+     *
+     * @default 10
+     * @examples [10]
+     * */
+    interval?: number
+
+    /**
+     * When there has been no new activity from the Source API multi-scrobbler will gradually increase the wait time between polling up to this value (in seconds)
+     *
+     * @default 30
+     * @examples [30]
+     * */
+    maxInterval?: number
+}
+export interface SubSonicSourceConfig extends CommonSourceConfig {
+    data: SubsonicData
+}
+
+export interface SubsonicSourceAIOConfig extends SubSonicSourceConfig {
+    type: 'subsonic'
+}

src/common/infrastructure/config/source/tautulli.ts

@@ -0,0 +1,8 @@
+import {PlexSourceConfig} from "./plex.js";
+
+export interface TautulliSourceConfig extends PlexSourceConfig {
+}
+
+export interface TautulliSourceAIOConfig extends TautulliSourceConfig {
+    type: 'tautulli'
+}

src/common/infrastructure/config/source/ytmusic.ts

@@ -0,0 +1,26 @@
+import {CommonSourceConfig, CommonSourceData} from "./index.js";
+import {PollingOptions} from "../common.js";
+
+export interface YTMusicData extends CommonSourceData, PollingOptions {
+    /**
+     * The cookie retrieved from the Request Headers of music.youtube.com after logging in.
+     *
+     * See https://github.com/nickp10/youtube-music-ts-api/blob/master/DOCUMENTATION.md#authenticate and https://ytmusicapi.readthedocs.io/en/latest/setup.html#copy-authentication-headers for how to retrieve this value.
+     *
+     * @examples ["VISITOR_INFO1_LIVE=jMp2xA1Xz2_PbVc; __Secure-3PAPISID=3AxsXpy0M/AkISpjek; ..."]
+     * */
+    cookie: string
+    /**
+     * If the 'X-Goog-AuthUser' header is present in the Request Headers for music.youtube.com it must also be included
+     *
+     * @example [0]
+     * */
+    authUser?: number
+}
+export interface YTMusicSourceConfig extends CommonSourceConfig {
+    data: YTMusicData
+}
+
+export interface YTMusicSourceAIOConfig extends YTMusicSourceConfig {
+    type: 'ytmusic'
+}

src/common/infrastructure/typings/lastfm-node-client.d.ts

@@ -0,0 +1,108 @@
+declare module 'lastfm-node-client' {
+    /**
+     * Must REMOVE (unset) any undefined/null properties from payload before sending or LastFM will return an error
+     * */
+    export interface TrackScrobblePayload {
+        /**
+         * join multiple artists with ', '
+         * */
+        artist: string
+
+        /**
+         * track title
+         * */
+        track: string
+
+        /**
+         * Unix timestamp of time track should be scrobbled at
+         * */
+        timestamp: number
+        /**
+         * length of track in seconds
+         * */
+        duration?: number
+
+        album?: string
+
+        albumArtist?: string
+    }
+
+    export interface TrackScrobbleResponse {
+        scrobbles: {
+            '@attr': {
+                accepted: number,
+                ignored: number
+                code: number
+            },
+            scrobble?: {
+                track: {
+                    '#text': string
+                },
+                timestamp: number,
+                ignoredMessage: {
+                    code: number
+                    '#text': string
+                }
+            }
+        }
+    }
+
+    export interface AuthGetSessionPayload {
+        token: string
+    }
+
+    export interface AuthGetSessionResponse {
+        session: {
+            key: string
+            name: string
+        }
+    }
+
+    export interface UserGetInfoResponse {
+        user: {
+            name: string
+        }
+    }
+
+    export interface UserGetRecentTracksPayload {
+        user: string
+        limit?: number
+        extended?: boolean
+    }
+
+    export interface UserGetRecentTracksResponse {
+        recenttracks: {
+            track: TrackObject[]
+        }
+    }
+
+    export interface TrackObject {
+        artist: {
+            '#text': string,
+            name: string,
+        },
+        name: string,
+        album: {
+            '#text': string,
+        },
+        duration: number,
+        date?: {
+            // @ts-ignore
+            uts: number,
+        },
+        '@attr'?: {
+            nowplaying: 'true' | 'false'
+        }
+        url: string,
+        mbid: string,
+    }
+
+    export default class LastFM {
+        constructor(apiKey: string, secret?: string, session?: string);
+
+        trackScrobble(params: TrackScrobblePayload): Promise<TrackScrobbleResponse>
+        authGetSession(params: AuthGetSessionPayload): Promise<AuthGetSessionResponse>
+        userGetInfo(): Promise<UserGetInfoResponse>
+        userGetRecentTracks(params: UserGetRecentTracksPayload): Promise<UserGetRecentTracksResponse>
+    }
+}

src/common/infrastructure/typings/passport-deezer.d.ts

@@ -0,0 +1,8 @@
+
+declare module 'passport-deezer' {
+    //import {Strategy as Oauth2Strategy} from 'passport-oauth2';
+    import {Strategy as PassportStrategy} from "passport";
+    export class Strategy extends PassportStrategy {
+        constructor(options: any, verify: any);
+    }
+}

src/common/logging.ts

@@ -0,0 +1,341 @@
+import path from "path";
+import {projectDir} from "./index.js";
+import winston, {format, Logger} from '@foxxmd/winston';
+import {DuplexTransport} from "winston-duplex";
+import {asLogOptions, LogConfig, LogInfo, LogLevel, LogOptions} from "./infrastructure/Atomic.js";
+import process from "process";
+import {fileOrDirectoryIsWriteable, truncateStringToLength} from "../utils.js";
+import {ErrorWithCause, stackWithCauses} from "pony-cause";
+import {NullTransport} from 'winston-null';
+import DailyRotateFile from 'winston-daily-rotate-file';
+import dayjs from "dayjs";
+import stringify from 'safe-stable-stringify';
+import {SPLAT, LEVEL, MESSAGE} from 'triple-beam';
+import {Symbol} from "typescript-json-schema";
+
+const {combine, printf, timestamp, label, splat, errors} = format;
+
+
+const {transports} = winston;
+
+export let logPath = path.resolve(projectDir, `./logs`);
+if (typeof process.env.CONFIG_DIR === 'string') {
+    logPath = path.resolve(process.env.CONFIG_DIR, './logs');
+}
+
+winston.loggers.add('noop', {transports: [new NullTransport()]});
+
+export const getLogger = (config: LogConfig = {}, name = 'app'): Logger => {
+
+    if (!winston.loggers.has(name)) {
+        const errors: (Error | string)[] = [];
+
+        let options: LogOptions = {};
+        if (asLogOptions(config)) {
+            options = config;
+        } else {
+            errors.push(`Logging levels were not valid. Must be one of: 'error', 'warn', 'info', 'verbose', 'debug' -- 'file' may be false.`);
+        }
+
+        const {level: configLevel} = options;
+        const defaultLevel = process.env.LOG_LEVEL || 'info';
+        const {
+            level = configLevel || defaultLevel,
+            file = configLevel || defaultLevel,
+            stream = configLevel || 'debug',
+            console = configLevel || 'debug'
+        } = options;
+
+        const consoleTransport = new transports.Console({level: console});
+
+        const myTransports = [
+            consoleTransport,
+            new DuplexTransport({
+                stream: {
+                    transform(chunk, e, cb) {
+                        cb(null, chunk);
+                    },
+                    objectMode: true,
+                },
+                name: 'duplex',
+                handleExceptions: true,
+                handleRejections: true,
+                level: stream,
+                dump: false,
+            }),
+        ];
+
+        if (file !== false) {
+            const rotateTransport = new DailyRotateFile({
+                dirname: logPath,
+                createSymlink: true,
+                symlinkName: 'scrobble-current.log',
+                filename: 'scrobble-%DATE%.log',
+                datePattern: 'YYYY-MM-DD',
+                maxSize: '5m',
+                level: file
+            });
+
+            try {
+                fileOrDirectoryIsWriteable(logPath);
+                // @ts-ignore
+                myTransports.push(rotateTransport);
+            } catch (e: any) {
+                let msg = 'WILL NOT write logs to rotating file due to an error while trying to access the specified logging directory';
+                errors.push(new ErrorWithCause<Error>(msg, {cause: e}));
+            }
+        }
+
+        const loggerOptions: winston.LoggerOptions = {
+            level: level,
+            format: labelledFormat(),
+            transports: myTransports,
+        };
+
+        winston.loggers.add(name, loggerOptions);
+
+        const logger = winston.loggers.get(name);
+        if (errors.length > 0) {
+            for (const e of errors) {
+                logger.error(e);
+            }
+        }
+        return logger;
+    }
+    return winston.loggers.get(name);
+}
+
+const breakSymbol = '<br />';
+export const formatLogToHtml = (chunk: any) => {
+    const line = chunk.toString().replace('\n', breakSymbol)
+        .replace(/(debug)\s/gi, '<span class="debug blue">$1 </span>')
+        .replace(/(warn)\s/gi, '<span class="warn yellow">$1 </span>')
+        .replace(/(info)\s/gi, '<span class="info green">$1 </span>')
+        .replace(/(verbose)\s/gi, '<span class="verbose purple">$1 </span>')
+        .replace(/(error)\s/gi, '<span class="error red">$1 </span>')
+        .trim();
+    if(line.slice(-6) !== breakSymbol) {
+        return `${line}${breakSymbol}`;
+    }
+    return line;
+}
+
+const levelSymbol = Symbol.for('level');
+const s = splat();
+//const errorsFormat = errors({stack: true});
+const CWD = process.cwd();
+
+const causeKeys = ['name',  'cause']
+
+export const defaultFormat = (defaultLabel = 'App') => printf(({
+                                                                   label,
+                                                                   [levelSymbol]: levelSym,
+                                                                   level,
+                                                                   message,
+                                                                   labels = [defaultLabel],
+                                                                   leaf,
+                                                                   timestamp,
+                                                                   durationMs,
+                                                                   [SPLAT]: splatObj,
+                                                                   stack,
+                                                                   ...rest
+                                                               }) => {
+    const keys = Object.keys(rest);
+    let stringifyValue = keys.length > 0 && !keys.every(x => causeKeys.some(y => y == x)) ? stringify(rest) : '';
+    let msg = message;
+    let stackMsg = '';
+    if (stack !== undefined) {
+        const stackArr = stack.split('\n');
+        const stackTop = stackArr[0];
+        const cleanedStack = stackArr
+            .slice(1) // don't need actual error message since we are showing it as msg
+            .map((x: string) => x.replace(CWD, 'CWD')) // replace file location up to cwd for user privacy
+            .join('\n'); // rejoin with newline to preserve formatting
+        stackMsg = `\n${cleanedStack}`;
+        if (msg === undefined || msg === null || typeof message === 'object') {
+            msg = stackTop;
+        } else {
+            stackMsg = `\n${stackTop}${stackMsg}`
+        }
+    }
+
+    let nodes = Array.isArray(labels) ? labels : [labels];
+    if (leaf !== null && leaf !== undefined && !nodes.includes(leaf)) {
+        nodes.push(leaf);
+    }
+    const labelContent = `${nodes.map((x: string) => `[${x}]`).join(' ')}`;
+
+    return `${timestamp} ${level.padEnd(8)}: ${labelContent} ${msg}${stringifyValue !== '' ? ` ${stringifyValue}` : ''}${stackMsg}`;
+});
+
+export const labelledFormat = (labelName = 'App') => {
+    const l = label({label: labelName, message: false});
+    return combine(
+        timestamp(
+            {
+                format: () => dayjs().local().format(),
+            }
+        ),
+        l,
+        s,
+        errorAwareFormat,
+        defaultFormat(labelName),
+    );
+}
+
+export const logLevels = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    http: 3,
+    verbose: 4,
+    debug: 5,
+    trace: 5,
+    silly: 6
+};
+
+export const LOG_LEVEL_REGEX: RegExp = /\s*(debug|warn|info|error|verbose)\s*:/i
+export const isLogLineMinLevel = (log: string | LogInfo, minLevelText: LogLevel): boolean => {
+    // @ts-ignore
+    const minLevel = logLevels[minLevelText];
+    let level: number;
+
+    if(typeof log === 'string') {
+        const lineLevelMatch =  log.match(LOG_LEVEL_REGEX)
+        if (lineLevelMatch === null) {
+            return false;
+        }
+        // @ts-ignore
+        level = logLevels[lineLevelMatch[1]];
+    } else {
+        const lineLevelMatch = log.level;
+        // @ts-ignore
+        level = logLevels[lineLevelMatch];
+    }
+    return level <= minLevel;
+}
+
+const isProbablyError = (val: any, explicitErrorName?: string) => {
+    if(typeof val !== 'object' || val === null) {
+        return false;
+    }
+    const {name, stack} = val;
+    if(explicitErrorName !== undefined) {
+        if(name !== undefined && name.toLowerCase().includes(explicitErrorName)) {
+            return true;
+        }
+        if(stack !== undefined && stack.trim().toLowerCase().indexOf(explicitErrorName.toLowerCase()) === 0) {
+            return true;
+        }
+        return false;
+    } else if(stack !== undefined) {
+        return true;
+    } else if(name !== undefined && name.toLowerCase().includes('error')) {
+        return true;
+    }
+
+    return false;
+}
+
+const errorAwareFormat = {
+    transform: (einfo: any, {stack = true}: any = {}) => {
+
+        // because winston logger.child() re-assigns its input to an object ALWAYS the object we recieve here will never actually be of type Error
+        const includeStack = stack && (!isProbablyError(einfo, 'simpleerror') && !isProbablyError(einfo.message, 'simpleerror'));
+
+        if (!isProbablyError(einfo.message) && !isProbablyError(einfo)) {
+            return einfo;
+        }
+
+        let info: any = {};
+
+        if (isProbablyError(einfo)) {
+            const tinfo = transformError(einfo);
+            info = Object.assign({}, tinfo, {
+                // @ts-ignore
+                level: einfo.level,
+                // @ts-ignore
+                [LEVEL]: einfo[LEVEL] || einfo.level,
+                message: tinfo.message,
+                // @ts-ignore
+                [MESSAGE]: tinfo[MESSAGE] || tinfo.message
+            });
+            if(includeStack) {
+                // so we have to create a dummy error and re-assign all error properties from our info object to it so we can get a proper stack trace
+                const dummyErr = new ErrorWithCause('');
+                const names = Object.getOwnPropertyNames(tinfo);
+                for(const k of names) {
+                    if(dummyErr.hasOwnProperty(k) || k === 'cause') {
+                        // @ts-ignore
+                        dummyErr[k] = tinfo[k];
+                    }
+                }
+                // @ts-ignore
+                info.stack = stackWithCauses(dummyErr);
+            }
+        } else {
+            const err = transformError(einfo.message);
+            info = Object.assign({}, einfo, err);
+            // @ts-ignore
+            info.message = err.message;
+            // @ts-ignore
+            info[MESSAGE] = err.message;
+
+            if(includeStack) {
+                const dummyErr = new ErrorWithCause('');
+                // Error properties are not enumerable
+                // https://stackoverflow.com/a/18278145/1469797
+                const names = Object.getOwnPropertyNames(err);
+                for(const k of names) {
+                    if(dummyErr.hasOwnProperty(k) || k === 'cause') {
+                        // @ts-ignore
+                        dummyErr[k] = err[k];
+                    }
+                }
+                // @ts-ignore
+                info.stack = stackWithCauses(dummyErr);
+            }
+        }
+
+        // remove redundant message from stack and make stack causes easier to read
+        if(info.stack !== undefined) {
+            let cleanedStack = info.stack.replace(info.message, '');
+            cleanedStack = `${cleanedStack}`;
+            cleanedStack = cleanedStack.replaceAll('caused by:', '\ncaused by:');
+            info.stack = cleanedStack;
+        }
+
+        return info;
+    }
+}
+
+export const transformError = (err: Error): any => _transformError(err, new Set());
+
+const _transformError = (err: Error, seen: Set<Error>) => {
+    if (!err || !isProbablyError(err)) {
+        return '';
+    }
+    if (seen.has(err)) {
+        return err;
+    }
+
+    try {
+
+        // @ts-ignore
+        let mOpts = err.matchOptions ?? matchOptions;
+
+        // @ts-ignore
+        const cause = err.cause as unknown;
+
+        if (cause !== undefined && cause instanceof Error) {
+            // @ts-ignore
+            err.cause = _transformError(cause, seen, mOpts);
+        }
+
+        return err;
+    } catch (e: any) {
+        // oops :(
+        // we're gonna swallow silently instead of reporting to avoid any infinite nesting and hopefully the original error looks funny enough to provide clues as to what to fix here
+        return err;
+    }
+}