add api support for backdrop images from tmdb

Author: elemated

src/api/contract_serializers.py

@@ -148,6 +148,8 @@ class CompleteMediaResponseSerializer(serializers.Serializer):
     title = serializers.CharField(allow_blank=True, allow_null=True)
     max_progress = serializers.IntegerField()
     image = serializers.CharField(allow_blank=True, allow_null=True)
+    # FORK: 16:9 artwork
+    backdrop = serializers.CharField(allow_null=True)
     synopsis = serializers.CharField(allow_blank=True, allow_null=True)
     genres = serializers.ListField(child=serializers.CharField(), allow_null=True)
     score = serializers.FloatField(allow_null=True)

src/api/contracts/openapi.yaml

@@ -2571,6 +2571,9 @@ components:
         image:
           type: string
           nullable: true
+        backdrop:
+          type: string
+          nullable: true
         synopsis:
           type: string
           nullable: true
@@ -2621,6 +2624,7 @@ components:
             type: object
             additionalProperties: {}
       required:
+      - backdrop
       - cast
       - consumptions
       - consumptions_number
@@ -2669,6 +2673,9 @@ components:
         image:
           type: string
           nullable: true
+        backdrop:
+          type: string
+          nullable: true
         synopsis:
           type: string
           nullable: true
@@ -2720,6 +2727,7 @@ components:
             type: object
             additionalProperties: {}
       required:
+      - backdrop
       - cast
       - consumptions
       - consumptions_number

src/api/serializers.py

@@ -2,6 +2,7 @@
 from django.utils.timezone import now
 from rest_framework import serializers
 
+from app.backdrops import resolve_backdrop  # FORK: horizontal artwork
 from app.helpers import build_provider_ids
 from app.models import (
     TV,
@@ -184,6 +185,8 @@ def to_representation(self, instance):
             "title": episode.get("name"),
             "max_progress": 1,
             "image": image,
+            # FORK: show-level backdrop
+            "backdrop": resolve_backdrop(media_metadata),
             "synopsis": episode.get("overview"),
             "genres": media_metadata.get("genres", []),
             "score": float(episode.get("vote_average")),
@@ -349,6 +352,8 @@ def to_representation(self, instance):
             if media_metadata.get("max_progress") is not None
             else 1,
             "image": media_metadata.get("image"),
+            # FORK: 16:9 artwork
+            "backdrop": resolve_backdrop(media_metadata),
             "synopsis": media_metadata.get("synopsis"),
             "genres": media_metadata.get("genres"),
             "score": float(media_metadata.get("score"))

src/api/tests/helpers.py

@@ -80,6 +80,7 @@ def check_complete_media_structure(test_case, item):
     test_case.assertIn("media_type", item)
     test_case.assertIn("title", item)
     test_case.assertIn("image", item)
+    test_case.assertIn("backdrop", item)
     test_case.assertIn("synopsis", item)
     test_case.assertIn("genres", item)
     test_case.assertIn("score", item)

src/api/tests/test_fork_media.py

@@ -3,6 +3,8 @@
 from http import HTTPStatus as HTTP  # noqa: N814
 from unittest.mock import patch
 
+from django.core.cache import cache
+
 from app.models import (
     CollectionEntry,
     ComicIssue,
@@ -15,6 +17,8 @@
 
 from .base import FloppyApiTestCase
 
+BACKDROP_URL = "https://image.tmdb.org/t/p/w1280/backdrop.jpg"
+
 
 class ForkMediaTypeOverlayTests(FloppyApiTestCase):
     """Fork media types are first-class citizens of the media endpoints."""
@@ -258,3 +262,128 @@ def test_collection_add_requires_item(self):
             **self.auth_headers,
         )
         self.assertEqual(response.status_code, HTTP.BAD_REQUEST)
+
+
+class ForkBackdropFieldTests(FloppyApiTestCase):
+    """Detail responses carry 16:9 artwork alongside the portrait poster."""
+
+    def setUp(self):
+        """Start every test with a cold backdrop cache."""
+        super().setUp()
+        cache.clear()
+        self.addCleanup(cache.clear)
+        self.tv_item = self.items_by_type[MediaTypes.TV.value][0]
+
+    def _tv_metadata(self):
+        return {
+            "media_id": self.tv_item.media_id,
+            "source": self.tv_item.source,
+            "source_url": "https://www.themoviedb.org/tv/1",
+            "media_type": MediaTypes.TV.value,
+            "title": self.tv_item.title,
+            "max_progress": 1,
+            "image": self.tv_item.image,
+            "synopsis": "",
+            "genres": [],
+            "score": None,
+            "score_count": None,
+            "details": {},
+            "related": {"seasons": [], "recommendations": []},
+        }
+
+    def _get_detail(self):
+        return self.call_api(
+            "get",
+            "api_media_detail",
+            args=(MediaTypes.TV.value, self.tv_item.source, self.tv_item.media_id),
+            headers=self.auth_headers,
+        )
+
+    @patch("api.views.services.get_media_metadata")
+    @patch("lists.models.CustomList._get_tmdb_backdrop")
+    def test_detail_serves_cached_backdrop_without_calling_tmdb(
+        self,
+        mock_backdrop,
+        mock_metadata,
+    ):
+        mock_metadata.return_value = self._tv_metadata()
+        cache.set(f"tmdb_backdrop_tv_{self.tv_item.media_id}", BACKDROP_URL, 60)
+
+        response = self._get_detail()
+
+        self.assertEqual(response.status_code, HTTP.OK)
+        payload = response.json()
+        self.assertEqual(payload["backdrop"], BACKDROP_URL)
+        # The poster is unchanged — backdrop is an addition, not a replacement.
+        self.assertEqual(payload["image"], self.tv_item.image)
+        mock_backdrop.assert_not_called()
+
+    @patch("api.views.services.get_media_metadata")
+    @patch("lists.models.CustomList._get_tmdb_backdrop", return_value=BACKDROP_URL)
+    def test_detail_fetches_backdrop_when_cache_is_cold(
+        self,
+        mock_backdrop,
+        mock_metadata,
+    ):
+        """A single detail view may pay for one provider call; the result caches."""
+        mock_metadata.return_value = self._tv_metadata()
+
+        response = self._get_detail()
+
+        self.assertEqual(response.json()["backdrop"], BACKDROP_URL)
+        mock_backdrop.assert_called_once_with(
+            MediaTypes.TV.value,
+            self.tv_item.media_id,
+        )
+
+    @patch("api.views.services.get_media_metadata")
+    @patch("lists.models.CustomList._get_tmdb_backdrop", return_value=None)
+    def test_detail_reports_null_when_no_backdrop_exists(
+        self,
+        mock_backdrop,
+        mock_metadata,
+    ):
+        """Clients need to distinguish "no artwork" from "a poster", so: null."""
+        mock_metadata.return_value = self._tv_metadata()
+
+        payload = self._get_detail().json()
+
+        self.assertIn("backdrop", payload)
+        self.assertIsNone(payload["backdrop"])
+
+    @patch("api.views.services.get_media_metadata")
+    @patch("lists.models.CustomList._get_tmdb_backdrop", return_value=BACKDROP_URL)
+    def test_episode_detail_carries_the_show_backdrop(
+        self,
+        mock_backdrop,
+        mock_metadata,
+    ):
+        """Episode stills are often missing; the show backdrop covers that gap."""
+        season_item = self.items_by_type[MediaTypes.SEASON.value][0]
+        episode_item = self.items_by_type[MediaTypes.EPISODE.value][0]
+        mock_metadata.return_value = self.build_episode_metadata(
+            tv_item=self.tv_item,
+            season_number=season_item.season_number,
+            episode_number=episode_item.episode_number,
+            title=episode_item.title,
+            image=episode_item.image,
+        )
+
+        response = self.call_api(
+            "get",
+            "api_media_episode_detail",
+            args=(
+                MediaTypes.TV.value,
+                self.tv_item.source,
+                self.tv_item.media_id,
+                season_item.season_number,
+                episode_item.episode_number,
+            ),
+            headers=self.auth_headers,
+        )
+
+        self.assertEqual(response.status_code, HTTP.OK)
+        payload = response.json()
+        self.assertEqual(payload["backdrop"], BACKDROP_URL)
+        # The fixture has no still_path, which is exactly the gap being filled.
+        self.assertIsNone(payload["image"])

src/api/tests/test_media_core.py

@@ -694,6 +694,7 @@ def test_media_detail_get_returns_expected_shape(self, mock_metadata):
                 "title",
                 "max_progress",
                 "image",
+                "backdrop",
                 "synopsis",
                 "genres",
                 "score",

src/app/backdrops.py

@@ -0,0 +1,133 @@
+"""Horizontal (16:9) backdrop resolution shared by the web UI and the API.
+
+Item.image holds a portrait poster (TMDB w500); backdrops are never stored on
+the model, only fetched from the provider and cached in Redis for 7 days by
+``lists.models.CustomList``.
+
+``resolve_backdrop`` returns ``None`` when no backdrop exists, leaving the
+choice of fallback to the caller: the web UI falls back to the poster so a
+card always renders, while the API reports ``null`` so clients can pick their
+own artwork.
+"""
+
+from django.conf import settings
+from django.core.cache import cache
+
+from app.models import MediaTypes, Sources
+
+# Episodes and seasons share their show's media_id, and TMDB files anime under
+# /tv, so all three resolve against the show-level backdrop.
+_SHOW_LEVEL_TYPES = (
+    MediaTypes.EPISODE.value,
+    MediaTypes.SEASON.value,
+    MediaTypes.ANIME.value,
+)
+_TVDB_TYPES = (MediaTypes.TV.value, *_SHOW_LEVEL_TYPES)
+
+
+def _read(item, key):
+    """Read a field from either a serialized dict or a model instance."""
+    if isinstance(item, dict):
+        return item.get(key)
+    return getattr(item, key, None)
+
+
+def _identity(item):
+    """Return (source, media_type, media_id) or None when incomplete."""
+    if not item:
+        return None
+    source = _read(item, "source")
+    media_type = _read(item, "media_type")
+    media_id = _read(item, "media_id")
+    if not source or not media_type or not media_id:
+        return None
+    return source, media_type, media_id
+
+
+def _tvdb_tmdb_id(item):
+    """Return the TMDB cross-reference the TVDB provider stores, if any."""
+    return (_read(item, "provider_external_ids") or {}).get("tmdb_id")
+
+
+def _usable(backdrop):
+    """Treat the placeholder image as no backdrop at all."""
+    if backdrop and backdrop != settings.IMG_NONE:
+        return backdrop
+    return None
+
+
+def cached_backdrop(item) -> str | None:
+    """Return an already-cached backdrop without triggering provider lookups."""
+    identity = _identity(item)
+    if identity is None:
+        return None
+    source, media_type, media_id = identity
+
+    if source == Sources.TMDB.value:
+        backdrop_media_type = (
+            MediaTypes.TV.value if media_type in _SHOW_LEVEL_TYPES else media_type
+        )
+        if backdrop_media_type in (MediaTypes.MOVIE.value, MediaTypes.TV.value):
+            return _usable(
+                cache.get(f"tmdb_backdrop_{backdrop_media_type}_{media_id}"),
+            )
+
+    if source == Sources.TVDB.value and media_type in _TVDB_TYPES:
+        tmdb_id = _tvdb_tmdb_id(item)
+        if tmdb_id:
+            return _usable(cache.get(f"tmdb_backdrop_tv_{tmdb_id}"))
+
+    if source == Sources.IGDB.value and media_type == MediaTypes.GAME.value:
+        return _usable(cache.get(f"igdb_backdrop_{media_id}"))
+
+    return None
+
+
+def resolve_backdrop(item, *, allow_network=True) -> str | None:
+    """Return a horizontal backdrop URL for an item, or None if there is none.
+
+    With ``allow_network=False`` only the Redis cache is consulted, so callers
+    on a hot path never block on a provider request.
+    """
+    cached = cached_backdrop(item)
+    if cached:
+        return cached
+
+    identity = _identity(item)
+    if identity is None or not allow_network:
+        return None
+    source, media_type, media_id = identity
+
+    try:
+        from lists.models import CustomList
+    except Exception:
+        return None
+
+    custom_list = CustomList()
+
+    if source == Sources.TMDB.value and media_type in _SHOW_LEVEL_TYPES:
+        return _fetch(custom_list._get_tmdb_backdrop, MediaTypes.TV.value, media_id)
+
+    if source == Sources.TMDB.value and media_type in (
+        MediaTypes.MOVIE.value,
+        MediaTypes.TV.value,
+    ):
+        return _fetch(custom_list._get_tmdb_backdrop, media_type, media_id)
+
+    if source == Sources.TVDB.value and media_type in _TVDB_TYPES:
+        tmdb_id = _tvdb_tmdb_id(item)
+        if tmdb_id:
+            return _fetch(custom_list._get_tmdb_backdrop, MediaTypes.TV.value, tmdb_id)
+
+    if source == Sources.IGDB.value and media_type == MediaTypes.GAME.value:
+        return _fetch(custom_list._get_igdb_backdrop, media_id)
+
+    return None
+
+
+def _fetch(getter, *args) -> str | None:
+    """Call a provider backdrop getter; artwork is never worth raising over."""
+    try:
+        return _usable(getter(*args))
+    except Exception:  # deliberate best-effort; failure is non-fatal here
+        return None