Scanning

A scan walks a library’s folders, files what it finds, and notices what has gone. Nothing is playable until a scan has found it.

Start a scan

Every library starts its first scan by itself as soon as you create it. After that, go to Settings → Server → Libraries and press the button on the library’s row: Scan now for a library that has never been scanned, Scan again for one that has.

Scan all, beside Add library, scans every library that isn’t already scanning. It asks first and leaves any scan already running alone.

You need to be an administrator, or have a role that allows scanning libraries, to start one.

What a scan does

While a scan runs, the library’s row shows which stage it’s at:

1. Reading files — Credenza walks every folder in the library and lists the files it can use.
2. Matching movies, Matching episodes or Matching games — each file is filed under a film, an episode or a game, using its name and folders. New items appear in your library now.
3. Measuring files — new and changed video files are read to find their length, format and size. Games skip this stage.

When it’s done, the row says how it went. Open the row to see the full result under Last scan, such as “Scanned 28 Sep 2026, 03:00 — 340 files, 12 movies added, 3 not recognised”.

Not recognised counts files the scanner couldn’t make sense of, like an episode file with no episode number in its name. They are left out rather than guessed at. Check Naming films or Naming shows and anime and rename them.

Fetching details comes after

Titles, artwork and descriptions don’t come from the scan. Once items are filed, Credenza asks the metadata providers about them in the background, and the library shows Fetching metadata… N to go until that’s done. It keeps going after the scan finishes, and a provider being slow or down never holds up a scan. See How matching works.

What a scan skips

• Files whose type isn’t on the list of Video file types (for games, the console’s own file types).
• Folders named in Folders to skip. By default these are extras, featurettes, behind the scenes, deleted scenes, trailers, samples and @eaDir, matched in any capitalisation.
• Any file or folder whose name starts with a dot.
• Files named sample, or ending in -sample, such as Heat-sample.mkv.
• Folders that are symbolic links. Linked files are followed, as long as what they point to exists.
• Anything in a folder the server can’t read. That folder is skipped and the rest of the scan carries on.

Scan on a schedule

Go to Settings → Server → Scanning. The table at the top has a row per library and a schedule for each:

• Never — only when I ask (the default)
• Every 15 minutes, Every 30 minutes, Every hour
• Every 6 hours, Every 12 hours
• Every day, at 3am
• Every Sunday, at 3am

Each row also says when the next scan is due. Times are in the time zone of the browser you set the schedule from.

Never or Pause

There are two ways to stop a library scanning by itself, and they aren’t the same:

• Never removes the schedule. The library scans only when you press the button.
• Pause keeps the schedule but stops acting on it. The library’s schedule reads “— paused” until you press Resume, and then it carries on at the same cadence.

Pause suits a short break, like while you reorganise a folder. Never suits a library on a drive that’s usually unplugged, which would otherwise fail a scan every time the schedule came round.

Neither affects the scan button on the Libraries page; you can always scan by hand.

A few more things worth knowing:

• A missed scan runs once. If the server was off at 3am, the scan runs soon after it comes back, then returns to its normal time. A server that was off for a week scans once, not seven times.
• A scan already running wins. If a scheduled scan comes due while you’re scanning that library by hand, the scheduled one is skipped rather than recorded as a failure.

What the scanner treats as a file

Below the schedule table, What a scan looks at applies to every library:

Setting	What it does
Video file types	The extensions the scanner collects, separated by commas. The default is .mkv, .mp4, .m4v, .avi, .mov, .ts and .webm. The leading dot is optional. Anything not listed is invisible to the scanner.
Folders to skip	Folder names ignored anywhere in a library, separated by commas and matched in any capitalisation. Folders starting with a dot are always skipped.
Stuck-scan check	How often, in minutes, the server looks in on a scan that is still measuring files.
Scan deadline	After this many hours a scan that is still running is failed and released, so one file the server can never measure can’t leave a library stuck. The default is 24 hours.

Changing these doesn’t rescan anything. Scan your libraries afterwards to apply them to what is already on disk.

When files move or disappear

Credenza never deletes an item because its file has gone. It marks the file missing instead, and keeps everything else.

• A file that disappears is marked missing. The item stays in the library with file missing on its tile or episode row, and can’t be played while every copy is missing. If the file comes back, the next scan picks it up again.
• A file that’s renamed or moved is, to the scanner, one file gone and a new one found. If the new name still gives the same title and year (or the same show, season and episode), it’s filed under the same item. If it gives a different title or year, it becomes a new item, and the old one stays behind with file missing. Remove it once you’re sure.
• A renamed show folder works the same way: the show under the new name is a new show, and the old one keeps its episodes marked missing.

Unplugged drives

A scan refuses to run rather than mark a whole library missing:

• If a library’s folder doesn’t exist or can’t be read, the scan fails with a reason and changes nothing.
• If a folder exists but is empty while the library still holds files from it, the scan also fails. An unmounted drive usually looks exactly like an empty folder, so Credenza assumes that’s what happened. Mount the drive and scan again. If you really have emptied that folder, remove it from the library under Edit…, or remove its items.

A folder that is empty in a brand-new library is fine; the scan just finds nothing.

More than one file for the same item

Two files that resolve to the same film, or the same episode, are filed as one item with two files. That’s normal for a 1080p and a 4K copy of the same film.

The largest file that’s still on disk plays. There’s no choice of version at play time. To make a smaller file the one that plays, unlink the larger one: open the item’s page as an administrator, find it under Files, and press Unlink. The file stays on disk, the scanner leaves it out from then on, and Relink puts it back. See Fixing matches.

Note

Split films, like cd1 and cd2, are recognised as one film, but only one part plays. Join them into a single file.