Metadata and NFO

Metadata is the information shown for a title: name, synopsis, cast, ratings and images. This page explains where it comes from, how NFO files fit in, and how to fix a wrong match.

Where the data comes from#

Information for one item (title, synopsis, cast, rating and so on) has four sources. From highest to lowest priority:

1. Fields you edited by hand in the admin console and locked.
2. The NFO file in the folder.
3. Providers (online metadata supplied by plugins, such as TMDB).
4. What the server infers from the folder and file names (title, year, season and episode numbers).

So if there is an NFO, the NFO wins. Fields it does not have are filled by providers. For new items that have an NFO, this happens only when Fill missing data is on in the library settings; it fills empty fields and missing images and never overwrites NFO values. If there is nothing else, you at least get the name inferred from the file name. Each library decides separately whether to read NFO files, which providers to use and in what order, and which language to use.

Providers#

Open Libraries, open the library's settings and go to the Metadata tab.

• Choose the Scrape language. By default it follows the server setting.
• Under Providers, add the ones you want. They are tried in order. A library with no providers selected ("No scraping") uses only file names and NFO. If no provider is installed, install one from Plugins.
• Each item first uses an ID from its name (see File and folder naming) or an ID it already has. Only without an ID does it search by title and year. A match is applied automatically only when its score is high enough and clearly ahead of the runner-up. Uncertain items are marked Needs identifying and wait for you. The server does not guess.
• New items are scraped in the background, so scanning and playback are not held up. Items being played, and their next episodes, are scraped first.
• Images can be filled from several sources and picked by your language preference.
• A failed scrape (network problem, provider temporarily down) is retried automatically. A request that can never succeed (for example a rejected address) is not repeated forever.

If you change the language, items that were already scraped are not updated automatically. Rescrape after saving.

Image sources FREE#

Under Advanced in the library settings, Image sources lets you add extra image sources, tried in order. While scraping, posters and backgrounds from these sources are added as candidates, and the best one is picked as the main image by language preference and rating. With none selected, only the images that come with the metadata provider are used.

Name recognition PRO · MAX#

For very messy names (release-group naming, anime fansub groups) that search cannot find, add a name recognizer under Name recognition on the Metadata tab. It looks at the path and the other file names in the folder to infer a better title and episode number (including absolute anime numbering), and passes that to the providers. If the first try does not match, it tries a second round with the information from the failed attempt.

Reading NFO files#

An NFO is an XML file next to the video. Formats made by Kodi, Emby, Jellyfin, tinyMediaManager, MoviePilot, MetaTube and similar tools can be read. The switch is Use local NFO (Advanced tab).

Where to put them:

The main things it reads: title, original title, sort title, synopsis, tagline, year and release date, ratings (including critic rating), certification, genres, tags, studios, countries, cast (with role, order, photo and person ID), directors, writers, collection, code, source IDs (TMDB, IMDb, TVDB and others), trailer and lock information.

Notes:

• Genres and tags. To put several values in one <genre> or <tag> element, separate them with a space, a slash and a space (Action / Sci-Fi). A comma or a slash without spaces is treated as part of one word and is not split.
• Collections. A <set> with only a name is not enough. Include the TMDB collection ID (<set tmdbcolid="…">, or a root-level <uniqueid type="tmdbset">) to create a collection.
• Date added. <dateadded> is used as the item's date added.
• Broken NFO files do not stop a scan. The usable parts are read; if nothing can be read, the file-name inference is used instead and the problem is logged in the admin console.
• Image addresses. <thumb> and <fanart> URLs in an NFO are used as image sources. Local image files take priority.
• Forcing a refresh. If you edit an NFO, a quick scan may not notice it (the folder time is unchanged). Run a Full scan, or use Refresh… on the item.

Writing NFO files (optional)#

In the library settings, turn on Write back NFO and images (Advanced tab; off by default). The server then writes what is in its database as standard NFO files next to your videos, so the data can move with you if you switch servers or open the same library in Kodi or Emby.

• It only fills gaps: an existing NFO is not overwritten. The files the server wrote itself are updated only when you explicitly re-scrape with Re-scrape and overwrite.
• Before replacing an NFO made by another tool, it saves a backup as <file name>.nfo.orig (the first time only). Your own notes and fields from other tools (<fileinfo>, <thumb>, <fanart> and so on) are kept as they are.
• It also writes posters, backgrounds and episode thumbnails, and person photos into .actors/. This happens only when the option is on and the folder is writable.
• If the library is mounted read-only, a "cannot write" notice is shown once. The server does not keep retrying.
• If you delete the database and rebuild the library from the NFO files, you get the same content. Watch history and member data are not stored in NFO files.

To overwrite the NFO of a whole library with the server's data, use NFO sync → Overwrite all NFOs in the library settings. It needs Write back NFO and images to be on. It runs in the background and takes a while for a big library. Each NFO is backed up as .orig before it is overwritten for the first time, and content the server does not recognize is kept.

Lock fields#

After you edit a field by hand on an item's edit page, you can lock it (the whole item, or single fields). Locked fields are not overwritten by later scraping or refreshing.

• Lock information is written into the NFO (<lockdata>, <lockedfields>) and restored when you rebuild from NFO.
• Manual edits are not written back to the NFO automatically.

Fix a wrong match (Identify)#

Use this when automatic matching got it wrong, or an item shows Needs identifying.

1. On the item, choose Identify.
2. Search by title and year, or enter a source ID directly (for example a TMDB or IMDb ID).
3. Pick the right result to apply it. The server fetches metadata and images again and remembers the ID, so later refreshes do not mismatch it again.

To avoid this for good, put the ID in the folder name (see File and folder naming) or in the NFO <uniqueid>.

Unidentify removes the match and sets the item back to Needs identifying. Fields the provider already wrote keep their values until you identify or re-scrape again.

Why a source found nothing (Source status)#

When the data or an image is missing, open the item and look at Source status (it is also shown in the Identify dialog and when you refresh an actor). For each plugin it lists what happened the last time: OK, Not found, Blocked, Needs sign-in, Verification required, Timed out, Error or Not finished, with a short reason and a link to that plugin's settings. An image on the local network that a plugin is not allowed to reach yet says so; turn on local network access in the plugin's settings.

Not finished means a slow source did not answer in time. The item keeps what it already has, and the server asks that plugin again later and fills only the fields and images that are still empty. Your manual edits are never overwritten.

Tags from file names#

Tags on an item come from NFO files, imports, metadata sources, your own edits and, with name recognition (PRO), from the file name: things a scan cannot measure, such as a hard-coded subtitle mark, are kept as tags. In the item editor they are listed under From the file name. They cannot be removed there and are updated when the item is recognized again. Resolution, HDR and subtitle tracks are never taken from the name: the server measures them in the file. Tags can be used for filtering and as poster badge rules.

Refresh metadata#

You can refresh an item, a season, a whole show or a whole library with Refresh metadata (Refresh… on the item).

• Search for missing metadata queues only the items that were never scraped, failed, or are waiting to be identified. Items that already have a match are left out. For the queued items, what the provider supplies replaces the provider's earlier values; it does not just fill empty fields.
• Replace all metadata re-reads the folder and NFO files and queues every scrapable item again.
• Manual edits and locked fields are not changed. Item IDs and watch history are kept.
• Images from sources beyond the limits set in System settings → Settings → Metadata are removed (see Images).

Data from a source is also fetched again by itself once it gets old (150 days by default). This is the scheduled task Refresh outdated metadata in Tasks → Schedule. It runs once a week during the night window, and you can change the time or run it now.

A library's Scan button (quick or full) only re-reads files and does not scrape again. To scrape again, use Refresh metadata on the library page.