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:

```xml
<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)
```xml
<LibraryMonitorDelay>60</LibraryMonitorDelay>
```

**Best for:**
- Local storage
- Fast network drives
- Small to medium file sizes

### Network File Systems (120-300 seconds)
```xml
<LibraryMonitorDelay>180</LibraryMonitorDelay>
```

**Best for:**
- NAS/Network storage
- Slow network connections
- Very large video files (4K, remux)

### Minimal Delay (30 seconds)
```xml
<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)
```xml
<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:

```csharp
// 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.

```xml
<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
```xml
<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)
```xml
<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
```xml
<LibraryMonitorDelay>30</LibraryMonitorDelay>
```

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

### Problem: Excessive library refreshes

**Solution:** Increase the delay
```xml
<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`

```csharp
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`

```csharp
_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)
```xml
<LibraryMonitorDelay>45</LibraryMonitorDelay>
<LibraryUpdateDuration>30</LibraryUpdateDuration>
```

### NAS-Based Setup
```xml
<LibraryMonitorDelay>120</LibraryMonitorDelay>
<LibraryUpdateDuration>30</LibraryUpdateDuration>
```

### Cloud/Remote Storage
```xml
<LibraryMonitorDelay>300</LibraryMonitorDelay>
<LibraryUpdateDuration>60</LibraryUpdateDuration>
```

### Fast SSD, Small Files
```xml
<LibraryMonitorDelay>30</LibraryMonitorDelay>
<LibraryUpdateDuration>15</LibraryUpdateDuration>
```

## See Also

- [Library Monitoring Documentation](library-monitoring.md)
- [File System Watcher Details](file-system-watcher.md)
- [Performance Tuning Guide](performance-tuning.md)

---

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