feat(images): client-selectable artwork size via image_size

cmd/silo/main.go

@@ -40,6 +40,7 @@ import (
 	"github.com/Silo-Server/silo-server/internal/adminjob"
 	"github.com/Silo-Server/silo-server/internal/api"
 	"github.com/Silo-Server/silo-server/internal/api/handlers"
+	"github.com/Silo-Server/silo-server/internal/artworkkey"
 	"github.com/Silo-Server/silo-server/internal/audiobooks"
 	"github.com/Silo-Server/silo-server/internal/audiobooks/abs"
 	"github.com/Silo-Server/silo-server/internal/audiobooks/podcastfeed"
@@ -2243,7 +2244,15 @@ func main() {
 			taskMgr.Register(tasks.NewRefreshMetadataTask(refreshWorker, metadataService))
 		}
 		if metadataImageCacheProcessor != nil {
-			taskMgr.Register(tasks.NewCacheMetadataImagesTask(metadataImageCacheProcessor))
+			cacheImagesTask := tasks.NewCacheMetadataImagesTask(metadataImageCacheProcessor)
+			// Artwork cached under an older variant ladder is missing the rungs
+			// a client can now ask for. Arm the one-shot regeneration pass; it
+			// records the version it finished and then costs nothing.
+			cacheImagesTask.SetLadderBackfill(
+				metadata.NewImageLadderBackfillStateRepository(pool),
+				artworkkey.LadderVersion,
+			)
+			taskMgr.Register(cacheImagesTask)
 			taskMgr.Register(tasks.NewBackfillMetadataImagesTask(metadataImageCacheProcessor))
 		}
 		if deps.S3Public != nil {

docs/feature-changelog.md

@@ -34,6 +34,17 @@ that can stream MKV keep direct play, and Firefox keeps its video and audio code
 
 ## 2026-08-24
 
+### Let clients choose the artwork size they receive
+Silo used to decide artwork width for you: card rows got narrow images, hero areas got wide ones. That guess is wrong often enough to matter — a TV renders a "card" at 600px, a phone renders a "hero" at 400 — and clients had no way to say so, so they either accepted a blurry image or wasted bandwidth on one far larger than the screen.
+
+Catalog browse, item and watch detail, seasons and episodes, and the home and library sections now accept `image_size=small|medium|large|original`. It applies to the whole response, so a screen never mixes resolutions, and it overrides every per-context default including the wider backdrop Continue Watching used. Sending nothing keeps today's behavior exactly, so no existing client changes; sending a value the server does not serve is a `400` rather than a silent fallback.
+
+Posters and stills gained a 780px width and logos a 1280px width to make `large` meaningful — the old ladder topped out at 500px for those, so "large" would have meant "the original" and nothing in between. Cast and crew headshots deliberately did not: they are only ever rendered small.
+
+Artwork cached before this change has no file at the new widths. A one-shot background pass regenerates it after the ordinary artwork queue drains, and until it reaches a given image the server serves the next narrower width it does have instead of a broken URL. Nothing to configure and no action required; the correct width appears on its own.
+
+Jellyfin clients benefit without changing anything: a request between 780 and 1199 pixels now maps to the new wider image rather than being rounded down. See [docs/images-api.md](images-api.md) for the width table and the `/api/v1/images/capability` endpoint clients should read it from.
+
 ### Restore loudness when Silo downmixes surround audio to stereo
 Surround sound mixed down by Silo could be about 6 dB quieter than the same
 file in other media apps. Server-owned stereo conversions now restore that

docs/images-api.md

@@ -0,0 +1,118 @@
+# Images API
+
+Silo caches artwork at a fixed ladder of widths and returns a presigned URL for
+one of them. By default the server picks the width from context — card rows get
+narrow images, hero areas get wide ones. A client that knows better can ask for a
+specific size instead.
+
+Commands and paths in this document are relative to the repository root.
+
+## The parameter
+
+Add `image_size` to a request. It applies to the whole response: every artwork
+URL in the body is resolved at that size, so a screen never mixes resolutions.
+
+```http
+GET /api/v1/catalog?image_size=large
+GET /api/v1/catalog/items/{id}?image_size=small
+GET /api/v1/home/sections?image_size=medium
+```
+
+Accepted values are `small`, `medium`, `large`, and `original`. Anything else is
+`400 invalid_image_size` — a typo is a client bug, and quietly serving a default
+would hide it behind artwork that is merely the wrong resolution.
+
+Omitting the parameter keeps the per-context defaults exactly as they were, so no
+existing client is affected.
+
+The parameter is accepted on:
+
+- catalog browse and query
+- item detail and watch detail
+- seasons, a single season, and episodes
+- home and library sections, including single-section items
+- the personal lists: `/favorites`, `/watchlist`, and `/history`
+
+Other surfaces ignore it.
+
+Within item detail this covers cast and crew headshots too: they follow the
+`profile` ladder, which has no wide rung, so `large` and `medium` land on the
+same 500px image.
+
+The `/people` endpoints do **not** take the parameter — their headshots are
+always the 500px variant. Browsing a person's filmography does honor it, because
+that is `/api/v1/catalog?source=person` rather than a person endpoint.
+
+On the personal lists the per-slot defaults are asymmetric — a 500px poster
+beside a 300px backdrop — so an explicit size changes both, not just the one that
+looks wrong.
+
+## Widths
+
+| Image type | `small` | `medium` | `large` | `original` |
+| --- | --- | --- | --- | --- |
+| poster | 300 | 500 | 780 | up to 1920 |
+| still | 300 | 500 | 780 | up to 1920 |
+| backdrop | 300 | 1920 | 1920 | up to 1920 |
+| logo | 500 | 500 | 1280 | up to 1920 |
+| profile | 300 | 500 | 500 | up to 1920 |
+
+`medium` is the width the server chose before this parameter existed, which is
+why it is not always the middle rung. `original` is the cached original, capped
+on ingest at 1920px on its longest edge — it is not the provider's untouched
+file.
+
+Artwork hosted by a metadata plugin rather than cached in the bucket has no
+fixed width. For those the size is forwarded to the plugin as a semantic variant
+hint — `card`, `featured`, `large`, or `original`, out of the SDK's open
+`card`/`featured`/`large`/`full`/`original` vocabulary — and the plugin picks the
+closest image it has, so the widths above are indicative rather than exact.
+
+Do not hardcode this table. Read it from the capability endpoint: the ladder is
+allowed to change, and the endpoint is generated from it.
+
+## Capability endpoint
+
+```http
+GET /api/v1/images/capability
+```
+
+```json
+{
+  "schema_version": 1,
+  "param": "image_size",
+  "sizes": ["small", "medium", "large", "original"],
+  "widths": {
+    "poster": { "small": 300, "medium": 500, "large": 780 },
+    "backdrop": { "small": 300, "medium": 1920, "large": 1920 },
+    "still": { "small": 300, "medium": 500, "large": 780 },
+    "logo": { "small": 500, "medium": 500, "large": 1280 },
+    "profile": { "small": 300, "medium": 500, "large": 500 }
+  },
+  "original_max_width_px": 1920
+}
+```
+
+A `404` here means the server predates `image_size`. Keep using the server's
+defaults rather than sending a parameter it will ignore.
+
+## Fallback while artwork is being regenerated
+
+The wide rungs (780px posters and stills, 1280px logos) were added after this
+ladder shipped, so artwork cached by an earlier version has no object at those
+keys. A one-shot background pass regenerates it, and until that pass reaches a
+given image the server serves the next narrower rung it does have, ending at the
+original.
+
+The practical consequence for a client is that shortly after a server upgrade,
+`image_size=large` may return an image narrower than the table above. It is never
+a broken URL, and no client action is required: the correct width appears once
+the pass completes. URLs served from a fallback carry a shortened expiry so the
+real rung is picked up promptly rather than a day later.
+
+## Jellyfin compatibility
+
+The Jellyfin-protocol surface maps its own `MaxWidth`/`MaxHeight`/`FillWidth`/
+`FillHeight` parameters onto the same ladder: up to 320px is `small`, 780px to
+1199px is `large`, 1200px and above is `original`, and everything else is
+`medium`.

internal/api/handlers/audiobook_groups.go

@@ -5,7 +5,9 @@ import (
 	"strconv"
 	"strings"
 
+	"github.com/Silo-Server/silo-server/internal/artworkkey"
 	"github.com/Silo-Server/silo-server/internal/catalog"
+	"github.com/Silo-Server/silo-server/internal/imagesize"
 )
 
 type audiobookGroupResponse struct {
@@ -104,7 +106,7 @@ func (h *CatalogHandler) HandleGetAudiobookGroups(w http.ResponseWriter, r *http
 		return
 	}
 
-	resolvedPosters := h.resolveAudiobookGroupPosterURLs(r, result.Groups)
+	resolvedPosters := h.resolveAudiobookGroupPosterURLs(r, result.Groups, filter.ImageSize)
 	resp := audiobookGroupsResponse{
 		Total:      result.Total,
 		TotalExact: result.TotalExact,
@@ -114,7 +116,7 @@ func (h *CatalogHandler) HandleGetAudiobookGroups(w http.ResponseWriter, r *http
 	for _, g := range result.Groups {
 		posterURLs := make([]string, 0, len(g.PosterPaths))
 		for _, path := range g.PosterPaths {
-			if resolved := resolvedPosters[cardThumbnailPath(path)]; resolved.URL != "" {
+			if resolved := resolvedPosters[sizedCardPath(path, artworkkey.ImagePoster, filter.ImageSize)]; resolved.URL != "" {
 				posterURLs = append(posterURLs, resolved.URL)
 			}
 		}
@@ -131,7 +133,11 @@ func (h *CatalogHandler) HandleGetAudiobookGroups(w http.ResponseWriter, r *http
 	writeJSON(w, http.StatusOK, resp)
 }
 
-func (h *CatalogHandler) resolveAudiobookGroupPosterURLs(r *http.Request, groups []catalog.AudiobookGroup) map[string]catalog.ResolvedImageURL {
+// resolveAudiobookGroupPosterURLs presigns the cover-stack posters for a page of
+// groups. size is the already-validated size off the request's access filter, so
+// the ladder rung and the plugin hint match the rest of the response instead of
+// being re-derived per item.
+func (h *CatalogHandler) resolveAudiobookGroupPosterURLs(r *http.Request, groups []catalog.AudiobookGroup, size imagesize.Size) map[string]catalog.ResolvedImageURL {
 	if h == nil || h.itemsH == nil || h.itemsH.detailSvc == nil || len(groups) == 0 {
 		return map[string]catalog.ResolvedImageURL{}
 	}
@@ -140,7 +146,7 @@ func (h *CatalogHandler) resolveAudiobookGroupPosterURLs(r *http.Request, groups
 	seen := make(map[string]struct{}, len(groups)*4)
 	for _, group := range groups {
 		for _, path := range group.PosterPaths {
-			normalized := cardThumbnailPath(path)
+			normalized := sizedCardPath(path, artworkkey.ImagePoster, size)
 			if normalized == "" {
 				continue
 			}
@@ -151,5 +157,5 @@ func (h *CatalogHandler) resolveAudiobookGroupPosterURLs(r *http.Request, groups
 			paths = append(paths, normalized)
 		}
 	}
-	return h.itemsH.detailSvc.PresignURLsWithExpiry(r.Context(), paths, "card")
+	return h.itemsH.detailSvc.PresignURLsWithExpiry(r.Context(), paths, requestVariantHint("card", size))
 }

internal/api/handlers/catalog.go

@@ -201,7 +201,7 @@ func (h *CatalogHandler) catalogItemResponses(r *http.Request, resultItems []*mo
 	responseWG.Add(2)
 	go func() {
 		defer responseWG.Done()
-		imageURLs = h.itemsH.itemListCardImageURLs(r.Context(), localizedItems)
+		imageURLs = h.itemsH.itemListCardImageURLs(r.Context(), localizedItems, accessFilter.ImageSize)
 	}()
 	go func() {
 		defer responseWG.Done()
@@ -714,7 +714,7 @@ func (h *CatalogHandler) HandlePostCatalogQuery(w http.ResponseWriter, r *http.R
 				item = localized
 			}
 		}
-		items = append(items, h.itemsH.toItemListResponseWithOverlay(r, item, nil, userStates[item.ContentID]))
+		items = append(items, h.itemsH.toItemListResponseWithOverlay(r, item, nil, userStates[item.ContentID], accessFilter.ImageSize))
 	}
 
 	writeJSON(w, http.StatusOK, browseResponse{
@@ -813,7 +813,7 @@ func (h *CatalogHandler) HandleLegacySearch(w http.ResponseWriter, r *http.Reque
 	userStates := h.itemsH.listItemUserStates(r, items)
 	resp := make([]itemListResponse, 0, len(items))
 	for _, item := range items {
-		resp = append(resp, h.itemsH.toItemListResponseWithOverlay(r, item, nil, userStates[item.ContentID]))
+		resp = append(resp, h.itemsH.toItemListResponseWithOverlay(r, item, nil, userStates[item.ContentID], accessFilter.ImageSize))
 	}
 
 	writeJSON(w, http.StatusOK, browseResponse{

internal/api/handlers/catalog_resources.go

@@ -271,7 +271,7 @@ func (h *CatalogResourceHandler) HandleGetSeasons(w http.ResponseWriter, r *http
 				if hasProgressMap {
 					userData = catalog.EpisodeRollupUserData(episodes, progressMap)
 				}
-				sr := h.items.seasonResponseFromEpisodes(r, s, episodes, userData)
+				sr := h.items.seasonResponseFromEpisodes(r, s, episodes, userData, filter.ImageSize)
 				resp = append(resp, sr)
 			}
 
@@ -366,6 +366,7 @@ func (h *CatalogResourceHandler) HandleGetSeason(w http.ResponseWriter, r *http.
 					season,
 					episodes,
 					h.items.getAggregateUserData(r, episodes),
+					filter.ImageSize,
 				),
 			})
 			return
@@ -462,6 +463,9 @@ func (h *CatalogResourceHandler) syntheticSeasonDetail(r *http.Request, seasonID
 	if err != nil {
 		return nil, err
 	}
+	// The entrypoint has already rejected an unparseable size; this only carries
+	// the validated one down to the detail service and the season response.
+	filter.ImageSize = requestImageSize(r)
 
 	seriesDetail, err := h.items.detailSvc.GetItemDetail(r.Context(), seriesID, filter)
 	if err != nil {
@@ -492,6 +496,7 @@ func (h *CatalogResourceHandler) syntheticSeasonDetail(r *http.Request, seasonID
 		season,
 		episodes,
 		h.items.getAggregateUserData(r, episodes),
+		filter.ImageSize,
 	)
 	return &catalog.ItemDetail{
 		ContentID:         seasonID,

internal/api/handlers/favorites.go

@@ -12,6 +12,7 @@ import (
 	"github.com/go-chi/chi/v5"
 
 	apimw "github.com/Silo-Server/silo-server/internal/api/middleware"
+	"github.com/Silo-Server/silo-server/internal/artworkkey"
 	"github.com/Silo-Server/silo-server/internal/catalog"
 	evt "github.com/Silo-Server/silo-server/internal/events"
 	"github.com/Silo-Server/silo-server/internal/models"
@@ -132,6 +133,9 @@ const (
 
 // HandleListFavorites handles GET /favorites.
 func (h *PersonalDataHandler) HandleListFavorites(w http.ResponseWriter, r *http.Request) {
+	if !rejectInvalidImageSize(w, r) {
+		return
+	}
 	userID := apimw.GetUserID(r.Context())
 	profileID := apimw.GetProfileID(r.Context())
 
@@ -288,6 +292,9 @@ func (h *PersonalDataHandler) dispatchLocalListEvent(ctx context.Context, list w
 
 // HandleListWatchlist handles GET /watchlist.
 func (h *PersonalDataHandler) HandleListWatchlist(w http.ResponseWriter, r *http.Request) {
+	if !rejectInvalidImageSize(w, r) {
+		return
+	}
 	userID := apimw.GetUserID(r.Context())
 	profileID := apimw.GetProfileID(r.Context())
 
@@ -453,6 +460,9 @@ func (h *PersonalDataHandler) HandleRemoveFromWatchlist(w http.ResponseWriter, r
 
 // HandleListHistory handles GET /history.
 func (h *PersonalDataHandler) HandleListHistory(w http.ResponseWriter, r *http.Request) {
+	if !rejectInvalidImageSize(w, r) {
+		return
+	}
 	userID := apimw.GetUserID(r.Context())
 	profileID := apimw.GetProfileID(r.Context())
 
@@ -587,6 +597,13 @@ func resolveItemsByIDs(h *PersonalDataHandler, r *http.Request, ids []string) ([
 	// Index by content ID for order-preserving lookup.
 	byID := make(map[string]*itemListResponse, len(mediaItems))
 	filter := requestAccessFilter(r)
+	// Parsed once for the whole list; the calling handler has already rejected
+	// an unrecognized value. Unset keeps the per-slot defaults below, which are
+	// deliberately asymmetric (a featured poster beside a card backdrop); an
+	// explicit size applies to every image in the response instead.
+	size := requestImageSize(r)
+	posterHint := requestVariantHint("featured", size)
+	cardHint := requestVariantHint("card", size)
 	accessibleItems := make([]*models.MediaItem, 0, len(mediaItems))
 	for _, mi := range mediaItems {
 		if err := h.itemRepo.EnsureAccessible(r.Context(), mi.ContentID, filter); err != nil {
@@ -622,8 +639,8 @@ func resolveItemsByIDs(h *PersonalDataHandler, r *http.Request, ids []string) ([
 			BackdropThumbhash: mi.BackdropThumbhash,
 			UserState:         userStates[mi.ContentID],
 		}
-		resp.PosterURL = h.presignURL(r, featuredPosterPath(mi.PosterPath), "featured")
-		resp.BackdropURL = h.presignURL(r, cardThumbnailPath(mi.BackdropPath), "card")
+		resp.PosterURL = h.presignURL(r, sizedPosterPath(mi.PosterPath, size), posterHint)
+		resp.BackdropURL = h.presignURL(r, sizedCardBackdropPath(mi.BackdropPath, size), cardHint)
 		byID[mi.ContentID] = &resp
 	}
 
@@ -664,14 +681,14 @@ func resolveItemsByIDs(h *PersonalDataHandler, r *http.Request, ids []string) ([
 					}
 					// Use episode still as backdrop, fall back to parent series images.
 					if ep.StillPath != "" {
-						resp.BackdropURL = h.presignURL(r, cardThumbnailPath(ep.StillPath), "card")
+						resp.BackdropURL = h.presignURL(r, sizedCardPath(ep.StillPath, artworkkey.ImageStill, size), cardHint)
 						resp.BackdropThumbhash = ep.StillThumbhash
 					} else if parent != nil {
-						resp.BackdropURL = h.presignURL(r, cardThumbnailPath(parent.BackdropPath), "card")
+						resp.BackdropURL = h.presignURL(r, sizedCardBackdropPath(parent.BackdropPath, size), cardHint)
 						resp.BackdropThumbhash = parent.BackdropThumbhash
 					}
 					if parent != nil {
-						resp.PosterURL = h.presignURL(r, featuredPosterPath(parent.PosterPath), "featured")
+						resp.PosterURL = h.presignURL(r, sizedPosterPath(parent.PosterPath, size), posterHint)
 						resp.PosterThumbhash = parent.PosterThumbhash
 						resp.Year = parent.Year
 						resp.Genres = parent.Genres