Scanning And Matching#

A scan finds the media files in a folder, reads what is already known about them, and matches each one to a title. It is progressive: useful early results first, then better ones as stronger evidence arrives. The folder's own settings, such as its type and whether it trusts existing NFO files, steer every step.

For every folder setting see Folders, and for the click-by-click setup see Add your first folder. When a scan misbehaves, Scan found too few and Scan stuck or slow start from the symptom.

Stage 1: File Discovery#

MetaTana walks the folder, filters likely media files, and records file facts such as path, extension, size, modified time, and folder context.

It also notices supporting files such as NFO, artwork, subtitles, and trailers so they can inform later metadata decisions.

Discovery skips hidden folders and NAS or system housekeeping folders such as @eaDir, #recycle, @Recycle, #snapshot, $RECYCLE.BIN, and System Volume Information, plus Sample folders, so NAS snapshots and sample clips never become library items.

Stage 2: Filename And Folder Evidence#

Filename parsing extracts useful hints:

• title-like text
• year
• season and episode numbers
• absolute episode numbers
• edition or version text
• quality and technical tags
• language and subtitle hints

A folder's declared type wins over filename guesses. If a folder or an accepted match says the item is anime, show, or movie, a misleading filename never overrides it.

A new folder is added as mixed unless MetaTana's check of its contents finds only one kind, so episodes in a folder that also holds movies are not forced to be movies. A folder under an Anime path is sampled as anime when it contains episodes, unless a nearer TV folder gives a different hint. Set Advanced › Folder type when you add the folder to force one type.

More filename rules:

• Multi-episode files keep every episode. Show.S01E01-E03.mkv, Show.S01E01E02.mkv, Show.S01E01.E02.E03.mkv, Show - S01E01-S01E03.mkv, and Show 1x01-03.mkv are stored as each episode they cover, not only the first. A range up to 100 episodes wide expands in full; a wider range is read as its first episode.
• Episode numbers go up to four digits. Show.S01E1234.mkv is episode 1234, not 123.
• Anime version suffixes are not part of the number. - 05v2, E05v2, S01E05v3, and 1x05v2 are all episode 5.
• Creditless openings and endings are extras. NCOP, NCED 2, NC.OP1, Creditless OP, and Creditless Ending 2 clips are stored as extras, never as episodes.
• A file name that starts with the episode number has no show title. S01E01 - Pilot.mkv is season 1, episode 1, with the episode title "Pilot" (the same goes for 1x02 - Title.mkv). The show comes from the show folder (see Stage 5).
• Season 2024 is a season. A year-numbered season folder, common for daily shows, is season 2024, never a show title.
• Dropped apostrophes and accents still match. Title comparison ignores them, so Bobs Burgers matches Bob's Burgers and Amelie matches Amélie.
• Plex edition tags are read as the edition. Blade Runner (1982) {edition-Final Cut}.mkv is Blade Runner (1982), Final Cut edition. The tag is not part of the title, so files renamed with the Plex preset match the same title and edition on the next scan.

Stage 3: Local Metadata#

Existing NFO and sidecar files give MetaTana a starting point. It can import provider IDs, title fields, people, studios, tags, ratings, artwork, and episode facts from local sidecars before using network providers.

Local artwork beside a new file is imported during the scan even when Autopilot handles the provider work, so a movie dropped with its poster shows it right away. A -poster.jpg or -fanart.jpg in the file's own folder is read first. A plain poster.jpg or fanart.jpg is read only for a movie in a folder of its own; a movie directly in a library folder, or in a folder shared with other movies, reads only the - versions. A movie never reads artwork from the folder above its own. Local artwork only fills empty slots.

Local metadata matters because many users have already curated libraries in another tool or player. A multi-episode NFO (several blocks in one file) is read as the full episode list.

When an episode NFO and the file name disagree on the season or episode number, the NFO's numbers win and the file waits in the Inbox. The file name keeps its numbers when it or its folder marks a special and the NFO names a regular season, or when the NFO also names a different title or media type.

A root tvshow.nfo supplies the show title without replacing episode titles read from filenames. Episode NFOs, provider titles, and titles you saved still take priority.

A folder can trust its existing NFOs and artwork (Trust existing NFOs and artwork in this folder under More options in the folder's Edit folder drawer on Folders). Titles identified from an NFO with provider IDs then skip the provider search in Stage 5, providers only fill fields that are still empty, and Autopilot leaves those titles alone. A folder with no choice yet behaves as trusted; after its first scan MetaTana turns trust on when more than half of the scanned titles have an NFO with provider IDs, and off otherwise. See NFO and artwork.

If an imported NFO value targets a locked movie field or a locked season label or overview, MetaTana keeps the stored value and keeps the NFO value as a suggestion to review, instead of overwriting the locked field during the scan.

Library Quick edit can lock the values it writes when you tick Lock after editing, which is off by default. Locked values survive later scans, scrapes, and sidecar writes.

A provider refresh from Metadata tasks (in Library › Needs attention) follows the same rule for movies and episodes: locked fields stay as they are, new provider values become suggestions, and a replacement is written only after you choose it.

Background scrapes and NFO repairs for titles, shows, and seasons use the metadata as it is when they run, not as it was when they were queued. Locked values and locked empty fields survive a retry or a background repair.

Collection repairs work the same way. When MetaTana rewrites the NFO files of the movies in a collection, each movie's locked fields and artwork choices are applied first.

Stage 4: Technical Metadata#

For each media file, MetaTana runs MediaInfo locally and stores codec, resolution, duration, container, HDR, audio, and subtitle facts on the file row.

Rescan all files on a folder also re-reads unchanged files, so older titles get their technical facts filled in without waiting for a scrape or Reload media info.

Stage 5: Provider Enrichment#

Configured providers improve identity and fill fields. Common provider roles:

• TMDB for movie, TV, episode, people, collection, and artwork metadata
• TheTVDB for TV and episode metadata
• OMDb for IMDb-linked metadata and ratings
• Fanart.tv for extended artwork
• MDBList for aggregate ratings
• AniList and MyAnimeList for anime identity where set up
• Trakt ratings, once Trakt is connected

Provider data is stored with its source so the app can tell which provider supplied which field.

Posters and details keep filling in while a long scan is still running. Provider lookups slow to one at a time during the scan instead of waiting for it to finish.

When a provider can't answer#

A provider outage never reads as "No match found". When TMDb or another provider can't be reached or is limiting requests, the item says so, for example "Couldn't reach TMDb. MetaTana will try again." A missing or rejected API key says what to fix instead, for example "TMDb rejected the API key. Check it in Settings, then Rescrape." AI Vision is not used for these items, so an outage never spends AI credits. Autopilot retries a title that failed only because a provider couldn't answer, up to 3 times.

Episodes: the show first, then the episode#

An episode file does not have to name its show:

1. The show folder names the show. The folder above the file (skipping one Season 01 or Specials folder) fills in a missing show title, so Breaking Bad (2008)/Season 01/S01E01 - Pilot.mkv works. A year in the folder name (Doctor Who (2005)) sets the show's year. Category folders (TV Shows, Anime, Movies) and generic ones (Extras, Disc 1) never name a show, and a file whose own name names a different show keeps it.
2. The show is looked up once. A tvshow.nfo or a provider ID in the folder name still comes first. Next, a show you already matched for that folder (by Scrape, an NFO, or by hand) is reused with no provider call. Otherwise MetaTana runs one provider search for the folder's title and year. A 1,000-episode series costs one show search per scan, not one per file.
3. Each file keeps its own episode. A file with a season and episode number is placed on the matched show. An absolute number (Title - 12) or an air date goes to the Inbox with the show already matched, and you only pick which season and episode it is. One exception: when the show matched a single AniList or MyAnimeList entry (one season or cour, with no TMDb or TVDB match), an absolute number that fits inside that entry's episode count is accepted as season 1. MetaTana stores that episode count once the show is confirmed, so files you add to the show later are placed the same way with no provider call. A number past the end of the entry still goes to the Inbox.
4. A show Scrape settles its episodes. After you Scrape the show, its episodes no longer wait in the Inbox for "which show?"; an episode still missing a season or episode number keeps asking which episode it is.

Also:

• A bare folder is trusted only with support. When the file names no show, its folder is accepted as the show only when it sits above a Season 01 or Specials folder, is a season-pack folder, or has a year or provider ID in its name. TV Shows/Kids/S01E01.mkv could be an organizing folder, so that match waits in the Inbox. A show you already matched for the folder is still reused.
• The file's year beats the folder's year. Doctor Who (2005)/Season 1/Doctor.Who.1963.S01E01.mkv is the 1963 show.
• Season-pack folders name the show. Sherlock.S02.1080p and Better Call Saul Season 1 give the show title without the season part. A pack folder inside a folder for the same show uses that folder's name and year.

Stage 6: AI Vision#

AI Vision is for hard cases. It uses sampled frames and reviewed hints to suggest identity when filenames and providers are not enough.

AI Vision identifies the title. The rest of the metadata still comes from providers once the title is known. AI Vision is Pro and runs when you ask for it (AI Scrape); background scans never spend hosted AI credits.

Stage 7: Review And Apply#

The scan never rewrites your library behind your back. Matches MetaTana is sure about (Good) are filed on their own when the folder's Autopilot is on; everything else waits in the Inbox with a reason. You review matches, scrape previews, and field changes before applying metadata or queueing file changes, and file changes can be undone in Activity.

Folder rules#

These rules apply to every folder, whichever way you added it.

Blu-ray and DVD folders are one item#

A complete BDMV or VIDEO_TS folder is one movie. For Blu-ray, MetaTana waits for non-empty index.bdmv and MovieObject.bdmv, a playlist, and a matching non-empty clip-info/stream pair. For DVD, it waits for non-empty VIDEO_TS.IFO, a title VOB, and that title's matching IFO. Zero-byte, paused, partial, or mismatched copies stay hidden. MetaTana uses the control file to represent the folder and never guesses that the largest .m2ts or .vob file is the main movie.

Internal disc files stay hidden from normal scanning. If the control file or playable payload is missing, MetaTana leaves the incomplete folder alone instead of creating a row for every stream.

Offline, unmounted, and read-only folders#

Before a scan or scrape starts, MetaTana checks that the selected library is really mounted and readable. Before NFO, artwork, rename, organize, or delete work, it also checks write access. If the folder is offline, unmounted, or not visible inside Docker, the action stops before any provider lookup, queued work, database change, or file change.

The error shows the library path. Mount or reconnect that path, then run the action again. MetaTana also accepts another path it has already verified for the same folder. It never guesses that a similarly named macOS mount such as /Volumes/Media-1 is the missing disk. Use Reconnect folder… to choose and verify the exact changed mount path.

Each folder's row in Folders shows its state, such as Offline, Not responding, Read only, or when it was last checked. Not responding means MetaTana could not finish the check quickly enough; it does not guess that a slow share is safe. An offline folder's row has Check again, and Reconnect folder… is in its ⋯ menu. Check again only checks access; it does not start work. A folder cannot scan until the fresh result says it is online.

Each folder records where it lives: This folder is on under More options in the folder's Edit folder drawer on Folders (and in the full add-folder form) offers This computer, A network share, or A removable drive. Paths that start with \\, //, smb:, or nfs: are set to a network share automatically; set the others yourself. For a network share or removable drive, when the folder is empty or can't be read, its items show Source offline in Library instead of File missing, because the share is likely disconnected or the drive unplugged rather than the files deleted. For a folder on this computer, files that disappear show as missing. Changes made to a network share from other computers may wait for the next scan.

A read-only folder (a Docker :ro mount, a read-only share, or an NTFS drive on macOS) scans and is watched like any other folder, and MetaTana fetches its metadata. Folders shows Read only with "Scans work, file changes are blocked". NFO, artwork, rename, organize, and delete need write access and do not run there.

On a read-only folder, Autopilot still identifies files and saves their metadata in MetaTana, but writes no files there. It leaves one notice per folder, not one per file, titled with the folder path followed by is read-only: "This folder is read-only, so MetaTana saved the metadata but wrote no NFO or artwork files. Give MetaTana write access to write them." Scrapes you start yourself and explicit file actions still stop with Library folder is not writable.

On Linux, MetaTana remembers the verified filesystem for custom or symlinked folder paths. If the disk disappears and leaves a normal writable folder behind, that folder does not count as the library. Use Reconnect folder… after the real filesystem returns.

When a write action is blocked, the result says: MetaTana started no provider, queue, metadata, or file work. The failed check left no half-written metadata behind.

Watching and Arrivals#

If a folder receives files that are still being written, use an Incoming folder: Arrivals waits for each file to settle. Watching a Library folder reacts to every write while a file is still being copied.

Ongoing scans, change watching, and Autopilot are on by default for every way to add a folder (Home, Library, and Folders). MetaTana starts watching after the first scan begins. Watch folders for changes in Settings › General › Scanning turns watching on or off for every folder at once. Turn off Keep this folder updated under Advanced for one scan only. A desktop exact-file drop scans only that file and never watches its parent folder.

When folder watching starts or a drive reconnects, MetaTana checks for changes made while it was offline. This check can take time on a large network share. Unchanged files skip matching.

Incremental and full scans#

Routine scans are incremental. Scan now, Scan all, scheduled scans, and folder watching process new and changed files, fill in technical details for files that are still missing them, and skip everything else. A desktop drop scans only the paths you dropped. The first scan of a folder reads every file because nothing has been seen yet.

A drop or Scan now starts without waiting for a backlog of metadata work from earlier scans to finish. It waits only for work that is already running, and Cancel works while it waits. Cancel also stops that scan's provider requests and retry waits. Other scans can keep running.

A full scan re-reads every file. Use one after you edit NFO files by hand or change a folder's role or type. To run one, open Folders and choose Rescan all files in the folder's ⋯ menu (it is also in Edit folder). It checks every file again, including unchanged ones, so it is slower. It runs once for that folder and does not change the incremental setting. To make every scan full, turn off Incremental scan in Settings › General › Scanning.

Changing a scan option keeps your other saved options. If Settings › General cannot load them, editing waits and the page shows Retry. Try again to load your saved choices before making changes.

Dry run#

Dry run is Preview only (no file changes) in Settings › General › Scanning. Autopilot changes no files while it is on: no moves, renames, NFO, artwork, subtitles or trailers. Autopilot proposes moves and renames for you to approve in the Inbox under Renames, and Arrivals leaves ready batches waiting for you to approve instead of filing them. Scans and metadata in MetaTana work as usual, and anything you start yourself (Rescrape, Write NFO, editor Save, Approve) still writes.

When Preview only is on, Home can show Preview only is on, so Autopilot changes no files. Select Turn off Preview only to let Autopilot write files again in folders where you allowed it, or Keep it on to keep approving each change.

Autopilot checks Dry run again right before each move it queued on its own. If you turn Dry run on while moves are waiting, those files stay where they are with "Preview only is on in Settings › General, so this file was not moved".

What to check after a scan#

Don't judge a scan from one page alone. Background work can finish after Library first loads:

• Library count: does it roughly match what's on disk?
• Activity: anything failed?
• The folder's row in Folders: scan status and when it was last checked
• Settings › Maintenance › Library health: ghost entries and untracked files
• Show, season, and episode grouping for TV
• The Inbox: files with no match or a Fair or Weak match waiting for you

If an older MetaTana version already indexed internal .m2ts or .vob files from a disc folder, run one successful full scan (Rescan all files) after upgrading. After the complete disc control item is safely stored, that same scan removes the old standalone stream records from MetaTana's database. It does not change the disc files. Failed, incomplete, cancelled, or targeted watcher scans keep the old records for safety.