Create and manage libraries

A library is a set of folders on your server that Kryspal Media scans and shows as movies and series. This page shows how to add a library, how scanning works and what to do when files go missing.

Library types#

Keep movies and series in separate libraries when you can. Recognition is more accurate, and a movie file whose name looks like an episode will not be taken for a series.

If a movie library holds folders that look like TV series, the admin console Overview shows a notice, because each episode would become a separate movie. Use the shortcut in the notice to add a TV library, then put those folders there.

Add a library#

1. Open Libraries in the admin console and select Add library.
2. Choose the type, give it a name, and add one or more folders under Folders. Use absolute paths on the server. Each folder must be inside the server's media folder (MEDIA_ROOT, /media in the standard compose file), and not inside the server's own data or cache folder; otherwise the server refuses it. A library can have several folders; they are merged into one library when scanning.
3. On the Metadata tab, choose the scrape language and the Providers to use (see Metadata and NFO). A new library starts with the metadata plugins that are installed and set up already selected. One that is installed but not set up yet shows Needs setup with a Set up button.
4. Select Create library. The server starts scanning the new library by itself; you do not need to start a scan. Items appear as the scan goes on.

Media outside /media#

A library folder must be inside the media root, MEDIA_ROOT (/media by default). The server deletes files, writes NFO files and downloads subtitles there, so it refuses any path outside the root.

MEDIA_ROOT can list several roots, separated by a colon. Mount each folder in the container and add it to the list:

environment:
  - MEDIA_ROOT=/media:/mnt/movies:/data/tv
volumes:
  - /volume1/movies:/mnt/movies
  - /volume2/tv:/data/tv

The folder browser starts from these roots.

This is for keeping the container paths you already use, for example after moving from Emby or Jellyfin. Otherwise several --media options in install.sh are enough. Do not set MEDIA_ROOT to / or to a folder that contains the server's data folder; the server refuses both.

Storage: local or cloud drive#

In a library's settings, Storage says whether the files are on a local disk or on a cloud drive. You choose it; the server does not guess. It only sets recommended values for the settings below it, and each of them can still be changed on its own (it then shows Custom, with a button to restore the recommended value).

Changing the storage of an existing library applies the recommendations the same way: settings that still follow the recommendation change, real-time monitoring and external audio change only if you have not set them yourself, and a note under the choice lists what changed. The library list and the library page show Local or Cloud drive on each library.

The first scan of a large library takes a while. Items that are already in the library can be browsed and played while it runs.

Folders can be local disks, network mounts (NFS, SMB), cloud-drive mounts, or folders that hold .strm files. Your library is read-only by default. Scanning, recognition and scraping never move, rename or delete your files. The exceptions are two options you turn on yourself on a library, both off by default: Write back NFO and images (see Metadata and NFO), which writes into the library, and Allow deletion, which lets you delete media files from the admin console.

What gets scanned#

The scanner knows the common video formats (mkv, mp4, avi, ts, m2ts, iso, strm and more). Next to each video it also finds NFO files, images, external subtitles and external audio tracks.

• Very small files and sample clips (names containing "sample") are skipped.
• Hidden folders and system folders (for example @eaDir, #recycle, #snapshot on a NAS) are skipped.
• A symbolic link that points outside the library folders is not scanned. If you organize your library with links, make sure the link target is inside a library folder too.

Exclude files#

In the library settings, open the Advanced tab and find Exclude:

• Extensions — for example .nfo.
• File name keywords — matches whole words in the file name, ignoring case. Only file names are checked, not folder names.
• Videos smaller than a size — keeps intro ads and tiny previews out. Does not apply to STRM files.

After you change these rules, run a Full scan once so they apply to files that are already in the library.

Scan methods#

Start a quick or full scan from the library's page in Libraries; progress is shown there, on the library's card in the list, and in Tasks. A library that is being scanned shows how many folders are done; one that is being scraped shows how many titles are waiting. The schedule of automatic scans is under Tasks → Schedule, where you can change the interval. After an upgrade that improves recognition, a full scan runs automatically so old items are recognized with the new rules. You do not need to do anything.

Scans read files only. They do not look up details again. To scrape a library again, use Refresh metadata on the library page; it searches again for unmatched items and updates matched ones from their existing match. If the library is already being scraped, it asks you to confirm before it queues the waiting titles again.

Real-time monitoring#

On by default. When files in a folder are added, renamed or removed, the folder is rescanned about 10 seconds after the batch of changes stops. You can turn it off for a single library under Real-time monitoring. When you turn it back on, changes made in the meantime are scanned once.

Limits:

• NFS, SMB, FUSE and most cloud-drive mounts do not send file change notifications. These libraries rely on scheduled and manual scans. This is a limit of the file system, not a mistake in your setup.
• If you watch very many folders you can hit the operating system limit (on Linux, fs.inotify.max_user_watches). The admin console tells you. Raise that system value and restart the server. Until then, scheduled scans keep the library up to date.

When files disappear#

A disk that is not mounted or a network drive that drops off makes files vanish for a while. Two protections apply, both under Missing files on the Advanced tab:

• Grace period (hours): an item is removed only after its files have been gone this long. If the files come back in time, watch history and metadata are kept.
• Mass-missing threshold (%): if one scan would mark more than this share of the items as missing, it pauses and waits for you to confirm in Tasks. The server assumes a mount problem rather than a deleted library. Setting it to 100% turns the protection off.

Files you delete on purpose are removed from the library, and their watch history goes with them.

If a file is replaced instead (for example an episode is renamed, or a movie gets a new file), the new item takes over the watch history of the missing one when it is the same episode of the same series, or the same movie by TMDB or IMDb ID, in the same library.

Delete a library#

On the library's settings, Delete library (in the Danger zone) removes all items and watch history of that library. Files on disk are not touched. This cannot be undone.