Features Overview¶

Torrentarr provides intelligent automation and monitoring for your media management setup, bridging the gap between qBittorrent and the Arr stack (Radarr/Sonarr/Lidarr/Readarr).

Core Features¶

🏥 Health Monitoring ¶

Continuous torrent health checks with automatic failure detection and recovery.

Key capabilities:

Stalled torrent detection - Automatically identifies and handles stuck downloads
Slow torrent handling - Monitors download speeds and ETA thresholds
File validation - After import is triggered, FFprobe can verify media when AutoDelete is on
Tracker monitoring - Detects dead or unreachable trackers
Smart removal - Protects near-complete downloads from accidental deletion

Learn more about Health Monitoring →

⚡ Instant Imports¶

Trigger imports in your Arr instances as soon as downloads complete, without waiting for Arr's periodic scans.

Benefits:

Faster availability - Media appears in your library within seconds
Reduced wait time - No more waiting for Arr's refresh cycles
Lower API load - Targeted import commands instead of full queue scans
Better UX - Request fulfillment happens immediately

How it works:

qBittorrent finishes downloading a file
Torrentarr detects completion instantly
Torrentarr tells Arr to import the specific download (Downloaded*Scan)
If Torrent.AutoDelete is on, FFprobe probes allowlisted files; a folder with zero valid media is blocklisted and deleted
Arr processes import immediately
Media appears in your library

Configuration:

Instant imports are automatic when Torrentarr is managing an Arr instance. No special configuration needed - just ensure Managed = true for your Arr instances.

🔄 Automated Re-searching¶

When downloads fail, Torrentarr automatically triggers new searches to find alternative releases.

Triggers:

Stalled torrents exceeding StalledDelay
Files failing FFprobe validation
Torrents moved to the failed category
Arr import errors matching ArrErrorCodesToBlocklist
Tracker errors or unavailable peers

Configuration:

[Radarr-Movies]
# Enable automatic re-searching
ReSearch = true

# Error codes that trigger re-search
ArrErrorCodesToBlocklist = [
  "Not an upgrade for existing movie file(s)",
  "Unable to determine if file is a sample"
]

Workflow:

Torrentarr detects download failure
Marks release as failed in Arr
Blacklists the release to prevent re-download
Removes torrent and files
Triggers Arr to search for alternative releases
Arr finds and downloads a new release

🔍 Missing Content Search¶

Automatically search for missing media in your Arr libraries.

Features:

Continuous searching - Automatically queries for missing movies/shows/albums
Smart scheduling - Configurable delays between searches to respect indexer limits
Search ordering - Search by date, reverse order, or quality priority
Upgrade searches - Find better quality versions of existing media
Quality unmet search - Enforce quality profile requirements
Custom format search - Search for releases meeting custom format scores

Example configuration:

[Sonarr-TV.Search]
# Search for missing episodes
SearchMissing = true

# Delay between searches (seconds)
SearchRequestsEvery = 300  # 5 minutes

# Search order
SearchByYear = true
SearchInReverse = false

# Upgrade searches
DoUpgradeSearch = true
QualityUnmetSearch = true

Use cases:

Initial library setup - Search through entire wanted list
New content - Automatically find newly aired episodes
Quality upgrades - Replace existing files with better versions
Hard-to-find media - Continuous searching for rare content

📊 Quality Upgrades¶

Automatically replace existing media with higher quality versions.

How it works:

Torrentarr monitors your library for quality-unmet items
Searches for releases matching your quality profile
Downloads better quality versions
Arr replaces old files with upgraded versions
qBittorrent continues seeding old files (if using Copy mode)

Configuration:

[Radarr-Movies.Search]
# Enable upgrade searching
DoUpgradeSearch = true

# Search for quality-unmet items
QualityUnmetSearch = true

# Custom format score enforcement
CustomFormatUnmetSearch = true
ForceMinimumCustomFormat = false

Example scenarios:

SD → HD - Upgrade 480p/720p to 1080p
HD → 4K - Upgrade 1080p to 2160p
Lossy → Lossless - Upgrade MP3 to FLAC (Lidarr)
Better codec - Upgrade x264 to x265/AV1
Proper/Repack - Replace scene releases with fixed versions

🎭 Temporary Quality Profiles¶

Temporarily lower quality requirements for missing media, then upgrade later. Temp profiles apply to Radarr, Sonarr, Lidarr, and Readarr.

Use case: You want FLAC music, but you'll accept MP3 for now to avoid missing content.

Workflow:

Album is missing, quality profile set to "Lossless (FLAC)"
Torrentarr temporarily switches it to "Any (MP3-320)"
Lidarr finds and downloads an MP3 release
After import, Torrentarr switches back to "Lossless (FLAC)"
Future upgrade searches look for FLAC versions

Configuration:

[Lidarr-Music.Search]
# Enable temporary profiles
UseTempForMissing = true

# Profile mappings (main → temporary)
QualityProfileMappings = {"Lossless (FLAC)" = "Any (MP3-320)"}

# Auto-reset after timeout
TempProfileResetTimeoutMinutes = 10080  # 7 days

# Reset on startup
ForceResetTempProfiles = true

🌐 Request Integration (Overseerr/Ombi)¶

Automatically process media requests from Overseerr or Ombi.

Features:

Approved-only mode - Only process approved requests
4K instance support - Route 4K requests to dedicated Arr instances
Automatic triggering - RSS sync and refresh on new requests
Status tracking - Monitor request fulfillment

Configuration:

[Radarr-Movies.Overseerr]
# Overseerr URL
OverseerrURL = "http://localhost:5055"

# Overseerr API key
OverseerrAPIKey = "your-api-key"

# Only process approved requests
ApprovedOnly = true

# 4K instance flag
Is4K = false

Supported:

✅ Radarr (movies)
✅ Sonarr (TV shows)
❌ Lidarr (Overseerr/Ombi don't support music)

🎯 Smart Seeding Management¶

Intelligent seeding controls with per-tracker customization.

Features:

Ratio limits - Stop seeding after reaching target ratio
Time limits - Remove torrents after seeding duration
Rate limiting - Control upload/download speeds per torrent
Per-tracker settings - Different rules for different trackers
Dead tracker removal - Clean up non-responsive trackers
Hit and Run protection - Prevent removal until tracker seeding obligations are met

Configuration:

[Radarr-Movies.Torrent.SeedingMode]
# Maximum upload ratio
MaxUploadRatio = 2.0

# Maximum seeding time (seconds)
MaxSeedingTime = 2592000  # 30 days

# Removal condition
RemoveTorrent = 3  # Remove when ratio OR time met

Per-tracker example:

[[Radarr-Movies.Torrent.Trackers]]
Name = "Private Tracker"
Priority = 10
URI = "https://tracker.example.com/announce"
MaxUploadRatio = 1.5
MaxSeedingTime = 1209600  # 14 days

🧹 Disk Space Management¶

Automatically pause/resume torrents based on available disk space.

Configuration:

[Settings]
# Free space threshold
FreeSpace = "50G"  # Pause downloads below 50 GB free

# Directory to monitor
FreeSpaceFolder = "/path/to/downloads"

# Enable auto pause/resume
AutoPauseResume = true

How it works:

Torrentarr monitors FreeSpaceFolder disk usage
When free space drops below FreeSpace threshold:
Pauses all downloads
Keeps seeding active
Logs warning message
When space frees up (files imported/deleted):
Resumes paused downloads
Continues normal operation

Benefits:

Prevents "disk full" errors
Avoids corrupted downloads
Maintains system stability
Automatic recovery

🔄 Auto-Updates¶

Automatically update Torrentarr to the latest version on a schedule.

Configuration:

[Settings]
# Enable auto-updates
AutoUpdateEnabled = true

# Update schedule (cron expression)
AutoUpdateCron = "0 3 * * 0"  # Sundays at 3:00 AM

Update process:

Torrentarr checks for new versions on schedule
Downloads latest release from GitHub
Downloads the GitHub release asset for the current platform and replaces the executable
Restarts Torrentarr automatically
Logs progress to Host logs

Supported installation methods:

✅ Native / binary (cron apply, WebUI, or POST /api/update)
✅ Docker (pull latest image — recommended over in-container apply)
⚠️ dotnet run / dev builds (update manually)

📝 Process Management¶

Automatic restart of crashed Arr worker tasks with configurable limits.

Configuration:

[Settings]
# Enable auto-restart
AutoRestartProcesses = true

# Maximum restarts within window
MaxProcessRestarts = 5

# Restart window (seconds)
ProcessRestartWindow = 300  # 5 minutes

# Delay before restart (seconds)
ProcessRestartDelay = 5

How it works:

Each Arr instance runs in a separate process
If a process crashes, Torrentarr automatically restarts it
If a process crashes repeatedly (5 times in 5 minutes), auto-restart is disabled for that process
Prevents infinite crash loops

Monitored processes:

Radarr manager processes
Sonarr manager processes
Lidarr manager processes
WebUI server
Auto-update worker
Network monitor

🌐 Web UI¶

Modern React-based dashboard for monitoring and management.

Features:

Real-time updates - Live status of all torrents and Arr instances
Process monitoring - View active processes and their status
Log viewer - Browse and search logs from the web interface
Configuration editor - Edit config.toml via web UI
Statistics - Dashboard with download stats and health metrics
Mobile responsive - Works on phones and tablets

Access:

http://localhost:6969/ui

Configuration:

[WebUI]
Host = "0.0.0.0"
Port = 6969

# Optional authentication token
Token = "your-secret-token"

# Theme
Theme = "Dark"  # Dark or Light

Security:

If Token is set, all API requests require the Authorization: Bearer header:

curl -H "Authorization: Bearer your-secret-token" http://localhost:6969/api/processes

📊 FFprobe File Validation¶

After Arr import is triggered, if Torrent.AutoDelete is enabled, Torrentarr probes allowlisted files in the content folder (qBitrr folder_cleanup). This does not block the Arr scan.

What it checks:

File is playable (when ffprobe is present)
Ebook/comic suffixes skip probe and count as valid
Missing ffprobe binary is treated as valid
Zero valid media after probe → Arr queue delete with blacklist and local files removed

Configuration:

[Settings]
# Auto-download FFprobe binary
FFprobeAutoUpdate = true

[Radarr-Movies.Torrent]
AutoDelete = true

Workflow:

Torrent completes download
Torrentarr triggers Arr Downloaded*Scan
If AutoDelete is on, FFprobe probes allowlisted files
✅ At least one valid file → leave content in place
❌ Zero valid media → blocklist + delete local files

Benefits:

Cleans folders that contain no real media after import
Detects fake/sample-only downloads
Ebook libraries are not failed by probe
Reduces manual intervention

🏷️ Tagless Operation¶

Manage torrents without requiring Arr instance tags (advanced).

Configuration:

[Settings]
# Disable tag requirement
Tagless = false  # Set to true to enable

When enabled:

Torrentarr uses categories instead of tags
Useful for setups where Arr doesn't apply tags consistently
May cause conflicts if multiple Arr instances use the same category

Recommended: Leave disabled (false) unless you have specific issues with tagging.

Feature Comparison¶

Feature	Radarr	Sonarr	Lidarr	Readarr
Health Monitoring	✅	✅	✅	✅
Instant Imports	✅	✅	✅	✅
Automated Re-searching	✅	✅	✅	✅
Missing Content Search	✅	✅	✅	✅
Quality Upgrades	✅	✅	✅	✅
Temporary Profiles	✅	✅	✅	✅
Request Integration	✅	✅	❌	❌
Smart Seeding	✅	✅	✅	✅
Per-Tracker Settings	✅	✅	✅	✅
Hit and Run Protection	✅	✅	✅	✅
FFprobe Validation	✅	✅	✅	✅
Search by Year	✅	✅	❌	✅
Search Specials	❌	✅	❌	❌

Getting Started with Features¶

Start simple - Enable basic health monitoring first
Add search automation - Configure missing content search
Enable upgrades - Turn on quality upgrade searches
Tune thresholds - Adjust ETA, stall delays, and limits based on your setup
Add advanced features - Temporary profiles, request integration, etc.

Common Feature Combinations¶

Media Hoarder Setup¶

For users who want everything, quickly:

[Radarr-Movies.Search]
SearchMissing = true
SearchRequestsEvery = 180
DoUpgradeSearch = false
SearchAgainOnSearchCompletion = true

[Radarr-Movies.Torrent]
MaximumETA = 172800  # 48 hours
DoNotRemoveSlow = true
StalledDelay = 30

Quality-Focused Setup¶

For users prioritizing quality over speed:

[Radarr-4K.Search]
SearchMissing = true
DoUpgradeSearch = true
QualityUnmetSearch = true
CustomFormatUnmetSearch = true
ForceMinimumCustomFormat = true

[Radarr-4K.Torrent]
MaximumETA = -1  # No limit
DoNotRemoveSlow = true
StalledDelay = 60

Private Tracker Setup¶

For users on private trackers with strict rules:

[Radarr-Private]
ImportMode = "Copy"  # Preserve seeding

[Radarr-Private.Torrent]
DoNotRemoveSlow = true
StalledDelay = 45
MaximumDeletablePercentage = 0.99

[Radarr-Private.Torrent.SeedingMode]
MaxUploadRatio = -1  # Never stop
MaxSeedingTime = 2592000  # 30 days minimum
RemoveTorrent = 2  # Time-based only

Feature Documentation¶

Detailed guides for each feature:

Health Monitoring - Comprehensive torrent health checks
Instant Imports - Fast media library updates
Automated Search - Missing content automation
Quality Upgrades - Automatic quality improvements
Custom Formats - Advanced quality scoring
Request Integration - Overseerr/Ombi integration
Process Management - Automatic restart handling
Disk Space Management - Free space monitoring
Auto Updates - Automatic version updates

Need Help?¶

Configuration Guide - Learn how to configure features
Troubleshooting - Common issues and solutions
FAQ - Frequently asked questions
GitHub Issues - Report bugs or request features

Feature Guides¶

Health Monitoring - Comprehensive torrent health checks
Instant Imports - Fast media library updates
Automated Search - Missing content automation
Quality Upgrades - Automatic quality improvements
Custom Formats - Advanced quality scoring
Request Integration - Overseerr/Ombi integration
Process Management - Automatic restart handling
Disk Space Management - Free space monitoring

Configuration¶

Arr Configuration - Radarr/Sonarr/Lidarr setup
Search Configuration - Search automation settings
Seeding Configuration - Seeding rules and limits
Torrent Configuration - Torrent handling options

Getting Started¶

Quick Start Guide - Set up your first feature
Installation - Install Torrentarr
First Run - Initial configuration

Next Steps¶

Choose Your Features - Review the features above and decide which ones fit your workflow
Configure Settings - Follow the Configuration Guide to enable features
Test & Monitor - Use the WebUI to monitor feature performance
Optimize - Tune thresholds and delays based on your setup
Get Support - Check Troubleshooting if issues arise

Features Overview¶

Core Features¶

🏥 Health Monitoring¶

⚡ Instant Imports¶

🔄 Automated Re-searching¶

🔍 Missing Content Search¶

📊 Quality Upgrades¶

🎭 Temporary Quality Profiles¶

🌐 Request Integration (Overseerr/Ombi)¶

🎯 Smart Seeding Management¶

🧹 Disk Space Management¶

🔄 Auto-Updates¶

📝 Process Management¶

🌐 Web UI¶

📊 FFprobe File Validation¶

🏷️ Tagless Operation¶

Feature Comparison¶

Getting Started with Features¶

Common Feature Combinations¶

Media Hoarder Setup¶

Quality-Focused Setup¶

Private Tracker Setup¶

Feature Documentation¶

Need Help?¶

Related Documentation¶

Feature Guides¶

Configuration¶

Getting Started¶

Next Steps¶

🏥 Health Monitoring ¶