media: four defects in asset detection and claiming

Case: the scan compared addon folder names exactly as stored, so
PUPVideos - the casing PinUP Popper writes - was not detected, while the
API lowercased and found it. One table, two answers. The scan already
folded case for .directb2s and .ini three lines above.

Claiming: --claim-user-media only checked medias/<canonical name>, so a
hand-placed wheel.jpg, a spec-named "(Wheel) <folder>.png" or a file at
the folder root was never claimed and stayed replaceable by the next
download. It now claims what actually resolves - the file the frontend
displays. The chain grew in 3.0 and this path never followed it.

specs_for_table_type: the per-table-type copies were rebuilt from four
fields, so every copy reported no spec token, no fallback kind, no set
support, and the image family for video kinds. Nothing reads those off a
copy today, which is the only reason it wasn't a bug. Copy the spec and
change the key instead.

Media download: dropped the bg_video request - vpinmediadb has never
carried one at any resolution - and stopped asking for fss_video, which
does not exist either. Both were silent no-ops. The backglass video and
the FSS playfield video are yours to supply.

PAR-16 and PAR-17 record the two a user can see.

Author: MizterB

common/media_paths.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from pathlib import Path
 
 # Extension families, ordered: resolution tries them in order and the first hit
@@ -73,10 +73,16 @@ def stem(self, table_type: str = "table") -> str:
 
 
 def specs_for_table_type(table_type: str = "table") -> list[MediaSpec]:
+    """The spec list with the playfield keys renamed for this table type.
+
+    Only the key changes: replace() copies the rest, so a spec from here still
+    carries its token, extension family, fallback and set support. Rebuilding one
+    field by field silently handed back defaults for everything not passed.
+    """
     specs: list[MediaSpec] = []
     for spec in MEDIA_SPECS:
         key = table_type if spec.key == "table" else f"{table_type}_video" if spec.key == "table_video" else spec.key
-        specs.append(MediaSpec(key, spec.attr, spec.filename_template, spec.asset_group))
+        specs.append(replace(spec, key=key))
     return specs
 
 

common/online/vpsdb_media.py

@@ -93,7 +93,11 @@ def process(media_type, metadata, key, filename, default_filename):
         process("realdmd_color", table_media, "realdmd_color", table.realDMDColorImagePath, str(default_media_path(table.fullPathTable, "realdmd_color", self.tabletype)))
         process("flyer", table_media, "flyer", table.FlyerImagePath, str(default_media_path(table.fullPathTable, "flyer", self.tabletype)))
         process(self.tabletype, table_media.get(self.tableresolution), self.tabletype, table.TableImagePath, str(default_media_path(table.fullPathTable, self.tabletype, self.tabletype)))
-        process("bg_video", table_media.get(self.tablevideoresolution), "bg_video", table.BGVideoPath, str(default_media_path(table.fullPathTable, "bg_video", self.tabletype)))
+        # Videos, and only the ones the index actually carries. There has never been
+        # a bg_video at any resolution, so the backglass video is yours to supply.
+        # Nor is there an fss_video: under table type fss the playfield video is
+        # simply not offered, and asking would quietly fetch nothing.
         process("dmd_video", table_media.get(self.tablevideoresolution), "dmd_video", table.DMDVideoPath, str(default_media_path(table.fullPathTable, "dmd_video", self.tabletype)))
-        process(f"{self.tabletype}_video", table_media.get(self.tablevideoresolution), f"{self.tabletype}_video", table.TableVideoPath, str(default_media_path(table.fullPathTable, f"{self.tabletype}_video", self.tabletype)))
+        if self.tabletype == "table":
+            process("table_video", table_media.get(self.tablevideoresolution), "table_video", table.TableVideoPath, str(default_media_path(table.fullPathTable, "table_video", self.tabletype)))
         process("audio", table_media, "audio", table.AudioPath, str(default_media_path(table.fullPathTable, "audio", self.tabletype)))

common/tables/metadata_service.py

@@ -6,7 +6,7 @@
 from common.config_access import MediaConfig, SettingsConfig
 from common.iniconfig import IniConfig
 from common.jobs import JobReporter
-from common.media_paths import media_filename_map
+from common.media_paths import MEDIA_SPECS, resolve_media_files
 from common.tables.metaconfig import MetaConfig
 from common.paths import get_ini_config
 from common.tables.standalonescripts import StandaloneScripts
@@ -139,25 +139,45 @@ def claim_media_for_table(table, tabletype, log=None):
         log(f"  Skipping {table.tableDirName}: no .info file")
         return 0
 
-    media_files = {
-        key: filename
-        for key, filename in media_filename_map(tabletype).items()
-        if key != "audio" and (key != "fss" or tabletype == "fss")
-    }
+    # Claim whatever actually resolves, not just the canonical filename. Asking the
+    # resolver is the only way a hand-placed wheel.jpg, a spec-named
+    # "(Wheel) <build>.png" or a file at the folder root gets claimed - checking
+    # medias/wheel.png alone left every one of them unclaimed, and therefore still
+    # replaceable by the next media download.
+    table_dir = table.fullPathTable
+    medias_dir = os.path.join(table_dir, "medias")
+    try:
+        table_contents = {entry.name for entry in os.scandir(table_dir) if entry.is_file()}
+    except OSError:
+        table_contents = set()
+    medias_contents = set()
+    for root, _dirs, files in os.walk(medias_dir):
+        rel = os.path.relpath(root, medias_dir)
+        prefix = "" if rel == "." else f"{rel.replace(os.sep, '/')}/"
+        for filename in files:
+            medias_contents.add(f"{prefix}{filename}")
+
+    resolved = resolve_media_files(table_dir, table_contents, medias_contents, tabletype)
 
-    medias_dir = os.path.join(table.fullPathTable, "medias")
     meta = MetaConfig(info_path)
     claimed = 0
 
-    for media_key, filename in media_files.items():
-        filepath = os.path.join(medias_dir, filename)
-        if os.path.exists(filepath):
-            existing = meta.getMedia(media_key)
-            if existing and existing.get("Source") == "user":
-                continue
-            meta.addMedia(media_key, "user", filepath, "")
-            log(f"  Claimed {media_key} ({filename}) as user media")
-            claimed += 1
+    for spec in MEDIA_SPECS:
+        if spec.key == "audio" or (spec.key == "fss" and tabletype != "fss"):
+            continue
+        path = resolved.get(spec.key)
+        if path is None:
+            continue
+        # The key the download path checks before it skips a kind, so a claim here
+        # is a claim it will honour.
+        media_key = (tabletype if spec.key == "table"
+                     else f"{tabletype}_video" if spec.key == "table_video" else spec.key)
+        existing = meta.getMedia(media_key)
+        if existing and existing.get("Source") == "user":
+            continue
+        meta.addMedia(media_key, "user", str(path), "")
+        log(f"  Claimed {media_key} ({path.name}) as user media")
+        claimed += 1
 
     return claimed
 

common/tables/tableparser.py

@@ -62,7 +62,10 @@ def loadTables(self, reload=False):  # reload if you want to rescan the tables
                 with os.scandir(table_dir) as entries:
                     for entry in entries:
                         if entry.is_dir():
-                            table_subdirs.add(entry.name)
+                            # Folded like the extension checks below, and like the
+                            # API's own listing: a folder someone named PUPVideos
+                            # holds a PUP pack whatever the shift key was doing.
+                            table_subdirs.add(entry.name.lower())
                             continue
                         table_contents.add(entry.name)
             except OSError:

docs/compatibility-3.0.md

@@ -141,6 +141,26 @@ with a `manufacturers.json` alias map for the exceptions.
 had nothing to render for it. A shared root exists because a manufacturer logo is neither
 per-table nor per-theme. Covered by `tests/test_shared_assets.py`.
 
+**PAR-16 — Addon folders are detected whatever their casing.**
+The library scan matched `pupvideos`, `serum`, `vni`, `music` and `medias` against the
+folder name exactly as stored, so a folder named `PUPVideos` — the casing PinUP Popper
+itself writes — was not detected. The API had always lowercased before comparing, so the
+same table reported a PUP pack there and none in the Manager UI and themes. The scan now
+folds case too. Tables whose folders are not all-lowercase will start reporting addons
+they always had (`pupPackExists`, `altColorExists`, `vniExists`, `altSoundExists`).
+*Why:* one table cannot have two answers, and the scan was already case-insensitive about
+`.directb2s` and `.ini` three lines away. Covered by `tests/test_media_resolution.py`.
+
+**PAR-17 — Claiming user media follows the resolution chain.**
+`--claim-user-media` only ever looked for the fixed canonical name in `medias/`, so a
+hand-placed `wheel.jpg`, a spec-named `(Wheel) <folder>.png`, or a file at the folder root
+was never claimed — and therefore stayed replaceable by the next media download. It now
+claims whatever actually resolves for each kind, which is the same file the frontend
+displays.
+*Why:* the resolution chain grew in 3.0 (PAR-09/PAR-10) and the claim path didn't follow
+it, which made the feature silently miss the files it exists to protect. Covered by
+`tests/test_media_resolution.py`.
+
 ## Explicitly *not* exceptions
 
 The theme-facing payload (`tables_json` keys, media path fields, stable values) and

tests/test_media_resolution.py

@@ -263,6 +263,139 @@ def test_list_media_sets_unions_the_library_and_adds_logo(self) -> None:
                              ["colorful", "logo", "tarcisio"])
 
 
+class SpecCopyTests(unittest.TestCase):
+    def test_a_table_type_copy_keeps_every_field_but_the_key(self) -> None:
+        """It used to be rebuilt from four fields, so the copies quietly reported
+        no token, no fallback, no set support, and the image family for videos."""
+        from common.media_paths import MEDIA_SPECS, specs_for_table_type
+
+        # One copy per spec, in order, so they pair up exactly.
+        for original, copy in zip(MEDIA_SPECS, specs_for_table_type("fss"), strict=True):
+            self.assertEqual(copy.token, original.token, original.key)
+            self.assertEqual(copy.family, original.family, original.key)
+            self.assertEqual(copy.fallback_kind, original.fallback_kind, original.key)
+            self.assertEqual(copy.supports_sets, original.supports_sets, original.key)
+            self.assertEqual(copy.attr, original.attr, original.key)
+
+    def test_the_fss_key_collision_stays_harmless(self) -> None:
+        """Under table type fss the playfield spec is renamed onto the fss key, so
+        two specs share it. Benign only because both resolve the same filename -
+        worth pinning, since a divergence would be silent."""
+        from common.media_paths import media_filename_map, specs_for_table_type
+
+        keyed_fss = [spec for spec in specs_for_table_type("fss") if spec.key == "fss"]
+
+        self.assertEqual(len(keyed_fss), 2)
+        self.assertEqual({spec.filename("fss") for spec in keyed_fss}, {"fss.png"})
+        self.assertEqual(media_filename_map("fss")["fss"], "fss.png")
+
+    def test_the_video_copies_keep_the_video_family(self) -> None:
+        from common.media_paths import VIDEO_FAMILY, specs_for_table_type
+
+        by_key = {spec.key: spec for spec in specs_for_table_type("table")}
+
+        self.assertEqual(by_key["table_video"].family, VIDEO_FAMILY)
+        self.assertEqual(by_key["dmd_video"].family, VIDEO_FAMILY)
+
+
+class ParserCasingTests(unittest.TestCase):
+    def test_addon_folders_are_found_whatever_their_casing(self) -> None:
+        """PUPVideos is the casing PinUP Popper writes, and the scanner used to
+        miss it while the API found it - the same table, two answers."""
+        import json
+
+        from common.tables.tableparser import TableParser
+
+        with TemporaryDirectory() as tmp:
+            root = Path(tmp) / FOLDER
+            (root / "medias").mkdir(parents=True)
+            (root / f"{BUILD}.vpx").write_bytes(b"vpx")
+            for name in ("PUPVideos", "Serum", "VNI", "Music"):
+                (root / name).mkdir()
+            (root / f"{FOLDER}.info").write_text(json.dumps({
+                "Info": {"Title": "Cactus Canyon"},
+                "VPXFile": {"filename": f"{BUILD}.vpx"},
+            }), encoding="utf-8")
+
+            table = TableParser(tmp).getAllTables()[0]
+
+        self.assertTrue(table.pupPackExists, "PUPVideos holds a PUP pack")
+        self.assertTrue(table.altColorExists)
+        self.assertTrue(table.vniExists)
+        self.assertTrue(table.musicExists)
+
+
+class ClaimTests(unittest.TestCase):
+    """--claim-user-media marks media as the user's so a refresh cannot replace it."""
+
+    def _table(self, tmp, *files):
+        import json
+
+        root = Path(tmp) / FOLDER
+        (root / "medias").mkdir(parents=True)
+        for rel in files:
+            path = root / rel
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(b"art")
+        (root / f"{FOLDER}.info").write_text(json.dumps({
+            "Info": {"Title": "Cactus Canyon"},
+            "VPXFile": {"filename": f"{BUILD}.vpx"},
+        }), encoding="utf-8")
+        return root
+
+    def _claim(self, root):
+        from types import SimpleNamespace
+
+        from common.tables.metaconfig import MetaConfig
+        from common.tables.metadata_service import claim_media_for_table
+
+        table = SimpleNamespace(fullPathTable=str(root), tableDirName=FOLDER)
+        count = claim_media_for_table(table, "table", log=lambda _m: None)
+        return count, MetaConfig(str(root / f"{FOLDER}.info")).getConfig().get("Medias", {})
+
+    def test_a_canonical_file_is_claimed_as_before(self) -> None:
+        with TemporaryDirectory() as tmp:
+            count, medias = self._claim(self._table(tmp, "medias/wheel.png"))
+
+        self.assertEqual(count, 1)
+        self.assertEqual(medias["wheel"]["Source"], "user")
+
+    def test_a_hand_placed_jpg_is_claimed(self) -> None:
+        """The resolution chain accepts the whole family; claiming has to as well."""
+        with TemporaryDirectory() as tmp:
+            _count, medias = self._claim(self._table(tmp, "medias/wheel.jpg"))
+
+        self.assertEqual(medias["wheel"]["Source"], "user")
+        self.assertEqual(medias["wheel"]["Path"], "wheel.jpg")
+
+    def test_a_spec_named_file_is_claimed(self) -> None:
+        with TemporaryDirectory() as tmp:
+            _count, medias = self._claim(
+                self._table(tmp, f"medias/(Wheel) {FOLDER}.png"))
+
+        self.assertEqual(medias["wheel"]["Source"], "user")
+        self.assertEqual(medias["wheel"]["Path"], f"(Wheel) {FOLDER}.png")
+
+    def test_a_file_at_the_folder_root_is_claimed(self) -> None:
+        with TemporaryDirectory() as tmp:
+            _count, medias = self._claim(self._table(tmp, "bg.png"))
+
+        self.assertEqual(medias["bg"]["Source"], "user")
+
+    def test_nothing_present_claims_nothing(self) -> None:
+        with TemporaryDirectory() as tmp:
+            count, medias = self._claim(self._table(tmp))
+
+        self.assertEqual(count, 0)
+        self.assertEqual(medias, {})
+
+    def test_audio_is_still_left_alone(self) -> None:
+        with TemporaryDirectory() as tmp:
+            _count, medias = self._claim(self._table(tmp, "medias/audio.mp3"))
+
+        self.assertNotIn("audio", medias)
+
+
 class ImportSideTests(unittest.TestCase):
     def _table(self, tmp, *files):
         root = Path(tmp) / FOLDER