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 them.

The Four Operations

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

Library Scan

What it does: Discovers new files, removes deleted ones, and matches new media to metadata sources.

Details:

• Walks through all your library folders looking for new, moved, or deleted media files
• For movies and TV shows, new files are matched to TMDB and their metadata and artwork are downloaded
• For music libraries, new files are matched to MusicBrainz and enriched from TheAudioDB
• Files that have been removed from disk are marked as unavailable
• Existing files that haven’t changed are skipped

Library Scan does not re-fetch metadata for items that are already in your library. It only processes new or changed files.

Automatic schedule: Library Scans run in three situations:

1. On server startup (if enabled) — catches files added while the server was offline
2. Daily at a configurable time (default: 4 AM) — useful for NAS and network shares where real-time monitoring may miss changes
3. When the file watcher detects changes — Norri 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, a scan is triggered automatically after a short delay to let batch operations (like a download tool adding multiple files) finish

Update Metadata

What it does: Checks metadata sources for recent changes and applies them to items already in your library.

Details:

• For movies and TV shows, queries TMDB for items that have changed in the last 14 days. Only items in your library that TMDB reports as changed get updated
• For music libraries, refreshes genres, biographies, and artwork from MusicBrainz and TheAudioDB for artists and albums that are missing data
• Updates ratings, descriptions, artwork, cast, and crew information
• 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 schedule: Runs daily at a configurable time (default: 3 AM).

Replace Metadata

What it does: Re-downloads all metadata for every item in the library, regardless of whether anything has changed.

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:

• For movies and TV shows, re-fetches everything from TMDB: metadata, ratings, descriptions, cast, crew, and all artwork types
• For music libraries, re-fetches everything from MusicBrainz and TheAudioDB: genres, biographies, classifications, social links, and artwork
• 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 the actual media files on disk to update technical information, including keyframe data used for accurate playback.

When to use:

• If you’ve replaced media files with different versions (e.g. 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
• After your initial library setup, to populate keyframe data for all existing files (see Keyframe Extraction below)

Details:

• For movies and TV shows, updates codec, resolution, bitrate, audio tracks, subtitle information, and keyframe positions
• For music libraries, updates codec, bitrate, sample rate, duration, and channel information
• Runs in two phases: first re-probes all files, then extracts keyframe data for any files that don’t have it yet
• 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.

Playback Analysis

Library Scan and Analyse Files both include a playback analysis step. Norri reads the internal structure of each video file to determine where it can safely split the video into segments for streaming. This data ensures that seeking, the progress bar, and subtitle timing all work accurately.

For most files (MKV containers), this analysis is near-instant and adds no noticeable time to scanning. For less common container formats (MP4, AVI), a separate analysis pass runs at the end of the scan. Progress is shown in the header bar as “Extracting keyframe data.”

If you play a file before this analysis has completed, there may be a short delay (a couple of seconds) while Norri reads the file structure on demand. Once the file has been scanned, playback starts near-instantly.

No configuration is required. This happens automatically as part of Library Scan and Analyse Files.

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 metadata updates, 4 AM for scans) 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 (codecs, resolution). Metadata and artwork 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 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.