Add audio overlay state to PlayerQueue (#295)

Author: marcelveldt

music_assistant_models/enums.py

@@ -668,7 +668,6 @@ class ProviderFeature(StrEnum):
     AUDIO_SOURCE = "audio_source"
     # provider can enumerate sound effect items (live, not library-backed)
     SOUND_EFFECTS = "sound_effects"
-    AUDIO_OVERLAY = "audio_overlay"  # plugin can mix an audio overlay into queue playback
 
     #
     # OTHER FEATURES (plugin-only)

music_assistant_models/player_queue.py

@@ -36,6 +36,13 @@ class PlayerQueue(DataClassDictMixin):
     repeat_mode: RepeatMode = RepeatMode.OFF
     crossfade_enabled: bool = False
     autoplay_enabled: bool = False
+    # audio overlay: a looping sound effect mixed into this queue's playback.
+    # overlay_source holds the selected sound effect (kept when the overlay is
+    # disabled so it can be re-enabled with the same sound), overlay_volume is
+    # the overlay loudness relative to the music in percent (100 = equally loud).
+    overlay_enabled: bool = False
+    overlay_source: ItemMapping | None = None
+    overlay_volume: int = 100
     # smart_fades_active: whether the queue's effective crossfade is currently smart crossfade
     # (i.e. crossfade is on, smart is preferred, and smart fades are available). Derived at runtime
     # by the server, read-only and not persisted; lets clients show a smart-fades indicator.

tests/test_player_queue.py

@@ -1,5 +1,7 @@
 """Tests for the PlayerQueue model (deprecated-key back-compat serialization)."""
 
+from music_assistant_models.enums import MediaType
+from music_assistant_models.media_items import ItemMapping
 from music_assistant_models.player_queue import PlayerQueue
 
 
@@ -26,3 +28,41 @@ def test_autoplay_dont_stop_backcompat_preserved() -> None:
     """The existing autoplay <-> dont_stop_the_music back-compat still holds."""
     d = _queue().to_dict()
     assert d["dont_stop_the_music_enabled"] == d["autoplay_enabled"]
+
+
+def test_overlay_defaults() -> None:
+    """The audio overlay fields have sane defaults."""
+    queue = _queue()
+    assert queue.overlay_enabled is False
+    assert queue.overlay_source is None
+    assert queue.overlay_volume == 100
+
+
+def test_overlay_serialize_roundtrip() -> None:
+    """A populated audio overlay survives a to_dict -> from_dict round-trip."""
+    queue = _queue()
+    queue.overlay_enabled = True
+    queue.overlay_source = ItemMapping(
+        media_type=MediaType.SOUND_EFFECT,
+        item_id="rain-loop",
+        provider="soundlib",
+        name="Rain Loop",
+    )
+    queue.overlay_volume = 40
+    restored = PlayerQueue.from_dict(queue.to_dict())
+    assert restored.overlay_enabled is True
+    assert restored.overlay_source is not None
+    assert restored.overlay_source.media_type == MediaType.SOUND_EFFECT
+    assert restored.overlay_source.item_id == "rain-loop"
+    assert restored.overlay_volume == 40
+
+
+def test_payload_without_overlay_keys_deserializes() -> None:
+    """Payloads from older servers without the overlay keys still deserialize."""
+    legacy = _queue().to_dict()
+    for key in ("overlay_enabled", "overlay_source", "overlay_volume"):
+        legacy.pop(key, None)
+    restored = PlayerQueue.from_dict(legacy)
+    assert restored.overlay_enabled is False
+    assert restored.overlay_source is None
+    assert restored.overlay_volume == 100