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, marks missing files unavailable, restores returning files, 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, such as codecs, resolution, and tracks. This reads media headers rather than decoding the entire file; the time needed depends on the file and storage
• Identifies new movies, shows, and music albums from their files and supported local metadata, then matches them and downloads metadata and artwork when online sources are enabled
• Files that have been removed from disk are marked as unavailable, with their library records retained
• Files that return to their original paths become available again
• Existing files that haven’t changed are skipped, and are not re-read

The first scan imports the files in the selected folders. Later scans normally process only new or changed files. Each movie, show, or album is identified and imported as the scan proceeds, so you can browse completed items while other items are still being processed. Your metadata preferences and locked fields apply throughout.

If a music lookup cannot finish, it is retried through the automatic Music Metadata and Artwork task without needing another scan. These retries require online metadata to be enabled and respect any waiting period requested by the provider.

Re-reading the technical details of existing files is a separate operation, Analyse Files, described below. See Unavailable Files for restoring missing media without losing its library records.

Automatic checks:

• Startup Scan runs when the server starts, if enabled, to catch files added while the server was offline
• Norri checks library folders periodically, every 5 minutes by default, to find changes missed by file notifications
• 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

Scheduled Deep Rescan provides a more thorough check inside all library folders for changes that routine checks may miss. It is enabled by default with a 12-hour interval, and runs when playback and library operations allow it. The interval starts again after the server starts or the previous attempt finishes. A deep rescan checks your files; use Replace Metadata when you want to replace existing metadata from your sources.

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

Music libraries also retry pending lookups after a temporary provider failure. Already imported tracks remain playable, and manually edited or locked metadata is preserved. A provider can ask Norri to wait before retrying, so an immediate refresh may leave a lookup pending.

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:

• To refresh the technical information for existing files without changing their metadata
• If technical information appears incorrect or missing
• After a Norri update, if its release notes recommend refreshing file information

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 does not need to finish before you can browse or play your media. Norri runs this as background tasks that fill in over time. See Settings → Scheduled Tasks → Background Tasks for their status and available controls.

Choose how each configurable task runs:

• Quiet hours: run automatically within the configured nightly window.
• Manual only: start it with Run now. Manual runs are also available when quiet hours are selected.

New configurable background tasks default to a quiet window of midnight to 8 AM, using the server’s time zone. Change Quiet window starts and Quiet window ends for each task to suit your household. Updating Norri keeps your saved windows.

Playback takes priority. Norri pauses affected background work and resumes it when eligible. The quiet window limits when automatic work can run; it does not guarantee that the task runs throughout that window. Norri responds to its own playback, transcoding, and library scans, but does not pause automatically for work in other applications on the computer.

Music Metadata and Artwork

Music scans normally match albums and fetch their online details during import. This task retries unfinished music lookups, including work left pending by an unavailable provider or an interrupted import. It fills in album and artist details, track information, and artwork. You can browse and play imported tracks while this work is pending.

The task is marked Automatic. It starts when music needs online enrichment, so it has no schedule or Run now control. Its status appears on the music library’s edit page and under Settings → Scheduled Tasks → Background Tasks. Reload the page to see the latest status.

Pending work survives server restarts. The task waits while a library scan or playback takes priority, and retries later if a provider is unavailable or asks Norri to wait. Library metadata preferences and locked fields still apply. Libraries using NFO only (offline) make no online metadata or artwork requests.

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 background task reads more of each video than a library scan needs for its basic codec and format information. It prepares seeking information for videos in your libraries.

Playback can start before this task finishes. The file format affects what happens next:

• Matroska (MKV) files carry a built-in index, so Norri reads their split points the moment you press play, remembers the result, and later playback can reuse that index.
• 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, playback can use a fallback seek index. Seeking becomes 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.

Existing previews remain available. If previews are missing, you can still play and seek without them. Previews become available after this background task finishes processing the video. Playing or scrubbing does not start thumbnail generation.

Use Settings → Scheduled Tasks → Background Tasks to set the task’s quiet window or select Run now. The task waits while playback has priority.

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.

Select Scan Now, Update, or Analyse on the corresponding card to request that operation. Replace shows a confirmation prompt first. A requested scan can wait for earlier work; a queued scan starts automatically when it can run. If Norri reports that an operation is already running, wait for it to finish before trying again.

Progress for library operations 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. Background task status is shown separately on the library settings page and under Settings → Scheduled Tasks.

While Norri is still discovering files, files processed so far shows completed work without a final percentage or estimated finish time. Counts labeled files in this folder apply only to the current folder. Changes between checking files and fetching metadata are normal as items are processed. Check the overall scan status to see whether the requested operation has finished or needs attention.

Configuration

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

Select Save Changes after changing these settings. Startup, deep rescan, and metadata schedule changes take effect after a server restart. A changed worker limit applies to the next library scan. Background task controls save separately when you change them.

Scan Workers

Routine library scans can process several independent movie folders, TV shows, or music albums at once. Each item goes through file checks, identification, and import using the library’s metadata settings. Parallel scan workers controls the amount of this work that can run at the same time. Deep rescans and other maintenance operations may process items differently.

Leave Auto selected for normal use. Norri chooses a limit based on the server’s available CPUs.

You can select a specific limit instead. More workers can increase memory use and demand on your disks or network share. Storage speed and online provider limits also affect scan time, so increasing the value does not always make a scan faster. Reduce it if scanning makes your server or storage less responsive.

Best Practices

• Choose off-peak hours: Set Daily Metadata Update and configurable background tasks to run when your server is least busy, typically overnight.
• Keep Scheduled Deep Rescan enabled: This catches file edits that routine folder checks may miss. Increase its interval if you want these thorough checks less often.
• 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:

• Queued library scans wait for earlier work and start automatically
• Background music retries wait while library scans or playback take priority
• If an operation stops making progress, Norri can stop it and report a failure. Check its error and your folder access before retrying

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: Imports new or changed files and matches new media. Existing locked fields are preserved
• 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. Descriptive metadata and artwork are unchanged; existing valid keyframe data can be reused

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 that the task is enabled and, for tasks with quiet hours, that the server is inside the configured window. Playback or a library scan can delay background work. Check the task’s status under Settings → Scheduled Tasks and use Run now where available. If it reports a failure, check server logs for the error before retrying.

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.