Changelog
0.15.0
What’s New?
Apple Music Source
Thanks to the efforts of @Exerra , Apple Music is now implemented as a Source for Multi-Scrobbler!
Exerra, the primary developer of node-musickit-api, discovered that the API access required for MS to monitor listening activity only needs credentials that can be acquired from the browser of a logged in user. Critically, this bypasses the long-standing assumption that a paid apple developer account was required to access these APIs.
Exerra also contributed the entire Apple Music Source implementation to Multi-Scrobbler :crown: If you end up using this Source please consider sponsoring them as a thank you for all this hard work!
Improved Subsonic Playback Reporting
The OpenSubsonic API recently finalized a new spec for Playback Reporting that, when implemented by both the client and server, enables realtime player position reporting/states. This allows MS to track Subsonic players with the same level of accuracy as Spotfy, Jellyfin, and other first-class Sources!
Huge thanks to @JannisPohle for the initial PR on cleaning up subsonic players ( #640 ) but then stepping up to also implement this playback functionality ( #590 ) :crown:
As emphasized above, this new functionality requires that both the Subsonic server and the client you use to play music from that server both implement Playback Reporting. An informational tooltip in the UI Preview will indicate if enhanced reporting is available.
Data Directories Standardization
Previously, all persistent data was stored in the directory defined by the CONFIG_DIR ENV, or defaulted to {projectDir}/config.
Now, these locations are configurable by data type and fallback to OS-standard locations:
- Configuration (
config.json,jellyfin.json, etc…) usesCONFIG_DIRENV or OS-standard locations like$XDG_CONFIG_HOME/multi-scrobbler - Data (
ms.db, logs folder, stored credentials, etc…) usesDATA_DIRENV or OS-standard locations like$XDG_DATA_HOME/multi-scrobbler
Upgrading
If you are using a Docker installation with default volume mounting to /config then no change is required. For backwards compatibility, the docker image installation defaults both of these ENVs to /config.
For users using the nodejs/local installation, you will likely want to explicitly set both ENVs for your start command. For instance, if you are currently storing everything in the config folder within the cloned repository and the working directory is also the repository folder then add these ENVs to the beginning of your command:
CONFIG_DIR=./config DATA_DIR=./config ... npm run startSee the Config and Data Directories section in the installation docs to find the OS-standard locations MS will use when these ENVs are not set.
Monitoring Behavior
In preparation for wider usage, the feature known as “Should Scrobble Behavior” has been renamed to “Monitoring Behavior”. The configuration naming has been changed to reflect this.
Upgrading
If you are an Icecast or Azuracast user who has systemScrobble in your File/AIO config options, rename this property to autoMonitor. The behavior for this property remains the same.
Example
Old:
[ { "name": "Station 1", "id": "myIceStation1", "data": { "url": "http://myIcecast.com/radio" }, "options": { "systemScrobble": true } }]New:
[ { "name": "Station 1", "id": "myIceStation1", "data": { "url": "http://myIcecast.com/radio" }, "options": { "autoMonitor": true } }]Config Improvements
Internally, config has undergone a complete overhaul and is now entirely built using Zod. This is a huge improvement over the hacky typescript-types-to-json-schema generator that was being used because the config shape now fully dictates validation, rather than there being a reflection middle step. It additionally removes the ajv library and saves almost 30MB in the docker image when uncompressed.
With the overhaul, a simplification of the config reduced development complexity and made the config explorer in docs clearer, at the expensive of a few, potential breaking changes.
Upgrading
User Stage Transforms
If you have User Stage transforms and they do not already have a "type": "user" property, you need to now add this property or validation will throw an error.
Example
Previous User Transform config could be untyped like
"options": { "playTransform": { "preCompare": [ { "title": [ "badTerm", ] } ], }Now, all user transforms must be typed like all other transforms or config parsing will throw an error:
"options": { "playTransform": { "preCompare": [ { "type": "user", "title": [ "badTerm", ] } ], }Removed Deprecated Cache Config
Cache Configuration was simplified in 0.14.0 but using pre-0.14.0 configuration only caused a deprecation warning. Now, these deprecations have been removed and using the old configuration will cause an error.
Node Native Runtime
Multi-Scrobbler has been refactored to remove the dependency on tsx as the runtime. Now, MS uses Nodejs’ type stripping so that it can directly run the source typescript files without needing the typescript runtime or any compilation steps.
This reduces packaging, tooling, and local run complexity:
- environments do not need to rely on
npmscripts for running MS- or needing to specify the tsx binary with node for commands
- Improves process monitoring readability
- Reduces memory usage since typescript does not need to be loaded into memory
- Reduces disk space since typescript does not need to be installed to run in production
- Tooling calls (mocha, vscode extensions) can directly use node without a shim
If you are currently running MS without using npm run start and have questions about how to migrate please open a discussion.
UI Preview Improvements
The New UI Preview introduced in 0.14.2 has seen several rounds of refinement thanks to user feedback. It is still in “read-only” mode for this release but the next release will begin to introduce write functionality. Check out the preview on your instance:
http://yourMsDomain/nextand share your feedback in the github issue!
Other Changelog Highlights
🐛 Bug Fixes
- (client) Correct create/update timestamps for queues and scrobbles
- (client) Correct SOT scrobble api requests to not have the same from/to value
- (listenbrainz) Fix play fetch more indicator
- (musicbrainz) Catch scenario where all search prereqs fail
- (rocksky) Fix missing albumArtist field #632
- (ui) Stabilize play timeline item order
- (mpd) Assign empty array if artists not defined #621
- (No Category) Fix play fetch options logging data for pageless functions
🧪 Testing
- (No Category) Fix db error test using transient db
Changes Since RC1
⛰️ Features
- (No Category) Reduce db write frequency when idle by buffering date updates #653
🐛 Bug Fixes
- (webscrobbler) Fix bad access of PlayerState #650
- (No Category) Fix missing logPath base dir argument
- (No Category) Guard against tracks/track in mb recording medium #649
📚 Documentation
- (No Category) Add missing user type to user transform examples
- (No Category) Clarify when activity is scrobbled
0.14.2 - UI Preview
What’s New?
Historical Scrobble Matching for teal.fm/Rocksky
Multi-Scrobbler checks your scrobble clients to see if an incoming Play was already scrobbled. This process was previously overhauled in v0.12.0 to make it work for any arbitrary time range, but this overhaul did not include teal.fm and Rocksky due to limitations in how querying atproto records works.
In v0.14.2 this has been resolved so that these clients have the same arbitrary timerange functionality matching as all other clients. This is achieved by initially downloading a full copy of your record and converting them into MS scrobbles to store in the new database. Then, the copy is kept in sync with real time queries to the atproto api. MS then queries this copy when matching scrobbles.
New UI Preview
The UI for MS has been fully rewritten and a preview is now available alongside the normal UI. Some highlights:
- mobile-first design
- live, visual updates for all activity
- search and filter all of your scrobbles
- scrobble timeline shows how MS processed your scrobble data from end-to-end
It can be used by navigating to
http(s)://yourMsDomain/nextI need your feedback on bugs, opinions on design choices, and general usage impressions! Refer to the github issue for the preview ui for more details and to provide feedback.
Some screenshots from the preview ui:
Left: Source/Client list (main page) | Right: Source detail page with Plays
Left: Scrobble duplicate check results | Right: musicbrainz transformer “no results” with used queries
visual indicator of live activity (just scrobbled) on main page
v0.14.1
Full Changelog
🐛 Bug Fixes
- (ui) Update JSX namespace to fix missing ambient in react 19
- (No Category) Fix argument order for logger labels
- (No Category) Add missing artist credit transforms causing Navidrome Source plays to create errors #613
⚙️ Miscellaneous Tasks
- (No Category) Re-generate lock file
v0.14.0
What’s New?
I am excited to release Multi-Scrobbler 0.14.0 :tada: This is one of the largest releases for MS in years which significantly rewrites large portions of MS’s architecture to allow it to scale in preparation for even more exciting, near-future functionality like the upcoming ui overhaul and eventual bulk scrobble transfer feature (move all your scrobbles from Client X to Client Y).
Stats for this release:
- 158 commits
- 243 files touched
- +15,400 additions
- -4,200 deletions
- No AI was used during development. This is organic, free-range coding.
I want to acknowledge and say a big thank you to all the users who helped test and give feedback during this release process. Your input, patience, and reporting was invaluable :heart: :
@4rft5 @FestiveByteRider @gabeklavans @psyciknz @DigitalStarSys @owendaprile @timmyhbk @Sioeen @Ectalite @HStep20
Backend Overhaul
This release introduces a huge architectural upgrade for the backend: almost all data is now backed by a sqlite database powered by drizzle.
Some visible change highlights:
- Discovered plays (from sources) are persisted
- Backlogged, already discovered plays are not re-sent to clients on each startup (they are found in database and ignored)
- Scrobbled plays (successfully sent by clients) are persisted
- Reduces dupe scrobbles since identical scrobble data in MS can now be compared across restarts
- Database migrations are automatic and also automatically make a backup of your database before upgrading
- All queues and Plays are now managed in database instead of in-memory
- Reduced memory usage in all usecases
- Drastically reduced memory when there are many sources/client (5+) or many queued scrobbles (100+)
- Source and Client statistics are persisted
- (breaking) Simplified cache configuration to leverage database where feasible
To prepare for database usage in 0.14.0, please read the Upgrade Path docs.
The migration should be simple for the majority of users. For edge cases and power users, the docs cover how to migrate more advanced settings.
Documentation Improvements
The introduction of the database forced a good look at, and cleanup of, the existing docs. Application-wide config should now be easier to read and the kitchensink examples are now more straight-forward and relevant to common usecases.
Other Changes (Changelog Highlight)
⛰️ Features
- (database) Implement database structures needed for historical plays
- (database) Track component last ready and last active at
- (tealfm) Add now playing support with
fm.teal.alpha.actor.statusby @HiiJax :tada: - (tealfm) Update lexicon defs with new mbid uri format teal-fm/teal#102
- (now playing) More robust handling of clients with real time status updates (teal, discord) #608
- (now playing) reduced logging noise
- (lastfm) bypass scrobble rejection for very short tracks (< 30 seconds) by omitting duration #596
- (No Category) refactor artists to directly map/associate MBIDs
⚙️ Miscellaneous Tasks
- (No Category) update all dependencies #594 by @philocalyst :tada:
📚 Documentation
- (lastfm) Document 2 week scrobble window
- (No Category) Overhaul kitchensink
- (No Category) Add
_IDand_NAMEexamples to all instances of ENV configs - (No Category) Add
idto all instances of file/aio configs - (No Category) Add more descriptive error logging for example config file parsing
0.13.3
What’s Changed
🐛 Bug Fixes
- (transform) Fix bad usage of cache potentially causing older-timestamped plays to be returned when newer play data was identical
- (spotify) Don’t use platform creation timestamp as
stateLastUpdatedAt, fixes spotify player accidentally going stale while still active
⚙️ Miscellaneous Tasks
- (lastfm) Increase connection test timeout for slow networks and add DNS resolution logging
v0.13.2
What’s New?
Discord Improvements
- Fall back to using release group MBID to retrieve album art if the defined release does not have associated art
- Use zero-width padding to allow single-character titles
Fresher Now Playing
For Sources that support multi-platform (plex, jellyfin), MS will more aggressively mark players as stale when there has been no activity but the Source still reports a player is alive. It will also switch Now Playing to the player that has actual activity if the “current” Now Playing player goes inactive (paused, stopped, stale).
Duplicate Scrobble Detection Docs
A new section in the docs has been added that goes into depth on:
- How MS detects duplicate scrobbles
- Configurations that won’t cause dupes
- Configurations that MAY cause dups
- Solutions for avoiding these scenarios
Full Changelog
⛰️ Features
- (discord) Implement fallback to release group art if present #578
- (endpointlz) Add stubbed playing-now route to make some clients happy(er) #579
- (endpointlz) Implement proper username handling for validate and now-playing routes #579
- (lastfm) Add more logging to auth process and clean up host detection
- (mpd) Rewrite with newer MPD client for better payload parsing #574
- (player) Skip stale updates based on state timestamp and prevent dead players from being created from stale updates
- (source) Add timestamps to play state to track player and play last updated, if present
🐛 Bug Fixes
- (cache) Explicitly define auth/metadata as memory when testing file caching
- (discord) Include known spotify cdn for media providers #569
- (discord) Workaround activity minimum character limit #578
- (endpointlz) Fix fallback route not returning a response
- (lastfm) Fix total results reporting for librefm
- (now playing) Prefer fresher players #480
- (player) Initialize player state in the past to prevent false positive on stale update check if update happens at the same time player is initialized
- (transformer) Try-catch cached steps and fallback to non-cache generation
- (webscrobbler) Convert express wildcard path to regex #583
- (No Category) Check undefined on correct property #567
- (No Category) Simplify listenrange usage
- (No Category) Fix missing await on stagger mapper initial sleep
- (No Category) Workaround for old play structure
📚 Documentation
- (mpd) Add permission guidance
- (No Category) Add base site env detection for cloudflare pages
- (No Category) Order BASE_SITE first to allow overriding other envs
- (No Category) Fix missing backticks causing template errors on version equality
- (No Category) Try to replace canonical urls for github.io with new site
- (No Category) Add duplicate scrobble guidance
- (No Category) Remove extra dupe detection section from client overview
🚜 Refactor
- (No Category) Replace fast-deep-equal with fast-equals #569
🧪 Testing
- (player) Fix incorrect variable used for advanced timestamp
⚙️ Miscellaneous Tasks
- (No Category) Remove references to KOITO_ALLOWED_HOSTS (#581) thanks @gabehf
- (No Category) Override rate-limit-threshold to use new version with reduced dependencies
v0.13.1
Changelog
- fix: Add missing next() invocation preventing ingress Sources from completing requests #561 #562
v0.13.0
What’s New?
Yandex Music Source
Thanks to @Druidblack for implementing a new source for the Yandex Music service! :tada:
Check the docs for setup and configuration.
Improved Source/Client Restart
An overhaul of the functionality responsible for Source polling and Client scrobble processing makes restarts from the dashboard cleaner and more dependable. There shouldn’t be any more instances of unable to restart due to waiting for signal... :tada:
New Docs Domain and Social Previews
Docs are now “officially” located at https://docs.multi-scrobbler.app
Docs have also been improved with nice social graph preview images (og:image) that will display when a page is shared on a social site. There are images generated for each page that include the page title and/or description.
Docker Log Colors
Logs viewed through docker logs now have ~f a n c y~ colors that mirror what is seen in the dashboard.
These are turned on by default but if you prefer plain logs they can be disabled by setting this environmental variable:
COLORED_STD=falseImage Cleanup Space Savings 🧹
Fixing how the frontend is served from the backend enabled almost all frontend packages to be removed from the production build. This, along with a node_modules cleanup script, results in a ~32% decrease in docker image size.
Breaking Changes
Changelog Highlights
⛰️ Features
- (client) Make scrobble processing abortable
- (client) Strict ENV types
- (docker) Use prune-mod to remove unneeded files in image
- (docker) Make colored console output the default
- (docs) Update docusaurus to 3.9.2
- (musicbrainz) Handle rate limiting within api calls
- (source) Make discover abortable
- (sources) Better type enforcement
- (yandex) add yandex music by @Druidblack #523
🐛 Bug Fixes
- (jellyfin) Fix typo on devicesBlock env assignment #522
- (scrobbler) Fix stagger map generation variable usage
- (No Category) Fix circular dependency in error utils
- (No Category) Align dockefile and devcontainer node/npm versions to fix lockfile mismatch
- (No Category) Initialize plays in correct scope
- (No Category) Build vite-express config based on production env to avoid making vite fallback to development
⚙️ Miscellaneous Tasks
- (No Category) Remove unused testing libraries and fix storybook version
- (No Category) Update node/npm engine constraints in package.json
- (No Category) Bump node to 24
- BREAKING: Bump node to 24
📚 Documentation
- (No Category) Add Yandex Music Source docs
- (No Category) Replace instances of foxxmd.github.io
- (No Category) Finalize a working social card strategy
🚜 Refactor
- (No Category) Implement abortable source polling
- (No Category) Reduce docker image by moving frontend packages to devDependencies
- (No Category) Install expressjs@5
- (No Category) Replace awaitjs/express with express usage
🧪 Testing
- (No Category) Make loop stop wait time configurable so tests run faster/more stable
v0.12.2
Changelog
- Fix play initialization not being reset on each API fetch invocation
v0.12.1
What’s New?
Music Assistant Source
Music Assistant 2.8.0 was released with support for custom Listenbrainz scrobbling URL which means the Multi-Scrobbler Listenbrainz Endpoint Source can now be used for scrobbling from Music Assistant! :tada:
See the Music Assistant setup instructions inside the LZ Endpoint docs to get started.
Notable Fixes and Improvements
- Fixed issues with transform re-use and caching #495 #510 #481
- Improved memory usage for caching and queued scrobbles #507 #484
- Everyone should consider setting up caching with valkey
- Fixed and improved dead scrobble retry behavior #488 #489
- Added Grafana dashboard for use with Prometheus metrics, thanks to @4rft5
Upcoming UI Overhaul
Many of the changes in this release are non-visible improvements/refactoring in preparation for a complete rewrite of the UI. If you would like see a preview of the UI or add feedback on what you’d like to see in a new UI, please check out Issue #500
Changelog
⛰️ Features
- (listenbrainz) Use upstream for backlogged
- (lzendpoint) Update json body parsing to support Music Assistant
- (scrobble) Increase default dead letter retries from 1 to 3
- (No Category) Implement play with lifecycle fixture
- (No Category) Add step and flow result to lifecycle
- (No Category) Add seenAt to source/client play meta
- (No Category) Skip fetching backlogged plays entirely if scrobbleBacklog=false
- (No Category) Add cache stats to prometheus metrics
🐛 Bug Fixes
- (musicbrainz) Catch recordings with no releases
- (scrobble) Improve dead scrobble iteration and logging
- (scrobble) Improve ui/api experience for dead scrobble processing
- (test) Fix expected plays for YTM interim plays
- (No Category) Remove schema-plugin types hint from docusaurus config
- (No Category) Fix type-erased meta property for json plays
- (No Category) Fix wrong operation for maxRandomStagger
- (No Category) Add stagger options as injected dependency to make tests faster
- (No Category) Better handling when stage fails but should continue
- (No Category) Refactor play tranforming to dogfood steps and fix caching #495
- (No Category) Fix sleep time between consecutive dead scrobble attempts
- (No Category) Only enable metrics collection for real runs
- (No Category) Use lifecycle invariant play for closest match
📚 Documentation
- (No Category) Add duplicate scrobble detection explanation
- (No Category) Add Music Assistant to lz endpoint docs
- (No Category) Add prometheus usage
- (No Category) Add netlify badge to footer on preview docs
- (No Category) Add more caching guidance
- (No Category) Fix discord link on jellyfin page
- (No Category) Add grafana dashboard
- (No Category) Simplify installation
- (No Category) Add music assistant to readme
🚜 Refactor
- (No Category) Move some utils into core folder
- (No Category) Fix JsonPlayObject to properly type dates
- (No Category) Separating functions so they are usuable by frontend storybook
- (No Category) Move stagger config responsibility to transformer
- (No Category) Refactor cache building to be able to specify both primary and secondary
- (No Category) Remove ttl from mb api to ensure primary/secondary ttl is used correctly