Add media details carousel with trailer/photo gallery and lightbox

- New TMDB (movie/tv/season) and IGDB (game) carousel data fetching,
  lazily loaded via an htmx fragment separate from the main page render.
- Details page top section splits into a CSS grid (poster+carousel,
  title+actions, chips, synopsis) for carousel-supported media types;
  score chips and action buttons extracted into standalone partials so
  the non-carousel layout can keep composing them exactly as before.
- Carousel: prev/next navigation, inline YouTube trailer playback with
  a custom thumbnail (falls back from maxresdefault to hqdefault when
  no high-res thumbnail exists), and a full-screen lightbox preserving
  original image aspect ratio.
- IGDB images use t_1080p instead of t_screenshot_big_2x for the
  main pane/lightbox, since the latter crops to a fixed 16:9 canvas
  rather than just scaling.
- Carousel is temporarily disabled below the md breakpoint while the
  mobile layout is still being polished; mobile keeps today's original
  stacked layout unchanged.

Fixes #850

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: dannyvfilms

src/app/carousel.py

@@ -0,0 +1,60 @@
+"""Media-details carousel (trailer + photos) resolution.
+
+Distinct from ``backdrops.py``: that module returns a single horizontal image
+(or ``None``) for card art, eagerly consulted on hot paths. This module
+returns a multi-item {"video", "photos"} payload for the details page's
+carousel, fetched lazily (only when the page's carousel fragment is
+requested) and only for the media types/sources that actually expose a
+trailer or photo gallery.
+"""
+
+from app.models import MediaTypes, Sources
+from app.providers import tmdb
+
+_TMDB_CAROUSEL_TYPES = (MediaTypes.MOVIE.value, MediaTypes.TV.value, MediaTypes.SEASON.value)
+
+
+def carousel_supported(media_type, source):
+    """Return whether the given media_type/source combination can have a carousel."""
+    if source == Sources.TMDB.value and media_type in _TMDB_CAROUSEL_TYPES:
+        return True
+    return bool(source == Sources.IGDB.value and media_type == MediaTypes.GAME.value)
+
+
+def resolve_carousel_media(media_type, source, media_id, *, season_number=None) -> dict | None:
+    """Return {"video": {...}|None, "photos": [{"url", "thumb_url"}, ...]} or None."""
+    if source == Sources.TMDB.value and media_type in _TMDB_CAROUSEL_TYPES:
+        data = tmdb.carousel_media(media_type, media_id, season_number=season_number)
+        photos = [
+            {
+                "url": tmdb.get_carousel_image_url(photo["file_path"], size="w1280"),
+                "thumb_url": tmdb.get_carousel_image_url(photo["file_path"], size="w300"),
+            }
+            for photo in data["photos"]
+        ]
+        if not data["video"] and not photos:
+            return None
+        return {"video": data["video"], "photos": photos}
+
+    if source == Sources.IGDB.value and media_type == MediaTypes.GAME.value:
+        from lists.models import CustomList
+
+        data = CustomList()._get_igdb_carousel_media(media_id)
+        photos = [
+            {
+                # t_screenshot_big_2x and similar named IGDB transforms crop to a
+                # fixed canvas; t_1080p only caps resolution, so it keeps the
+                # source image's real aspect ratio for the main pane/lightbox.
+                "url": f"https://images.igdb.com/igdb/image/upload/t_1080p/{image_id}.jpg",
+                "thumb_url": (
+                    f"https://images.igdb.com/igdb/image/upload/"
+                    f"t_screenshot_big_2x/{image_id}.jpg"
+                ),
+            }
+            for image_id in data["photos"]
+        ]
+        if not data["video"] and not photos:
+            return None
+        return {"video": data["video"], "photos": photos}
+
+    return None

src/app/media_details_views.py

@@ -11,6 +11,9 @@
 from django.utils import timezone
 from django.views.decorators.http import require_GET
 
+from app import (
+    carousel as carousel_media,
+)
 from app import (
     config,
     credits,  # noqa: A004  # app.credits module, not the site builtin
@@ -67,7 +70,11 @@
     _resolve_detail_tag_genres,
 )
 from app.track_modal_views import _DummyPodcastWrapper
-from app.view_constants import DETAIL_SECONDARY_FRAGMENT, force_live_metadata_cache_key
+from app.view_constants import (
+    DETAIL_CAROUSEL_FRAGMENT,
+    DETAIL_SECONDARY_FRAGMENT,
+    force_live_metadata_cache_key,
+)
 from lists.views_helpers import get_public_list_for_item
 
 logger = logging.getLogger(__name__)
@@ -172,7 +179,15 @@ def media_details(
     title,
 ):
     """Return the details page for a media item."""
+    if request.GET.get("fragment") == DETAIL_CAROUSEL_FRAGMENT:
+        return render(
+            request,
+            "app/components/detail_carousel_fragment.html",
+            {"carousel": carousel_media.resolve_carousel_media(media_type, source, media_id)},
+        )
+
     detail_view_started_at = time.perf_counter()
+    carousel_supported = carousel_media.carousel_supported(media_type, source)
     render_secondary_only = (
         request.GET.get("fragment") == DETAIL_SECONDARY_FRAGMENT
         and media_type != MediaTypes.PODCAST.value
@@ -181,6 +196,11 @@ def media_details(
         not render_secondary_only and media_type != MediaTypes.PODCAST.value
     )
     detail_return_url = _detail_request_url(request)
+    detail_carousel_fragment_url = (
+        _detail_request_url(request, fragment=DETAIL_CAROUSEL_FRAGMENT)
+        if carousel_supported
+        else None
+    )
     detail_secondary_fragment_url = _detail_request_url(
         request,
         fragment=DETAIL_SECONDARY_FRAGMENT,
@@ -2108,6 +2128,8 @@ def _activity_key(entry):
         "detail_secondary_fragment_url": detail_secondary_fragment_url,
         "defer_detail_secondary": defer_detail_secondary,
         "render_secondary_only": render_secondary_only,
+        "carousel_supported": carousel_supported,
+        "detail_carousel_fragment_url": detail_carousel_fragment_url,
         **_build_detail_person_rows(media_metadata, item=detail_item),
     }
     logger.info(

src/app/providers/tmdb.py

@@ -47,6 +47,10 @@
     "season/{season}/watch/providers",
 )
 TMDB_SEASON_CACHE_VERSION = 4
+# Media-details carousel (trailer + photos): fetched lazily, its own cache
+# entry, independent of the movie/tv/season append_to_response payloads above.
+CAROUSEL_CACHE_TTL_SUCCESS = 60 * 60 * 24 * 7
+CAROUSEL_CACHE_TTL_ABSENT = 60 * 60 * 24
 
 
 def base_params(language=None):
@@ -1092,6 +1096,90 @@ def tv(media_id, language=None):
     return data
 
 
+def _carousel_cache_key(media_type, media_id, season_number=None):
+    """Return the cache key for a media-details carousel payload."""
+    key = f"tmdb_carousel_{media_type}_{media_id}"
+    if season_number is not None:
+        key += f"_s{season_number}"
+    return key
+
+
+def _parse_carousel_video(response):
+    """Return the single best YouTube trailer from a TMDB videos append, if any."""
+    videos = response.get("videos", {}).get("results", []) or []
+    youtube_videos = [v for v in videos if v.get("site") == "YouTube" and v.get("key")]
+    trailers = [v for v in youtube_videos if v.get("type") == "Trailer"]
+    video = next(iter(trailers), None) or next(iter(youtube_videos), None)
+    if not video:
+        return None
+    return {
+        "key": video["key"],
+        "name": video.get("name", ""),
+        "type": video.get("type", ""),
+    }
+
+
+def _parse_carousel_photos(response):
+    """Return normalized backdrop photos from a TMDB images append."""
+    backdrops = response.get("images", {}).get("backdrops", []) or []
+    return [
+        {
+            "file_path": photo["file_path"],
+            "width": photo.get("width"),
+            "height": photo.get("height"),
+        }
+        for photo in backdrops
+        if photo.get("file_path")
+    ]
+
+
+def carousel_media(media_type, media_id, season_number=None, language=None):
+    """Return {"video": {...}|None, "photos": [...]} for the details carousel.
+
+    Fetched lazily via its own request/cache entry, never folded into the
+    movie/tv/season append_to_response calls (those are already close to
+    TMDB_APPEND_TO_RESPONSE_MAX_REMOTE_CALLS).
+    """
+    cache_key = _carousel_cache_key(media_type, media_id, season_number)
+    data = cache.get(cache_key)
+    if data is not None:
+        return data
+
+    if media_type == MediaTypes.MOVIE.value:
+        url = f"{base_url}/movie/{media_id}"
+    elif media_type == MediaTypes.SEASON.value:
+        url = f"{base_url}/tv/{media_id}/season/{season_number}"
+    else:
+        url = f"{base_url}/tv/{media_id}"
+
+    params = {
+        **base_params(language),
+        "append_to_response": "videos,images",
+    }
+
+    try:
+        response = services.api_request(
+            Sources.TMDB.value,
+            "GET",
+            url,
+            params=params,
+        )
+    except requests.exceptions.HTTPError as error:
+        handle_error(error)
+
+    data = {
+        "video": _parse_carousel_video(response),
+        "photos": _parse_carousel_photos(response),
+    }
+    ttl = (
+        CAROUSEL_CACHE_TTL_SUCCESS
+        if data["video"] or data["photos"]
+        else CAROUSEL_CACHE_TTL_ABSENT
+    )
+    cache.set(cache_key, data, ttl)
+    return data
+
+
 def _build_tv_crew(response):
     """Build sorted crew list for a TV show, prepending created_by as Creators."""
     crew = get_crew_credits(response.get("aggregate_credits", {}), is_aggregate=True)
@@ -1566,6 +1654,13 @@ def get_profile_image_url(path, size="w185"):
     return settings.IMG_NONE
 
 
+def get_carousel_image_url(path, size="w1280"):
+    """Return a media-details carousel image URL (backdrops/photos)."""
+    if path:
+        return f"https://image.tmdb.org/t/p/{size}{path}"
+    return settings.IMG_NONE
+
+
 def _upgrade_person_image_url(url):
     """Upgrade legacy person profile URLs to a higher-resolution size."""
     if not url:

src/app/season_details_views.py

@@ -10,6 +10,7 @@
 from django.utils import timezone
 from django.views.decorators.http import require_GET
 
+from app import carousel as carousel_media
 from app import config, helpers
 from app.activity_builders import (
     _normalize_detail_episode_actions,
@@ -48,6 +49,7 @@
     _resolve_detail_tag_genres,
 )
 from app.view_constants import (
+    DETAIL_CAROUSEL_FRAGMENT,
     DETAIL_SECONDARY_FRAGMENT,
     LOCAL_ONLY_MISSING_SEASON_BANNER,
 )
@@ -70,10 +72,32 @@ def season_details(
     parent_media_type=None,
 ):
     """Return the details page for a season."""
+    if request.GET.get("fragment") == DETAIL_CAROUSEL_FRAGMENT:
+        return render(
+            request,
+            "app/components/detail_carousel_fragment.html",
+            {
+                "carousel": carousel_media.resolve_carousel_media(
+                    MediaTypes.SEASON.value,
+                    source,
+                    media_id,
+                    season_number=season_number,
+                ),
+            },
+        )
+
     detail_view_started_at = time.perf_counter()
+    carousel_supported = carousel_media.carousel_supported(
+        MediaTypes.SEASON.value, source
+    )
     render_secondary_only = request.GET.get("fragment") == DETAIL_SECONDARY_FRAGMENT
     defer_detail_secondary = not render_secondary_only
     detail_return_url = _detail_request_url(request)
+    detail_carousel_fragment_url = (
+        _detail_request_url(request, fragment=DETAIL_CAROUSEL_FRAGMENT)
+        if carousel_supported
+        else None
+    )
     detail_secondary_fragment_url = _detail_request_url(
         request,
         fragment=DETAIL_SECONDARY_FRAGMENT,
@@ -1017,6 +1041,8 @@ def _fetch_episode_items(numbers):
         "detail_secondary_fragment_url": detail_secondary_fragment_url,
         "defer_detail_secondary": defer_detail_secondary,
         "render_secondary_only": render_secondary_only,
+        "carousel_supported": carousel_supported,
+        "detail_carousel_fragment_url": detail_carousel_fragment_url,
         **_build_detail_person_rows(season_metadata),
     }
     logger.info(

src/app/view_constants.py

@@ -6,6 +6,7 @@
     "server, to restore provider data and progress tracking."
 )
 DETAIL_SECONDARY_FRAGMENT = "secondary"
+DETAIL_CAROUSEL_FRAGMENT = "carousel"
 
 FORCE_LIVE_METADATA_TIMEOUT = 60  # seconds