fix(plex): generate previews for every version of multi-version media (#268) (#269)

Plex items with multiple versions (e.g. a 1080p + a 4K file) only got a
preview BIF for ONE version. Regression from the #225 multi-server rewrite,
which collapsed enumeration to remote_path=str(locations[0]) (first version
only); pre-rewrite the generator looped every MediaPart.

list_items() now yields one MediaItem per version file (each entry in
item.locations), so every version gets its own BIF. The shared bundle_metadata
carries all (hash, file) pairs and PlexBundleAdapter selects each version's
bundle hash by matching the per-item path — no adapter change needed.

Coverage: library scans + manual generation now do all versions; Radarr/Sonarr
path-based webhooks already did (each import is a specific file). Plex-native
webhooks that resolve by item-id still pick one version (resolve_item_to_remote_path
returns a single path) — a narrower follow-up.

Tests: multi-version movie + episode each yield one MediaItem per version.


Claude-Session: https://claude.ai/code/session_01YC1Z1JFBVJ5xKi5YAqYKfc

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: stevezau

media_preview_generator/servers/plex.py

@@ -1522,13 +1522,23 @@ def list_items(self, library_id: str) -> Iterator[MediaItem]:
                     locations = _extract_item_locations(m)
                     if not locations:
                         continue
-                    yield MediaItem(
-                        id=_plex_item_id(m),
-                        library_id=str(target.key),
-                        title=_build_episode_title(m),
-                        remote_path=str(locations[0]),
-                        bundle_metadata=_extract_plex_bundle_metadata(m),
-                    )
+                    # #268: one MediaItem per version. A Plex item can have
+                    # several versions (1080p + 4K), each a distinct file in
+                    # ``locations``. Emitting one item per file gives every
+                    # version its own BIF; the shared ``bundle_metadata`` holds
+                    # all (hash, file) pairs and PlexBundleAdapter selects each
+                    # version's bundle hash by matching the per-item path.
+                    bundle_md = _extract_plex_bundle_metadata(m)
+                    item_id = _plex_item_id(m)
+                    title = _build_episode_title(m)
+                    for location in locations:
+                        yield MediaItem(
+                            id=item_id,
+                            library_id=str(target.key),
+                            title=title,
+                            remote_path=str(location),
+                            bundle_metadata=bundle_md,
+                        )
             elif target.METADATA_TYPE == "movie":
                 logger.info(
                     "Plex library {!r}: requesting full movie list from server "
@@ -1545,13 +1555,18 @@ def list_items(self, library_id: str) -> Iterator[MediaItem]:
                     locations = _extract_item_locations(m)
                     if not locations:
                         continue
-                    yield MediaItem(
-                        id=_plex_item_id(m),
-                        library_id=str(target.key),
-                        title=str(getattr(m, "title", "") or ""),
-                        remote_path=str(locations[0]),
-                        bundle_metadata=_extract_plex_bundle_metadata(m),
-                    )
+                    # #268: one MediaItem per version (see episode branch above).
+                    bundle_md = _extract_plex_bundle_metadata(m)
+                    item_id = _plex_item_id(m)
+                    title = str(getattr(m, "title", "") or "")
+                    for location in locations:
+                        yield MediaItem(
+                            id=item_id,
+                            library_id=str(target.key),
+                            title=title,
+                            remote_path=str(location),
+                            bundle_metadata=bundle_md,
+                        )
             else:
                 logger.info(
                     "Skipping Plex library {} (unsupported METADATA_TYPE={})",

tests/test_servers_plex.py

@@ -486,6 +486,75 @@ def test_captures_bundle_metadata_from_plexapi_parts(self, mock_config):
             "introducing _extract_plex_bundle_metadata."
         )
 
+    def test_yields_one_item_per_version_for_multi_version_movie(self, mock_config):
+        """#268: a movie with multiple versions (multiple files) must yield ONE
+        MediaItem per version so each version gets its own BIF — regression from
+        the #225 rewrite which collapsed to ``locations[0]`` (first version only)."""
+        wrapper = PlexServer(mock_config)
+
+        def _media(hash_, file_):
+            part = MagicMock()
+            part.hash = hash_
+            part.file = file_
+            media = MagicMock()
+            media.parts = [part]
+            return media
+
+        movie = MagicMock(spec=["key", "ratingKey", "title", "locations", "media"])
+        movie.key = "/library/metadata/99"
+        movie.ratingKey = 99
+        movie.title = "Foo (2024)"
+        movie.locations = ["/data/Foo (2024)/Foo-1080p.mkv", "/data/Foo (2024)/Foo-2160p.mkv"]
+        movie.media = [
+            _media("hash1080", "/data/Foo (2024)/Foo-1080p.mkv"),
+            _media("hash4k", "/data/Foo (2024)/Foo-2160p.mkv"),
+        ]
+
+        section = MagicMock()
+        section.key = 1
+        section.METADATA_TYPE = "movie"
+        section.search.return_value = [movie]
+        plex = MagicMock()
+        plex.library.sections.return_value = [section]
+        wrapper._plex = plex
+
+        items = list(wrapper.list_items("1"))
+        assert len(items) == 2, "expected one MediaItem per version"
+        assert {it.remote_path for it in items} == {
+            "/data/Foo (2024)/Foo-1080p.mkv",
+            "/data/Foo (2024)/Foo-2160p.mkv",
+        }
+        assert all(it.id == "99" for it in items), "all versions share the item id"
+
+    def test_yields_one_item_per_version_for_multi_version_episode(self, mock_config):
+        """#268, episode side: multi-version episodes must also fan out per version."""
+        wrapper = PlexServer(mock_config)
+        ep = MagicMock(
+            spec=["key", "ratingKey", "title", "grandparentTitle", "parentIndex", "index", "locations", "media"]
+        )
+        ep.key = "/library/metadata/7"
+        ep.ratingKey = 7
+        ep.grandparentTitle = "Test Show"
+        ep.parentIndex = 1
+        ep.index = 1
+        ep.locations = ["/tv/Show/S01E01-1080p.mkv", "/tv/Show/S01E01-2160p.mkv"]
+        ep.media = []
+
+        section = MagicMock()
+        section.key = 2
+        section.METADATA_TYPE = "episode"
+        section.search.return_value = [ep]
+        plex = MagicMock()
+        plex.library.sections.return_value = [section]
+        wrapper._plex = plex
+
+        items = list(wrapper.list_items("2"))
+        assert len(items) == 2
+        assert {it.remote_path for it in items} == {
+            "/tv/Show/S01E01-1080p.mkv",
+            "/tv/Show/S01E01-2160p.mkv",
+        }
+
 
 class TestResolveItemToRemotePath:
     def test_returns_first_part_path(self, plex_wrapper):