pgsql-jellyfin/docs/library-monitor-delay-configuration.md

Library Monitor Delay Configuration

Overview

The LibraryMonitorDelay setting controls how long Jellyfin waits after detecting a file system change before processing the change. This delay is necessary because file operations (especially large video files) are not atomic and can take time to complete.

Configuration

Location

The setting is configurable in your Jellyfin configuration file (typically system.xml or via the Dashboard).

Default Value

60 seconds - This provides a good balance between responsiveness and stability for most use cases.

Minimum Value

30 seconds - The system enforces a minimum of 30 seconds to prevent:

• Processing incomplete file transfers
• Excessive system load from rapid refreshes
• Metadata corruption from accessing files still being written

Maximum Value

Unlimited - You can set this as high as needed for very slow network file systems or large file transfers.

How to Configure

Method 1: Via Configuration File

Edit your config/system.xml file:

<ServerConfiguration>
  <!-- Delay in seconds after file system change before processing -->
  <!-- Default: 60, Minimum: 30 -->
  <LibraryMonitorDelay>60</LibraryMonitorDelay>
</ServerConfiguration>

Method 2: Via Dashboard (If Available)

1. Open Jellyfin Dashboard
2. Navigate to Settings → Library
3. Find Library Monitor Delay setting
4. Set value (minimum 30 seconds)
5. Save changes
6. Restart Jellyfin

Use Cases

Standard Setup (60 seconds - Default)

<LibraryMonitorDelay>60</LibraryMonitorDelay>

Best for:

• Local storage
• Fast network drives
• Small to medium file sizes

Network File Systems (120-300 seconds)

<LibraryMonitorDelay>180</LibraryMonitorDelay>

Best for:

• NAS/Network storage
• Slow network connections
• Very large video files (4K, remux)

Minimal Delay (30 seconds)

<LibraryMonitorDelay>30</LibraryMonitorDelay>

Best for:

• Fast local SSDs
• Small files (music, photos)
• When immediate updates are critical

⚠️ Warning: Using 30 seconds may cause issues with:

• Large file transfers not completing in time
• Metadata refresh on partially written files
• Increased system load

Extended Delay (300+ seconds)

<LibraryMonitorDelay>600</LibraryMonitorDelay>

Best for:

• Very slow network storage
• Satellite/remote connections
• Extremely large files (100GB+ remux files)
• Bulk file operations

How It Works

Timeline Example (60 second delay)

Time 0:00 - File starts copying to watched directory
    ↓
Time 0:05 - FileSystemWatcher detects change (OS notification)
    ↓
Time 1:05 - LibraryMonitorDelay expires (60 seconds)
    ↓
Time 1:05 - Jellyfin begins processing the file
    ↓
Time 1:10 - File is added to library
    ↓
Time 1:40 - Notification sent to clients (+ LibraryUpdateDuration 30s)

Total time from detection to notification: ~95 seconds

Validation

The system automatically enforces the 30-second minimum:

// If you set a value less than 30, it will be clamped to 30
LibraryMonitorDelay = 15;  // ❌ Invalid
// Actual value used: 30  // ✅ Enforced minimum

Examples:

• Setting value: 10 → Actual value: 30 (minimum enforced)
• Setting value: 45 → Actual value: 45 (valid)
• Setting value: 60 → Actual value: 60 (default)
• Setting value: 300 → Actual value: 300 (valid)

Related Settings

LibraryUpdateDuration (30 seconds default)

Additional delay before sending notifications to clients after library changes.

<LibraryUpdateDuration>30</LibraryUpdateDuration>

Combined delay example:

• File detected: 0s
• LibraryMonitorDelay: 60s
• Processing complete: 65s
• LibraryUpdateDuration: +30s
• Client notification: 95s total

Troubleshooting

Problem: Files showing as corrupted or incomplete

Solution: Increase the delay

<LibraryMonitorDelay>120</LibraryMonitorDelay>

Reason: File transfer wasn't complete before Jellyfin tried to process it.

Problem: Library updates too slow

Solution: Decrease the delay (but not below 30)

<LibraryMonitorDelay>30</LibraryMonitorDelay>

Warning: May cause issues with slow storage or large files.

Problem: Setting value of 10 doesn't work

Solution: Use at least 30 seconds

<LibraryMonitorDelay>30</LibraryMonitorDelay>

Reason: System enforces a minimum of 30 seconds for stability.

Problem: Excessive library refreshes

Solution: Increase the delay

<LibraryMonitorDelay>300</LibraryMonitorDelay>

Reason: Multiple file changes within the delay period are batched together.

Performance Considerations

Impact of Different Values

Setting	Pros	Cons	Best For
30s	Fast updates, immediate feedback	May process incomplete files	Local SSD, small files
60s (default)	Good balance, reliable	Slight delay in updates	Most use cases
120s	Handles slow transfers well	Noticeable delay	Network storage
300s+	Very safe for slow systems	Long delay before updates	Very slow storage, bulk ops

CPU and I/O Impact

• Lower values (30-60s): More frequent processing, higher CPU/disk usage
• Higher values (120-300s): Less frequent processing, lower system load, batched operations

Network Considerations

Local Storage:

• Recommended: 30-60 seconds
• File changes are immediate, low latency

Network Storage (LAN):

• Recommended: 60-120 seconds
• Account for network transfer time

Network Storage (WAN/Remote):

• Recommended: 180-600 seconds
• Account for high latency and slow transfer speeds

Technical Details

Implementation

File: MediaBrowser.Model/Configuration/ServerConfiguration.cs

private int _libraryMonitorDelay = 60;

public int LibraryMonitorDelay
{
    get => _libraryMonitorDelay;
    set => _libraryMonitorDelay = value < 30 ? 30 : value;  // Enforces minimum of 30
}

Used By

File: Emby.Server.Implementations/IO/FileRefresher.cs

_timer = new Timer(
    OnTimerCallback,
    null,
    TimeSpan.FromSeconds(_configurationManager.Configuration.LibraryMonitorDelay),
    TimeSpan.FromMilliseconds(-1)
);

Best Practices

1. Start with default (60s) and adjust based on your needs
2. Monitor logs for incomplete file errors
3. Increase for network storage (120-180s)
4. Don't go below 30s unless using very fast local storage
5. Test with your largest files to find the right value
6. Batch operations benefit from higher values

Example Configurations

Home Media Server (Local Storage)

<LibraryMonitorDelay>45</LibraryMonitorDelay>
<LibraryUpdateDuration>30</LibraryUpdateDuration>

NAS-Based Setup

<LibraryMonitorDelay>120</LibraryMonitorDelay>
<LibraryUpdateDuration>30</LibraryUpdateDuration>

Cloud/Remote Storage

<LibraryMonitorDelay>300</LibraryMonitorDelay>
<LibraryUpdateDuration>60</LibraryUpdateDuration>

Fast SSD, Small Files

<LibraryMonitorDelay>30</LibraryMonitorDelay>
<LibraryUpdateDuration>15</LibraryUpdateDuration>

See Also

• Library Monitoring Documentation
• File System Watcher Details
• Performance Tuning Guide

---

Last Updated: 2026-03-03 Minimum Value: 30 seconds (enforced by code) Default Value: 60 seconds Configurable: Yes