From c21c48e61eef35807484e7b4eec26586eb860f1a Mon Sep 17 00:00:00 2001 From: Frank Date: Mon, 2 Nov 2026 02:56:03 -0800 Subject: [PATCH] docs(jellyfin): the door that scans is /Library/Refresh, and the art door names its field MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The page sent the next agent to POST /Items/{id}/Refresh?Recursive=true per library to make a new folder visible. Measured against a Shows library that had never been identified: that route answers 204 and queues nothing — item census byte-identical, ScheduledTasks idle, journal silent, and still a silent 204 after a service restart. The door that works is POST /Library/Refresh, and the progress read is ScheduledTasks -> Scan Media Library -> CurrentProgressPercentage. RefreshStatus on the VirtualFolders record stays Idle through a real scan, so it is not a progress read at all; a 204 cannot distinguish accepted-and-discarded from accepted-and-queued, so the acceptance read is the journal naming folders. Also recorded the art door's wire shape, because guessing it reads as a server bug: the list response carries the address in Url (there is no ImageUrl), the Download POST takes camelCase type/imageUrl and answers 204, and PascalCase or an empty imageUrl answers 500. RemoteImages is empty for items with no ProviderIds, so art coverage is capped by identification, not by the image door. --- serverAppConfigs-docs/Dankserver/Jellyfin.md | 35 ++++++++++++++++---- 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/serverAppConfigs-docs/Dankserver/Jellyfin.md b/serverAppConfigs-docs/Dankserver/Jellyfin.md index 9d11766..2c4298c 100644 --- a/serverAppConfigs-docs/Dankserver/Jellyfin.md +++ b/serverAppConfigs-docs/Dankserver/Jellyfin.md @@ -119,6 +119,17 @@ store on a build where the automatic image pass will not run at all — it is ho the Movies library got its art: 2,515 of 2,564 films carry a primary now, and the rest have none in TMDb (shorts like `Astartes`, files whose names match nothing). +**The Download door's exact wire shape:** the list response carries the address in +`Url` — there is no `ImageUrl` field — and the POST takes camelCase query params, +`?type=Primary&imageUrl=`, answering `204`; the stored tag then appears in +`ImageTags`. PascalCase params, or an `imageUrl` left empty, answer `500`, which +reads as a server fault and is a field-name fault. + +**`RemoteImages` answers empty for an item with no `ProviderIds`** — no provider id, +nothing to look up. Art coverage is capped by identification, not by the image door: +the items a campaign returns nothing for are the unidentified ones, and no image +retry will change that. + **API shape on 12.x:** `/Items` and `/Items/{id}` need `UserId` when authenticated by API key — without it the answer is `400 Error processing request`, which reads exactly like an authentication failure. `MetadataRefreshMode` @@ -284,12 +295,24 @@ anything. The fix is `systemctl --user restart jellyfin.service`, one POST after health answers, and then believe `ScheduledTasks` State at 130 % CPU, not the response code. -**A scan that must see a new folder has to be recursive.** `POST /Library/Refresh` -is the incremental pass, and inotify does not cross a rootless podman bind, so -folders created on the host stay invisible to it. The move is -`POST /Items/{id}/Refresh?Recursive=true` (204) per library, the id from -`GET /Library/VirtualFolders` — its field is `ItemId`, not `Id` — and that same -record's `RefreshStatus` is the progress read. +**The door that scans is `POST /Library/Refresh` (204), and `ScheduledTasks` is the +progress read.** Measured 2026-11-02 against a `Shows` library that had never been +identified: the per-library `POST /Items/{id}/Refresh?Recursive=true` answers `204` +and queues **nothing** — item census identical afterwards, `Scan Media Library` +idle, journal silent — and it is still an empty `204` after a service restart, so +that status code carries no information at all. `/Library/Refresh` walks every +library; within seconds the journal names folders (`…/TVShows/…`, +`EpisodeMetadataService`) and `GET /ScheduledTasks` reports +`Scan Media Library | Running | 75 %` while the process sits near 200 % CPU. + +**`RefreshStatus` on the `GET /Library/VirtualFolders` record is not a progress +read.** It stayed `Idle` through a scan that was verifiably running at 75 %. The +record's useful field is `ItemId`, and the live library set is still the entries +whose `Locations` are non-empty. + +`inotify` does not cross a rootless podman bind, so folders created on the host +stay invisible until a pass like this runs; every pass that writes into a library +ends by firing one. **`Movies` has no watcher at all.** `EnableRealtimeMonitor` is per library (table in *Data layout*) and it is false for `Movies` and `Collections`. Nothing notices a