Swaparr Documentation

Swaparr Logo
Beta Notice: Swaparr is a rewritten implementation by Admin9705 for Huntarr integration. Please note that the original Swaparr project does not provide support for this Huntarr-specific implementation. For Huntarr-related issues, use Huntarr's support channels.

Swaparr is a stalled download cleaning utility for the *arr applications built into Huntarr. It provides basic features and easier configuration when compared to Cleanuperr.

Important Warning: Swaparr works on all downloads started via the *arr application, not only the ones scheduled by Huntarr. This results in stalled or otherwise flagged downloads being removed. If you want to keep these downloads, deactivate Swaparr for those downloads.
Project Credit: Original Swaparr by ThijmenGThN • GitHub Stars: ⭐ 172 • Version: v0.10.0 • ⭐ Star the Project

Overview

What Problem Does Swaparr Solve?

While your *arr applications are excellent at managing media downloads, they can struggle with:

How Swaparr Helps

Swaparr automates the cleanup process by:

Configuration

The following settings correspond to the options you see in the Swaparr Configuration panel:

Enable Swaparr

What it does: Master switch to enable or disable automatic removal of stalled downloads.

When to use: Turn this on after configuring your other settings. You can disable this temporarily to stop Swaparr without losing your configuration.

Max Strikes

What it does: Number of times a download must be flagged as problematic before being removed (default: 3).

How it works: Each monitoring cycle, Swaparr checks downloads. If a download meets the "stalled" criteria, it gets a strike. Once it reaches your max strikes setting, it gets removed.

Recommended values:

Max Download Time

What it does: Maximum time before considering a download stalled (examples: 2h, 120m, 7200s).

How it works: If a download has been running longer than this time without making progress, it will receive a strike.

Recommended values:

Ignore Above Size

What it does: Ignore downloads larger than this size (examples: 25GB, 10GB, 5000MB).

Why this matters: Large files naturally take longer to download. This prevents Swaparr from removing legitimate large downloads that are progressing slowly.

Recommended values:

Remove from Client

What it does: Also remove downloads from the download client (recommended: enabled).

When enabled: Removes the download from both the *arr application and your download client (qBittorrent, Deluge, etc.)

When disabled: Only removes from the *arr application, but leaves the download in your client

Recommendation: Keep this enabled for complete cleanup. Only disable if you want to manually review removed downloads in your client.

Dry Run Mode

What it does: Test mode - logs what would be removed without actually removing anything.

Perfect for:

Recommendation: Enable this first, run for a few cycles, check the logs, then disable once you're confident in your settings.

Sleep Duration

What it does: Time to wait between Swaparr processing cycles (default: 900 seconds / 15 minutes).

Timing Example: Assume a download is stalled right from the beginning. Using the default values of Sleep Duration of 15 minutes and 3 strikes:

After 0-15 minutes (whenever Swaparr runs) the download is monitored by Swaparr. 15 minutes later there is no progress: strike 1; 15 minutes later: strike 2; further 15 minutes: strike 3 and the download is removed.

In total it takes 45-60 minutes (depending on the first run of Swaparr) to remove bad downloads.

Note: Bad downloads as specified by Swaparr's security features are removed immediately with the next scan.

How it affects performance:

Consider your setup: If you have many active downloads, shorter intervals help. If you have a slower system or fewer downloads, longer intervals are fine.

Security Features

Swaparr includes advanced security features to protect your system from malicious downloads and suspicious content by analyzing download names and titles. Detection is based on filename patterns, not file contents.

Malicious File Detection

What it does: Automatically detect and immediately remove downloads with malicious file types.

How it works: Scans download names for dangerous file extensions and suspicious patterns. Unlike the strike system, malicious content is removed immediately without warnings.

When to enable: Highly recommended for all users, especially those using public trackers where malicious content is more common.

Important: This feature analyzes filename patterns only, not actual file contents. It's designed to catch obviously malicious downloads based on their names.

Malicious File Extensions

What it does: File extensions to consider malicious and block immediately.

Default blocked extensions:

Enhanced Protection: Adding extensions like .vob, .iso, .mdf, .msi, .arj, .ace, .001, .rar, and .zip to the Malicious File Extensions list helps cut down on failed imports significantly. These formats are commonly used on public anonymous trackers to distribute password-protected files and zip bombs, which can reduce failed imports from 30% to less than 5%.

Customization: Use the tag input system to add or remove extensions. Type the extension (with or without the dot) and press Enter or click the + button.

Suspicious Patterns

What it does: Filename patterns that indicate potentially malicious or unwanted content.

Default blocked patterns:

Examples of what gets blocked:

Customization: Add patterns that are common in your region or specific to content you want to avoid.

Age-Based Cleanup

Age-based cleanup automatically removes downloads that have been stuck for too long, regardless of strike count. This provides a safety net for downloads that might slip through the normal strike system.

Enable Age-Based Removal

What it does: Remove downloads that have been stuck longer than the specified age limit.

How it works: Tracks when Swaparr first noticed each download and removes it after the specified number of days, even if it hasn't reached the maximum strike count.

When to use: Enable this to prevent downloads from sitting in queues indefinitely. Particularly useful for handling edge cases where the normal strike system might not catch problematic downloads.

Maximum Age (Days)

What it does: Remove downloads older than this many days (default: 7 days).

Recommended values:

Consider your setup: Private trackers with limited seeders might need longer age limits. Public trackers with many alternatives can use shorter limits.

Age Tracking: The age timer starts when Swaparr first sees a download in the queue, not when the download actually started. This ensures accurate tracking across Swaparr restarts.

Quality-Based Filtering

Quality-based filtering automatically removes downloads with poor or undesirable quality indicators in their names. This helps maintain high standards for your media library.

Enable Quality-Based Filtering

What it does: Automatically remove downloads with blocked quality patterns in their names.

How it works: Scans download names for quality indicators that suggest poor viewing/listening experience. Like malicious file detection, quality-blocked content is removed immediately without strikes.

When to use: Enable if you want to maintain high quality standards and automatically reject low-quality releases.

Blocked Quality Patterns

What it does: Quality patterns to block based on their indicators in filenames.

Default blocked qualities:

Examples of what gets blocked:

Quality standards comparison:

Quality Type Video Quality Audio Quality Recommendation
CAM/TS Very Poor Very Poor Block (Default)
DVDScr/R6 Poor Fair Block (Default)
HDTV/WEB-DL Good Good Allow
BluRay/Remux Excellent Excellent Allow

Customization: Use the tag input system to add quality patterns specific to your preferences. For example, you might want to block "720p" if you only accept 1080p or higher.

Be Careful: Adding too many quality patterns might block legitimate releases. Start with the defaults and add patterns gradually based on your specific needs.

*arr Instance Setup

Swaparr uses your existing *arr configurations from Huntarr. In the Swaparr configuration, you'll see checkboxes for each of your configured instances:

Application What Gets Monitored Best Practices
Sonarr Instances TV show download queues Enable for instances with frequent stalled episodes
Radarr Instances Movie download queues Especially useful for instances downloading large 4K movies
Lidarr Instances Music download queues Enable if you frequently download FLAC or large music collections
Readarr Instances Book/audiobook download queues Useful for large audiobook files that might stall
Whisparr Instances Adult content download queues Enable based on your monitoring needs

How Swaparr Works

Monitoring Cycle

Every sleep duration interval, Swaparr performs these steps:

  1. Instance Discovery: Finds your enabled *arr instances
  2. Queue Analysis: Gets current download queues from each instance
  3. Progress Check: Compares current state with previous cycles
  4. Strike Assessment: Awards strikes to downloads meeting removal criteria
  5. Action Execution: Removes downloads that exceed max strikes
  6. Statistics Update: Updates persistent statistics and logs results

When Downloads Get Strikes

A download receives a strike when it meets ALL these conditions:

Statistics Tracking

Swaparr tracks comprehensive statistics visible on your home dashboard:

Statistic What It Counts When It Increases
Processed Total downloads analyzed Every download checked during monitoring cycles
Strikes Strikes issued to problematic downloads When a download meets strike criteria
Removals Downloads removed via strike system When a download reaches max strikes and gets removed
Malicious Removals Downloads removed for malicious content When malicious file detection blocks a download
Quality Removals Downloads removed for poor quality When quality-based filtering blocks a download
Age Removals Downloads removed for being too old When age-based cleanup removes stale downloads
Ignored Downloads skipped due to rules When downloads are larger than ignore size or already completed

Best Practices

Getting Started

  1. Start with Dry Run: Enable dry run mode and monitor logs for 24-48 hours
  2. Conservative Settings: Use 4-5 max strikes and longer download times initially
  3. Monitor Statistics: Watch the dashboard stats to understand Swaparr's impact
  4. Gradual Adjustment: Fine-tune settings based on your specific download patterns
  5. Check Logs: Review logs regularly to ensure expected behavior

Configuration Tips

Advanced Alternative: For more sophisticated download management, consider Cleanuperr, which offers more comprehensive management capabilities.

Example Configurations

Aggressive Setup (Fast Connection, Reliable Trackers)

Balanced Setup (Most Users)

Conservative Setup (Slower Connection, Private Trackers)

Troubleshooting

Common Issues

No Downloads Detected

If Swaparr reports no downloads to monitor:

Downloads Not Being Removed

If problematic downloads aren't being removed:

Too Aggressive Removal

If Swaparr is removing downloads too quickly:

Performance Issues

If Swaparr is impacting system performance:

Logging and Debugging

Swaparr provides detailed logging to help diagnose issues. Look for these log entries:

Support: For issues specific to Huntarr's Swaparr implementation, use Huntarr's support channels: Discord or Reddit. For general Swaparr questions, refer to the original project documentation.
← Back to Apps Settings Documentation →