From 503e0d671b62f2bdd0354a2bdc3daca5dc8d0f3b Mon Sep 17 00:00:00 2001
From: Shadowghost <Shadowghost@users.noreply.github.com>
Date: Tue, 15 Sep 2026 11:13:52 -0400
Subject: Backport pull request #17859 from jellyfin/release-12.z

Report image resolutions for TMDb images when no image size is configured

Original-merge: b2ed322c475d430b0bf71913072006ae997b0233

Merged-by: crobibero <cody@robibe.ro>

Backported-by: Cody Robibero <cody@robibe.ro>
---
 MediaBrowser.Providers/Plugins/Tmdb/TmdbClientManager.cs |  6 +++---
 MediaBrowser.Providers/Plugins/Tmdb/TmdbUtils.cs         | 14 ++++++++++++++
 tests/Jellyfin.Providers.Tests/Tmdb/TmdbUtilsTests.cs    | 13 +++++++++++++
 3 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/MediaBrowser.Providers/Plugins/Tmdb/TmdbClientManager.cs b/MediaBrowser.Providers/Plugins/Tmdb/TmdbClientManager.cs
index fb3e5ee92b..6b1b54ce02 100644
--- a/MediaBrowser.Providers/Plugins/Tmdb/TmdbClientManager.cs
+++ b/MediaBrowser.Providers/Plugins/Tmdb/TmdbClientManager.cs
@@ -568,8 +568,8 @@ namespace MediaBrowser.Providers.Plugins.Tmdb
                 return null;
             }
 
-            // Use "original" as default size if size is null or empty to prevent malformed URLs
-            var imageSize = string.IsNullOrEmpty(size) ? "original" : size;
+            // Use the original size as default if size is null or empty to prevent malformed URLs
+            var imageSize = string.IsNullOrEmpty(size) ? TmdbUtils.OriginalImageSize : size;
 
             return _tmDbClient.GetImageUrl(imageSize, path, true).ToString();
         }
@@ -660,7 +660,7 @@ namespace MediaBrowser.Providers.Plugins.Tmdb
         private IEnumerable<RemoteImageInfo> ConvertToRemoteImageInfo(IReadOnlyList<ImageData> images, string? size, ImageType type, string requestLanguage)
         {
             // sizes provided are for original resolution, don't store them when downloading scaled images
-            var scaleImage = !string.Equals(size, "original", StringComparison.OrdinalIgnoreCase);
+            var scaleImage = !TmdbUtils.IsOriginalImageSize(size);
 
             for (var i = 0; i < images.Count; i++)
             {
diff --git a/MediaBrowser.Providers/Plugins/Tmdb/TmdbUtils.cs b/MediaBrowser.Providers/Plugins/Tmdb/TmdbUtils.cs
index a002140d1e..f004251594 100644
--- a/MediaBrowser.Providers/Plugins/Tmdb/TmdbUtils.cs
+++ b/MediaBrowser.Providers/Plugins/Tmdb/TmdbUtils.cs
@@ -34,6 +34,11 @@ namespace MediaBrowser.Providers.Plugins.Tmdb
         /// </summary>
         public const string ApiKey = "4219e299c89411838049ab0dab19ebd5";
 
+        /// <summary>
+        /// The image size representing the unscaled image as served by TMDb.
+        /// </summary>
+        public const string OriginalImageSize = "original";
+
         private const int TitleExactScore = 8;
         private const int TitlePrefixScore = 4;
         private const int YearExactScore = 2;
@@ -485,6 +490,15 @@ namespace MediaBrowser.Providers.Plugins.Tmdb
                 : imageLanguage;
         }
 
+        /// <summary>
+        /// Determines whether the configured image size fetches the image at its original resolution.
+        /// An unset size falls back to <see cref="OriginalImageSize"/>, see TmdbClientManager.GetUrl.
+        /// </summary>
+        /// <param name="size">The configured image size.</param>
+        /// <returns><c>true</c> if the original image is fetched; otherwise, <c>false</c>.</returns>
+        public static bool IsOriginalImageSize(string? size)
+            => string.IsNullOrEmpty(size) || string.Equals(size, OriginalImageSize, StringComparison.OrdinalIgnoreCase);
+
         /// <summary>
         /// Combines the metadata country code and the parental rating from the API into the value we store in our database.
         /// </summary>
diff --git a/tests/Jellyfin.Providers.Tests/Tmdb/TmdbUtilsTests.cs b/tests/Jellyfin.Providers.Tests/Tmdb/TmdbUtilsTests.cs
index 8926a7b13c..03bad3555e 100644
--- a/tests/Jellyfin.Providers.Tests/Tmdb/TmdbUtilsTests.cs
+++ b/tests/Jellyfin.Providers.Tests/Tmdb/TmdbUtilsTests.cs
@@ -104,6 +104,19 @@ namespace Jellyfin.Providers.Tests.Tmdb
             Assert.Equal(expected, TmdbUtils.NormalizeTitle(title));
         }
 
+        [Theory]
+        // An unconfigured size fetches the original image, so it keeps the original resolution.
+        [InlineData(null, true)]
+        [InlineData("", true)]
+        [InlineData("original", true)]
+        [InlineData("Original", true)]
+        [InlineData("w500", false)]
+        [InlineData("original2", false)]
+        public static void IsOriginalImageSize_Valid_Success(string? size, bool expected)
+        {
+            Assert.Equal(expected, TmdbUtils.IsOriginalImageSize(size));
+        }
+
         [Theory]
         [MemberData(nameof(FindBestMatch_Movies_TestData))]
         public static void FindBestMatch_Movies_PicksExpected(string description, string name, int year, IReadOnlyList<SearchMovie> results, int expectedId)
-- 
cgit v1.2.3