Fix Sonos abrupt track switches when reordering an active queue (#4237)

Author: marcelveldt

music_assistant/controllers/player_queues.py

@@ -1521,13 +1521,22 @@ async def _enqueue_with_option(
             return
         # handle add: add/append item(s) to the remaining queue items
         if option == QueueOption.ADD:
+            # When shuffling, mix the new items into the not-yet-played tail. While playing,
+            # keep the item right after the buffered one in place: it has already been enqueued
+            # to the player (and prepared for crossfade), so reshuffling it would swap the
+            # upcoming track underneath the player and cause an abrupt, non-crossfaded switch.
+            if not queue.shuffle_enabled:
+                add_at_index = len(self._queue_items[queue_id]) + 1
+            elif queue.state in (PlaybackState.PLAYING, PlaybackState.PAUSED):
+                add_at_index = insert_at_index + 1
+            else:
+                add_at_index = insert_at_index
             await self.load(
                 queue_id=queue_id,
                 queue_items=queue_items,
-                insert_at_index=insert_at_index
-                if queue.shuffle_enabled
-                else len(self._queue_items[queue_id]) + 1,
-                shuffle=queue.shuffle_enabled,
+                insert_at_index=add_at_index,
+                # radio tracks are already ordered in a pattern we want to keep
+                shuffle=queue.shuffle_enabled and not radio_mode,
             )
             # handle edgecase, queue is empty and items are only added (not played)
             # mark first item as new index

music_assistant/providers/sonos/player.py

@@ -71,7 +71,7 @@ class SonosQueue:
     """Simple representation of a Sonos (cloud) Queue."""
 
     items: list[PlayerMedia] = field(default_factory=list)
-    last_updated: float = time.time()
+    last_updated: float = field(default_factory=time.time)
     includes_beginning: bool = False
     includes_end: bool = False
 
@@ -789,6 +789,7 @@ async def _set_sonos_queue_from_mass_queue(self, queue_id: str) -> None:
             self.sonos_queue.items.clear()
             self.sonos_queue.includes_beginning = False
             self.sonos_queue.includes_end = False
+            self._bump_queue_version()
             return
         current_index = queue.current_index or 0
         current_index = (
@@ -832,6 +833,9 @@ async def _set_sonos_queue_from_mass_queue(self, queue_id: str) -> None:
         self.sonos_queue.items = items
         self.sonos_queue.includes_beginning = offset == 0
         self.sonos_queue.includes_end = includes_end
+        # bump only after the new window is assigned (no await in between) so Sonos never sees a
+        # new version while itemWindow still serves the previous items
+        self._bump_queue_version()
         self.logger.log(
             VERBOSE_LOG_LEVEL,
             "Set Sonos queue items from MA queue %s on player %s: %s",
@@ -866,3 +870,13 @@ def _extract_mac_from_player_id(self) -> str | None:
 
         # Format as XX:XX:XX:XX:XX:XX
         return ":".join(mac_hex[i : i + 2].upper() for i in range(0, 12, 2))
+
+    def _bump_queue_version(self) -> None:
+        """
+        Advance the Sonos cloud-queue version to the current time.
+
+        The version is exposed as the queueVersion in the cloud-queue endpoints; advancing it on
+        every window rebuild is what makes Sonos refetch the window instead of replaying a stale
+        cached one.
+        """
+        self.sonos_queue.last_updated = time.time()

music_assistant/providers/sonos/provider.py

@@ -175,7 +175,6 @@ async def _handle_sonos_queue_itemwindow(
         https://docs.sonos.com/reference/itemwindow
         """
         context_version = request.query.get("contextVersion", "1")
-        queue_version = request.query.get("queueVersion", str(int(player.sonos_queue.last_updated)))
         # because Sonos does not show our queue in the app anyways,
         # we just return the previous, current and next item in the queue.
         # the beginning/end flags must be honest though: signalling end-of-queue
@@ -187,7 +186,10 @@ async def _handle_sonos_queue_itemwindow(
             "includesBeginningOfQueue": player.sonos_queue.includes_beginning,
             "includesEndOfQueue": player.sonos_queue.includes_end,
             "contextVersion": context_version,
-            "queueVersion": queue_version,
+            # report the version of the items we actually serve (the current window) instead of
+            # echoing the player's requested version, otherwise a refreshed window keeps a stale
+            # version label and Sonos never realises it changed.
+            "queueVersion": str(player.sonos_queue.last_updated),
             "items": [self._parse_sonos_queue_item(x) for x in items],
         }
         return web.json_response(result)
@@ -201,9 +203,11 @@ async def _handle_sonos_queue_version(
         https://docs.sonos.com/reference/version
         """
         context_version = request.query.get("contextVersion") or "1"
+        # keep sub-second resolution: the window can be rebuilt several times within the same
+        # second and Sonos treats an unchanged queueVersion as "nothing changed" (stale window).
         result = {
             "contextVersion": context_version,
-            "queueVersion": str(int(player.sonos_queue.last_updated)),
+            "queueVersion": str(player.sonos_queue.last_updated),
         }
         return web.json_response(result)
 
@@ -217,7 +221,7 @@ async def _handle_sonos_queue_context(
         """
         result = {
             "contextVersion": "1",
-            "queueVersion": str(int(player.sonos_queue.last_updated)),
+            "queueVersion": str(player.sonos_queue.last_updated),
             "container": {
                 "type": "trackList",
                 "name": "Music Assistant",