Library Maintenance

Norri keeps your libraries up to date with a combination of automatic background tasks and manual maintenance tools. This guide explains what each operation does and when to use it.

The Four Operations

Norri has four distinct maintenance operations. Each one has a specific purpose. Some run automatically on a schedule, and all can be triggered manually from a library’s settings page.

Library Scan

What it does: Finds new files, removes deleted ones, and matches new media from your metadata sources.

Details:

• Walks through all your library folders looking for new, moved, or deleted media files
• Reads the technical details of each new file (video and audio codecs, resolution, tracks, and so on) as it is added. This is a fast read of the file header, taking a fraction of a second per file, not a full analysis of the whole file
• Matches new files using the metadata sources configured for the library, then downloads metadata and artwork
• Files that have been removed from disk are marked as unavailable
• Existing files that haven’t changed are skipped, and are not re-read

Library Scan does not re-fetch metadata for items that are already in your library. It only processes new or changed files. Re-reading the technical details of files you already have is a separate operation, Analyse Files, described below.

Automatic triggers: Library Scan can run in three situations:

1. Startup Scan runs when the server starts, if enabled, to catch files added while the server was offline
2. Daily Library Scan runs at a configurable time, defaulting to 4 AM, and is useful for NAS and network shares where Automatic File Detection may miss changes
3. Automatic File Detection monitors your library folders for new, modified, or deleted files. Local folders are monitored in real time. Network shares are polled every 5 minutes. When changes are detected, Library Scan starts automatically after a short delay so batch operations, such as a download tool adding multiple files, can finish

Update Metadata

What it does: Fetches updated details, ratings, and artwork from your metadata sources. Respects locked fields.

Details:

• Checks your metadata sources for changes to items already in your library
• Updates details, ratings, descriptions, artwork, cast, crew, genres, biographies, and other source-provided fields where available
• Respects locked fields and locked artwork. These are never overwritten
• For updated items, checks if artwork specifically changed. If so, re-downloads it. If not, downloads only if missing on disk

Because only changed items are touched, this runs quickly even for large libraries.

Automatic trigger: Daily Metadata Update runs daily at a configurable time, defaulting to 3 AM.

Replace Metadata

What it does: Re-downloads all metadata from your metadata sources, replacing existing data except locked fields.

When to use:

• After a database issue or migration
• If you suspect metadata is incorrect or incomplete
• If you want to pull newly available artwork (like logos) that weren’t available when items were first added

Details:

• Re-downloads source-provided metadata, ratings, descriptions, people, genres, biographies, classifications, social links, and artwork where available
• Replaces all existing metadata and artwork, except anything you’ve locked
• Does not scan for new files. Use Library Scan for that

No automatic schedule: This operation is manual only, triggered from the library settings page.

Analyse Files

What it does: Re-reads media files to update their technical details (codec, resolution, audio, HDR, tracks). This is the same information first read when a file is added during a Library Scan.

When to use:

• If you’ve replaced media files with different versions, for example upgraded from 1080p to 4K or re-encoded audio to a different format
• If technical information appears incorrect or missing
• After a ffprobe update that provides better detection

Details:

• For movies and TV shows, updates codec, resolution, bitrate, HDR format, audio tracks, and subtitle information
• For music libraries, updates codec, bitrate, sample rate, duration, and channel information
• Does not contact any metadata sources or change any metadata
• Does not download or change artwork

No automatic schedule: This operation is manual only, triggered from the library settings page.

Background Tasks

Some work is heavier and does not need to finish before you can browse or play your media. Norri runs this as background tasks that fill in over time and never get in the way of watching. See Settings → Scheduled Tasks to configure them.

Each background task can run in three ways, and you can combine them:

• On a schedule: pick the days and time it should run
• As a background task: it runs automatically during a quiet period (a nightly window you can set)
• Manually: a Run now button, both on the Scheduled Tasks page and on each library’s settings page

The key difference from other media servers: background tasks always pause while something is playing, and resume when playback stops. Heavy work never competes with your viewing.

Extract Keyframes

Norri reads the internal structure of each video file to find where it can safely split the video into segments for streaming. This keeps seeking, the progress bar, and subtitle timing accurate.

This is separate from the quick codec and format read that happens during a Library Scan. Finding every split point means looking deeper into the file, which is slower, so it no longer runs inside a Library Scan. Scans finish faster as a result, and this work runs as a background task instead. It covers every video file in your libraries, whatever the container.

You never have to wait for it, and the details depend on the container:

• Matroska (MKV) files carry a built-in index, so Norri reads their split points the moment you press play, remembers the result, and future playback starts near-instantly.
• Other containers, such as MP4, AVI, or TS, take longer to read, so the background task prepares them ahead of time. If you play one before the background task has reached it, it still plays right away. Seeking and the progress bar become more precise once the background task has processed it.

People Enrichment

When new movies and shows are added, Norri records who is in them but does not download every cast and crew photo during the scan. That would make scans slow. Instead, this runs as a background task.

Cast and crew photos still appear straight away, downloaded on demand the first time they are shown. People Enrichment fills in the rest, along with biography details, in the background.

Extract Trickplay Thumbnails

Trickplay thumbnails are the small preview images that appear when you drag along the progress bar, so you can find a scene by eye instead of guessing.

Norri builds them by sampling frames from each video and stitching them into image sheets. Doing that during a scan would slow it down badly, so it runs as a background task instead.

You never have to wait for it. If you open something before its thumbnails exist, Norri generates them on demand, which takes a short while on a long film. The background task works through the rest of your library so previews are ready in advance.

Individual users can turn previews off for themselves under Settings → Playback. See Video Player for what they look like in use.

Running Operations Manually

Go to Settings → Libraries, select a library, and scroll to the Library Actions section. Each operation has its own card with a description and action button.

Library Scan, Update Metadata, and Analyse Files run immediately when you click the button. Replace Metadata shows a confirmation prompt first, since it overwrites existing data.

Progress for any running operation is shown on the library settings page, in the sidebar, and in the header bar. You can navigate away and the operation continues in the background.

Configuration

You can configure automatic tasks in Settings → Scheduled Tasks (admin only).

Scan Workers

Library Scans process multiple files at the same time to make full use of available hardware. The Parallel scan workers setting controls how many files are handled simultaneously.

Auto mode (the default) calculates a worker count from CPU cores: total cores minus 2, capped at 8. This reserves capacity for the server itself and any active playback. On machines with 3 or fewer cores, scans run one file at a time.

Override auto mode by selecting a specific worker count. Each worker spawns an ffprobe subprocess to analyze media files, so higher values require more memory.

Best Practices

• Stagger the times so operations don’t overlap. The defaults, 3 AM for Daily Metadata Update and 4 AM for Daily Library Scan, work well.
• Choose off-peak hours: Schedule tasks when your server is least busy, typically overnight.
• Keep Startup Scan enabled: This catches any files added while the server was down.

Conflict Prevention

Norri automatically prevents tasks from interfering with each other:

• If two tasks overlap, one waits for the other to finish
• Tasks that stall (no progress for 10 minutes) are automatically cancelled
• Manual operations won’t start if a scan is already running. You’ll see a message asking you to wait
• No user action required. The system handles scheduling conflicts automatically

Locked Fields & Artwork

You can lock individual metadata fields and artwork on any item’s edit page. Locked items are never overwritten by any automatic or manual maintenance operation.

What can be locked:

• Text fields: title, original title, overview, tagline, content rating, genres, cast, crew
• Artwork: poster, backdrop, logo, cover (music)

How locking works with each operation:

• Library Scan: Only affects new items (which can’t have locks yet), so there’s no conflict
• Update Metadata: Skips locked metadata fields and locked artwork types
• Replace Metadata: Same as Update Metadata. Locked fields and artwork are preserved even when everything else is re-fetched
• Analyse Files: Only updates technical data, such as codecs, resolution, HDR format, and tracks. Metadata, artwork, and cached keyframe data are untouched

To lock or unlock fields, go to the item’s edit page and click the lock icon next to any field or artwork type.

Quick Reference

Troubleshooting

Tasks not running

Check the server logs for scheduled task activity. You should see log entries like:

• “Next metadata update scheduled for…”
• “Starting library scan…”
• “Completed library scan for X libraries”

New files not appearing

1. Verify the file is in a monitored library folder
2. Check that the file extension is supported (.mkv, .mp4, .avi, .flac, .mp3, etc.)
3. Try running a manual Library Scan from the library settings page
4. Check server logs for scanning errors

Metadata not updating

1. Check that the item has a valid match (TMDB for movies/TV, MusicBrainz for music)
2. Try running Update Metadata or Replace Metadata on the library
3. Check server logs for API errors

”A scan or metadata operation is already running” message

A previous operation is still in progress. Wait for it to complete, then try again. You can check progress in the sidebar or on the library settings page.