Changelog
v0.12.0
What’s New?
Overhauled Historical Scrobble Matching
MS was originally built with only real-time scrobbling as a design goal so the logic behind “check if this track-to-be-scrobbled already exists for Scrobbler X” only extended as far as checking scrobbles MS had already seen, or the first page of scrobbles returned from the scrobbler’s API. MS has long since evolved beyond these (6 year old) goals but the existing scrobble logic had stayed mostly the same which means many users have had problems with MS when it comes to scrobbling old scrobbles that don’t conform to this real-time assumption.
Now, ~3000 changed lines later and thanks to testing from @4rft5 , this logic has been completely overhauled to enable arbitrary time-range checks for any historical scrobbles: allowing MS to scrobble everything with the assurance they won’t be duplicated, regardless of when they were scrobbled.
Note: This is a fully internal, functional change that does not require any changes in configuration or behavior from you, the user.
Some caveats that will be improved in future releases:
- This change does not yet apply to Rocksky or teal.fm due to constraints on searching PDS repositories. This will be addressed in a future release with manual user interaction.
- There may be issues with fetching in some edge cases pertaining to many results returned. EX: you imported scrobbles into a client with no timestamps so “1 hour timerange” contains ~3000 scrobbles – MS may behave unexpectedly in this scenario. Please file an issue if this scenario applies to you.
This change also paves the way for bulk scrobble migrations between clients. Be on the lookout for this in a future release ;)
Improved Support for File/AIO Config in Documentation
File and AIO Configuration for every Source/Client, on the documentation website, has been improved with new tools:
- A schema explorer lets you browse all possible properties of the config to more easily understand its shape and what is required
- A json editor enables you to modify the examples in-place, while validating your changes against the accompanying schema
- You can edit plain json or use the point-and-click for a guided experience if you aren’t comfortable with json yet
These same tools are available on the Config Playground for general AIO editing and exploration.
Breaking Changes
Koito Support in Listenbrainz Client
The Listenbrainz Client previously has partial support for scrobbling to Koito instances due to a partially compatible listenbrainz api. The new historical scrobble logic makes this support impossible so this support has been fully removed.
If you are still using a LZ client for interacting with a Koito instance you need to migrate your configuration to use the official Koito Client configuration.
This does not affect users already using the Koito client.
Spotify Premium
As of March 9th 2026 Spotify no longer allows Spotify Developer Apps to be owned by a non-premium account.
If you have a non-premium account in this scenario you will likely experience 403 errors the next time your authentication needs to be refreshed.
Note that non-premium accounts can still use MS but you need to re-create an app that is owned by a premium account, first. See the Premium Account Required expandable section in the Spotify Source docs for instructions on how to implement this workaround.
Full Changelog
⛰️ Features
- (docs) Implement config example/structure guidance
- (jellyin) Add external URL guidance
- (scrobbler) Implement play-dependent, arbitrary timerange fetching for duplicate checks
- (scrobbler) Re-implement scrobble preload
- (scrobbler) Improved dupe detection
- (ui) Add service status page link to dashboard
- (ui) Default logs to trace
- (No Category) Implement timerange consolidation
- (No Category) Implement better request retry logic
🐛 Bug Fixes
- (discord) Add hidden activity type
- (discord) Don’t throw on unknown activity type
- (lastfm) Check for singular scrobble response
- (lastfm) Fix not returning nowPlaying scrobble
- (lastfm) Default to not including now playing in history response
- (nowPlaying) Scrobbler should report now playing if player state is known nowPlayingMode source
- (plex) Also read MBIDs from
guidfield @owendaprile - (sources) Add a confidence signal to plays generated from authoratiative sources to avoid fuzzy matching repeats
- (transform) Fix missing defaults assignment for stage config parsing
- (transform) Fix user transform default value
- (transform) Fix transform for stage not using name for selection #481
📚 Documentation
- (spotify) Add premium account guidance
- (No Category) Fix broken links and anchors
🚜 Refactor
- (atproto) Replace naive TID impl with @ewanc26/tid
- (docs) Replace docusaurus json-schema-plugin
- (listenbrainz) Remove Koito support
- BREAKING: Remove Koito support
- (source) Reduce logging noise for activity checks
- (No Category) Use trace logging for defaults
- (No Category) Re-implement retry logic for LZ with fixed request init
- (No Category) Reorganized and consolidate source/client types
⚙️ Miscellaneous Tasks
- (No Category) Exclude schema folder from search
- (No Category) Add netlify-specific build command
v0.11.5
What’s New?
Discord Rich Presence
MS now supports using Discord Rich Presence for Now Playing functionality.
This means that any Source that reports Now Playing or a real-time player, can be used to update your Discord status with a “Listening to…” activity :tada:
There are two types of Discord integrations to choose from:
- App integration uses your existing Discord application on your desktop/laptop
- It also supports a containerized version of Discord
- Headless integration communicates directly with Discord’s API gateway so it is not tied to any specific Discord instance
Check out the parent Discord docs page to get an overview of the differences between these integrations.
Upstream Service Status Page
There is now a status page for monitoring the reachability of public services used by some Sources/Clients is available at
https://status.multi-scrobbler.app
This monitor runs on a VPS and checks the uptime of actual APIs for these services, not just landing pages. On a ~minute interval it checks:
- Listenbrainz API
- Musicbrainz API
- CoverArtArchive API
- Last.fm API
- A few MS-hosted support services
The idea is that this monitor can help you check if external service communication issues are internet-wide or if maybe the issue is in your network.
Full Changelog
⛰️ Features
- (discord) Initial implementation #468
- (discord) Artwork fallback and ENV config
- (discord) Add album art functionality
- (discord) Use artwork url if its from a known domain
- (discord) Use release mbid to get coverart if fallback would otherwise be used
- (discord) Implement retry for cover art api
- (musicbrainz) Implement CoverArtArchive API
- (nowplaying) Update now playing based on play presence AND player status
- (scrobblers) Run preCompare transform hook on playing now data
🐛 Bug Fixes
- (scrobblers) Don’t queue now playing data if scrobbler is not ready
- (transform) Use temporally-invariant hash comparison
- (No Category) Fix config validation error source
- (No Category) Fix labels for MS heartbeat task
📚 Documentation
- (discord) Add discord docs
- (discord) Update artwork guidance for cover art archive
- (discord) Add discord container instructions
- (faq) Add connection/dns guidance
- (No Category) Add status page to monitoring section
v0.11.4
What’s New?
- A very small release to fix a bug with parsing Spotify data #470
v0.11.3
What’s New?
Deezer Improvements
Errors in parsing Deezer history have been fixed thanks to @Ectalite graciously sharing Deezer access to restart stalled development.
Additionally, the Deezer Source now supports scrobbling for a child account when the main account is the owner of a Family Plan.
Jellyfin Config Changes
The allowUnknown File Config property has been deprecated and will be removed in a future release.
It has been replaced by the allowMediaTypes list, which enables more granular control over what types of media can be scrobbled. The list should be one or more of the official media types listed in the jellyfin sdk. The undocumented MusicVideo type is also supported.
If you were using "allowUnknown": true, replace it with the below property in your jellyfin.json config:
{ "allowMediaTypes": ["audio","unknown"]}This setting is also now available as an ENV of comma-separated media types.
JELLYFIN_MEDIATYPES_ALLOW=audio,video,musicvideoChangelog
⛰️ Features
- (deezer) Add family account monitoring #344
🐛 Bug Fixes
- (deezer) Fix error list access #344
- (jellyfin) Fix options being required #469
- (jellyfin) Allow all media types when
allowUnknownis true #445 - (No Category) Compatibility for old scrobbles #462
- (No Category) Normalize state param for auth redirect URLs #443
- (No Category) Allow musicvideo media type and use
allowedMediaTypesfor NowPlayingItem check #445
📚 Documentation
- (plex) Add Musicbrainz stage guidance #447
- (No Category) Make compose default tab for installation
- (No Category) Update screenshot
⚙️ Miscellaneous Tasks
- (docker) Add source OCI labels #463 thanks @Kernald
- (No Category) Fix links in issue templates
- (No Category) Remove unused dockerfile
- (No Category) Update git-cliff workflow
- (No Category) Bump lastfm-ts-api version
v0.11.2
What’s New?
Debugging Plays and Help
Plays found in the Source “Tracks Discovered” and Client “Scrobbled/Failed” lists now include a Debug button that, when clicked, copies a json object with data that can be used for troubleshooting issues with multi-scrobbler.

At this stage the data is purely for me to help debug user issues. It should make reproduction of issues much easier and will provide insight into stage modifications. In the future the UI will include a Diff tool to help visualize Play changes over time for self-help.
Check the new Help docs for how to use this debug information to most effectively create an issue for Multi-scrobbler.
Full Changelog
Features
- (scrobblers) Refactor scrobbling functions to capture transactional data
- (No Category) Use json diff to track play changes
- (No Category) Add debug copy action to ui
Bug Fixes
- (librefm) Relax response content-type
- (maloja) Fix logging objects
- (musicbrainz) Check for undefined status #458
- (plex) Do not use album artist MBID when existing artist or is VA #450
- (sonos) Gracefully handle failure when fetching device state #455
- (sonos) Check for UpnpClass existing #398
- (No Category) TS typings for brainz meta and missed recording-track rename
- (No Category) Deep clone discovered plays
Documentation
- (No Category) Comment why compilations don’t work for maloja
- (No Category) Add help docs and update github issue template with play debug data
Refactor
- (sonos) Move device/group filters before track type checks to enable easier user workarounds
v0.11.1
What’s New?
Sonos Source
Sonos devices are now supported as Sources. MS can monitor all devices in your Sonos network given any device’s IP. MS supports multiple listening sessions based on device/zone.
Big thanks to @bkredell for the financial support that enabled me to purchase a speaker to do development with. Without this, the implementation would not have been possible.
ENV Config for all Sources
Previously, Sources that were also Clients could only be configured using File or AIO config. This was due to an old design decision that hasn’t been relevant for quite some time. 0.11.1 removes this superficial limitation so that all Sources can be configured using ENV config. Explicitly, these Sources now have ENV config available:
Memory Optimizations
Several optimizations to reduce memory usage should result in 30-50% less memory used, after startup is finished.
Prometheus Metrics
Multi-scrobbler now exposes a prometheus metrics endpoint with these data points:
- Count of discovered plays per Source
- Count of Queued/Scrobbled/Deadletter scrobbles per Client
- Number of issues per Source/Client
- If any of these metrics is > 0 it means your Source/Client is not operating normally
Musicbrainz Track Search and Plex
One of the MBIDs Plex can provide is a Track MBID, which is associated with a Recording and specific Release. 0.11.1 implements searching by this MBID (generically) and fixes parsing of this ID from plex. Sources that provide this can ensure that the exact album you want for a scrobble is used.
Note: Musicbrainz will not search by this id by default. You will need to use the basicOrIds search method to leverage the Track MBID.
Full Changelog
Features
- (lastfm) Add response content logging #449
- (musicbrainz) Search by track MBID using basicorids #447
- (sonos) Implement Sonos Source #398
- (sonos) Fix first media seen logging and add debug guidance to docs
- (sonos) Add group/device filtering
- (No Category) Add prometheus metrics #438
- (No Category) Implement ENV config for clients as sources
Bug Fixes
- (musicbrainz) Find correct release when release or track mbid is present
- (prometheus) Set content type to plain text #438
Documentation
- (sonos) Update admonitions
- (tealfm) Update tealfm links
- (No Category) Add missing default preset to quickstart MB instructions
- (No Category) Add prometheus usage
Refactor
- (musicbrainz) Rename recording mbid property to recording
- (sonos) Add missing sonos source dynamic usage
- (No Category) Add type label for prometheus metrics
- (No Category) Use compiled json for schema in production
- (No Category) Use dynamic import for components
Miscellaneous Tasks
- (No Category) Add config types to issue template
v0.11.0
What’s New?
Libre.fm Source/Client
Mutli-scrobbler now supports Libre.fm as a Source and Client.
Additionally, if you are running your own Libre.fm instance there are options for defining your own instance as the endpoint.
Musicbrainz Search Improvements
When enhancing your scrobbles with Musicbrainz there are now 1) additional methods for searching and 2) an additional album sorting mechanism to bias matches towards the actual text from your original scrobble.
The order in which searches are executed has also been updated to be fully user-configurable. However, this is a breaking change if you previously had search-related file-config options (fallback*) or are using PRESETS ENV. See Breaking Changes below for how to migrate.
Breaking Changes
Musicbrainz Stage
If you are using the Musicbrainz Stage transformer with any of the following options then you will eventually need to update your config to maintain existing behavior:
- File Config
fallbackAlbumSearchfallbackArtistSearchfallbackFreeTextSearch
- ENV Config
MB_PRESETS
If none of these apply to you no action is required.
If these do apply to you: your existing configuration WILL continue to work but these options have been deprecated and will be removed in a future release. You should still migrate as soon as convenient.
In v0.11.0 Musicbrainz uses a searchOrder list to define the order that search methods are run in. See the Search Methods docs section for more information.
To migrate:
File Config
"fallbackAlbumSearch": truereplace with"searchOrder": ["album"]"fallbackArtistSearch": "native"- replace with
"searchOrder": ["artist"] - and add
"searchArtistMethod": "native"(ornaive)
- replace with
"fallbackFreeTextSearch": "true"replace with"searchOrder": ["freetext"]
The directions above assume you are using each option by itself. If you are using more than one then simply combine replacements.
EX using both fallbackFreeTextSearch and fallbackAlbumSearch, replace with "searchOrder": ["album", "freetext"]
You will likely also want to add isrc and basic search methods to the front of your searchOrder, as this emulates the previous MB search behavior:
"searchOrder": ["isrc","basic","album","freetext"]ENV Config
MB_PRESETS=...adddefaultto beginning of your list IEMB_PRESETS=default,native,sensible
Removed Deprecated Jellyfin Source
The old, webhook-based Jellyfin source has been deprecated since v0.8.4 (September 2024). It has not been in the documentation for well over a year. It has now been fully removed.
Removed Deprecated Plex/Tautulli Sources
The old webhook-based Plex and Tautulli (notification agent) Sources have been deprecated since v0.8.7 (October 2024). They have not been in the documentation for well over a year. They have now been fully removed.
Full Changelog
Features
- (No Category) Librefm Source/Client #401
- (musicbrainz) Improved missing mbid parsing and tests
- (musicbrainz) BREAKING: Replace fallback search with searchOrder for more search control
- (musicbrainz) BREAKING: Improve ENV presets
- (musicbrainz) Add exclusive search by recording MBID #431 thanks @gabeklavans
- (musicbrainz) Implement basic-or-ids search
- (musicbrainz) Implement field scoring
- (plex) Retrieve MusicBrainz IDs #426 thanks @owendaprile
Bug Fixes
- (endpointlz) Mark play as new from source
- (librefm) Log warning for empty account rather than throwing #401
- (mpd) Add missing MPD envs to source building #432
- (musicbrainz) Simplify config parsing and log original ids
- (musicbrainz) Check for release data type before logging #434
- (tealfm) Don’t define brainz artist array if empty
- (No Category) Move preCompare transform hook for clients to the correct place in lifecycle #435
- (No Category) Don’t mutate original error when merging cause stack for logging
- (No Category) Remove cache assignment in child class
- (No Category) Add missing undici dependency #437 thanks @jackwilsdon
Documentation
- (musicbrainz) Update search methods
- (No Category) Improve MB docs
- (No Category) Add read-only install instructions #429 thanks @drake7707
- (No Category) Re-style details and add custom admonition details component
- (No Category) Use AdmonitionDetails
Miscellaneous Tasks
- (No Category) BREAKING: Remove deprecated Jellyfin Source
- (No Category) BREAKING: Remove deprecated Plex/Tautulli Sources
Testing
- (lastfm) Improve artist and mbid parsing
v0.10.8
Changelog
Features
- (tealfm) Implement service filtering and parse isrc/music service from records
Bug Fixes
- (musicbrainz) Don’t assume duration is missing
- (No Category) Convert MB length to seconds #423 #427
- (rocksky) Fix generated name for ENV configured rocksky client #424 thanks to @SilverKnightKMA
Documentation
- (No Category) Add valkey docker compose connection example
Refactor
- (No Category) Move ISRC to main play data
v0.10.7
This release includes more accurate and granular Musicbrainz search, flow control for scrobble transformations, and secrets interpolation into config files.
What’s New?
Flow Control for Scrobble Enhancements
Stages for enhancing your Scrobbles now support Flow Control, enabling you to configure how Scrobbles are transformed based on the outcome of a Stage. Three properties are added to Stage configuration:
onSuccess(defaultcontinue) - If the Stage successfully finishes processingonFailure(defaultstop) - If the Stage encounters an error while processing, or otherwise fails to achieve the transformation resultonSkip(defaultcontinue) - If the Stage does not process the Play data due to stage-levelwhenor other stage-specific skip conditions
This enables more complex transformation scenarios like: only run Native Stage if Musicbrainz Stage fails to find a match.
More Musicbrainz Search Improvements
- Album+title fallback search is now configurable, rather than automatic, using
fallbackAlbumSearch - Search uses ISRC codes to match, if available. This will greatly improve matching when using the Spotify Source
- Musicbrainz docs have been reworked for clarity and to add more examples.
Secrets Interpolation
Multi-scrobbler can now interpolate ENV values directly into any json config files using bracketed identifiers like [[MY_SECRET]].
This enables sensitive data to be removed from config files which should make using secrets injection platforms easier as well as committing configs to git safer.
Quickstart Musicbrainz
The Quickstart docs have been updated to include an optional step for setting up Musicbrainz via ENV.
Full Changelog
Features
- (musicbrainz) Make fallback album search configurable #414
- (musicbrainz) Search by ISRC before anything else #418
- (transformers) Add onSkip flow control #414
- (transformers) Log more transform stage detail for components
- (No Category) Add additional metadata from spotify and for listenbrainz submissions #418
- (No Category) Implement secret interpolation from ENV #420
- (No Category) Log as WARN if there are unmatched interpolation keys
Bug Fixes
- (musicbrainz) Throw errors on pre/post fetch so onFailure works as expected #414
- (musicbrainz) Add missing duration logic
- (spotify) Don’t report player state if spotify api doesn’t return an item #412
- (transformer) Improve stage error logging
- (transforms) Update types to allow json validation without type for user #267
Documentation
- (transformers) Add Flow Control
- (No Category) Add musicbrainz step to quickstart
- (No Category) Better language for mb quickstart section
- (No Category) Add config interpolation docs
- (No Category) Better warnings for ENV interpolation
- (No Category) Improve general transform docs
v0.10.6
Bug Fixes
- (musicbrainz) Wrong default argument for preRequest
- (transformer) Don’t try to build env transformer when no ENV exists