From 54eabf49f036ecd00fd7c5fde618685888706118 Mon Sep 17 00:00:00 2001
From: FoxxMD <FoxxMD@users.noreply.github.com>
Date: Tue, 13 Jan 2026 14:53:51 +0000
Subject: [PATCH] feat(sonos): Fix first media seen logging and add debug
 guidance to docs

add env gate to sonos test playground
---
 docsite/docs/configuration/sources/sonos.mdx | 54 +++++++++++++++++++-
 src/backend/sources/SonosSource.ts           |  8 ++-
 src/backend/tests/sonos/sonos.test.ts        | 22 +++++---
 3 files changed, 75 insertions(+), 9 deletions(-)

diff --git a/docsite/docs/configuration/sources/sonos.mdx b/docsite/docs/configuration/sources/sonos.mdx
index 20e4b799..2f48a63b 100644
--- a/docsite/docs/configuration/sources/sonos.mdx
+++ b/docsite/docs/configuration/sources/sonos.mdx
@@ -25,10 +25,62 @@ Activity reporting for **other [Sources](/configuration/sources)** does not work
 
 If you have other Sources configured for Multi-Scrobbler that you may play *through Sonos* you should try to add Sonos to the "deny" list for that Source so that it does not try to monitor Sonos activity. Check the documentation for each individual Source to see how to configure this exclusion.
 
-An example of this for [Plex](/configuration/sources/plex) would be to add Sonos to the "block" list ENV EX: `PLEX_DEVICES_BLOCK=sonos`
+For example, to prevent the [Plex](/configuration/sources/plex) Source from monitoring audio played through Sonos, add Sonos to the "block" list ENV EX: `PLEX_DEVICES_BLOCK=sonos`
 
 :::
 
+<details>
+
+<summary>How to report issues</summary>
+
+If your Sonos Source is logging errors or the scrobble data is not as expected please [create a bug report](https://github.com/FoxxMD/multi-scrobbler/issues/new?template=01-bug-report.yml) **after** enabling the following debug logging options based on the config type you have:
+
+<Tabs groupdId="sonosBugConfig">
+<TabItem value="env" label="ENV">
+
+Enable [Debug Mode](/configuration#debug-mode) using `DEBUG_MODE=true`
+
+</TabItem>
+<TabItem value="file" label="File">
+
+Enable `logPayload` and `logFitlerFailure` in your `sonos.json`, or AIO file, config:
+
+```json
+[
+  {
+    "enable": true,
+    "name": "MySonos",
+    "data": {
+      "host": "192.168.0.150"
+    },
+    "options": {
+      "logFilterFailure":  "warn",
+      "logPayload": true
+     }
+  }
+]
+```
+
+</TabItem>
+
+</Tabs>
+
+Additional logging for the Sonos library may be enabled by including this environmental variable (regardless of config type):
+
+```
+DEBUG=sonos:*
+```
+
+The above changes:
+
+* Triggers multi-scrobbler to log the raw data recieved from Sonos when a new track/device/service is seen for the first time
+* Trigger multi-scrobbler to log the reason it considers a play from Sonos as invalid (and will not monitor it)
+* Logs low-level activity from the Sonos library
+
+Please include these additional logs when creating a bug report. They are essential to troubleshooting your issue.
+
+</details>
+
 ## Configuration
 
 You **must** define the IP address of at least one Sonos/accessory in order for Multi-scrobbler to connect to your Sonos system.
diff --git a/src/backend/sources/SonosSource.ts b/src/backend/sources/SonosSource.ts
index 1fcf89c5..87354b74 100644
--- a/src/backend/sources/SonosSource.ts
+++ b/src/backend/sources/SonosSource.ts
@@ -129,9 +129,13 @@ export class SonosSource extends MemoryPositionalSource {
                 let status = CLIENT_PLAYER_STATE[x.state.transportState];
 
                 let seen = true;
-                if (!this.mediaIdsSeen.data.includes(x.state.positionInfo.TrackURI)) {
+
+                // TrackURI seems to correspond to 1) the device/group playing and 2) the service/source playing
+                // but NOT the content actually playing -- 2) does not update when content playing changes on the same service
+                const mediaId = `${x.state.positionInfo.TrackURI}--${typeof x.state.positionInfo.TrackMetaData !== 'string' ? x.state.positionInfo.TrackMetaData.TrackUri : x.state.positionInfo.TrackMetaData}`;
+                if (!this.mediaIdsSeen.data.includes(mediaId)) {
                     seen = false;
-                    this.mediaIdsSeen.add(x.state.positionInfo.TrackURI);
+                    this.mediaIdsSeen.add(mediaId);
                     if (this.config.options?.logPayload || isDebugMode()) {
                         this.logger.debug({ device: { Name, GroupName, Uuid }, state: x.state }, 'Sonos Data');
                     }
diff --git a/src/backend/tests/sonos/sonos.test.ts b/src/backend/tests/sonos/sonos.test.ts
index c054daae..4fa5e5e3 100644
--- a/src/backend/tests/sonos/sonos.test.ts
+++ b/src/backend/tests/sonos/sonos.test.ts
@@ -20,10 +20,20 @@ const createSource = async (data: SonosData): Promise<SonosSource> => {
     return source;
 }
 
-// it('does stuff', async function() {
+describe('#Sonos', function() {
 
-//     const s = await createSource({host: process.env.SONOS_HOST});
-//     await s.checkConnection();
-//     await s.getRecentlyPlayed();
-//     const f = 1;
-// });
\ No newline at end of file
+    before(function () {
+        if (process.env.SONOS_TEST !== 'true') {
+            this.skip();
+        }
+    });
+
+    it('does stuff', async function() {
+
+        const s = await createSource({host: process.env.SONOS_HOST_TEST});
+        await s.checkConnection();
+        await s.getRecentlyPlayed();
+        const f = 1;
+    });
+
+});
\ No newline at end of file
-- 
2.51.2