mirror/Huntarr.io
1
0
Fork 0
mirror of https://github.com/plexguide/Huntarr.io.git synced 2026-01-11 07:18:27 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
dev
Huntarr.io/docs/apps/swaparr.html
Admin9705 86da4fa668 Update Swaparr documentation to clarify functionality and enhance user warnings 
- Revised the description of Swaparr to emphasize its role as a stalled download cleaning utility integrated with Huntarr.
- Added an important warning regarding the impact of Swaparr on all downloads initiated by *arr applications.
- Included a detailed timing example to illustrate the download monitoring process and removal timeline.
- Expanded the list of malicious file extensions to improve protection against potential threats, with a note on the significance of these additions.
2025-06-15 12:54:13 -04:00

562 lines
40 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Swaparr Documentation - Huntarr.io</title>
<link rel="stylesheet" href="../css/main.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
<script src="../js/main.js" defer></script>
</head>
<body>
<div class="sidebar">
<div class="sidebar-logo">
<img src="../images/huntarr-logo.png" alt="Huntarr Logo">
<h2>Huntarr.io</h2>
</div>
<nav class="sidebar-nav">
<div class="sidebar-section">
<h3 class="sidebar-section-title">Getting Started</h3>
<ul>
<li><a href="../donate.html"><i class="fas fa-heart" style="color: #e91e63; font-size: 18px; width: 24px; height: 24px; margin-right: 8px; display: inline-flex; align-items: center; justify-content: center;"></i> Donate</a></li>
<li><a href="../getting-started/installation.html"><svg class="svg-icon" viewBox="0 0 24 24" fill="currentColor"><path d="M19 9h-4V3H9v6H5l7 7 7-7zM5 18v2h14v-2H5z"></path></svg> Installation</a></li>
</ul>
</div>
<div class="sidebar-section">
<h3 class="sidebar-section-title">Core</h3>
<ul>
<li><a href="../index.html"><svg class="svg-icon" viewBox="0 0 24 24" fill="currentColor"><path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"></path></svg> Home</a></li>
<li class="active"><a href="index.html"><svg class="svg-icon" viewBox="0 0 24 24" fill="currentColor"><path d="M4 8h4V4H4v4zm6 12h4v-4h-4v4zm-6 0h4v-4H4v4zm0-6h4v-4H4v4zm6 0h4v-4h-4v4zm6-10v4h4V4h-4zm-6 4h4V4h-4v4zm6 6h4v-4h-4v4zm0 6h4v-4h-4v4z"></path></svg> Apps</a></li>
<li><a href="../settings/settings.html"><svg class="svg-icon" viewBox="0 0 24 24" fill="currentColor"><path d="M19.14 12.94c.04-.3.06-.61.06-.94 0-.32-.02-.64-.07-.94l2.03-1.58c.18-.14.23-.41.12-.61l-1.92-3.32c-.12-.22-.37-.29-.59-.22l-2.39.96c-.5-.38-1.03-.7-1.62-.94l-.36-2.54c-.04-.24-.24-.41-.48-.41h-3.84c-.24 0-.43.17-.47.41l-.36 2.54c-.59.24-1.13.57-1.62.94l-2.39-.96c-.22-.08-.47 0-.59.22L2.74 8.87c-.12.21-.08.47.12.61l2.03 1.58c-.05.3-.09.63-.09.94s.02.64.07.94l-2.03 1.58c-.18.14-.23.41-.12.61l1.92 3.32c.12.22.37.29.59.22l2.39-.96c.5.38 1.03.7 1.62.94l.36 2.54c.05.24.24.41.48.41h3.84c.24 0 .44-.17.47-.41l.36-2.54c.59-.24 1.13-.56 1.62-.94l2.39.96c.22.08.47 0 .59-.22l1.92-3.32c.12-.22.07-.47-.12-.61l-2.01-1.58zM12 15.6c-1.98 0-3.6-1.62-3.6-3.6s1.62-3.6 3.6-3.6 3.6 1.62 3.6 3.6-1.62 3.6-3.6 3.6z"></path></svg> Settings</a></li>
<li><a href="../features/index.html"><i class="fas fa-star" style="width: 24px; height: 24px; margin-right: 8px; display: inline-flex; align-items: center; justify-content: center;"></i> Features</a></li>
<li><a href="../faq.html"><i class="fas fa-question-circle" style="width: 24px; height: 24px; margin-right: 8px; display: inline-flex; align-items: center; justify-content: center;"></i> FAQ</a></li>
</ul>
</div>
<div class="sidebar-section">
<h3 class="sidebar-section-title">Resources</h3>
<ul>
<li><a href="https://github.com/plexguide/Huntarr.io" target="_blank"><svg class="svg-icon" viewBox="0 0 24 24" fill="currentColor"><path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"></path></svg> GitHub</a></li>
<li><a href="https://discord.com/invite/PGJJjR5Cww" target="_blank"><i class="fab fa-discord" style="color: #5865F2; font-size: 18px; width: 24px; height: 24px; margin-right: 8px; display: inline-flex; align-items: center; justify-content: center;"></i> Discord</a></li>
<li><a href="https://www.reddit.com/r/huntarr/" target="_blank"><i class="fab fa-reddit-alien" style="color: #FF4500; font-size: 18px; width: 24px; height: 24px; margin-right: 8px; display: inline-flex; align-items: center; justify-content: center;"></i> Reddit</a></li>
</ul>
</div>
</nav>
</div>
<div class="main-content">
<div class="container">
<h1>Swaparr Documentation</h1>
<div style="text-align: center; margin: 20px auto;">
<img src="../images/arrs/swaparr.png" alt="Swaparr Logo" style="width: 80px; height: 80px; object-fit: contain;">
</div>
<div class="alert alert-warning" style="margin: 20px 0; padding: 15px; background: rgba(255, 193, 7, 0.1); border-left: 4px solid #ffc107;">
<strong><i class="fas fa-info-circle" style="margin-right: 8px;"></i>Beta Notice:</strong>
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.
</div>
<p>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.</p>
<div class="alert alert-warning" style="margin: 20px 0; padding: 15px; background: rgba(255, 193, 7, 0.1); border-left: 4px solid #ffc107;">
<strong><i class="fas fa-exclamation-triangle" style="margin-right: 8px;"></i>Important Warning:</strong>
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.
</div>
<div class="alert alert-info" style="margin: 20px 0; padding: 15px; background: rgba(13, 202, 240, 0.1); border-left: 4px solid #0dcaf0;">
<strong><i class="fas fa-star" style="margin-right: 8px; color: #fbbf24;"></i>Project Credit:</strong>
Original Swaparr by <a href="https://github.com/ThijmenGThN" target="_blank" style="color: #0dcaf0;">ThijmenGThN</a> •
GitHub Stars: ⭐ 172 •
Version: v0.10.0 •
<a href="https://github.com/ThijmenGThN/swaparr" target="_blank" style="color: #fbbf24;">⭐ Star the Project</a>
</div>
<h2 id="overview">Overview</h2>
<h3><i class="fas fa-exclamation-triangle" style="margin-right: 10px; color: #f39c12;"></i>What Problem Does Swaparr Solve?</h3>
<p>While your *arr applications are excellent at managing media downloads, they can struggle with:</p>
<ul>
<li><strong>Stalled Downloads:</strong> Downloads that appear to be active but haven't made progress</li>
<li><strong>Failed Downloads:</strong> Downloads that have failed but remain in the queue</li>
<li><strong>Stuck Imports:</strong> Downloads that completed but aren't being imported properly</li>
<li><strong>Queue Clogging:</strong> Problematic downloads preventing new ones from starting</li>
<li><strong>Manual Cleanup:</strong> Having to manually remove problematic downloads regularly</li>
</ul>
<h3><i class="fas fa-magic" style="margin-right: 10px; color: #2ecc71;"></i>How Swaparr Helps</h3>
<p>Swaparr automates the cleanup process by:</p>
<ul>
<li><strong>Monitoring Download Progress:</strong> Continuously checks download status and progress</li>
<li><strong>Smart Detection:</strong> Identifies truly stalled downloads vs. slow but progressing ones</li>
<li><strong>Automatic Removal:</strong> Removes problematic downloads automatically</li>
<li><strong>Strike System:</strong> Uses a configurable strike system before taking action</li>
<li><strong>Safe Operation:</strong> Includes dry-run mode and comprehensive logging</li>
</ul>
<h2 id="configuration">Configuration</h2>
<p>The following settings correspond to the options you see in the Swaparr Configuration panel:</p>
<h3 id="enable-swaparr"><i class="fas fa-power-off" style="margin-right: 8px; color: #2ecc71;"></i>Enable Swaparr</h3>
<p><strong>What it does:</strong> Master switch to enable or disable automatic removal of stalled downloads.</p>
<p><strong>When to use:</strong> Turn this on after configuring your other settings. You can disable this temporarily to stop Swaparr without losing your configuration.</p>
<h3 id="max-strikes"><i class="fas fa-shield-alt" style="margin-right: 8px; color: #e74c3c;"></i>Max Strikes</h3>
<p><strong>What it does:</strong> Number of times a download must be flagged as problematic before being removed (default: 3).</p>
<p><strong>How it works:</strong> 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.</p>
<p><strong>Recommended values:</strong></p>
<ul>
<li><strong>1-2 strikes:</strong> Aggressive cleanup, faster response (for users with reliable indexers)</li>
<li><strong>3-4 strikes:</strong> Balanced approach (recommended for most users)</li>
<li><strong>5+ strikes:</strong> Conservative, gives downloads more time (for slower connections or unreliable indexers)</li>
</ul>
<h3 id="max-download-time"><i class="fas fa-clock" style="margin-right: 8px; color: #3498db;"></i>Max Download Time</h3>
<p><strong>What it does:</strong> Maximum time before considering a download stalled (examples: 2h, 120m, 7200s).</p>
<p><strong>How it works:</strong> If a download has been running longer than this time without making progress, it will receive a strike.</p>
<p><strong>Recommended values:</strong></p>
<ul>
<li><strong>1-2 hours:</strong> For fast connections and reliable trackers</li>
<li><strong>2-4 hours:</strong> Balanced setting for most users</li>
<li><strong>4+ hours:</strong> For slower connections or private trackers with limited seeds</li>
</ul>
<h3 id="ignore-above-size"><i class="fas fa-hdd" style="margin-right: 8px; color: #9b59b6;"></i>Ignore Above Size</h3>
<p><strong>What it does:</strong> Ignore downloads larger than this size (examples: 25GB, 10GB, 5000MB).</p>
<p><strong>Why this matters:</strong> Large files naturally take longer to download. This prevents Swaparr from removing legitimate large downloads that are progressing slowly.</p>
<p><strong>Recommended values:</strong></p>
<ul>
<li><strong>TV Shows:</strong> 10-25GB (season packs, 4K episodes)</li>
<li><strong>Movies:</strong> 25-50GB (4K movies, remuxes)</li>
<li><strong>Music:</strong> 5-10GB (FLAC albums, discographies)</li>
</ul>
<h3 id="remove-from-client"><i class="fas fa-trash" style="margin-right: 8px; color: #e67e22;"></i>Remove from Client</h3>
<p><strong>What it does:</strong> Also remove downloads from the download client (recommended: enabled).</p>
<p><strong>When enabled:</strong> Removes the download from both the *arr application and your download client (qBittorrent, Deluge, etc.)</p>
<p><strong>When disabled:</strong> Only removes from the *arr application, but leaves the download in your client</p>
<p><strong>Recommendation:</strong> Keep this enabled for complete cleanup. Only disable if you want to manually review removed downloads in your client.</p>
<h3 id="dry-run-mode"><i class="fas fa-eye" style="margin-right: 8px; color: #f39c12;"></i>Dry Run Mode</h3>
<p><strong>What it does:</strong> Test mode - logs what would be removed without actually removing anything.</p>
<p><strong>Perfect for:</strong></p>
<ul>
<li>Testing your configuration before going live</li>
<li>Seeing what Swaparr would remove with your current settings</li>
<li>Troubleshooting why certain downloads aren't being removed</li>
<li>Understanding Swaparr's behavior before trusting it with your downloads</li>
</ul>
<p><strong>Recommendation:</strong> Enable this first, run for a few cycles, check the logs, then disable once you're confident in your settings.</p>
<h3 id="sleep-duration"><i class="fas fa-moon" style="margin-right: 8px; color: #6c5ce7;"></i>Sleep Duration</h3>
<p><strong>What it does:</strong> Time to wait between Swaparr processing cycles (default: 900 seconds / 15 minutes).</p>
<div class="alert alert-info" style="margin: 15px 0; padding: 15px; background: rgba(13, 202, 240, 0.1); border-left: 4px solid #0dcaf0;">
<strong><i class="fas fa-clock" style="margin-right: 8px;"></i>Timing Example:</strong>
Assume a download is stalled right from the beginning. Using the default values of Sleep Duration of 15 minutes and 3 strikes:
<br><br>
After 0-15 minutes (whenever Swaparr runs) the download is monitored by Swaparr. 15 minutes later there is no progress: <strong>strike 1</strong>; 15 minutes later: <strong>strike 2</strong>; further 15 minutes: <strong>strike 3</strong> and the download is removed.
<br><br>
In total it takes <strong>45-60 minutes</strong> (depending on the first run of Swaparr) to remove bad downloads.
<br><br>
<strong>Note:</strong> Bad downloads as specified by Swaparr's security features are removed immediately with the next scan.
</div>
<p><strong>How it affects performance:</strong></p>
<ul>
<li><strong>Shorter intervals (5-10 min):</strong> Faster response to stalled downloads, more system load</li>
<li><strong>Medium intervals (15-30 min):</strong> Good balance, recommended for most users</li>
<li><strong>Longer intervals (45+ min):</strong> Less system load, slower response to issues</li>
</ul>
<p><strong>Consider your setup:</strong> If you have many active downloads, shorter intervals help. If you have a slower system or fewer downloads, longer intervals are fine.</p>
<h2 id="security-features">Security Features</h2>
<p>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.</p>
<h3 id="malicious-file-detection"><i class="fas fa-shield-alt" style="margin-right: 8px; color: #e74c3c;"></i>Malicious File Detection</h3>
<p><strong>What it does:</strong> Automatically detect and immediately remove downloads with malicious file types.</p>
<p><strong>How it works:</strong> Scans download names for dangerous file extensions and suspicious patterns. Unlike the strike system, malicious content is removed immediately without warnings.</p>
<p><strong>When to enable:</strong> Highly recommended for all users, especially those using public trackers where malicious content is more common.</p>
<div class="alert alert-warning" style="margin: 15px 0; padding: 15px; background: rgba(255, 193, 7, 0.1); border-left: 4px solid #ffc107;">
<strong><i class="fas fa-exclamation-triangle" style="margin-right: 8px;"></i>Important:</strong>
This feature analyzes filename patterns only, not actual file contents. It's designed to catch obviously malicious downloads based on their names.
</div>
<h3 id="malicious-extensions"><i class="fas fa-file-code" style="margin-right: 8px; color: #e67e22;"></i>Malicious File Extensions</h3>
<p><strong>What it does:</strong> File extensions to consider malicious and block immediately.</p>
<p><strong>Default blocked extensions:</strong></p>
<ul>
<li><strong>Executable files:</strong> .exe, .bat, .cmd, .com, .scr, .pif, .msi</li>
<li><strong>Script files:</strong> .vbs, .js, .jse, .wsf, .wsh</li>
<li><strong>Archive formats:</strong> .zipx, .arj, .ace, .001, .rar, .zip (suspicious variants and password-protected archives)</li>
<li><strong>Disc image files:</strong> .iso, .mdf, .vob (often used to distribute malware)</li>
<li><strong>Link files:</strong> .lnk (Windows shortcuts)</li>
<li><strong>Java archives:</strong> .jar (can contain malware)</li>
</ul>
<div class="alert alert-info" style="margin: 15px 0; padding: 15px; background: rgba(13, 202, 240, 0.1); border-left: 4px solid #0dcaf0;">
<strong><i class="fas fa-shield-alt" style="margin-right: 8px;"></i>Enhanced Protection:</strong>
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%.
</div>
<p><strong>Customization:</strong> 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.</p>
<h3 id="suspicious-patterns"><i class="fas fa-search" style="margin-right: 8px; color: #f39c12;"></i>Suspicious Patterns</h3>
<p><strong>What it does:</strong> Filename patterns that indicate potentially malicious or unwanted content.</p>
<p><strong>Default blocked patterns:</strong></p>
<ul>
<li><strong>Common malware indicators:</strong> keygen, crack, patch.exe, activator</li>
<li><strong>Suspicious files:</strong> password.txt, readme.txt, install.exe, setup.exe</li>
</ul>
<p><strong>Examples of what gets blocked:</strong></p>
<ul>
<li>"Movie.Name.2024.1080p.KEYGEN.mkv" - Contains "keygen"</li>
<li>"Software.Name.v1.2.Crack.Only.zip" - Contains "crack"</li>
<li>"Game.Install.Password.txt.exe" - Contains suspicious pattern</li>
</ul>
<p><strong>Customization:</strong> Add patterns that are common in your region or specific to content you want to avoid.</p>
<h2 id="age-based-cleanup">Age-Based Cleanup</h2>
<p>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.</p>
<h3 id="age-based-removal"><i class="fas fa-calendar-times" style="margin-right: 8px; color: #e74c3c;"></i>Enable Age-Based Removal</h3>
<p><strong>What it does:</strong> Remove downloads that have been stuck longer than the specified age limit.</p>
<p><strong>How it works:</strong> 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.</p>
<p><strong>When to use:</strong> 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.</p>
<h3 id="max-age-days"><i class="fas fa-hourglass-end" style="margin-right: 8px; color: #f39c12;"></i>Maximum Age (Days)</h3>
<p><strong>What it does:</strong> Remove downloads older than this many days (default: 7 days).</p>
<p><strong>Recommended values:</strong></p>
<ul>
<li><strong>3-5 days:</strong> Aggressive cleanup, good for users with reliable download sources</li>
<li><strong>7-10 days:</strong> Balanced approach, gives enough time for slow downloads (recommended)</li>
<li><strong>14+ days:</strong> Conservative, for users with very slow connections or unreliable trackers</li>
</ul>
<p><strong>Consider your setup:</strong> Private trackers with limited seeders might need longer age limits. Public trackers with many alternatives can use shorter limits.</p>
<div class="alert alert-info" style="margin: 15px 0; padding: 15px; background: rgba(13, 202, 240, 0.1); border-left: 4px solid #0dcaf0;">
<strong><i class="fas fa-info-circle" style="margin-right: 8px;"></i>Age Tracking:</strong>
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.
</div>
<h2 id="quality-based-filtering">Quality-Based Filtering</h2>
<p>Quality-based filtering automatically removes downloads with poor or undesirable quality indicators in their names. This helps maintain high standards for your media library.</p>
<h3 id="quality-based-removal"><i class="fas fa-filter" style="margin-right: 8px; color: #9b59b6;"></i>Enable Quality-Based Filtering</h3>
<p><strong>What it does:</strong> Automatically remove downloads with blocked quality patterns in their names.</p>
<p><strong>How it works:</strong> Scans download names for quality indicators that suggest poor viewing/listening experience. Like malicious file detection, quality-blocked content is removed immediately without strikes.</p>
<p><strong>When to use:</strong> Enable if you want to maintain high quality standards and automatically reject low-quality releases.</p>
<h3 id="blocked-quality-patterns"><i class="fas fa-ban" style="margin-right: 8px; color: #e74c3c;"></i>Blocked Quality Patterns</h3>
<p><strong>What it does:</strong> Quality patterns to block based on their indicators in filenames.</p>
<p><strong>Default blocked qualities:</strong></p>
<ul>
<li><strong>Camera recordings:</strong> cam, camrip, hdcam - Recorded in theaters with handheld cameras</li>
<li><strong>Telesyncs:</strong> ts, telesync, tc, telecine - Audio/video from different sources, poor sync</li>
<li><strong>Pre-retail:</strong> r6, dvdscr, dvdscreener - Pre-release screeners, often watermarked</li>
<li><strong>Workprints:</strong> workprint, wp - Unfinished cuts, missing effects or audio</li>
</ul>
<p><strong>Examples of what gets blocked:</strong></p>
<ul>
<li>"Movie.Name.2024.CAM.XviD.avi" - CAM recording</li>
<li>"Show.S01E01.TS.HDTV.x264.mkv" - Telesync quality</li>
<li>"Movie.2024.R6.DVDScr.XviD.avi" - DVD screener</li>
<li>"New.Movie.2024.WORKPRINT.x264.mp4" - Work print</li>
</ul>
<p><strong>Quality standards comparison:</strong></p>
<table>
<tr>
<th>Quality Type</th>
<th>Video Quality</th>
<th>Audio Quality</th>
<th>Recommendation</th>
</tr>
<tr>
<td><strong>CAM/TS</strong></td>
<td>Very Poor</td>
<td>Very Poor</td>
<td style="color: #e74c3c;">Block (Default)</td>
</tr>
<tr>
<td><strong>DVDScr/R6</strong></td>
<td>Poor</td>
<td>Fair</td>
<td style="color: #e74c3c;">Block (Default)</td>
</tr>
<tr>
<td><strong>HDTV/WEB-DL</strong></td>
<td>Good</td>
<td>Good</td>
<td style="color: #2ecc71;">Allow</td>
</tr>
<tr>
<td><strong>BluRay/Remux</strong></td>
<td>Excellent</td>
<td>Excellent</td>
<td style="color: #2ecc71;">Allow</td>
</tr>
</table>
<p><strong>Customization:</strong> 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.</p>
<div class="alert alert-warning" style="margin: 15px 0; padding: 15px; background: rgba(255, 193, 7, 0.1); border-left: 4px solid #ffc107;">
<strong><i class="fas fa-exclamation-triangle" style="margin-right: 8px;"></i>Be Careful:</strong>
Adding too many quality patterns might block legitimate releases. Start with the defaults and add patterns gradually based on your specific needs.
</div>
<h2 id="*arr-instance-setup">*arr Instance Setup</h2>
<p>Swaparr uses your existing *arr configurations from Huntarr. In the Swaparr configuration, you'll see checkboxes for each of your configured instances:</p>
<table>
<tr>
<th>Application</th>
<th>What Gets Monitored</th>
<th>Best Practices</th>
</tr>
<tr>
<td><strong>Sonarr Instances</strong></td>
<td>TV show download queues</td>
<td>Enable for instances with frequent stalled episodes</td>
</tr>
<tr>
<td><strong>Radarr Instances</strong></td>
<td>Movie download queues</td>
<td>Especially useful for instances downloading large 4K movies</td>
</tr>
<tr>
<td><strong>Lidarr Instances</strong></td>
<td>Music download queues</td>
<td>Enable if you frequently download FLAC or large music collections</td>
</tr>
<tr>
<td><strong>Readarr Instances</strong></td>
<td>Book/audiobook download queues</td>
<td>Useful for large audiobook files that might stall</td>
</tr>
<tr>
<td><strong>Whisparr Instances</strong></td>
<td>Adult content download queues</td>
<td>Enable based on your monitoring needs</td>
</tr>
</table>
<h2 id="operation">How Swaparr Works</h2>
<h3 id="monitoring-cycle">Monitoring Cycle</h3>
<p>Every sleep duration interval, Swaparr performs these steps:</p>
<ol>
<li><strong>Instance Discovery:</strong> Finds your enabled *arr instances</li>
<li><strong>Queue Analysis:</strong> Gets current download queues from each instance</li>
<li><strong>Progress Check:</strong> Compares current state with previous cycles</li>
<li><strong>Strike Assessment:</strong> Awards strikes to downloads meeting removal criteria</li>
<li><strong>Action Execution:</strong> Removes downloads that exceed max strikes</li>
<li><strong>Statistics Update:</strong> Updates persistent statistics and logs results</li>
</ol>
<h3 id="detection-criteria">When Downloads Get Strikes</h3>
<p>A download receives a strike when it meets ALL these conditions:</p>
<ul>
<li>Has been downloading longer than your <strong>Max Download Time</strong></li>
<li>Is smaller than your <strong>Ignore Above Size</strong> setting</li>
<li>Shows no progress since the last monitoring cycle</li>
<li>Is not in a "completed" or "seeding" state</li>
</ul>
<h3 id="statistics">Statistics Tracking</h3>
<p>Swaparr tracks comprehensive statistics visible on your home dashboard:</p>
<table>
<tr>
<th>Statistic</th>
<th>What It Counts</th>
<th>When It Increases</th>
</tr>
<tr>
<td><strong>Processed</strong></td>
<td>Total downloads analyzed</td>
<td>Every download checked during monitoring cycles</td>
</tr>
<tr>
<td><strong>Strikes</strong></td>
<td>Strikes issued to problematic downloads</td>
<td>When a download meets strike criteria</td>
</tr>
<tr>
<td><strong>Removals</strong></td>
<td>Downloads removed via strike system</td>
<td>When a download reaches max strikes and gets removed</td>
</tr>
<tr>
<td><strong>Malicious Removals</strong></td>
<td>Downloads removed for malicious content</td>
<td>When malicious file detection blocks a download</td>
</tr>
<tr>
<td><strong>Quality Removals</strong></td>
<td>Downloads removed for poor quality</td>
<td>When quality-based filtering blocks a download</td>
</tr>
<tr>
<td><strong>Age Removals</strong></td>
<td>Downloads removed for being too old</td>
<td>When age-based cleanup removes stale downloads</td>
</tr>
<tr>
<td><strong>Ignored</strong></td>
<td>Downloads skipped due to rules</td>
<td>When downloads are larger than ignore size or already completed</td>
</tr>
</table>
<h2 id="best-practices">Best Practices</h2>
<h3><i class="fas fa-lightbulb" style="margin-right: 10px; color: #f39c12;"></i>Getting Started</h3>
<ol>
<li><strong>Start with Dry Run:</strong> Enable dry run mode and monitor logs for 24-48 hours</li>
<li><strong>Conservative Settings:</strong> Use 4-5 max strikes and longer download times initially</li>
<li><strong>Monitor Statistics:</strong> Watch the dashboard stats to understand Swaparr's impact</li>
<li><strong>Gradual Adjustment:</strong> Fine-tune settings based on your specific download patterns</li>
<li><strong>Check Logs:</strong> Review logs regularly to ensure expected behavior</li>
</ol>
<h3><i class="fas fa-cogs" style="margin-right: 10px; color: #3498db;"></i>Configuration Tips</h3>
<ul>
<li><strong>Match Your Connection:</strong> Adjust max download time based on your internet speed</li>
<li><strong>Consider Your Trackers:</strong> Private trackers may need more conservative settings</li>
<li><strong>Instance Selection:</strong> Only monitor instances that commonly have stalled downloads</li>
<li><strong>Size Limits:</strong> Set ignore above size to protect large, slow downloads</li>
<li><strong>Peak Hours:</strong> Consider longer sleep duration during peak internet usage</li>
</ul>
<div class="alert alert-info">
<strong>Advanced Alternative:</strong> For more sophisticated download management, consider
<a href="https://github.com/flmorg/cleanuperr" target="_blank" style="color: #3498db;"><strong>Cleanuperr</strong></a>,
which offers more comprehensive management capabilities.
</div>
<h2 id="example-configurations">Example Configurations</h2>
<h3><i class="fas fa-rocket" style="margin-right: 8px; color: #e67e22;"></i>Aggressive Setup (Fast Connection, Reliable Trackers)</h3>
<ul>
<li><strong>Max Strikes:</strong> 2</li>
<li><strong>Max Download Time:</strong> 1h</li>
<li><strong>Ignore Above Size:</strong> 50GB</li>
<li><strong>Sleep Duration:</strong> 600 seconds (10 minutes)</li>
<li><strong>Remove from Client:</strong> Enabled</li>
<li><strong>Malicious File Detection:</strong> Enabled</li>
<li><strong>Age-Based Removal:</strong> Enabled (5 days)</li>
<li><strong>Quality-Based Filtering:</strong> Enabled (default patterns)</li>
</ul>
<h3><i class="fas fa-balance-scale" style="margin-right: 8px; color: #2ecc71;"></i>Balanced Setup (Most Users)</h3>
<ul>
<li><strong>Max Strikes:</strong> 3</li>
<li><strong>Max Download Time:</strong> 2h</li>
<li><strong>Ignore Above Size:</strong> 25GB</li>
<li><strong>Sleep Duration:</strong> 900 seconds (15 minutes)</li>
<li><strong>Remove from Client:</strong> Enabled</li>
<li><strong>Malicious File Detection:</strong> Enabled</li>
<li><strong>Age-Based Removal:</strong> Enabled (7 days)</li>
<li><strong>Quality-Based Filtering:</strong> Optional (based on preferences)</li>
</ul>
<h3><i class="fas fa-shield-alt" style="margin-right: 8px; color: #3498db;"></i>Conservative Setup (Slower Connection, Private Trackers)</h3>
<ul>
<li><strong>Max Strikes:</strong> 5</li>
<li><strong>Max Download Time:</strong> 4h</li>
<li><strong>Ignore Above Size:</strong> 15GB</li>
<li><strong>Sleep Duration:</strong> 1800 seconds (30 minutes)</li>
<li><strong>Remove from Client:</strong> Enabled</li>
<li><strong>Malicious File Detection:</strong> Enabled</li>
<li><strong>Age-Based Removal:</strong> Enabled (14 days)</li>
<li><strong>Quality-Based Filtering:</strong> Disabled (manual quality control)</li>
</ul>
<h2 id="troubleshooting">Troubleshooting</h2>
<h3>Common Issues</h3>
<h4><i class="fas fa-search" style="margin-right: 8px;"></i>No Downloads Detected</h4>
<p>If Swaparr reports no downloads to monitor:</p>
<ul>
<li>Verify your *arr instances are properly configured in Huntarr Settings</li>
<li>Check that you've enabled the correct instances in Swaparr configuration</li>
<li>Ensure the selected instances have active downloads in their queues</li>
<li>Test API connectivity using the *arr instance connection tests</li>
<li>Check Huntarr logs for Swaparr connection errors</li>
</ul>
<h4><i class="fas fa-ban" style="margin-right: 8px;"></i>Downloads Not Being Removed</h4>
<p>If problematic downloads aren't being removed:</p>
<ul>
<li>Verify <strong>Dry Run Mode</strong> is disabled</li>
<li>Check if downloads exceed your <strong>Ignore Above Size</strong> setting</li>
<li>Ensure downloads have been stalled longer than <strong>Max Download Time</strong></li>
<li>Confirm downloads have accumulated enough strikes (check logs)</li>
<li>Verify <strong>Enable Swaparr</strong> is turned on</li>
<li>Check download client API permissions</li>
</ul>
<h4><i class="fas fa-fast-forward" style="margin-right: 8px;"></i>Too Aggressive Removal</h4>
<p>If Swaparr is removing downloads too quickly:</p>
<ul>
<li>Increase <strong>Max Strikes</strong> to give downloads more chances</li>
<li>Extend <strong>Max Download Time</strong> for slower downloads</li>
<li>Increase <strong>Ignore Above Size</strong> to protect larger files</li>
<li>Extend <strong>Sleep Duration</strong> to reduce monitoring frequency</li>
<li>Consider your network conditions and typical download speeds</li>
</ul>
<h4><i class="fas fa-clock" style="margin-right: 8px;"></i>Performance Issues</h4>
<p>If Swaparr is impacting system performance:</p>
<ul>
<li>Increase <strong>Sleep Duration</strong> to reduce processing frequency</li>
<li>Disable monitoring for instances with very large queues</li>
<li>Check if your *arr applications are responding slowly</li>
<li>Monitor system resource usage during Swaparr cycles</li>
</ul>
<h3>Logging and Debugging</h3>
<p>Swaparr provides detailed logging to help diagnose issues. Look for these log entries:</p>
<ul>
<li><strong>Cycle Start/End:</strong> Beginning and completion of each monitoring cycle</li>
<li><strong>Instance Processing:</strong> Which *arr instances are being checked</li>
<li><strong>Strike Assignment:</strong> When downloads receive strikes and why</li>
<li><strong>Removal Actions:</strong> Successful or failed removal attempts</li>
<li><strong>Statistics Updates:</strong> Changes to tracked statistics</li>
<li><strong>API Errors:</strong> Connection issues with *arr applications or download clients</li>
</ul>
<div class="alert alert-info">
<strong><i class="fas fa-life-ring" style="margin-right: 8px;"></i>Support:</strong>
For issues specific to Huntarr's Swaparr implementation, use Huntarr's support channels:
<a href="https://discord.com/invite/PGJJjR5Cww" target="_blank">Discord</a> or
<a href="https://www.reddit.com/r/huntarr/" target="_blank">Reddit</a>.
For general Swaparr questions, refer to the original project documentation.
</div>
<div class="section-nav">
<a href="index.html">← Back to Apps</a>
<a href="../settings/settings.html">Settings Documentation →</a>
</div>
<footer>
Huntarr.io | Swaparr Documentation | Thanks 4 Using Huntarr - Admin9705
</footer>
</div>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink