See 0.8.7 for the recent major changes.

• Fix handling of local (not signed in) users in the new Plex API Source #218

What's New?

Plex API Source

A new Source has been implemented for Plex that uses the official API instead of webhooks. There are many benefits to the new source:

• Does not require Plex Pass (webhooks are Plex Pass only) so all users can use it
• Simplified networking and setup
• Leverage MS's calculated player to better record listening activity instead of relying on Plex's scrobble behavior
• Automatic scrobbling user filtering based on authentication

The old webhook-based Plex Source has been deprecated. See the documentation for migration steps.

Tautulli Deprecation

The Tautulli Source was initially implemented as a way for non Plex Pass users to monitor Plex. I am considering deprecating it for maintainability of the project and because the new Plex API Source should replace it. Please provide feedback if you think it should not be deprecated or what else needs to be implemented for the new Plex source to accommodate your use case.

MS Player Improvements

The internal logic for MS's "player", which is used for calculating play state and listening activity for Source's that report Player position, has had a major rework to leverage a "real-time" simulation of the Source rather than relying on timestamps. There should be no functional change for end-users besides more accurate player reporting. If you notice any regression in behavior or bugs please create an issue.

Daylight Savings Time Fix

Thanks to the users in #214 for discovering and isolating an issue with MS's logging library that caused empty files to be created on dates that transitioned from Standard Time to DST. This release bumps the logging library version that includes a fix for this issue that should save American users the headache European users had to endure 😅

Full Changelog

Bug Fixes

• (No Category) Bump @foxxmd/logging to fix DST rolling file issue

Documentation

• (plex) Clean up api/webhook sections and add migration guide
• (tautulli) Add deprecation notice and discussion link
• (No Category) Fix Jellyfin API migration version

Features

• (player) Implement real-time positional state tracking
• (plex) Initial Plex API Source implementation
• (plex) Add track progress tracking to api source
• (plex) Implement album art for UI
• (ui) Show indeterminate state for non-positional players
• (No Category) Reduce drop reason logging noise for jellyfin/plex API sources
• (No Category) Improved filtering for platform players with multiple states

What's New?

Jellyfin API Improvements

The new Jellyfin API Source was missing a decent amount of polishing from its initial release (#196 #200 #209). This release fixes many bugs and also introduces new configuration for allow/block scrobbling by library and media type enforcement.

Configuration Validation Improvements

The maintenance-mode typescript-json-schema library that was being used to validate configuration has been replaced with the much improved ts-json-schema-generator. Validation rules are now generated at runtime instead of using static files from the project which will make maintenance easier. This change, along with refactored validation logic, should make validation errors in logs easier to read and more specific.

Album Art

Players in Sources on the dashboard now support album art. This has been implemented for Jellyfin and Spotify so far. Other sources will have album art implemented in the future.

Github Issues

The issues template have been refactored to use forms and additional templates have been added for feature requests and source/client suggestions. The new templates should help make bug issues easier to write for new users and easier for me to read!

Full Changelog

Features

• (jellyfin) Add debug options for media data troubleshooting
• (jellyfin) Support and enforce library collection type
• (ui) Improve player ui when in stopped state
• (No Category) Improve client/source schema validation generation and error handling
• (No Category) Implement platform output when building track info

Bug Fixes

• (jellyfin) Guard against undefined playback data #209
• (jellyfin) Guard against active session without now playing data #209
• (jellyfin) Fix not handling stopped session state preventing last play in playlist from scrobbling #209
• (jellyfin) Enforce media type when determining session validity
• (jellyfin) Detect theme song extras play and discard #209
• (ytmusic) Allow authUser to be number or string
• (player) Fix missing calculated status on player stop
• (No Category) Fix some source schemas to reflect documentation WRT optional properties
• (No Category) Fix example configs so they pass validation tests

Documentation

• (No Category) Update jellyfin instructions in quickstart to use API Source
• (No Category) Update/fix docker-compose usage
• (No Category) Fix link typo for flatpak
• (No Category) Enable parsing json5 for AIO examples

Miscellaneous Tasks

• (vscode) Add markdown extension to devcontainer
• (No Category) Migrate bug report template to form
• (No Category) Add templates for feature request and new source/client
• (No Category) Add issue template config
• (No Category) Use silent logger for source config tests
• (No Category) Missing schema package in regular deps and freeze ts version
• (No Category) Replace typescript-json-schema with ts-json-schema-generator

Testing

• (jellyfin) Update valid activity tests
• (No Category) Add tests for example configs and test parsing/validation
• (No Category) Add long timeout to first config parse due to slow schema generation

Ci

• (No Category) Add ACT run for just backend test
• (No Category) Make test workflow reusable and add run sanity check
• (No Category) Fix sanity test checkout ref and shorten APP_VERSION sha usage for PRs

What's New?

• Fix documentation mismatch between new Jellyfin API Source config allow/block options #196
• Fix missing lowercase transform for Jellyfin API Source config options

What's New?

Jellyfin Source API

A new Jellyfin Source that uses the official API library has been implemented. This supersedes and deprecates the existing webhook-plugin-based Jellyfin Source. Benefits of new implementation:

• More accurate information about plays fixes multiple artists reporting
• Eliminates need for exposed MS instance (to Jellyfin) which simplifies networking
• User can authenticate using user/pass OR Api Key
• More attention/development on @jellyfin/sdk should mean better support going forward

See the Jellyfin Source docs for migration steps from webhook to API. The webhook Source will be removed in a future version of MS.

Scrobble Modification Conditions

Scrobbles Modifications, introduced in the last release, can now have "conditional" criteria to help you decide when a search-replace operation on a scrobble should occur.

See the Scrobble Modification docs for how to use this and examples.

Development Improvements

Git Workflow

Workflows for MS have been simplified. The develop branch has been removed in favor of using master as the active development branch. All PRs should now target master instead of develop. Additionally, the develop docker image has been renamed edge.

VS Code

VS Code settings have been committed and docs have been added to make MS development with VS Code as close to one-click as possible. Settings include debug configurations, test running, typescript build, and devcontainer environment.

Full Changelog

Bug Fixes

• (jellyfin) Map AlbumArtist Name property
• (plex) Refactor plex webhook formdata parsing to be more defensive
• (No Category) Bump @foxxmd/logging version to fix read-only system issues -- thanks to @jackwilsdon for the fix in FoxxMD/logging#2
• (No Category) Strip wrapping quotes from base url
• (No Category) Freeze typescript to fix weird unused error directive problem

Features

• (jellyfin) Update schema
• (jellyfin) Refactor Jellyfin source to use Jellyfin API
• (jellyfin) Implement partial WS client for future use
• (modifications) Implement "when" conditions for scrobble modifications
• (modifications) Refactor hooks to accept an array of parts
• (No Category) Improve upstream scrobble refresh logic and caching controls
• (No Category) Add VSCode native dev settings
• (No Category) Add VSCode devcontainer

Documentation

• (No Category) Fix link -- thanks to @jackwilsdon
• (No Category) Fix redirect for local documentation -- thanks to @jackwilsdon
• (No Category) Fix youtube music identifier
• (No Category) Update development docs for VSCode usage
• (No Category) Add when condition docs and examples
• (No Category) Add scrobble modification logging docs

Miscellaneous Tasks

• (ci) Disable alpine builds for PR image
• (ci) Add dependabot PR test gh action
• (deps) Bump the npm_and_yarn group across 2 directories with 7 updates
• (vscode) Add default built task
• (No Category) Refactor git/dev workflow to use master as unstable branch
• (No Category) Fix latest/tag for images and disable alpine builds
• (No Category) Update faker to official release
• (No Category) Update dockerfile to ignore devcontainer and vscode settings

Testing

• (No Category) Add missing version prop for test components

Full Changelog: 0.8.3...0.8.4

What's New?

VLC as Source

VLC has been implemented as a Source. In addition to scrobbling based on reported fields (ID3 tags) of audio tracks played in VLC a user can specify regular expressions to parse artist/title/album information from filenames when no ID3 tag is present.

Recent Scrobbles bug fix

A major bug was fixed that caused a scrobble client to not store upstream scrobbles (used for duplicate checking) on startup.

Youtube Music Woes

Improvements to logging and handling of inconsistent YTM upstream data has been added as well as entries in the FAQ regarding these problems.

Full Changelog

Features

• (vlc) Implement vlc Source #177
• (vlc) Use regex from configuration to extract metadata from filenames
• (youtube) Increase level of auth update logging when configured to output changes #158
• (youtube) Use just-validated history as recently played on new plays #156

Bug Fixes

• (maloja) Improve handling for Maloja warnings-as-errors #180
• (No Category) Actually store recent scrobbles

Documentation

• (vlc) Add VLC docs
• (vlc) Some fixes for VLC docs
• (youtube) Add FAQ entries for YTM auth and scrobble issues

What's New?

MPD (Music Player Daemon) Source

MPD is now a supported Source.

Scrobble Modification

Multi-scrobbler now supports modifying a scrobble (artists, album, track) in-flight using search-and-replace or regex patterns from configuration. The scrobble can be modified:

• on discovery from a source
• during comparison when checking duplicates
• before sending to scrobble client

Why?

You may need to "clean up" data from a Source or before sending to a scrobble Client due to any number of reasons:

• ID3 tags in your music collection are dirty or have repeating garbage IE [YourMusicSource.com] My Artist - My Title
• A Source's service often incorrectly adds data to some field IE My Artist - My Title (Album Version) when the title should just be My Title
• An Artist you listen to often is spelled different between a Source and a Client which causes duplicate scrobbles

In any scenario where a repeating pattern can be found in the data it would be nice to be able to fix it before the data gets downstream or to help prevent duplicate scrobbling. Multi-scrobbler can help you do this. See the documentation for examples and usage.

Deezer Deprecation

Deezer has discontinued support for their API and so the Deezer Source is now deprecated. The Source will continue to function and will not be removed any time soon but it is still recommended to switch to a more stable alternative such as Deezer -> last.fm -> lfm source for multi-scrobbler.

See this issue for more information.

Full Changelog

Bug Fixes

• (tests) Do not re-use scrobbler between tests

Features

• (mpd) Implement MPD Source MVP
• (mpd) Use idle event to wake up from polling early
• (musikcube) Provide more error logging and example config
• (scrobble) Enable forcing existing scrobbles refresh on every scrobble #173
• (ui) Add timestamp to recent pages #167
• (No Category) On polling error retry check source is initialized and reinitialize if not
• (No Category) Implement common play transform functionality
• (No Category) Add album option to play string building function
• (No Category) Improve logging for play transforms
• (No Category) Implement play transforms in source/client logic #173
• (No Category) Implement removing field if field is an empty string after transforming

Documentation

• (deezer) Deprecate due to discontinued API support #175
• (No Category) Add Play Transform docs
• (No Category) Fix compare example

Miscellaneous Tasks

• (ci) Update untagged package schedule to run once a week

Refactor

• (listenbrainz) Simplify scrobble api calls and logging
• (scrobbler) Consolidate refresh logic and add more logging
• (scrobbler) Change refresh force to user-configurable staleness time #173

Testing

• (No Category) Use faker 9.1RC for more plausible artist/album names in generated data

What's New?

This release is entirely for documentation and developer experience improvement.

100% Docusaurus and Self-Hosted Docs

While MS was already using Docusaurus for the docs website the prior approach to writing docs was to keep them as plain markdown as possible so they were still accessible without needing access to an external website. With the "plain" markdown docs you could potentially browse from your own markdown reader in a cloned repository.

The downside to this interoperability is that docs, specifically configuration, had grown to be very long and full of nested/too many headers for each iteration of env/file + regular sections for clients/services. Adding additional examples made the problem even worse.

The solution, then, was to make the Docusaurus documentation part of multi-scrobbler! Now the same docs found at https://foxxmd.github.io/multi-scrobbler can also be found at the /docs URL on your multi-scrobbler instance (http://yourHost:9078/docs)

This enabled me to lean fully into Docusaurus and all of the layout, styling, and organization it offers. Alongside general improvements new docs have been added to help onboarding. Some highlights:

• A Quickstart guide has been added for aiding onboarding
• Improved readability and usefulness of all content in Configuration docs
  • ENV, File, and all-in-one File configuration has moved to Tabs under each Source/Client
    • Switching config type syncs tabs selection across all sections and in the URL
  • Full configuration examples are displayed for file and AIO-file parsed from the examples in the config directory
• Improved styling across all docs
  • Copious usage of collapsed sections for examples to make scanning docs easier
  • Improved Table of Contents with only important headings
  • Admonition elements for increasing readability for tips/notes/warnings...
• Installation docs use Tabs for docker and docker-compose examples
• Actual development docs and tutorial (!)
  • Overview of common development elements
  • Full tutorial for creating a new Source
  • Moved flatpak instructions into docs

And many more...check out the docs site or click on Docs in your MS dashboard to see the updated site.

Flatpak Convenience Setup

A bash script for automating building flatpak from source has been added at flatpak/setup.sh:

• Removes node_modules and generates sources for flatpak-builder for both MS and the docsite
• Builds the flatpak app in a given directory

Effectively making flatpak builds a one-line process rather than the manual 7-8 commands it was before.

See flatpak build instructions in the new docs.

Full Changelog

Documentation

• (feat) Add architecture overview, common dev structures, and dev guidance for Sources
• (fix) Update package scripts to use npx to invoke docusarus
• (fix) Add missing docsite build steps to alpine docker variant
• (flatpak) Implement bash setup script and move flatpak instructions to docsite
• (No Category) Update docusaurus to v3
• (No Category) Update docusaurs playground schema for MS to latest
• (No Category) Improve TOC for docusaurus and github
• (No Category) Implement self-hosted docs
• (No Category) Replace manual notes with admonitions
• (No Category) Lean 100% into docusaurus documentation
• (No Category) Refactor installation.md for docusaurus
• (No Category) Update kitchensink.md code block titles
• (No Category) Parse and render config examples from repository
• (No Category) Add quick start guide
• (No Category) Use relative paths for volume mounting

What's New?

Musikcube Source

Musikcube, a cross-platform terminal-based music player, is now supported as a Source.

Configuration Normalization

In previous versions many of the common, optional options for source/clients, such as maxRequestRetries or maxPollRetries, were mixed into the data property for configs alongside properties that were specific to that source/client. Additionally, there was an existing options property that already had some common properties, but not all...

jellyfin.json

[
  {
    "name": "default",
    "enable": false,
    "clients": [],
    "data": {
      "maxRequestRetries": 3,
      "scrobbleThresholds": {
        "percent": 30,
        "duration": 30
      },
      "users": ["MyUser"]
    },
    "options": {
      "logPayload": false
    }
  }
]

These common properties have been refactored into the options object so that data is now solely for data that is specific to the source/client. This should make configs easier to reason about as well as making programmatic config validity checks easier.

[
  {
    "name": "default",
    "enable": false,
    "clients": [],
    "data": {
      "users": ["MyUser"]
    },
    "options": {
      "logPayload": false,
      "maxRequestRetries": 3,
      "scrobbleThresholds": {
        "percent": 30,
        "duration": 30
      }
    }
  }
]

This is potentially a breaking change, behaviorally, but MS will continue to operate without any changes to your config. The options that have been moved are all optional, minor settings that help fine-tune your experience with MS but do not majorly affect how it works or functionally affect how your sources/clients behave.

If you use any of the properties that have been migrated but have not moved them then MS will simply ignore them until they are moved.

For a complete list of moved properties and how to migrate them see this comment.

Docker Image Change

Due to consistent issues with DNS in alpine-based images ( #160 #126 #134) the image base is being changed to Debian. The image size will increase relatively significantly ( 60MB -> 120MB ) but the benefit is a more stable experience for docker users. Thanks to @Ardakilic for helping diagnose docker image issues and extensive testing/usage of the debian image.

This is not a breaking change but is still a significant refactor. If you have issues with the new default image please open an issue. Alternatively, there will still be an alpine-based image published with a -alpine suffix so you can continue to use the original image if you would prefer, though this may go away in the future.

TLDR

Previously...

• latest or develop or 0.7.1 -> alpine based
• latest-debian or develop-debian ... -> debian-based

Now...

• latest or develop or 0.8.0 -> debian based
• latest-alpine or develop-alpine ... -> alpine-based and may go away in the future

Youtube Music Improvements

The monitoring behavior for YTM has been improved to prevent duplicate scrobbling as well as provide insight into YTM history issues. #156

Additionally, the authentication method for YTM has been improved to save updated cookies from YTM if/when they are changed which may help with authentication issues in long-running MS instances.

Full Changelog

Bug Fixes

• (chromecast) Add missing avahi-utils package for debian image
• (spotify) Convert URL to string for redirectUri
• (vite) Use default base string if no other path detected
• (webscrobbler) Add preflight route #157
• (webscrobbler) Fix formatting of slug url in logs
• (youtube) Catch auth issues that occur during polling #158
• (No Category) Refactor Base URL normalization to cover more cases #155

Documentation

• (No Category) BREAKING: Update schema
• (No Category) Clarify BASE_URL usage and add more examples #155
• (No Category) Add scripting on deploy for plausible analytics
• (No Category) Update screenshot

Features

• (client) Implement initial refresh count and config control #153
• (docker) BREAKING: Use debian image as default
• (youtube) Surface library history playlist and raw recently played for debugging #156
• (youtube) Sync cookies with those returned from YTM responses #158
• (youtube) Use full-fat list diffing to watch for new plays #156
• (No Category) Update normalize-url to prevent port erasure #155

Miscellaneous Tasks

• (ci) Update setup-node to v4 to squash node deprecation warnings
• (No Category) Npm audit fixes
• (No Category) Update dependencies

Refactor

• (client) Use same init logic as source
• (config) BREAKING: Move scrobble thresholds to options
• (config) BREAKING: Move source retry config to options
• (config) BREAKING: Move remaining common options out of source data and into options
• (config) BREAKING: Move common options out of client config and into new option property
• (No Category) Move all init logic into common abstract base class
• (No Category) Use @foxxmd/get-version to render app version

Ci

• (No Category) Use checked out repo to get git info rather than GH variables
• (No Category) Implement gated automated PR building
• (No Category) Add package cleanup and manual triggers

What's New?

Apprise Notification

Support for notifying of scrobbles and errors via Apprise using an apprise-api server. See the docs for configuration.

Disable Web

The API and Dashboard can now be disabled. This can be useful for users who do not want a point of ingress in to MS on insecure networks.

Full Changelog

Documentation

• (No Category) Add config section and config example for disabling web server #150

Features

• (mpris) Less noisy error handling
• (No Category) Implement option for disabling web server #150
• (No Category) Implement notifications via Apprise

Miscellaneous Tasks

• (No Category) Remove some unused packages
• (No Category) Update schema
• (No Category) Bump version for release

Refactor

• (logging) Reduce noise for polling interval logging
• (logging) Balance debug/verbose level logging
• (No Category) Reduce usage of ErrorWithCause
• (No Category) Optimize imports
• (No Category) Use updated logger to reduce log file path logic complexity
• (No Category) Remove pony-cause dependency