91e1164090
* feat(metadata): register builtin NFO provider and broaden parsing Phases A and B of the #216 local-NFO work, implemented test-first. Registration & hint-first identity (Phase A): - Migration seeds a reserved kind='builtin' silo.builtin installation and an 'nfo' metadata capability (default_enabled=false, priority 1 for movie/series) with a partial unique index and documented Down. - In-process builtin provider registry (internal/metadata/builtin.go); buildProviders returns the registered provider for builtin rows. - Guard rails keep the reserved row out of every plugin surface (user plugin-settings, installations list, image resolvers, preload, auto-update, store Delete, mutation handlers -> 409); silo.builtin is a reserved manifest id. - Startup sync materializes legacy content_level='' chains per level, then appends builtin capabilities disabled via AppendProviderToAllChains (idempotent); resolveEnabledProvidersBy priority now respects default_enabled=false. - NFO uniqueids seed the trusted-hint machinery via IdentityHintProvider with per-mode conflict policy (stored IDs win on scheduled refresh, NFO wins on manual refresh, Identify skips NFO); ID-less candidates are excluded from provider-priority tie-breaks and nfo never counts as corroboration. - Web chain-editor empty-state gate is now server-derived so builtin providers are reachable on plugin-less servers. Parser breadth & sidecar hardening (Phase B): - Parser covers the practical Kodi/Jellyfin field set for <movie> and <tvshow>: original title, tagline, runtime, dates, content rating, genres/studios/countries/tags, multi-source ratings with scale normalization, cast with roles/order, director/credits. Empty collections stay nil so merge early-returns apply. - findNFO parses candidates and falls through on read/parse failure or root-type mismatch, so a stray movie.nfo cannot shadow tvshow.nfo; GetMetadata gains the same ContentType guard Search has. - New FieldReleaseDates lock gates Year/ReleaseDate/First+LastAirDate in merge (Go) and the edit-metadata dialog (web), closing the gap where a manual refresh re-applied NFO dates over admin corrections. - Merge-contract tests pin NFO fill semantics, genres whole-list first-provider-wins, and NFO edits propagating on manual refresh only. - Docs: new admin wiki page (supported fields, merge semantics, naming-supplies-structure contract), index bullet, sidecar wording revision, v1-scope feature-detection note. Zero behavior change while the provider is disabled (default); pinned by CI-mode and DB-gated test suites. Part of #216 AI-use disclosure: implemented with Claude Code (Fable 5) via spec-driven TDD and agent-assisted implementation. * feat(metadata): ingest local sidecar artwork and read series-depth NFO Phases C and D of the #216 local-NFO work, implemented test-first, plus the mixed-library use-case pins. Together these deliver the headline case: a series absent from every remote database (e.g. a fitness library) scans into a fully presented show -> named seasons -> titled episodes tree from NFO files and sidecar art alone. Local sidecar artwork through the S3 image cache (Phase C): - The NFO provider implements ImageProvider: poster/backdrop/logo sidecar discovery with a fixed precedence map, symlink/non-regular rejection, an 8 MiB cap, and file:// source URLs at rating 0. Generic filenames apply only via the sidecar search paths, so a shared folder.jpg in a flat multi-movie directory applies to none. - file:// becomes a live local source scheme: routed into *_source_path (never *_path), accepted by every image enqueue gate, attributed as provider "local", excluded from cached-path detection. - The image-cache processor caches local files with lexical-on-logical confinement to the library roots, open-handle reads with re-checks, the same variant widths as remote art, and stable (7-day) failure classification. Keys land under local/{contentType}/{contentID}/{hash8}/{imageType}; superseded prefixes are cleaned on re-cache and item deletion. - applyIfBetter gains a local exemption so rating-0 local art can fill matched items without being stickily displaced; ImageRequest carries additive sidecar path context. Series depth (Phase D): - SeasonsRequest/EpisodesRequest carry additive local path context (series roots, per-season directories, per-episode file paths), derived from naming at match time and reconstructed on refresh. - season.nfo supplies season name/plot; NFO season numbers are advisory (directory-derived number wins with a Warn - naming owns structure). <episodedetails> gains aired/runtime/ratings; <basename>.nfo titles episodes and <basename>-thumb.ext supplies thumbs; filename SxxEyy wins over NFO numbers. - Episode NFOs work without a season.nfo (provider seasons unioned with on-disk seasons); SynthesizeFallbackEpisodes always runs after persist so NFO-less episodes keep synthesized rows. Season/episode file:// art rides the Phase C pipeline unchanged. - Migration adds season:1/episode:1 to the builtin NFO capability's default_priority (still default_enabled=false). Mixed sports-library use case (tests only, no product change): - Pins the classification contract for one library holding movie-shaped and show-shaped content (WWE PPV events as movies next to a "WWE SmackDown" show, NASCAR/F1/FIFA with partial TVDB/TMDB data): naming decides movie-vs-series per file before any provider runs; the NFO supplies metadata/identity but never flips type (ContentType guard); the per-root Type override is the correction path. - NFO-driven type classification at scan time is recorded as an explicit deferred open question. Part of #216 AI-use disclosure: implemented with Claude Code (Fable 5) via spec-driven TDD and agent-assisted implementation. * docs(metadata): document local NFO metadata architecture Add a single as-built architecture page (docs/architecture/local-nfo-metadata.md) for the #216 local-NFO feature: the builtin registration model, hint-first identity semantics, the file:// -> S3 artwork pipeline and its deployment constraint, series depth, the mixed-library classification contract, and known limitations. This replaces the working implementation plan, the per-phase specs, and the narrow sidecar-artwork note, which were planning drafts and are left untracked; admin-facing behavior remains in the wiki. Part of #216 AI-use disclosure: planned, drafted, and consolidated with Claude Code (Fable 5) using multi-agent exploration and adversarial review. * fix(metadata): address PR review findings on NFO builtin provider Fold in the valid, low-risk fixes surfaced by automated review on #390: - imagecache: extract validateCacheRequest so CacheBytes (the local sidecar season/episode path) enforces the same episode-requires-season guard as Cache, preventing distinct episodes' art from colliding under one S3 key. - image_cache_processor: close the sidecar symlink-swap window by rejecting the opened handle unless os.SameFile matches the Lstat'd file, so a leaf swapped to a symlink can't pull an out-of-root target into the public cache. - plugins: guard the reserved builtin installation row in the store's Update, matching Delete, so its version/enabled/capabilities can never be rewritten even if a mutation slips past the HTTP layer. - cmd/silo: bound SyncBuiltinProviderChains with a 30s timeout so a stuck DB round-trip fails fast at startup instead of hanging. - metadata: panic instead of silently no-op'ing on an invalid RegisterBuiltinProvider call (init-time programmer error). - docs: correct the media-folder-and-naming NFO paragraph to state season/episode NFOs and sidecar artwork are actively read. --------- Co-authored-by: Quick104 <31828688+Quick104@users.noreply.github.com>
127 lines
7.2 KiB
Markdown
127 lines
7.2 KiB
Markdown
# Local NFO metadata and sidecar artwork (as built)
|
|
|
|
Implements #216: Kodi/Jellyfin-style `.nfo` files and sidecar images
|
|
(`poster.jpg`, `fanart.jpg`, …) next to movies and shows are read by a builtin
|
|
metadata provider, so curated local libraries work with partial or zero
|
|
TMDB/TVDB coverage. Admin-facing usage lives in
|
|
`docs/wiki/admin/nfo-local-metadata.md`; this page records the architecture for
|
|
maintainers.
|
|
|
|
## Registration: a builtin provider in the plugin chain
|
|
|
|
Provider chains are keyed on `plugin_installations` rows, so builtins are
|
|
registered **as data**: a reserved installation (`plugin_id='silo.builtin'`,
|
|
`kind='builtin'`, sentinel `install_path`, `update_policy='manual'`) plus a
|
|
`metadata_provider.v1` capability `nfo` with `default_priority` 1 for
|
|
movie/series/season/episode and `default_enabled=false`
|
|
(`migrations/sql/20260712100125_builtin_host_providers.sql`,
|
|
`...124741_nfo_capability_season_episode_levels.sql`).
|
|
|
|
- `internal/metadata/builtin.go` is the in-process registry; providers
|
|
self-register (`internal/metadata/nfo/register.go`) and `buildProviders`
|
|
(`internal/metadata/chain.go`) returns the in-process provider for
|
|
`kind='builtin'` rows instead of constructing a gRPC plugin.
|
|
- Guard rails keep the reserved row out of every plugin surface (user plugin
|
|
settings, installations list, image resolvers, preload, auto-update, store
|
|
delete, mutation handlers); `silo.builtin` is a reserved manifest id. Generic
|
|
installation reads must **not** filter builtins — the chain enabled-check
|
|
depends on them.
|
|
- On startup, `SyncBuiltinProviderChains` (`internal/metadata/builtin_sync.go`)
|
|
first materializes legacy `content_level=''` chains per level, then appends
|
|
builtin capabilities to all existing chains, disabled. New libraries pick the
|
|
capability up through normal chain seeding. The chain-less fallback respects
|
|
`default_enabled=false`.
|
|
- **Everything is inert until an admin enables "NFO Files" on a library.**
|
|
|
|
## Identity: hint-first, never candidate-first
|
|
|
|
NFO `<uniqueid>` values (tmdb/imdb/tvdb) are **trusted identity hints** seeded
|
|
before remote search (`IdentityHintProvider`, applied in
|
|
`internal/metadata/service.go`), unlocking full remote enrichment even when
|
|
search-by-title fails. Conflict policy by mode:
|
|
|
|
- initial match / scheduled refresh: NFO hints beat folder-name hints; stored
|
|
durable IDs beat NFO hints (no background identity flips);
|
|
- manual refresh: NFO hints beat stored IDs — the recovery path for a corrected
|
|
NFO. The item's `content_id` re-anchors too (not just its stored provider
|
|
IDs): a provider-anchored item whose fixed `<uniqueid>` now derives a
|
|
different anchor is renamed to it, or merged onto the existing item already
|
|
holding that id;
|
|
- manual Identify: the user's choice wins; the NFO provider is skipped for the
|
|
whole operation.
|
|
|
|
The NFO search candidate exists only for the title-only case and is defanged:
|
|
ID-less candidates lose provider-priority tie-breaks to ID-bearing group
|
|
members, `nfo` never counts as corroboration, and Phase-2 NFO results cannot
|
|
inject provider-id keys. A title-only NFO yields a `matched` item under a
|
|
path-deterministic `local:` content id; adding a `<uniqueid>` later promotes it
|
|
to that provider anchor on the next refresh (this promotion from an unanchored
|
|
id runs on scheduled refresh too — only an *already-anchored* identity is held
|
|
stable in the background). NFO field edits propagate on **manual refresh only**
|
|
(scheduled refresh is fill-empty by design).
|
|
|
|
## Sidecar artwork: copy into the S3 image cache
|
|
|
|
Sidecar images (`poster`/`folder`/`cover`, `fanart`/`backdrop`/`background`,
|
|
`logo`/`clearlogo`, and `<basename>-poster/-fanart/-logo` variants; extensions
|
|
`.jpg/.jpeg/.png/.webp`, 8 MiB cap, symlinked leaves rejected) are discovered
|
|
by the provider's `GetImages` (`internal/metadata/nfo/images.go`). Clients —
|
|
including jellycompat — always receive the normal presigned
|
|
`poster_url`/`backdrop_url`/`logo_url`; library files are never served
|
|
directly, and API nodes never need filesystem access to libraries.
|
|
|
|
- Sources are recorded as `file://<absolute-logical-path>` in `*_source_path`
|
|
columns and cached by the metadata image-cache processor under
|
|
`local/{contentType}/{contentID}/{hash8}/{imageType}/...` (`hash8` = content
|
|
hash; the discriminator sits before the imageType segment because variant
|
|
clamping reads the parent directory). Editing the file and refreshing rotates
|
|
the key; the stale hashed prefix is deleted after a successful re-cache, and
|
|
item deletion trims local paths to the content prefix.
|
|
- The processor confines each read to the owning library's `media_folders`
|
|
roots: a lexical check on the logical path, then a symlink-resolving re-check
|
|
(both path and roots are resolved, so a legitimately symlinked root stays
|
|
valid while an intermediate directory symlink escaping a root is rejected).
|
|
Missing/unreadable/out-of-root and structurally-unusable (non-regular,
|
|
over-cap) paths are stable failures with a long retry deferral; recovery is
|
|
refresh-driven — the provider-artwork backfill sweep deliberately skips
|
|
`file://` sources.
|
|
- Generic filenames attach only when the directory holds a single content
|
|
group; a shared `folder.jpg` in a flat multi-movie folder applies to none.
|
|
`<basename>-poster.jpg` style names always attach to their file.
|
|
- `applyBestImages`' final write has a local exemption so rating-0 local art
|
|
can fill already-matched items and cannot be stickily displaced by remote
|
|
art; the localization pass skips language-neutral local candidates.
|
|
|
|
**Deployment constraint:** the host running the metadata image-cache processor
|
|
must mount the media libraries at the same paths as the scanner/metadata
|
|
worker, otherwise local artwork jobs fail until the mount is present.
|
|
|
|
## Series depth and mixed libraries
|
|
|
|
`SeasonsRequest`/`EpisodesRequest` carry local path context; `season.nfo`
|
|
supplies season name/plot, `<basename>.nfo` + `<basename>-thumb.ext` supply
|
|
episode metadata/thumbs (`internal/metadata/nfo/series_depth.go`). **Naming
|
|
supplies structure; NFOs supply metadata**: NFO season/episode numbers are
|
|
advisory — directory/filename-derived numbers win with a warning. Episode NFOs
|
|
work without a `season.nfo`; `SynthesizeFallbackEpisodes` still covers
|
|
NFO-less episodes.
|
|
|
|
In `mixed` libraries, movie-vs-series is decided per file by naming before any
|
|
provider runs (`internal/naming/filename.go`); the NFO provider is seeded into
|
|
all levels and behaves as in dedicated libraries. The provider's root-element
|
|
type guard means a `tvshow.nfo` next to a movie-classified file is ignored,
|
|
never applied; the per-root Type override is the correction path. This is the
|
|
contract for sports/mixed libraries (events as movies, weekly shows as series).
|
|
|
|
## Known limitations
|
|
|
|
- The admin image picker does not surface local art (automatic chain path
|
|
only).
|
|
- Multi-part movies: a basename-mismatched NFO in a folder holding multiple
|
|
content groups is not found (directory candidates are suppressed there).
|
|
- No NFO writing, no music/audiobook/ebook NFO (those ecosystems use
|
|
OPF/metadata.json — future builtin providers via the same registry).
|
|
- Feature detection: the `nfo` capability's presence in
|
|
`GET /api/v1/libraries/provider-defaults` (see
|
|
`docs/architecture/v1-scope.md`).
|