docs: document NFO fields, local artwork names, and NFO use in Mixed libraries #42

Use local NFO metadata explains how to turn on the NFO Files provider and which file names to use, but not which NFO elements Silo reads. It also leaves out the artwork file names for movies and shows, the rules that decide when local art applies, and how NFOs behave in a Mixed library. Administrators with curated Kodi, Jellyfin, or tinyMediaManager libraries, or home video and sports libraries with no online match, need this to get their local data to show. The server repository is removing its copy of this material in Silo-Server/silo-server#1635.

The old server page is linked for reference. Parts of it were stale, so check each claim against current silo-server code (internal/metadata/nfo/) and docs/architecture/local-nfo-metadata.md before publishing.

What to change

src/content/docs/docs/running-a-server/local-metadata.md

• Field table. Replace the prose list in "What gets used" with a table (old table):

  Element	Applies to	Becomes
  <title>, <originaltitle>, <tagline>, <plot>	movie, series	title, original title, tagline, overview
  <year>	movie, series	year; taken from the premiere date when omitted
  <runtime>	movie, series	runtime in minutes; non-numeric values are ignored
  <premiered> or <releasedate>	movie	release date, YYYY-MM-DD
  <premiered> or <aired>	series	first air date, YYYY-MM-DD
  <mpaa>	movie, series	content rating
  <genre>, <studio>, <country>, <tag> (repeated)	movie, series	genres, studios, countries, keywords
  <ratings> / <rating>	movie, series	ratings from the named sources imdb, tmdb or themoviedb, tomatometerallcritics (also rottentomatoes), and tomatometerallaudience; a bare legacy <rating> fills the IMDb rating
  <actor> with name, role, order	movie, series	cast; actor <thumb> is ignored
  <director>, <credits>	movie, series	directors and writers
  <uniqueid type="tmdb">, type="imdb", type="tvdb"	movie, series	provider IDs used to identify the title
  <title>, <plot> in season.nfo	season	season name and overview
  <title>, <plot>, <aired>, <runtime>, <ratings> in <episodedetails>	episode	episode title, overview, air date, runtime, ratings

• Add: Silo ignores elements it doesn't read, so exports from Kodi, Jellyfin, or tinyMediaManager work as they are. Keep the existing line that NFOs don't set watched status, personal ratings, or collections.

• Season artwork. Replace the poster.jpg sentence. Silo looks for poster, folder, or cover inside the season folder, then seasonNN-poster in the show folder (for example season01-poster.jpg). Season 0 also accepts season-specials-poster. Extensions: .jpg, .jpeg, .png, .webp.

• Movie and show artwork. Add a section:

  • Poster: poster, folder, cover, or <media basename>-poster.
  • Background: fanart, backdrop, background, or <media basename>-fanart.
  • Logo: logo, clearlogo, or <media basename>-logo.
  • Same extensions as season art. Files over 8 MiB, empty files, and symlinks are skipped.
  • Names without the basename (poster.jpg, folder.jpg) apply only when the folder holds a single title. A shared folder.jpg in a folder of several movies applies to none of them. <media basename>-poster.jpg always applies to its own file.
  • Local art is used only when NFO Files is enabled for the library, but it works without an .nfo file.
  • After replacing an image, refresh the item.
  • The image picker in Edit Metadata doesn't list local art.
  • Servers with more than one node: the node that caches images must see the media at the same paths as the scanner, or local art fails to load.

• A fully local series. Add an example with no online match:

  Fitness/
    Workout Series/
      tvshow.nfo            # show title and plot, no <uniqueid> needed
      poster.jpg
      fanart.jpg
      Season 01/
        season.nfo          # season name, such as "Course A"
        poster.jpg          # season poster
        Workout Series S01E01 - Chest and Back.mkv
        Workout Series S01E01 - Chest and Back.nfo        # episode title and plot
        Workout Series S01E01 - Chest and Back-thumb.jpg  # episode image
  

  Folder and file names build the show, season, and episode tree; the NFOs supply names, descriptions, and images. An episode without an .nfo keeps the title Episode N, so a partly curated show still works.

• Identity. Add to "When changes don't appear":

  • An NFO with only a title matches locally, without an online provider.
  • Adding a <uniqueid> later links the item to that provider at the next refresh.
  • If an NFO had the wrong <uniqueid>, fix it and refresh the item. A manual refresh follows the NFO's ID, even over the ID the item already has.
  • Match Item ignores the NFO, so the title you pick wins.

• Mixed libraries. Add a section, with a sports example:

  WWE/
    WrestleMania 41 (2025)/
      WrestleMania 41 (2025).mkv
      movie.nfo             # event title and plot; <uniqueid> optional
      poster.jpg
    WWE SmackDown/
      tvshow.nfo
      Season 27/
        season.nfo
        poster.jpg
        WWE SmackDown S27E15.mkv
        WWE SmackDown S27E15.nfo
        WWE SmackDown S27E15-thumb.jpg
  

  • Folder and file names decide whether a file is a movie or an episode before any NFO is read. An NFO never changes that. A tvshow.nfo beside a file classified as a movie is ignored.
  • Link to the Mixed classification order on Add and manage libraries (requested in the companion naming issue). Put every episode in a Season NN folder: a show folder with a provider tag and no season folders is classified as a movie.
  • An event with <uniqueid type="tmdb"> still gets online data; events without one use their NFO and local art.
  • If a folder is classified wrongly, fixing the NFO won't move it. If the folder is listed under Ambiguous Roots in Admin > Libraries, change its Type there, then scan. Otherwise fix the folder layout.
  • Tools that generate these libraries should write Title (Year)/ folders for events and SxxEyy names inside Season NN folders for shows.

src/content/docs/docs/running-a-server/media-folders.md

• The movie example shows a poster.jpg. Say that Silo uses it only when NFO Files is enabled for the library, and link to the artwork section above.

Don't carry over

• The old page says the NFO provider sits at priority 1 by default. It is off by default, and in libraries that existed before the provider shipped it was added last. The manual's current steps (enable NFO Files and move it first) are correct.
• The old page describes Mixed classification as "An SxxEyy pattern or a Season NN folder routes a file to the series lane; everything else is a movie." That isn't the order the code applies: a movie-style parent folder wins over an SxxEyy token when there's no season folder. Use the order from the naming issue.
• The GET /api/v1/libraries/provider-defaults feature-detection note is for client developers, not administrators.

AI disclosure: drafted with Claude Code (claude-opus-5-5[1m]) from an audit of the server repository's docs against the manual and current server code.