fix(backend): discard ScreenScraper chroma-key green placeholder art

gantoine · gantoine · commit 579e12574ca8 · 2026-07-11T07:57:36.000-04:00
ScreenScraper serves a solid chroma-key green (#00FF00) square when a
requested image (box-2D front/back/side) doesn't exist. RomM stored it as
real artwork, so the v2 3D box painted a bright green face and the flat
cover showed green in the gallery.

Detect the placeholder at download time and drop it: covers fall back to
the procedural placeholder, and a discarded box-2D face falls back to the
dark cover placeholder the box already paints (rather than bright green).

- Add _is_chroma_key_placeholder + _discard_if_chroma_key in the resources
  handler; wire into _store_cover and store_media_file.
- store_media_file also cleans up pre-existing green files on rescan.

Generated-By: PostHog Code
Task-Id: 5534668f-a2b6-4575-b6c1-73dcd965062c
diff --git a/backend/handler/filesystem/resources_handler.py b/backend/handler/filesystem/resources_handler.py
@@ -72,6 +72,40 @@ def _check_content_type(
     return True
 
 
+# Some providers (notably ScreenScraper) serve a solid chroma-key green square
+# as a stand-in when a requested image doesn't exist. Persisting it would paint
+# a bright green cover or 3D-box face, so we detect and drop it instead.
+_CHROMA_KEY_GREEN = (0, 255, 0)
+_CHROMA_KEY_TOLERANCE = 24
+_CHROMA_KEY_COVERAGE = 0.9
+
+
+def _is_chroma_key_placeholder(image_path: Path) -> bool:
+    """True if the image is (almost) entirely a chroma-key green fill."""
+    try:
+        with Image.open(image_path) as img:
+            sample = img.convert("RGB")
+            sample.thumbnail((32, 32))  # cheap: sample a downscaled copy
+            raw = sample.tobytes()  # flat RGB triples
+    except (UnidentifiedImageError, OSError, ValueError):
+        return False
+
+    total = len(raw) // 3
+    if total == 0:
+        return False
+
+    r0, g0, b0 = _CHROMA_KEY_GREEN
+    green = 0
+    for i in range(0, total * 3, 3):
+        if (
+            abs(raw[i] - r0) <= _CHROMA_KEY_TOLERANCE
+            and abs(raw[i + 1] - g0) <= _CHROMA_KEY_TOLERANCE
+            and abs(raw[i + 2] - b0) <= _CHROMA_KEY_TOLERANCE
+        ):
+            green += 1
+    return green / total >= _CHROMA_KEY_COVERAGE
+
+
 class FSResourcesHandler(FSHandler):
     def __init__(self) -> None:
         super().__init__(base_path=RESOURCES_BASE_PATH)
@@ -110,6 +144,22 @@ def resize_cover_to_small(self, cover: ImageFile.ImageFile, save_path: str) -> N
 
         small_img.save(save_path)
 
+    async def _discard_if_chroma_key(self, relative_path: str) -> bool:
+        """Remove a just-downloaded image if it's a chroma-key placeholder.
+
+        Returns True when the file was discarded, so callers can treat the
+        artwork as missing (falling back to the dark placeholder).
+        """
+        if not await self.file_exists(relative_path):
+            return False
+
+        if not _is_chroma_key_placeholder(self.validate_path(relative_path)):
+            return False
+
+        log.debug(f"Discarding chroma-key placeholder image {relative_path}")
+        await self.remove_file(relative_path)
+        return True
+
     async def _store_cover(
         self, entity: Rom | Collection, url_cover: str, size: CoverSize
     ) -> None:
@@ -136,6 +186,9 @@ async def _store_cover(
                 # the user's source image if the destination were a hardlink.
                 await self.copy_file(resolved, dest_path, allow_link=False)
 
+                if await self._discard_if_chroma_key(dest_path):
+                    return None
+
                 if ENABLE_SCHEDULED_CONVERT_IMAGES_TO_WEBP:
                     self.image_converter.convert_to_webp(
                         self.validate_path(f"{cover_file}/{size.value}.png"),
@@ -177,6 +230,11 @@ async def _store_cover(
                                 async for chunk in response.aiter_raw():
                                     await f.write(chunk)
 
+                        if await self._discard_if_chroma_key(
+                            f"{cover_file}/{size.value}.png"
+                        ):
+                            return None
+
                         if ENABLE_SCHEDULED_CONVERT_IMAGES_TO_WEBP:
                             self.image_converter.convert_to_webp(
                                 self.validate_path(f"{cover_file}/{size.value}.png"),
@@ -551,48 +609,52 @@ def get_media_resources_path(
         return os.path.join("roms", str(platform_id), str(rom_id), media_type.value)
 
     async def store_media_file(self, url_media: str, dest_path: str) -> None:
-        httpx_client = ctx_httpx_client.get()
         directory, filename = os.path.split(dest_path)
 
         if await self.file_exists(dest_path):
             log.debug(f"Media file {dest_path} already exists, skipping download")
-            return
-
-        # Ensure destination directory exists
-        await self.make_directory(directory)
-
-        # Handle local-file URIs from metadata handlers (gamelist, LaunchBox)
-        if url_media.startswith(LOCAL_FILE_SCHEMES):
-            try:
-                resolved = _resolve_local_file_uri(url_media)
-                if resolved is not None and await AnyioPath(resolved).exists():
-                    await self.copy_file(resolved, dest_path, allow_link=True)
-            except Exception as exc:
-                log.error(f"Unable to copy media file {url_media}: {str(exc)}")
-                return None
         else:
-            # Handle HTTP URLs
-            httpx_client = ctx_httpx_client.get()
-            try:
-                async with httpx_client.stream(
-                    "GET", url_media, timeout=120
-                ) as response:
-                    if response.status_code == status.HTTP_200_OK:
-                        if not _check_content_type(
-                            response,
-                            ("image/", "video/", "application/pdf"),
-                            "media",
-                        ):
-                            return None
+            # Ensure destination directory exists
+            await self.make_directory(directory)
+
+            # Handle local-file URIs from metadata handlers (gamelist, LaunchBox)
+            if url_media.startswith(LOCAL_FILE_SCHEMES):
+                try:
+                    resolved = _resolve_local_file_uri(url_media)
+                    if resolved is not None and await AnyioPath(resolved).exists():
+                        await self.copy_file(resolved, dest_path, allow_link=True)
+                except Exception as exc:
+                    log.error(f"Unable to copy media file {url_media}: {str(exc)}")
+                    return None
+            else:
+                # Handle HTTP URLs
+                httpx_client = ctx_httpx_client.get()
+                try:
+                    async with httpx_client.stream(
+                        "GET", url_media, timeout=120
+                    ) as response:
+                        if response.status_code == status.HTTP_200_OK:
+                            if not _check_content_type(
+                                response,
+                                ("image/", "video/", "application/pdf"),
+                                "media",
+                            ):
+                                return None
+
+                            async with await self.write_file_streamed(
+                                path=directory, filename=filename
+                            ) as f:
+                                async for chunk in response.aiter_raw():
+                                    await f.write(chunk)
+                except httpx.TransportError as exc:
+                    log.error(f"Unable to fetch media file at {url_media}: {str(exc)}")
+                    return None
 
-                        async with await self.write_file_streamed(
-                            path=directory, filename=filename
-                        ) as f:
-                            async for chunk in response.aiter_raw():
-                                await f.write(chunk)
-            except httpx.TransportError as exc:
-                log.error(f"Unable to fetch media file at {url_media}: {str(exc)}")
-                return None
+        # Drop ScreenScraper's green "missing art" placeholder so a box face
+        # (box-2D-back / box-2D-side) falls back to the dark placeholder rather
+        # than rendering bright green. Runs for pre-existing files too, cleaning
+        # them up on rescan.
+        await self._discard_if_chroma_key(dest_path)
 
     async def remove_media_resources_path(
         self,
diff --git a/backend/tests/handler/filesystem/test_resources_handler.py b/backend/tests/handler/filesystem/test_resources_handler.py
@@ -4,13 +4,15 @@
 
 import httpx
 import pytest
+from PIL import Image
 
 from config import RESOURCES_BASE_PATH
 from handler.filesystem.base_handler import CoverSize
 from handler.filesystem.resources_handler import (
     FSResourcesHandler,
     _check_content_type,
     _content_type_essence,
+    _is_chroma_key_placeholder,
 )
 from models.collection import Collection
 from models.rom import Rom
@@ -662,3 +664,101 @@ def test_existing_resources_structure(self, handler: FSResourcesHandler):
         assert isinstance(ra_badges, str)
         assert "retroachievements" in ra_base
         assert "badges" in ra_badges
+
+
+class TestChromaKeyDetection:
+    """Tests for ScreenScraper chroma-key green placeholder handling."""
+
+    @pytest.fixture
+    def handler(self):
+        return FSResourcesHandler()
+
+    def _write_image(self, path: Path, color: tuple[int, int, int]) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        Image.new("RGB", (64, 64), color).save(path)
+
+    def test_detects_solid_chroma_key_green(self, tmp_path):
+        image = tmp_path / "green.png"
+        self._write_image(image, (0, 255, 0))
+        assert _is_chroma_key_placeholder(image) is True
+
+    def test_detects_near_chroma_key_green(self, tmp_path):
+        # Within tolerance of pure #00FF00.
+        image = tmp_path / "near_green.png"
+        self._write_image(image, (10, 250, 8))
+        assert _is_chroma_key_placeholder(image) is True
+
+    def test_ignores_normal_artwork(self, tmp_path):
+        image = tmp_path / "cover.png"
+        self._write_image(image, (85, 62, 152))  # the placeholder purple
+        assert _is_chroma_key_placeholder(image) is False
+
+    def test_ignores_forest_green_artwork(self, tmp_path):
+        # A dark/natural green cover must not be mistaken for the chroma key.
+        image = tmp_path / "forest.png"
+        self._write_image(image, (34, 139, 34))
+        assert _is_chroma_key_placeholder(image) is False
+
+    def test_ignores_non_image_file(self, tmp_path):
+        not_an_image = tmp_path / "data.bin"
+        not_an_image.write_bytes(b"not an image")
+        assert _is_chroma_key_placeholder(not_an_image) is False
+
+    @pytest.mark.asyncio
+    async def test_discard_removes_chroma_key_file(
+        self, handler: FSResourcesHandler, tmp_path
+    ):
+        handler.base_path = tmp_path
+        rel = "roms/1/1/box2d_back/box2d_back.png"
+        self._write_image(tmp_path / rel, (0, 255, 0))
+
+        discarded = await handler._discard_if_chroma_key(rel)
+
+        assert discarded is True
+        assert not (tmp_path / rel).exists()
+
+    @pytest.mark.asyncio
+    async def test_discard_keeps_real_artwork(
+        self, handler: FSResourcesHandler, tmp_path
+    ):
+        handler.base_path = tmp_path
+        rel = "roms/1/1/box2d_back/box2d_back.png"
+        self._write_image(tmp_path / rel, (85, 62, 152))
+
+        discarded = await handler._discard_if_chroma_key(rel)
+
+        assert discarded is False
+        assert (tmp_path / rel).exists()
+
+    @pytest.mark.asyncio
+    async def test_discard_missing_file_is_noop(
+        self, handler: FSResourcesHandler, tmp_path
+    ):
+        handler.base_path = tmp_path
+        assert await handler._discard_if_chroma_key("roms/1/1/nope.png") is False
+
+    @pytest.mark.asyncio
+    async def test_store_media_file_discards_existing_chroma_key(
+        self, handler: FSResourcesHandler, tmp_path
+    ):
+        # A green placeholder already on disk is dropped on rescan, so the box
+        # face falls back to the dark placeholder instead of rendering green.
+        handler.base_path = tmp_path
+        rel = "roms/1/1/box2d_back/box2d_back.png"
+        self._write_image(tmp_path / rel, (0, 255, 0))
+
+        await handler.store_media_file("http://example.com/x.png", rel)
+
+        assert not (tmp_path / rel).exists()
+
+    @pytest.mark.asyncio
+    async def test_store_media_file_keeps_existing_real_art(
+        self, handler: FSResourcesHandler, tmp_path
+    ):
+        handler.base_path = tmp_path
+        rel = "roms/1/1/box2d_back/box2d_back.png"
+        self._write_image(tmp_path / rel, (85, 62, 152))
+
+        await handler.store_media_file("http://example.com/x.png", rel)
+
+        assert (tmp_path / rel).exists()
