Add API command to get the color palette for any image (music-assistant#4193)

Author: marcelveldt

music_assistant/controllers/metadata.py

@@ -47,6 +47,7 @@
     ItemMapping,
     MediaItemImage,
     MediaItemMetadata,
+    MediaItemPalette,
     MediaItemType,
     Playlist,
     Podcast,
@@ -70,6 +71,7 @@
     update_current_task_progress_text,
 )
 from music_assistant.helpers.api import api_command
+from music_assistant.helpers.colors import get_palette, get_palette_for_url
 from music_assistant.helpers.compare import compare_strings
 from music_assistant.helpers.images import (
     cleanup_thumb_cache,
@@ -648,6 +650,25 @@ def get_image_url(
             return f"{base_url}/imageproxy/{image_id}?size={size}&fmt={image_format}"
         return image.path
 
+    @api_command("metadata/get_image_palette")
+    async def get_image_palette(self, image: MediaItemImage | str) -> MediaItemPalette | None:
+        """
+        Get the color palette extracted from an image.
+
+        The palette follows the Sendspin color@v1 spec (primary, accent, on_dark,
+        on_light, background_dark and background_light). Results are cached, so
+        repeated requests for the same image are cheap.
+
+        :param image: A MediaItemImage to read colors from, or an image URL (either a
+            direct URL or an imageproxy URL as produced by `get_image_url`).
+        """
+        if not isinstance(image, MediaItemImage):
+            return await get_palette_for_url(self.mass, image)
+        try:
+            return await get_palette(self.mass, image.path, image.provider)
+        except (FileNotFoundError, OSError):
+            return None
+
     async def get_thumbnail(
         self,
         path: str,

music_assistant/controllers/players/controller.py

@@ -100,7 +100,7 @@
     get_sendspin_player_id,
 )
 from music_assistant.helpers.api import api_command
-from music_assistant.helpers.colors import get_palette_for_url, peek_palette_for_url
+from music_assistant.helpers.colors import get_palette_for_url
 from music_assistant.helpers.tags import async_parse_tags
 from music_assistant.helpers.util import (
     TaskManager,
@@ -1668,25 +1668,30 @@ def _schedule_palette_fetch(
         :param trigger_update: When True, re-emit player state once palette is ready
                                (current track). When False, only warm the cache (prefetch).
         """
-        if not image_url or peek_palette_for_url(image_url) is not None:
+        if not image_url:
             return
+        # Key the task on the image (not just the player) so a track change always
+        # schedules a fetch for the new image instead of being dropped by an in-flight
+        # fetch for the previous one; repeated schedules for the same image still dedupe.
         slot = "current" if trigger_update else "next"
         self.mass.create_task(
             self._fetch_palette(player_id, image_url, trigger_update=trigger_update),
-            task_id=f"palette_fetch_{player_id}_{slot}",
+            task_id=f"palette_fetch_{player_id}_{slot}_{image_url}",
             abort_existing=False,
         )
 
     async def _fetch_palette(self, player_id: str, image_url: str, *, trigger_update: bool) -> None:
         palette = await get_palette_for_url(self.mass, image_url)
         if palette is None or not trigger_update:
-            return
+            return  # prefetch only warms the cache controller; nothing to attach
         player = self.get_player(player_id)
         if player is None:
             return
         current = player.state.current_media
         if current is None or current.image_url != image_url:
             return  # media changed while fetching
+        # Carry the palette on player state so the (sync) serialization reads it back.
+        player.set_resolved_palette(image_url, palette)
         # Avoid trigger_player_update so a concurrent state-change debounce
         # doesn't cancel our timer via the shared player_update_state task_id.
         self.mass.call_later(

music_assistant/helpers/colors.py

@@ -6,14 +6,14 @@
 chosen (and adjusted where needed) so that every spec-mandated contrast pair
 clears the WCAG AA 4.5:1 threshold.
 
-A process-wide in-memory cache keyed on a hash of provider and image path
-avoids redundant extraction while the server is running.
+Extracted palettes are stored in the cache controller (sqlite), keyed on a
+hash of provider and image path, so results persist across restarts and are
+shared process-wide.
 """
 
 from __future__ import annotations
 
 import asyncio
-from collections import OrderedDict
 from typing import TYPE_CHECKING
 
 from modern_colorthief import get_palette as _mmcq_palette
@@ -30,7 +30,6 @@
     from music_assistant.mass import MusicAssistant
 
 
-_PALETTE_MEMORY_CACHE_MAX = 256
 _PALETTE_QUANTIZE_COLORS = 5
 _COLORTHIEF_QUALITY = 10
 # Minimum contrast ratio between colors (Sendspin color@v1 requires WCAG AA ≥ 4.5:1).
@@ -44,23 +43,13 @@
 _BACKGROUND_ADJUST_STEPS = 20
 _SIMILARITY_THRESHOLD = 60  # squared euclidean RGB distance for accent picking
 
-_RGB = tuple[int, int, int]
-
-_palette_memory_cache: OrderedDict[str, MediaItemPalette] = OrderedDict()
-
-
-def _get_from_memory_cache(key: str) -> MediaItemPalette | None:
-    if key in _palette_memory_cache:
-        _palette_memory_cache.move_to_end(key)
-        return _palette_memory_cache[key]
-    return None
+# Cache controller namespace for extracted palettes. Palettes are
+# content-addressed (hash of provider+path) and deterministic, so a long
+# expiration is safe: a palette only changes if the underlying image changes.
+_CACHE_PROVIDER = "palette"
+_CACHE_EXPIRATION = 90 * 24 * 3600  # 90 days
 
-
-def _put_in_memory_cache(key: str, palette: MediaItemPalette) -> None:
-    _palette_memory_cache[key] = palette
-    _palette_memory_cache.move_to_end(key)
-    while len(_palette_memory_cache) > _PALETTE_MEMORY_CACHE_MAX:
-        _palette_memory_cache.popitem(last=False)
+_RGB = tuple[int, int, int]
 
 
 def _relative_luminance(rgb: _RGB) -> float:
@@ -229,14 +218,24 @@ async def _extract_and_cache(
 ) -> MediaItemPalette:
     img_data = await get_image_data(mass, path_or_url, provider)
     palette = await asyncio.to_thread(extract_palette, img_data)
-    _put_in_memory_cache(key, palette)
+    # Only persist a palette that actually yielded colors; an empty result is
+    # usually a transient decode/download failure that should be retried rather
+    # than cached for weeks.
+    if palette.primary is not None:
+        await mass.cache.set(
+            key,
+            palette.to_dict(),
+            provider=_CACHE_PROVIDER,
+            expiration=_CACHE_EXPIRATION,
+        )
     return palette
 
 
 async def get_palette(
     mass: MusicAssistant, path_or_url: str, provider: str
 ) -> MediaItemPalette | None:
-    """Get the color palette for an image, using a process-wide memory cache.
+    """
+    Get the color palette for an image, backed by the cache controller.
 
     :param mass: The MusicAssistant instance.
     :param path_or_url: Image path or URL (same format as get_image_data).
@@ -246,9 +245,13 @@ async def get_palette(
         return None
     key = create_thumb_hash(provider, path_or_url)
 
-    if cached := _get_from_memory_cache(key):
+    cached: MediaItemPalette | None = await mass.cache.get(
+        key, provider=_CACHE_PROVIDER, base_class=MediaItemPalette
+    )
+    if cached is not None:
         return cached
 
+    # Dedupe concurrent extraction (e.g. now-playing + prefetch) for the same image.
     task: asyncio.Task[MediaItemPalette] = mass.create_task(
         _extract_and_cache,
         mass,
@@ -261,27 +264,6 @@ async def get_palette(
     return await asyncio.shield(task)
 
 
-def peek_palette_for_url(image_url: str | None) -> MediaItemPalette | None:
-    """Return the cached palette for an image URL, or None.
-
-    Memory-only sync lookup. Use to attach a palette to a PlayerMedia without
-    blocking when a prior async fetch has already populated the cache.
-    """
-    if not image_url:
-        return None
-    # /imageproxy/<id>: `image_id` is by construction equal to
-    # `create_thumb_hash(provider, path)` (see MetaDataController.compute_image_id),
-    # which is also the key get_palette() stores under, so we can peek directly.
-    if image_id := _extract_imageproxy_id(image_url):
-        return _get_from_memory_cache(image_id)
-    if extracted := _extract_imageproxy_params(image_url):
-        path, provider = extracted
-    else:
-        path, provider = image_url, "builtin"
-    key = create_thumb_hash(provider, path)
-    return _get_from_memory_cache(key)
-
-
 async def get_palette_for_url(
     mass: MusicAssistant, image_url: str | None
 ) -> MediaItemPalette | None:

music_assistant/models/player.py

@@ -66,6 +66,7 @@
 
 if TYPE_CHECKING:
     from music_assistant_models.config_entries import ConfigEntry, ConfigValueType, PlayerConfig
+    from music_assistant_models.media_items import MediaItemPalette
     from music_assistant_models.player_queue import PlayerQueue
 
     from .player_provider import PlayerProvider
@@ -98,6 +99,11 @@ class Player(ABC):
     _attr_active_source: str | None = None
     _attr_active_sound_mode: str | None = None
     _attr_current_media: PlayerMedia | None = None
+    # Palette for the image currently shown, resolved asynchronously from the
+    # cache controller and carried here so the (synchronous) state serialization
+    # can read it back without blocking. See set_resolved_palette.
+    _attr_current_palette: MediaItemPalette | None = None
+    _attr_current_palette_url: str | None = None
     _attr_needs_poll: bool = False
     _attr_poll_interval: int = 30
     _attr_hidden_by_default: bool = False
@@ -1387,6 +1393,22 @@ def set_current_media(  # noqa: PLR0913
         if custom_data:
             self._attr_current_media.custom_data = custom_data
 
+    @final
+    def set_resolved_palette(self, image_url: str, palette: MediaItemPalette) -> None:
+        """
+        Store the resolved color palette for the currently shown image.
+
+        The palette is resolved asynchronously (from the cache controller) by the
+        PlayerController; it is carried on the player here so the synchronous state
+        serialization can attach it without blocking. May only be called by the
+        PlayerController.
+
+        :param image_url: Image URL the palette was extracted from.
+        :param palette: The extracted color palette.
+        """
+        self._attr_current_palette_url = image_url
+        self._attr_current_palette = palette
+
     @final
     def set_config(self, config: PlayerConfig) -> None:
         """
@@ -1764,9 +1786,6 @@ def __final_active_group(self) -> str | None:
     @final
     def __final_current_media(self) -> PlayerMedia | None:
         """Return the FINAL current media for the player."""
-        # Lazy import to avoid helpers.colors -> helpers.images -> models.plugin cycle.
-        from music_assistant.helpers.colors import peek_palette_for_url  # noqa: PLC0415
-
         # if the player is grouped/synced, use the current_media of the group/parent player
         if parent_player_id := (self.__final_active_group or self.__final_synced_to):
             if parent_player_id != self.player_id and (
@@ -1804,7 +1823,7 @@ def __final_current_media(self) -> PlayerMedia | None:
                     artist=stream_metadata.artist,
                     album=stream_metadata.album or stream_metadata.description or current_item.name,
                     image_url=image_url,
-                    palette=peek_palette_for_url(image_url),
+                    palette=self._resolved_palette(image_url),
                     duration=stream_metadata.duration or current_item.duration,
                     source_id=active_queue.queue_id,
                     queue_item_id=current_item.queue_item_id,
@@ -1836,7 +1855,7 @@ def __final_current_media(self) -> PlayerMedia | None:
                     artist=getattr(media_item, "artist_str", None),
                     album=album.name if album else podcast.name if podcast else description,
                     image_url=image_url,
-                    palette=peek_palette_for_url(image_url),
+                    palette=self._resolved_palette(image_url),
                     duration=media_item.duration,
                     source_id=active_queue.queue_id,
                     queue_item_id=current_item.queue_item_id,
@@ -1850,7 +1869,7 @@ def __final_current_media(self) -> PlayerMedia | None:
                 media_type=current_item.media_type,
                 title=current_item.name,
                 image_url=item_image_url,
-                palette=peek_palette_for_url(item_image_url),
+                palette=self._resolved_palette(item_image_url),
                 duration=current_item.duration,
                 source_id=active_queue.queue_id,
                 queue_item_id=current_item.queue_item_id,
@@ -1870,7 +1889,7 @@ def __final_current_media(self) -> PlayerMedia | None:
                 artist=self.current_media.artist,
                 album=self.current_media.album,
                 image_url=image_url,
-                palette=peek_palette_for_url(image_url),
+                palette=self._resolved_palette(image_url),
                 duration=self.current_media.duration,
                 source_id=self.current_media.source_id or active_source,
                 queue_item_id=self.current_media.queue_item_id,
@@ -1882,6 +1901,12 @@ def __final_current_media(self) -> PlayerMedia | None:
             )
         return None
 
+    def _resolved_palette(self, image_url: str | None) -> MediaItemPalette | None:
+        """Return the carried palette if it matches image_url, else None."""
+        if image_url and image_url == self._attr_current_palette_url:
+            return self._attr_current_palette
+        return None
+
     @cached_property
     @final
     def __final_source_list(self) -> UniqueList[PlayerSource]:

tests/core/test_image_proxy.py

@@ -76,8 +76,8 @@ async def test_image_id_matches_thumb_and_palette_cache_key(
 
     The thumbnail and color-palette caches both key off
     `create_thumb_hash(provider, path)`. If `compute_image_id` ever diverged
-    from that, `peek_palette_for_url` for /imageproxy/<id> URLs would silently
-    stop hitting and the on-disk thumbnail cache would split into two buckets.
+    from that, palette lookups for /imageproxy/<id> URLs would miss and the
+    on-disk thumbnail cache would split into two buckets.
     """
     image_id = metadata_controller.compute_image_id("filesystem", "/local/cover.jpg")
     assert image_id == create_thumb_hash("filesystem", "/local/cover.jpg")

tests/core/test_metadata.py

@@ -0,0 +1,64 @@
+"""Tests for the MetaDataController public API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+from music_assistant_models.enums import ImageType
+from music_assistant_models.media_items import MediaItemImage, MediaItemPalette
+
+from music_assistant.controllers.metadata import MetaDataController
+
+if TYPE_CHECKING:
+    from music_assistant.mass import MusicAssistant
+
+
+@pytest.fixture
+async def metadata_controller(mass_minimal: MusicAssistant) -> MetaDataController:
+    """Construct a MetaDataController with the minimal MA fixture."""
+    await mass_minimal.cache._setup_database()
+    controller = MetaDataController(mass_minimal)
+    mass_minimal.metadata = controller
+    return controller
+
+
+async def test_get_image_palette_dispatches_by_input_type(
+    metadata_controller: MetaDataController, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A MediaItemImage resolves by (path, provider); a plain URL goes via get_palette_for_url."""
+    palette = MediaItemPalette(primary=(1, 2, 3))
+    calls: dict[str, object] = {}
+
+    async def fake_get_palette(_mass: object, path: str, provider: str) -> MediaItemPalette:
+        calls["get_palette"] = (path, provider)
+        return palette
+
+    async def fake_get_palette_for_url(_mass: object, url: str) -> MediaItemPalette:
+        calls["get_palette_for_url"] = url
+        return palette
+
+    monkeypatch.setattr("music_assistant.controllers.metadata.get_palette", fake_get_palette)
+    monkeypatch.setattr(
+        "music_assistant.controllers.metadata.get_palette_for_url", fake_get_palette_for_url
+    )
+
+    image = MediaItemImage(type=ImageType.THUMB, path="cover.jpg", provider="spotify")
+    assert await metadata_controller.get_image_palette(image) is palette
+    assert calls["get_palette"] == ("cover.jpg", "spotify")
+
+    assert await metadata_controller.get_image_palette("https://example/cover.jpg") is palette
+    assert calls["get_palette_for_url"] == "https://example/cover.jpg"
+
+
+async def test_get_image_palette_returns_none_for_unreadable_image(
+    metadata_controller: MetaDataController, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """An image whose data can't be read yields None instead of raising."""
+
+    async def boom(_mass: object, path: str, _provider: str) -> MediaItemPalette:
+        raise FileNotFoundError(path)
+
+    monkeypatch.setattr("music_assistant.controllers.metadata.get_palette", boom)
+    image = MediaItemImage(type=ImageType.THUMB, path="missing.jpg", provider="filesystem")
+    assert await metadata_controller.get_image_palette(image) is None