feat: Optimize Plex artwork image loading (#123)

Change Plex image sizes to a maximum width or height of 480px.

Closes #80
Fixes #113

Author: zehnm

src/external_metadata.py

@@ -12,8 +12,8 @@
 import os
 from io import BytesIO
 from pathlib import Path
-from typing import Dict
-from urllib.parse import urlparse
+from typing import Dict, Literal
+from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
 
 import google_play_scraper
 import httpx
@@ -27,6 +27,7 @@
 CACHE_ROOT = "external_cache"
 ICON_SUBDIR = "icons"
 ICON_SIZE = (240, 240)
+IMAGE_SIZE_MAX = 480
 
 
 # Paths
@@ -171,8 +172,12 @@ def load_and_encode() -> str:
 
 
 def _is_url(path: str) -> bool:
-    parsed = urlparse(path)
-    return parsed.scheme in ("http", "https")
+    """Check if the provided string is a valid http/https URL."""
+    try:
+        parsed = urlparse(path)
+        return parsed.scheme in ("http", "https") and bool(parsed.netloc)
+    except (ValueError, AttributeError):
+        return False
 
 
 async def _fetch_google_play_metadata(package_id: str) -> Dict[str, str] | None:
@@ -229,3 +234,72 @@ async def get_app_metadata(package_id: str) -> Dict[str, str]:
 
     _LOG.debug("Falling back to default metadata for %s", package_id)
     return {"name": package_id, "icon": ""}
+
+
+def get_resized_image_url(url: str, max_size: int = IMAGE_SIZE_MAX) -> str | Literal[b""]:
+    """
+    Adjust width and height query parameters while maintaining aspect ratio.
+
+    Only performs the rewrite if the URL path contains '/photo/:/transcode' (Plex transcode URL).
+    - If parameters are missing: returns original URL.
+    - If parameters are invalid (non-numeric/<=0): returns original URL.
+    - If one parameter exists: sets it to max_size.
+    - If both exist: resizes proportionally to fit within max_size.
+    """
+    if not url or not _is_url(url):
+        _LOG.warning("Invalid URL provided for resizing: %s", url)
+        return url
+
+    parsed_url = urlparse(url)
+
+    # Only rewrite Plex transcode URLs
+    # Other services can be added later
+    if "/photo/:/transcode" not in parsed_url.path:
+        return url
+
+    query_dict = parse_qs(parsed_url.query, keep_blank_values=True)
+
+    width_str = query_dict.get("width", [None])[0]
+    height_str = query_dict.get("height", [None])[0]
+
+    # Helper to validate and convert numeric strings
+    def _safe_int(val):
+        try:
+            res = int(val)
+            return res if res > 0 else None
+        except (TypeError, ValueError):
+            return None
+
+    w = _safe_int(width_str)
+    h = _safe_int(height_str)
+
+    # both parameters present
+    if w is not None and h is not None:
+        if w > max_size or h > max_size:
+            if w > h:
+                new_w = max_size
+                new_h = max(1, int(h * (max_size / w)))
+            else:
+                new_h = max_size
+                new_w = max(1, int(w * (max_size / h)))
+
+            query_dict["width"] = [str(new_w)]
+            query_dict["height"] = [str(new_h)]
+        else:
+            return url  # No resizing needed
+
+    # only width present
+    elif w is not None:
+        query_dict["width"] = [str(max_size)]
+
+    # only height present
+    elif h is not None:
+        query_dict["height"] = [str(max_size)]
+
+    # If neither are valid/present, return original
+    else:
+        return url
+
+    # Reconstruct the URL safely
+    new_query = urlencode(query_dict, doseq=True)
+    return urlunparse(parsed_url._replace(query=new_query))

src/tv.py

@@ -51,7 +51,11 @@
 import discover
 import inputs
 from config import AtvDevice
-from external_metadata import encode_icon_to_data_uri, get_app_metadata
+from external_metadata import (
+    encode_icon_to_data_uri,
+    get_app_metadata,
+    get_resized_image_url,
+)
 from profiles import KeyPress, Profile
 from util import filter_data_img_properties
 
@@ -974,6 +978,8 @@ async def _handle_new_media_status(self, status: MediaStatus):
             if status.images[0].url != self._media_image_url:
                 self._media_image_url = status.images[0].url
                 update[MediaAttr.MEDIA_IMAGE_URL] = self._media_image_url
+                # Reformat the media image URL if necessary (image size parameters)
+                update[MediaAttr.MEDIA_IMAGE_URL] = get_resized_image_url(self._media_image_url)
             self._use_app_url = False
         else:
             self._media_image_url = None

tests/test_external_metadata.py

@@ -0,0 +1,54 @@
+import unittest
+
+from src.external_metadata import get_resized_image_url
+
+
+class TestGetResizedImageUrl(unittest.TestCase):
+
+    def test_valid_url_with_both_dimensions_exceeding_max_size(self):
+        url = "https://192.168.1.10:32400/photo/:/transcode?height=1800&machineIdentifier=xxx&quality=90&url=http%3A%2F%2F127.0.0.1%3A32400%2Flibrary%2Fmetadata%2F20%2Fthumb%2F1764553003&width=1200&X-Plex-Token=abc"
+        result = get_resized_image_url(url, max_size=480)
+        expected_url = "https://192.168.1.10:32400/photo/:/transcode?height=480&machineIdentifier=xxx&quality=90&url=http%3A%2F%2F127.0.0.1%3A32400%2Flibrary%2Fmetadata%2F20%2Fthumb%2F1764553003&width=320&X-Plex-Token=abc"
+        self.assertEqual(expected_url, result, "Expected resized dimensions within max_size")
+
+    def test_valid_url_with_only_width_parameter(self):
+        url = "https://192.168.1.10:32400/photo/:/transcode?machineIdentifier=xxx&quality=90&url=http%3A%2F%2F127.0.0.1%3A32400%2Flibrary%2Fmetadata%2F20%2Fthumb%2F1764553003&width=1200&X-Plex-Token=abc"
+        result = get_resized_image_url(url, max_size=480)
+        expected_url = "https://192.168.1.10:32400/photo/:/transcode?machineIdentifier=xxx&quality=90&url=http%3A%2F%2F127.0.0.1%3A32400%2Flibrary%2Fmetadata%2F20%2Fthumb%2F1764553003&width=480&X-Plex-Token=abc"
+        self.assertEqual(expected_url, result, "Expected max_size applied only to width")
+
+    def test_valid_url_with_only_height_parameter(self):
+        url = "https://192.168.1.10:32400/photo/:/transcode?height=1800&machineIdentifier=xxx&quality=90&url=http%3A%2F%2F127.0.0.1%3A32400%2Flibrary%2Fmetadata%2F20%2Fthumb%2F1764553003&X-Plex-Token=abc"
+        result = get_resized_image_url(url, max_size=480)
+        expected_url = "https://192.168.1.10:32400/photo/:/transcode?height=480&machineIdentifier=xxx&quality=90&url=http%3A%2F%2F127.0.0.1%3A32400%2Flibrary%2Fmetadata%2F20%2Fthumb%2F1764553003&X-Plex-Token=abc"
+        self.assertEqual(expected_url, result, "Expected max_size applied only to height")
+
+    def test_valid_url_with_both_dimensions_within_max_size(self):
+        url = "http://example.com/photo/:/transcode?width=50&height=40"
+        result = get_resized_image_url(url, max_size=100)
+        self.assertEqual(url, result, "Expected original URL as dimensions fit within max_size")
+
+    def test_url_with_invalid_width_and_height(self):
+        url = "http://example.com/photo/:/transcode?width=-50&height=abc"
+        result = get_resized_image_url(url, max_size=100)
+        self.assertEqual(url, result, "Expected original URL for invalid width and height")
+
+    def test_invalid_url(self):
+        url = "not_a_valid_url"
+        result = get_resized_image_url(url, max_size=100)
+        self.assertEqual(url, result, "Expected original URL for an invalid URL input")
+
+    def test_empty_url(self):
+        url = ""
+        result = get_resized_image_url(url, max_size=100)
+        self.assertEqual(url, result, "Expected original empty URL")
+
+    def test_url_without_query_parameters(self):
+        url = "http://example.com/photo/:/transcode"
+        result = get_resized_image_url(url, max_size=100)
+        self.assertEqual(url, result, "Expected original URL when no query parameters are present")
+
+    def test_valid_non_plex_url_with_both_dimensions_exceeding_max_size(self):
+        url = "https://192.168.1.10:32400/transcode?height=1800&machineIdentifier=xxx&quality=90&url=http%3A%2F%2F127.0.0.1%3A32400%2Flibrary%2Fmetadata%2F20%2Fthumb%2F1764553003&width=1200&X-Plex-Token=abc"
+        result = get_resized_image_url(url, max_size=480)
+        self.assertEqual(url, result, "Non-Plex URLs should not be modified")