SurgeDL Quick Start Guide #

Reading Time: ~3–5 Minutes
Audience: First-time users and new installations

Welcome to SurgeDL! This quick start guide walks you through the complete lifecycle of adding, monitoring, controlling, and accessing your very first download in under five minutes.

Step 1: Launch SurgeDL #

• On macOS: Open your Applications folder and click SurgeDL, or press Cmd + Space, type SurgeDL, and press Enter.
• On Windows: Double-click the SurgeDL icon on your Desktop or open the Start Menu and click SurgeDL.

When the application opens, you are greeted by the main workspace:

+---------------------------------------------------------------------------------------+
|  ● ● ●  ⚡ SurgeDL v2.3 [Trial: 30 days left]       [➕ Add Download]     🧲 📦 📺 ⚙️ ⋯ |
+------------------+--------------------------------------------------------------------+
| 📁 All Downloads |  [All (0)] [Active (0)] [Completed (0)] [Paused (0)]  [🔍 Search...] |
| ⬇️ Downloading   +--------------------------------------------------------------------+
| ✅ Completed     |  Order | Priority | Download | Size | Progress | Speed | ETA | Action  |
| ⏸ Paused        |--------------------------------------------------------------------|
| 🎬 Video         |                                                                    |
| 📦 Compressed    |                    No active downloads in queue                    |
| ⚙️ Programs      |                                                                    |
| 🎵 Music         |                                                                    |
| 📄 Documents     |                                                                    |
| 🧲 Torrents      |                                                                    |
+------------------+--------------------------------------------------------------------+
| 💽 Macintosh HD  | SurgeDL v2.3.0 • Swarm Engine Active       Active: 0 • Speed: 0 B/s |
+------------------+--------------------------------------------------------------------+

[SCREENSHOT S01 — SurgeDL Main Downloads Screen]

Caption: SurgeDL main downloads screen showing the navigation sidebar, center toolbar, and initial empty queue state.

Step 2: Add a Download URL #

SurgeDL offers multiple methods to start a download. For your first transfer, use the direct manual entry method:

1. Copy any direct download link to your clipboard (for example, a .zip, .iso, .exe, or .mp4 URL).
2. Click the prominent blue ➕ Add Download button located in the center of the top toolbar (or press Ctrl+N on Windows, Cmd+N on macOS).
3. The Add Direct Download URL dialog will appear.
4. Paste your URL into the URL (HTTP / HTTPS / HLS .m3u8) field (if you copied a valid URL, SurgeDL will automatically populate it for you).

+------------------------------------------------------------+
| ⚡ Add Direct Download URL                                  |
|                                                            |
| URL (HTTP / HTTPS / HLS .m3u8):                            |
| [ https://proof.ovh.net/files/10Mb.dat                   ] |
|                                                            |
| Audio URL (Optional for DASH/split audio streams):         |
| [ Optional separate audio stream URL                     ] |
|                                                            |
| Connections: [ 16 Connections (Maximum ⚡)           ▾ ]   |
|                                                            |
| ▶ Authenticated downloads — session headers               |
|                                                            |
|                                    [Cancel] [Start Download]|
+------------------------------------------------------------+

[SCREENSHOT S02 — Add Download Modal]

Caption: The Add Direct Download URL modal with pre-filled link, connection selector, and optional session authentication panel.

Step 3: Choose Destination & Confirm Details #

By default, SurgeDL automatically organizes files into category subfolders inside your system Downloads/SurgeDL directory.

When you click Start Download in the URL modal, the signature Floating Download Dialog will appear:

[SCREENSHOT S03 — Pre-Download Confirmation Dialog]

Caption: The Pre-Download Confirmation view displaying detected file size, category selector, and custom target directory picker.

1. Verify File Name & Size: SurgeDL probes the remote server headers to verify the exact file name and total byte size.
2. Category Selection: SurgeDL automatically categorizes the file based on its extension (e.g., Compressed, Programs, Video, Music, Documents). You can manually change the category dropdown if desired.
3. Change Destination (Optional): If you wish to save the file in a specific folder, click the browse button (...) next to Save As and choose your destination folder.
4. Click ⚡ Start Download (or click 🕒 Download Later if you want to leave it queued in a paused state).

Step 4: Monitor Progress & Speed #

Once the download begins, the Floating Download Dialog displays live telemetry:

+---------------------------------------------------------------+
| ⚡ SurgeDL  The Hyper-Accelerated Download Engine   [DOWNLOADING]|
+---------------------------------------------------------------+
|  [📄 DAT]  10Mb.dat                                           |
|            https://proof.ovh.net/files/10Mb.dat               |
|            [DAT] [10.0 MB]                                    |
|                                                               |
|  [==========================>                     ] 58.4%     |
|  5.84 MB / 10.0 MB                                            |
+---------------------------------------------------------------+
| [⚡ Speed: 8.4 MB/s] [🕒 Left: 00:01] [⏱️ Elapsed: 2s] [🔀 Conns: 16]|
+---------------------------------------------------------------+
| Real-Time Download Speed                   [⚡ Unlimited ▾] Peak: 9.2 MB/s |
| [~~~~~~~~~~~~~~~~/\~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~] |
+---------------------------------------------------------------+
| ▸ Active Download Threads (16)                   [Show Details]|
+---------------------------------------------------------------+
| [x] Close this window when download completes                 |
|                     [⏸ Pause] [📁 Open Folder] [✕ Cancel]    |
+---------------------------------------------------------------+

[SCREENSHOT S04 — Floating Active Download Dialog]

Caption: Live active download dialog showing multi-threaded speed graph, progress bar, time left, and connection telemetry.

Key indicators to watch:

• Progress Bar & Percentage: Shows cumulative bytes received across all parallel worker threads.
• Download Speed & Peak: Displays your current transfer rate alongside your highest recorded speed.
• Connections (Threads): Reflects the active number of parallel HTTP range connections accelerating your download.
• Active Download Threads Accordion: Click Show Details to reveal a live progress bar for each individual thread, demonstrating dynamic work-stealing in real time.

Step 5: Pause and Resume a Download #

SurgeDL supports pause and resume on any web server that supports standard HTTP byte ranges:

1. To Pause: Click the ⏸ Pause button in the floating dialog, or select the row in the main table and click ⏸ in the toolbar. The download stops immediately, and SurgeDL writes a .surgedl.json checkpoint file alongside the .part file on disk.
2. To Resume: Click ▶ Resume in the floating dialog or the main toolbar. SurgeDL validates the server ETag / Last-Modified date and immediately resumes downloading from the exact byte where it paused. You do not lose previously downloaded data.

Step 6: Access Your Completed File #

When the progress bar reaches 100%, SurgeDL finalizes the .part file, publishes the complete file to your target folder, and plays an audio chime:

1. Direct Launch: Click Open / Play to open the file directly in your default operating system viewer or media player.
2. Reveal in Finder / Explorer: Click 📁 Open Folder to open the containing directory with the downloaded file highlighted.
3. From the Main Window: In the main SurgeDL table, double-click the completed download row or right-click the row and select Show in Folder.

[SCREENSHOT S05 — Completed Download Row and Context Menu]

Caption: Right-click context menu on a completed download showing options to Show in Folder, Extract Archive, or launch Media Tools.

Quick Tips for Best Results #

• Smart Clipboard: SurgeDL can automatically detect downloadable URLs you copy in your web browser. Click 📋 Clip: ON in the top toolbar to enable or disable the non-intrusive floating download toast.
• Speed Limiting: Need to play games or attend a video call while downloading? Click ⚡ Unlimited ▾ on the top toolbar or inside the floating dialog to select a preset limit like 1.0 MB/s or 2.0 MB/s.
• Video Streams & Playlists: Have a web video or playlist link? Simply paste the media or playlist link into ➕ Add Download or click 📺 Playlist to queue whole playlists in one click.

SurgeDL User Guide — Chapter 5: Understanding the SurgeDL Interface #

SurgeDL features a refined desktop user interface inspired by modern operating system aesthetics, with tailored dark mode styling, native system window integration, and a clear hierarchy of controls.

This chapter provides a detailed reference for every user interface element, toolbar button, category filter, table column, and inspector panel within the application.

+------------------------------------------------------------------------------------------------------+
| 1. TITLEBAR: Traffic Lights | SurgeDL Brand & License | [➕ Add URL] [🧲 Torrent] [📦 Batch] [📺 Playlist] [🎬 Converter] | Power | Limit | 🌓 | ≡ Menu |
+------------------------------------+-----------------------------------------------------------------+
| 2. SIDEBAR                         | 3. CONTENT AREA HEADER                                          |
|                                    | Filter Pills: [All] [Active] [Completed] [Paused]                |
| Downloads:                         | Search: [🔍 Search downloads... ]  Sort: [⇅ Date Added ▾]       |
|   📁 All Downloads          (12)   | Quick Actions: [▶] [⏸] [⏹] [📂] [🗑] [💥 Delete All]            |
|   ⬇️ Downloading             (2)   +-----------------------------------------------------------------+
|   ✅ Completed               (8)   | 4. DOWNLOADS TABLE                                              |
|   ⏸ Paused                  (2)   | Order | Priority | Download | Size | Progress | Rate | ETA | Status |
|                                    |-------+----------+----------+------+----------+------+-----+--------|
| Queues:                            |   1   |  Normal  | File.zip | 1.2G | [====> ] | 4M/s | 02m | Downld |
|   ⚡ Default Queue           (10)   |   2   |   High   | Song.mp3 |  12M | [======] |  --  |  -- | Done   |
|   🌙 Night Queue             (2)   +-----------------------------------------------------------------+
|   [+ New Queue]                    | 5. BOTTOM INSPECTOR PANEL                                       |
|                                    | Tabs: [:: Details] [📄 Files] [👥 Peers] [🌐 Trackers] [📝 Log]  |
| Categories:                        | Grid: File Name | Destination | Source URL | Live Stream Player |
|   🎬 Video                   (4)   +-----------------------------------------------------------------+
|   📦 Compressed              (3)   | 6. STATUS FOOTER                                                |
|   ⚙️ Programs                (2)   | SurgeDL v2.3.0 • FFmpeg Active • Swarm Active | Active: 2 | 4.2 MB/s|
|   🎵 Music                   (1)   +-----------------------------------------------------------------+
|   📄 Documents               (1)   
|   🧲 Torrents                (1)   
|                                    
| 💽 Macintosh HD (245 GB Free)      
+------------------------------------+

[SCREENSHOT S01 — SurgeDL Main Downloads Screen]

The full SurgeDL desktop interface showing the modern titlebar, primary action buttons, sidebar queues and categories, download table, and status footer.

5.1 The Titlebar & Primary Actions #

The top titlebar serves as the primary command center for SurgeDL.

5.1.1 Window Management & Branding (Left Area) #

• Window Controls:
• macOS: Standard traffic light buttons (Red = Close/Minimize to Tray, Yellow = Minimize to Dock, Green = Fullscreen/Zoom).
• Windows: Integrated modern frameless titlebar with native Minimize, Maximize, and Close buttons.
• App Brand Title (⚡ SurgeDL v2.3): Displays the active application release.
• License Registration Badge (#licenseBadge):
• Displays your current licensing state: e.g., Trial: 30 days left with a status dot, or Licensed when activated.
• Clicking this badge opens the SurgeDL License Registration dialog.

5.1.2 Primary Action Buttons #

The toolbar provides quick access to core download operations:

5.1.3 Queue Power Completion Selector #

Located adjacent to the toolbar buttons:

• ⚡ Done: Stay Idle (Default): Leaves your computer running normally after all queue downloads finish.
• ⚡ Done: Sleep PC: Automatically puts your computer into low-power Sleep mode once all active downloads finish.
• ⚡ Done: Shut Down: Automatically shuts down your computer once all active downloads finish. A safety modal with a 30-second abort countdown is displayed before power-off occurs.

5.1.4 Global Speed Limiter Dropdown (`#speedLimiterBtn`) #

Clicking the speed pill displays the global bandwidth throttling menu:

• Unlimited (MAX): Removes all download rate restrictions (default on startup).
• 512 KB/s (Eco): Restricts total application bandwidth to 512 KB/s (ideal for shared networks).
• 1.0 MB/s (Normal): Caps total throughput to 1 MB/s.
• 2.0 MB/s (Fast): Caps total throughput to 2 MB/s.
• 5.0 MB/s (Turbo): Caps total throughput to 5 MB/s.
• Custom... (KB/s): Opens a prompt allowing you to specify an exact custom limit in kilobytes per second.

5.1.5 Theme Toggle Button (`#themeToggleBtn`) #

Instantly switches the user interface between Dark Mode and Light Mode with smooth CSS variable transitions.

5.1.6 The Global UniMenu (`≡` Menu Button — `#globalUniMenuBtn`) #

The top-right ≡ button unifies all secondary management, configuration, file import/export, and utility tools into a clean, categorized drop-down menu:

• 📁 File:
• ➕ Add Download... (Ctrl+N): Open direct URL download modal.
• 🧲 Add Torrent / Magnet...: Open BitTorrent swarm dialog.
• 📦 Batch Downloads...: Open pattern generator and page crawler.
• 📺 Web Playlist Grabber...: Open web playlist parser.
• 📥 Import URLs from File...: Import batch download lists from plain text (.txt), legacy export format (.ef2), or CSV files.
• 📤 Export Download List...: Export completed or active downloads list to a portable text file for backup or migration.
• ⚡ Queue & Controls:
• ▶ Resume All: Resume all paused downloads across the active queue.
• ⏸ Pause All: Pause all currently active downloads.
• ⏹ Stop All: Stop all network transfers immediately.
• 🧹 Clear Inactive / Completed: Remove finished tasks from the view.
• ⚡ Speed Limiter...: Open bandwidth limiter options.
• ⏰ Off-Peak Scheduler...: Configure overnight automated download windows.
• ⚡ Power Action on Completion...: Select Sleep or Shutdown behavior.
• 🛠️ Tools:
• 🎬 Studio Media Converter: Open FFmpeg media processing suite.
• 🎯 Toggle Drop Target Widget: Show or hide the floating desktop drop target widget.
• 🔄 Check for Updates...: Query online manifest for engine and yt-dlp resolver updates.
• 📋 Smart Clipboard URL Watcher: Toggle automatic clipboard URL detection on/off.
• ⚙️ Settings & Help:
• ⚙️ Options & Preferences... (Ctrl+,): Open the comprehensive 7-tab configuration window.
• 🎨 Theme Accent Colors...: Customize interface accent color (Blue, Emerald, Purple, Amber, Crimson).
• 🔔 Audio Chimes: Toggle audible alerts on download completion.
• 📖 User Guide / Documentation (F1): Opens this comprehensive offline user guide.
• 🔑 Register SurgeDL License...: Enter activation serial key.
• ℹ️ About SurgeDL: View version, bundled engine releases, and credits.

5.2 The Sidebar Navigation #

The left sidebar categorizes your download inventory into filterable status views, dedicated queues, file categories, and monitors local storage health.

5.2.1 Status Views (Downloads Section) #

• 📁 All Downloads (#countAll): Displays all items currently present in SurgeDL's history.
• ⬇️ Downloading (#countDownloading): Filters the list to show only tasks actively receiving data or muxing media.
• ✅ Completed (#countCompleted): Filters the list to display downloads that have finished 100%.
• ⏸ Paused (#countPaused): Filters the list to show paused or queued downloads waiting for user resumption.

5.2.2 Multiple Named Queues Section (`#queueListNav`) #

SurgeDL supports multiple independent download queues:

• ⚡ Default Queue (#queueDefault): The primary queue assigned to standard downloads.
• Custom Named Queues (e.g., "🌙 Night Queue", "Work Files", "Media"): Displays all user-defined queues with live active item counts and inline Pause (⏸) / Resume (▶) controls.
• + New Queue Button (#btnAddQueue): Opens the Create Download Queue modal to name a new queue and set custom concurrency rules.
• Queue Management: Right-click any custom queue to delete it or re-order tasks.

5.2.3 Media & Format Categories #

SurgeDL automatically sorts downloads into dedicated category views based on file extensions:

• 🎬 Video (#countVideo): Movies, clips, and streams (.mp4, .mkv, .webm, .avi, .mov, .flv, .wmv).
• 📦 Compressed (#countCompressed): Archives and disk images (.zip, .rar, .7z, .tar, .gz, .iso, .bz2, .xz).
• ⚙️ Programs (#countPrograms): Installers and software packages (.exe, .msi, .apk, .dmg, .pkg, .deb).
• 🎵 Music (#countMusic): Audio tracks and podcasts (.mp3, .wav, .aac, .flac, .m4a, .opus, .ogg).
• 📄 Documents (#countDocuments): Text documents, spreadsheets, and reading material (.pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .txt, .csv, .epub).
• 🧲 Torrents (#countTorrents): Active or completed BitTorrent swarms and magnet downloads.

5.2.4 Storage Card (`#diskCard`) #

Located at the bottom of the sidebar, the storage card monitors your target hard drive health in real time:

• Drive Label (#diskName): Displays the primary volume name (e.g., Macintosh HD (/ ) or C:).
• Free Space (#diskFree): Displays exact available free storage in gigabytes (e.g., Free: 245.2 GB).
• Storage Meter (#diskFill & #diskPercent): A colored gauge illustrating percentage of drive capacity utilized.

5.3 The Main Workspace & Download Table #

The main content area presents the download list with rich telemetry and direct action triggers.

5.3.1 Filter Pills & Search Bar #

• Filter Pills (All, Active, Completed, Paused): One-click pills above the table that instantly narrow your visible downloads without navigating away from your active category.
• Search Input (#searchInput): Real-time text search. Type any portion of a file name, domain, or extension to immediately filter visible rows.
• Sort Dropdown (#sortSelect): Sorts rows by:
• ⇅ Date Added (Default: newest first)
• ⇅ Name (A-Z) (Alphabetical)
• ⇅ Size (Largest) (Largest byte volume first)
• ⇅ Status (Grouped by Downloading, Completed, Paused)
• Table Action Buttons: Compact toolbar buttons providing one-click access to Resume (▶), Pause (⏸), Stop All (⏹), Open Folder (📂), Delete Selected (🗑), and Delete All (💥 Delete All).

5.3.2 Download Table Columns #

5.3.3 Rich Context Menu (Right-Click Actions) #

Right-clicking any download row provides instant access to advanced management options:

• ▶ Resume Download: Starts or continues transferring the selected file.
• ⏸ Pause Download: Temporarily halts transfer, preserving downloaded chunks.
• 🔄 Refresh Download Address...: For temporary or expired links (such as file hosters or pre-signed cloud storage links that returned 403 Forbidden). Prompts for a fresh URL and resumes downloading without losing already finished byte ranges.
• ⚡ Set Speed Limit...: Apply a specific bandwidth ceiling (in KB/s) to this individual download task.
• 📂 Move to Queue...: Move the task to another named queue (e.g., from Default Queue to Night Queue).
• ℹ️ Properties / File Info: Opens the comprehensive technical details modal for the download.
• 📂 Show in Folder: Opens macOS Finder or Windows Explorer with the completed file highlighted.
• 📋 Copy Download Link: Copies the remote URL to the system clipboard.
• 🗑 Delete Download...: Removes the download record from SurgeDL history.
• 💥 Delete Download and File: Removes the record and permanently purges the file from your disk.

5.4 The Bottom Inspector Panel #

Clicking any row in the download table activates the Inspector Panel located at the bottom of the workspace. Click the toggle arrow (▼) on the far right to expand or collapse the panel.

[SCREENSHOT S06 — Bottom Inspector Panel]

The Inspector Panel displaying file details, file path with open/copy buttons, and the embedded live video preview card.

5.4.1 Inspector Tabs #

1. :: Details (#inspTabDetails): Displays file name, local destination path, source URL, engine type, transfer speed/ETA, priority, and date added. Includes:

• 📂 Open Button: Immediately reveals the destination folder on disk.
• 📋 Copy Button: Copies the full source download URL to your clipboard.
• ▶ Live Stream Preview Card: Features an embedded HTML5 video player allowing you to watch downloading videos and torrents sequentially before completion.

1. 📄 Files (#inspTabFiles): For multi-file BitTorrent swarms, lists every contained file, its relative path, individual size, and download progress.
2. 👥 Peers (#inspTabPeers): For BitTorrent tasks, displays connected remote peer IP addresses, client software names, download rates, and upload rates.
3. 🌐 Trackers (#inspTabTrackers): Lists announce tracker URLs and tracker connection status for torrent downloads.
4. 📝 Log (#inspTabLog): Displays a timestamped activity log of connection events, HTTP status codes, and worker segment allocations.

5.5 The Status Footer #

The persistent footer at the bottom of the main window provides system-wide operational metrics:

• App Version Badge (#appVersionBadge): Shows installed SurgeDL version (v2.3.0).
• FFmpeg Badge (#ffmpegBadge): Indicates whether the bundled FFmpeg processor is active or detects GPU hardware encoders.
• Swarm Status (#swarmStatusBadge): Indicates the background WebTorrent swarm client state.
• Active Count (#statActiveCount): Displays the number of downloads currently transferring data.
• Total Speed (#statTotalSpeed): Reflects cumulative real-time throughput across all active tasks (e.g., 14.8 MB/s).
• Sound Toggle (#soundToggleBtn): Click to toggle audio chimes on or off (🔔 Sound: On / 🔔 Sound: Off).

5.6 The Desktop Drop Target Widget #

SurgeDL includes a signature floating Desktop Drop Target Widget designed for rapid drag-and-drop workflows without keeping the main application window in the foreground:

• Always-On-Top Floating Pill: Floats unobtrusively on your desktop or over your web browser.
• Live Telemetry: Shows active download count and real-time total throughput directly on the widget.
• Drag-and-Drop Ingestion:
• Drag any highlighted text URL or hyperlink directly into the widget to trigger the download confirmation modal.
• Drag .torrent files into the widget for immediate swarm parsing.
• Window Controls: Click the widget icon to bring the main SurgeDL window to the front, or click the minimize button to hide it to the system tray.
• How to Toggle: Enable or disable via ≡ Menu ➔ Tools ➔ Toggle Drop Target Widget or in Options ➔ General.

SurgeDL User Guide — Chapters 6 to 8: Adding, Managing & Monitoring Downloads #

6. Adding Downloads #

SurgeDL offers six verified methods to add downloads, ranging from standard manual entry to automated clipboard capturing, browser interception, pattern generation, site crawling, and playlist grabbing.

6.1 Manual URL Download (The Add Download Modal) #

To download any file directly using an HTTP, HTTPS, or HLS (.m3u8) address:

1. Copy the download link to your clipboard.
2. Click ➕ Add Download on the top toolbar, or press Ctrl+N (Windows) / Cmd+N (macOS).
3. The Add Direct Download URL dialog will appear. SurgeDL automatically inspects your clipboard and populates the URL field if a valid web address is detected.

+-------------------------------------------------------------------------+
| ⚡ Add Direct Download URL                                               |
|                                                                         |
| URL (HTTP / HTTPS / HLS .m3u8):                                         |
| [ https://proof.ovh.net/files/100Mb.dat                               ] |
|                                                                         |
| Audio URL (Optional for DASH/split audio streams):                      |
| [                                                                     ] |
|                                                                         |
| Connections: [ 16 Connections (Maximum ⚡)                          ▾ ] |
|                                                                         |
| ▼ Authenticated downloads — session headers                             |
|   Session Cookies:                                                      |
|   [ auth_token=9a8b7c...; session_id=xyz                              ] |
|   Referer URL:                           User-Agent (Optional):         |
|   [ https://source.com/download        ] [ Mozilla/5.0...             ] |
|                                                                         |
|                                             [Cancel]   [Start Download] |
+-------------------------------------------------------------------------+

[SCREENSHOT S02 — Add Download Modal]

The Add Direct Download URL modal with pre-filled link, connection selector, and authenticated session headers.

Configuration Options in the Add Modal: #

• Audio URL (Optional): Used when downloading separate video and audio streams (such as DASH manifests or manual media tracks). SurgeDL will download both streams in parallel and merge them automatically using FFmpeg.
• Connections: Select the number of parallel download threads:
• 8 Connections: Standard servers with strict rate limits.
• 16 Connections (Maximum ⚡): Recommended default for high acceleration.
• 24 Connections (Turbo CDN): High-bandwidth enterprise CDNs.
• 32 Connections (Extreme): Ultra-high-speed multi-gigabit connections.
• Authenticated Downloads — Session Headers (Resolve Protected Streams):

Click the headers accordion to supply credentials for protected file servers:

• Session Cookies: Paste authentication cookies (e.g., Cookie: session_id=...). The input is securely masked.
• Referer URL: Set a custom HTTP Referer header required by file-hosting forums or gated portals.
• User-Agent: Specify a custom browser identity string if the server blocks generic download clients.

6.2 Smart Clipboard URL Watcher #

SurgeDL includes a non-intrusive background monitor that inspects your system clipboard for downloadable links.

How It Works: #

1. When you copy a link in any browser, email client, or chat app, SurgeDL evaluates the URL every 1.2 seconds against two criteria:

• Downloadable Extensions: .zip, .iso, .exe, .msi, .tar, .gz, .7z, .rar, .mp4, .mkv, .mov, .avi, .mp3, .pdf, .apk, .dmg, .bin.
• Streaming Media & Web Links: Supported public video platforms, podcast feeds, and direct media streaming URLs (.mp4, .m3u8, .webm).
• BitTorrent Links: Any link starting with magnet:?xt=urn:btih:.

1. When a matching link is detected, a compact floating toast notification appears in the lower-right corner of your screen:

+------------------------------------------------------+
| 🔗 Download Link Detected                         ✕  |
| 100Mb.dat (https://proof.ovh.net/files/100Mb.dat)   |
|                                                      |
|                          [Ignore]   [⬇ Download Now] |
+------------------------------------------------------+

[SCREENSHOT S07 — Smart Clipboard Floating Toast]

The non-intrusive floating clipboard toast showing detected file name, domain, and 1-click download button.

• Click ⬇ Download Now to open the download confirmation dialog immediately.
• Click Ignore or the close button (✕) to dismiss the notification.
• To turn clipboard monitoring off, click 📋 Clip: ON in the top toolbar. The button will switch to 📋 Clip: OFF.

6.3 Drag and Drop (.torrent Files) #

You can add BitTorrent downloads simply by dragging .torrent files into SurgeDL:

1. Drag any .torrent file from your desktop or file manager over the SurgeDL window.
2. A full-screen translucent overlay will activate: "🧲 Drop .torrent File to Download Swarm".
3. Release the mouse button. SurgeDL will immediately parse the torrent metadata, strip the .torrent suffix, and open the download dialog.

6.4 Batch URL Pattern Generator #

When downloading sequential files (such as multi-part archives, image galleries, or video episodes), use the built-in Batch Downloader:

1. Click 📦 Batch on the top toolbar.
2. Under the ⚙️ URL Pattern Generator tab, enter a URL containing bracketed numeric or alphabetic ranges:

• Numeric Range: https://example.com/files/archive_[01-20].zip
• Alphabetic Range: https://example.com/gallery/img_[a-f].jpg

1. Click the quick presets (🖼️ Gallery, 📦 Archive, or 🎬 Video) for immediate template syntax.
2. Review the Expansion Preview box, which lists every generated URL.
3. Select your target Connections and Priority, then click ⚡ Start Batch Download. All items are enqueued simultaneously.

6.5 Webpage Media Crawler #

SurgeDL can scan any public webpage and extract all downloadable media files:

1. Click 📦 Batch and switch to the 🕸️ Webpage Media Crawler tab.
2. Enter any website URL and click 🔍 Scan Webpage.
3. SurgeDL crawls the page HTML and extracts videos, audio, compressed archives, documents, and programs.
4. Filter found items by category pills or use the search box.
5. Check the items you wish to save and click ⚡ Download Selected.

6.6 Universal Web Playlist Grabber #

To download entire video playlists or audio albums:

1. Click 📺 Playlist on the top toolbar (or select from ≡ Menu ➔ File).
2. Paste the public playlist URL (e.g., https://example.com/playlist?list=...) into the input field.
3. Click 🔍 Scan Playlist. SurgeDL uses its bundled media resolver engine to parse the playlist entries, displaying titles, uploaders, durations, and video thumbnails.
4. Choose your target format from the Download as dropdown:

• Highest Available (Up to 4K): Best possible video and audio quality.
• 1080p Full HD: Crisp 1080p MP4.
• 720p HD: Fast, bandwidth-efficient 720p MP4.
• Extract Audio (320kbps MP3): Automatically converts videos to pristine 320kbps MP3 audio files.

1. Click ⚡ Add Selected to Queue to start batch downloading.

6.7 Import Download Lists from File (.txt, .ef2, .csv) #

SurgeDL allows you to import bulk download queues from external files:

1. Click ≡ Menu ➔ File ➔ 📥 Import URLs from File...
2. Select any supported list file:

• Plain Text (.txt): One HTTP/HTTPS or Magnet URL per line.
• Standard Batch Export Format (.ef2): Compatible with standard export files generated by conventional download managers and legacy download utilities.
• Comma-Separated Values (.csv): URLs with optional custom filename columns.

1. SurgeDL parses the file, displays an import summary modal, and enqueues the tasks directly into your active download queue.

6.8 Browser Extension "Download All Links with SurgeDL" #

When browsing forums, galleries, or software indexes with dozens of download links:

1. Right-click anywhere on the webpage in Chrome, Edge, Brave, or Firefox.
2. Select "Download All Links with SurgeDL" from the context menu.
3. The SurgeDL Bulk Link Selector dialog will appear displaying all detected links on the page.
4. Filter links by extension pills (e.g. ZIP, PDF, MP4), check the desired files, and click Download Selected.

6.9 Floating Desktop Drop Target Drag-and-Drop #

When the floating Desktop Drop Target widget is open on your desktop:

1. Drag any link directly from your browser, email, or Slack/Discord onto the widget.
2. SurgeDL immediately brings up the download confirmation dialog pre-filled with the dropped address.
3. You can also drop .torrent files directly onto the target to instantly open the BitTorrent swarm dialog.

7. Managing Downloads #

SurgeDL provides complete operational control over every task in your download queue.

7.1 Start, Pause, and Resume Downloads #

Active Task States:
[QUEUED] ➔ [DOWNLOADING] ⇄ [PAUSED] ➔ [COMPLETED]
                ↓
             [ERROR] (Retryable)

• Starting a Download: If Auto Start is enabled in settings, downloads begin immediately upon confirmation. Otherwise, newly added tasks enter the PAUSED or QUEUED state until you click ▶ Resume.
• Pausing a Download: Click the ⏸ button in the task row or toolbar. SurgeDL cleanly closes all active HTTP range sockets, flushes buffered chunks to disk, and updates the .surgedl.json metadata checkpoint file.
• Resuming a Download: Click ▶. SurgeDL queries the server to verify the ETag and file modification timestamps. If the server validates the range request, downloading resumes from the exact byte where it left off.
• Stop All (⏹): Click ⏹ on the main toolbar or select ⏹ Stop All from the ≡ Menu to immediately pause all active downloads across the entire application.

7.2 Priority Management and Queue Re-ordering #

SurgeDL allows you to dictate which files receive network priority:

• Priority Weighting: Click the Priority column dropdown for any task and choose High, Normal, or Low. When multiple downloads compete for bandwidth, high-priority tasks receive allocation preference.
• Queue Re-ordering: In the Order column, click the Up Arrow (▲) or Down Arrow (▼) to adjust the task's execution order.

7.3 Redownloading and Retrying #

If a download was interrupted by server-side errors, or if you wish to re-fetch a fresh copy:

1. Right-click the download task in the main table.
2. Select 🔄 Redownload from Start.
3. SurgeDL resets the progress counter, purges partial .part chunks, and initiates a clean download from byte 0.

7.4 Refreshing Expired / 403 Download Addresses #

Many file-sharing hosts, cloud storage providers (such as pre-signed Amazon S3 or Google Cloud Storage links), and premium video portals generate temporary download URLs that expire after 1 to 24 hours. If an interrupted download fails with 403 Forbidden or URL Expired:

1. Right-click the failed or paused task in the download list.
2. Select 🔄 Refresh Download Address...
3. SurgeDL pauses the task and opens the Refresh Download Address dialog.
4. Re-visit the download webpage in your browser to generate a fresh link, copy it, and paste it into the dialog.
5. Click Verify & Update Address. SurgeDL validates the new URL, verifies that the remote file size and checksum match the original file, and resumes downloading from the exact byte where it paused, preventing wasted time and bandwidth!

7.5 Per-Task Speed Limit Throttling #

To prevent a large download from dominating your connection while leaving other tasks unconstrained:

1. Right-click any download row in the table.
2. Select ⚡ Set Speed Limit...
3. Choose a preset or enter a custom rate in KB/s (e.g. 500 for 500 KB/s, or 0 for unlimited).
4. SurgeDL applies an isolated token-bucket bandwidth throttle specifically to that individual task.

7.6 Moving Downloads Across Queues #

SurgeDL allows you to organize downloads into different queues (such as Default Queue, Night Queue, Work Files):

1. Right-click the download row in the table.
2. Select 📂 Move to Queue...
3. Select your destination queue from the dropdown list.
4. The download is immediately transferred to the selected queue and will follow that queue's specific execution schedule.

7.7 Deleting Downloads: History vs. Hard Disk #

SurgeDL strictly protects users against accidental data loss when deleting items.

When you click the delete icon (🗑) or press the Delete key:

[SCREENSHOT S08 — Confirm Deletion Dialog]

The Confirm Deletion modal showing the safety checkbox to permanently delete files from your hard drive.

1. Delete from SurgeDL List (Default):

• The file entry is removed from SurgeDL's history and database.
• Your downloaded file remains untouched on your hard drive.

1. Delete File from Hard Disk as Well:

• If you check the red-highlighted checkbox:

[x] Delete completely downloaded files from your hard disk as well. Be careful !

• SurgeDL will permanently delete the downloaded file (and any .part files) from your computer.

7.8 Accessing Completed Files #

• Open File (Enter): Press Enter on a highlighted completed row or right-click and select ⚡ Open / Play to launch the file in your system default application.
• Show in Folder (📂): Click the 📂 icon or select 📂 Show in Folder to open the containing folder in macOS Finder or Windows Explorer with the specific file selected.

7.9 Download Properties Dialog #

To inspect exhaustive technical information about any download:

1. Right-click the download row and select ℹ️ Properties / File Info.
2. The Download Properties dialog displays:

• File Name & Category: Target name and classification.
• File Size: Total bytes reported by server.
• Save Path: Local disk destination with 📋 Copy and 📂 Open buttons.
• Source URL: Full remote URL with a 📋 Copy button.
• Engine: Specific acceleration core used (MultiPart, Stream, WebTorrent, Local).
• Priority & Created/Completed Timestamps: Exact audit timestamps.
• Disk Status: Confirms whether the file currently exists on disk and its verified byte size.

7.10 Exporting Download Lists to File #

To back up your download history, share a link collection, or migrate tasks:

1. Click ≡ Menu ➔ File ➔ 📤 Export Download List...
2. Choose to export all downloads or only completed items.
3. Select your preferred destination file (.txt or .ef2).
4. SurgeDL writes a clean, portable manifest that can be imported back into SurgeDL at any time.

8. Understanding Download Information & Telemetry #

SurgeDL provides real-time telemetry across both the main table and the signature Floating Download Dialog.

8.1 The Floating Download Dialog #

When a download starts, SurgeDL displays a dedicated floating dialog window featuring real-time diagnostic instruments:

[SCREENSHOT S04 — Floating Active Download Dialog]

The floating download dialog featuring real-time speed graph, active thread accordion, and bandwidth throttle controls.

1. Brand Identity & Status Header: Displays the active engine tagline and an animated status pill (DOWNLOADING, PAUSED, MUXING, COMPLETED).
2. File Meta Card: Shows the target file name, full URL, file extension badge, and total file size.
3. Progress Bar & Byte Counter: Displays cumulative completion percentage and exact transferred bytes (e.g., 45.2 MB / 100.0 MB).
4. Metric Cards Grid:

• ⚡ Download Speed: Real-time transfer speed updated every 250 milliseconds.
• 🕒 Time Left (ETA): Accurate time remaining calculated dynamically using weighted moving average transfer rates.
• ⏱️ Time Elapsed: Duration since transfer was initiated.
• 🔀 Connections: Active parallel HTTP range worker connections (e.g., 16).

1. Real-Time Speed Graph Canvas:

• An interactive canvas graph rendering live bandwidth fluctuations.
• Peak Speed Indicator: Displays the maximum throughput reached during the transfer.
• In-Dialog Speed Throttle (⚡ Unlimited ▾): Adjust bandwidth limits directly inside the dialog without opening main settings.

1. Active Download Threads Accordion:

• Click Show Details to expand the thread breakdown.
• Displays an individual progress gauge for each of the 16 or 32 connections, showing how the dynamic work-stealing engine divides and conquers file segments in real time.

1. Auto-Close Checkbox: Check [x] Close this window when download completes to automatically dismiss the dialog upon successful completion.

8.2 Download Status Reference Table #

SurgeDL User Guide — Chapters 9 to 11: Acceleration, Categories & Search #

9. Download Acceleration Architecture #

SurgeDL utilizes an advanced multi-connection range download core designed to maximize bandwidth saturation. This chapter explains how the acceleration engine functions, what dynamic work-stealing achieves, and the real-world conditions that affect transfer speeds.

9.1 How Multi-Part Segmented Acceleration Works #

When a standard web browser downloads a file, it establishes a single TCP socket connection to the server. If the server throttles individual connections to 2 MB/s, your download speed is strictly capped at 2 MB/s, regardless of whether your broadband line can handle 100 MB/s.

SurgeDL overcomes this limitation through HTTP Byte-Range Segmenting:

Single-Connection Browser Download:
[Server] ─── (Connection 1: Throttled to 2 MB/s) ───▶ [Disk] Total: 2 MB/s

SurgeDL Multi-Part Acceleration (16 Connections):
[Server] ─── (Thread 1: Bytes 000-025MB) ──▶ 
[Server] ─── (Thread 2: Bytes 026-050MB) ──▶
[Server] ─── (Thread 3: Bytes 051-075MB) ──▶ [Multi-Part Core] ──▶ [Sparse .part File]
[Server] ─── (Thread 4: Bytes 076-100MB) ──▶                       Total: 32 MB/s
... up to 32 parallel streams ...

1. Range Probing: Before transferring payload bytes, SurgeDL sends an initial probe request with the header Range: bytes=0-1023.
2. Server Capability Check:

• If the server responds with HTTP 206 Partial Content and a valid Content-Range header, SurgeDL confirms that the server supports range requests.
• SurgeDL notes the remote ETag or Last-Modified validator headers to ensure cache integrity.

1. Sparse Pre-Allocation: SurgeDL immediately creates a .part container file on your drive and pre-allocates the exact byte length (fs.ftruncateSync). On modern Windows NTFS and ReFS volumes, native sparse file allocation is engaged to minimize filesystem fragmentation.
2. Segment Division: SurgeDL divides the total file size into equal ranges distributed across up to 32 worker threads. Each worker connects simultaneously, pulling its assigned segment in parallel.

9.2 Dynamic Work-Stealing Algorithm #

A common flaw in legacy download managers is the "straggler thread problem": if 15 threads finish their segments quickly but the 16th thread is stuck on a slow or congested network route, the download stalls at 95% waiting for the single slow connection.

SurgeDL eliminates this bottleneck with an intelligent Dynamic Work-Stealing Algorithm:

Segment 1: [████████████████████] Finished! -> Becomes Idle
Segment 2: [████████████████████] Finished! -> Becomes Idle
Segment 3: [████████░░░░░░░░░░░░] Working... 12 MB remaining
                ↓
Dynamic Bisection (Work-Stealing):
Worker 1 (Idle) STEALS the upper half of Segment 3!
Worker 3 downloads: Bytes 40MB - 46MB
Worker 1 downloads: Bytes 46MB - 52MB (New Segment 4)

How Work-Stealing Operates: #

• Whenever any worker thread finishes its assigned segment, it immediately scans the remaining segments across all active workers.
• If it locates an active segment with more than 256 KB of remaining data, it bisects the remaining un-downloaded range into two halves.
• The original worker continues downloading the lower half, while the newly freed worker instantly steals the upper half, opening a fresh HTTP range connection.
• This bisection can occur dynamically up to 128 total segments, ensuring that all connection slots remain 100% active until the very final byte is written.

9.3 Checkpoint Integrity & Resumption #

SurgeDL writes real-time progress checkpoints to a companion metadata file named <filename>.surgedl.json:

• Every second, the exact byte position (current) of every active segment is synced to disk (fs.fsyncSync).
• If your computer abruptly loses power, shuts down, or disconnects from Wi-Fi, the .part file and .surgedl.json checkpoint remain intact.
• When you click ▶ Resume, SurgeDL verifies that the remote server's ETag and Last-Modified headers match the checkpoint. If verified, all workers resume from their exact previous byte positions with zero corruption and zero lost data.

9.4 Real-World Acceleration Realities #

While multi-part acceleration provides dramatic speed increases on most hosts, users should be aware of technical constraints:

• Servers Without Range Support: Some file hosts return HTTP 200 OK instead of HTTP 206 Partial Content. These servers do not support byte ranges; SurgeDL will safely download them using a single reliable connection.
• Per-IP Rate Throttling: If a server restricts your entire IP address to 10 MB/s, opening 16 connections will split the 10 MB/s pool across 16 streams rather than multiplying it.
• Local Line Saturation: SurgeDL cannot exceed the maximum physical throughput provided by your Internet Service Provider (ISP).

10. Automatic & Custom Categories #

SurgeDL simplifies organization by automatically sorting downloads into categories based on file signatures and extensions.

10.1 Default Category Classifications #

10.2 Customizing Category Save Folders #

You can customize where each category saves files on your computer:

1. Click ⚙️ Options on the top toolbar (or select Preferences... on macOS).
2. Switch to the Save To tab.
3. Under Category-Specific Save Folders, specify a custom directory for any category:

[SCREENSHOT S09 — Options Save To Tab]

Caption: The Save To configuration tab showing default download folder and category-specific path overrides.

• Click the browse button (...) next to any category to choose a custom local folder (e.g., directing all Video downloads to an external media drive D:\Media\Movies).
• If a category path is left blank, SurgeDL defaults to your primary Default Download Folder.

11. Search, Filter, and Sort #

As your download history expands, SurgeDL provides real-time search, category navigation, status pills, and multi-field sorting.

11.1 Real-Time Search (#searchInput) #

• Located at the top-right of the main content workspace.
• Type any word, file extension, or domain into the 🔍 Search downloads... input box.
• The table updates instantly with zero lag, displaying only rows matching your search query across file names and URLs.

11.2 Status Filter Pills #

Above the download table, four status pills provide quick filtering:

• All (#pillCountAll): Displays all downloads in the currently selected sidebar category.
• Active (#pillCountActive): Isolates tasks currently transferring data or muxing media.
• Completed (#pillCountCompleted): Displays only 100% finished downloads.
• Paused (#pillCountPaused): Displays paused or queued downloads awaiting action.

11.3 Multi-Field Sorting (#sortSelect) #

Use the sort dropdown to arrange downloads according to your preferences:

• ⇅ Date Added (Default): Places the most recently added downloads at the top.
• ⇅ Name (A-Z): Alphabetical sort by file name.
• ⇅ Size (Largest): Sorts by total file size, placing largest files first.
• ⇅ Status: Groups tasks by current state (Downloading, Completed, Paused).

SurgeDL User Guide — Chapter 12: Browser Integration #

SurgeDL integrates directly with your favorite web browsers to automatically capture file downloads and inject an on-screen video grabber onto web video players.

This chapter details supported browsers, the Manifest V3 native messaging architecture, installation and configuration steps, and safety bypass rules.

12.1 Supported Browsers #

SurgeDL provides native browser extension packages for all major Chromium and Gecko web browsers:

• Google Chrome: Version 88 or later (Manifest V3).
• Microsoft Edge: Version 88 or later.
• Mozilla Firefox: Version 109 or later (Gecko MV3).
• Brave Browser: All current releases.
• Opera & Vivaldi: Supported via standard Chromium native messaging host registration.

12.2 Integration Architecture & Native Messaging #

Unlike legacy download managers that rely on fragile HTTP polling, SurgeDL utilizes the official Chrome and Mozilla Native Messaging API:

[Web Browser]
  └── SurgeDL Integration Module (MV3 Extension)
        ├── Intercepts clicks on downloadable extensions (.zip, .exe, .iso, etc.)
        ├── Injects on-screen Video Grabber button onto HTML5 video players
        └── Communicates via Standard I/O (StdIO)
              ↓
[SurgeDL Native Messaging Host] (`native-host.cjs` / `native-host.bat`)
  └── 4-Byte Little-Endian Length Header Protocol (Zero network latency)
        ↓
[SurgeDL Background Engine Daemon] (Port 3000 Loopback)
  └── Multi-Part Range Acceleration Core & Dynamic Work-Stealing

Benefits of the Native Messaging Architecture: #

1. Instantaneous Handoff: Downloads are transferred to SurgeDL in under 5 milliseconds via operating system standard input/output streams.
2. Offline Resilience: If the SurgeDL user interface is closed, the native host automatically spawns the background engine daemon to handle the download seamlessly.
3. Session Credential Preservation: The extension securely extracts session cookies, referer URLs, and user-agent strings, passing them directly to SurgeDL so protected downloads never fail with 403 Forbidden errors.

12.3 Installing and Enabling the Extension #

12.3.1 Automatic Installation via the Desktop Installer #

When you install SurgeDL on Windows using SurgeDL Setup 2.3.0.exe or register the application on macOS, SurgeDL automatically registers the native messaging host manifests in your system registry and user profile:

• Windows Registry:

HKCU\Software\Google\Chrome\NativeMessagingHosts\com.bizmolabs.surgedl

HKCU\Software\Microsoft\Edge\NativeMessagingHosts\com.bizmolabs.surgedl

HKCU\Software\Mozilla\NativeMessagingHosts\com.bizmolabs.surgedl

• macOS Application Support:

~/Library/Application Support/Google/Chrome/NativeMessagingHosts/com.bizmolabs.surgedl.json

~/Library/Application Support/Mozilla/NativeMessagingHosts/com.bizmolabs.surgedl.json

12.3.2 Loading the Extension in Your Browser #

Until published directly to the Chrome Web Store and Firefox Add-ons repository, load the extension module locally:

1. For Chrome, Edge, and Brave:

• Open your browser and navigate to:
• Chrome: chrome://extensions
• Edge: edge://extensions
• Brave: brave://extensions
• Enable the Developer mode toggle in the top-right corner.
• Click Load unpacked.
• Browse to the extension folder inside your SurgeDL directory (e.g., %LOCALAPPDATA%\Programs\surgedl\extension on Windows, or the extension directory in the application bundle).
• Click Select Folder. The SurgeDL Integration Module icon will appear in your browser toolbar.

1. For Mozilla Firefox:

• Open Firefox and navigate to about:debugging#/runtime/this-firefox.
• Click Load Temporary Add-on....
• Select manifest.json located inside the SurgeDL extension directory.

12.4 How Downloads Are Captured #

Once enabled, SurgeDL seamlessly handles web file transfers:

1. Direct Link Clicks: When you click a link pointing to any extension listed in your File Types settings (e.g., .zip, .rar, .exe, .iso, .mp4, .pdf), the SurgeDL extension intercepts the web request before the browser starts downloading.
2. Browser Download Cancellation: The extension cancels the browser's slow, single-threaded download to avoid saving duplicate files.
3. Automatic Handoff: The extension passes the URL, cookies, and referer headers to SurgeDL, which immediately launches the Floating Download Dialog and engages multi-threaded acceleration.

12.5 The Floating Web Video Grabber #

When browsing websites with embedded video players (such as open media platforms or news portals), SurgeDL injects a floating Download Video panel onto the video player:

[SCREENSHOT S10 — Floating Video Grabber on Web Player]

Caption: The floating video grabber injected above an HTML5 web player with quality resolution options.

• Hover your mouse over any active video player.
• A semi-transparent ⚡ Download this video badge appears in the top-right corner of the player.
• Click the badge to reveal available stream resolutions (e.g., 1080p Full HD, 720p HD, 480p, or Audio MP3).
• Clicking your preferred quality sends the video directly to SurgeDL, losslessly multiplexing video and audio tracks with FFmpeg.

12.6 Automatic Banking & Sensitive Site Bypass #

To protect user security and prevent financial transaction errors, SurgeDL contains an automated Banking & Security Bypass Rule:

• The Problem: Many online banking portals generate dynamic, one-time security tokens for PDF transaction receipts, account statements, and tax forms. If a download manager attempts to open separate parallel connections using these links, the bank's security system terminates the user's session or flags the account.
• SurgeDL's Solution: SurgeDL automatically detects banking and government domains (e.g., banking portals, .gov sites, and dynamic receipt routes). When a download originates from one of these domains, SurgeDL automatically steps aside, allowing your web browser to handle the download natively without interruption.

12.7 Temporarily Bypassing SurgeDL #

If you want your web browser to handle a specific download rather than SurgeDL:

1. Keyboard Bypass: Hold down the Alt key while clicking any download link. SurgeDL will ignore the click and allow your browser's native download bar to proceed.
2. Extension Popup Toggle:

• Click the SurgeDL icon in your browser toolbar.
• Toggle the Capture Downloads switch to OFF.
• Turn it back ON when you are ready to resume accelerated downloads.

1. Site Ignore List: If you want SurgeDL to permanently ignore a specific website, open ⚙️ Options ➔ File Types in SurgeDL, and add the domain (e.g., company-intranet.local) to the Do not capture downloads from the following sites list.

12.8 Troubleshooting Browser Integration #

SurgeDL User Guide — Chapters 13 & 14: Video & BitTorrent Engines #

13. Web Video & Stream Downloads #

SurgeDL features an integrated media stream resolver powered by an optimized, bundled build of the industry-standard yt-dlp engine paired with FFmpeg. This subsystem automatically navigates streaming protocols, fragmented media manifests, and strict platform throttling.

13.1 Supported Video Platforms & Media Types #

SurgeDL reliably downloads video and audio streams from leading public media platforms:

• Video & Audio Platforms: Supported public web video portals, online talks, educational lectures, and open media feeds.
• Web Clips & Media Feeds: Public web media clips, podcast audio streams, and user-authorized broadcasts.
• Audio Services: Public audio streams and web podcasts.
• Streaming Manifests: Direct HTTP Live Streaming (.m3u8 HLS playlists) and multi-part media segments.

13.2 Adaptive Stream Chunking & Connection Resilience #

Modern streaming platforms employ aggressive rate-limiting mechanisms that can cause third-party downloads to fail with HTTP 403 Forbidden or drop in transfer speed.

SurgeDL maintains high streaming reliability through specialized connection handling:

Network Challenge                      SurgeDL Architecture Solution
───────────────────────────────────    ─────────────────────────────────────────────────
Expiring CDN Tokens (Connection Drops) 10 MB Chunking (--http-chunk-size 10M) with automatic retries
Standard Client Identification         Modern Web Browser Identity Profiles
Dynamic Stream Signature Parsing       Internal Runtime Parsing Engine
Session Header Management              Automatic Header Hygiene & Clean Sanitization
Split Video + Audio Manifests          Automatic FFmpeg Lossless Multiplexing

1. Dynamic Manifest Parsing: When media providers update streaming manifest specifications, SurgeDL executes dynamic runtime parsing to resolve stream addresses seamlessly.
2. Header Hygiene: For security and reliability, SurgeDL automatically sanitizes browser tracking parameters when fetching raw media fragments to avoid session conflicts.
3. URL Normalization: If you paste complex media share links with tracking query parameters, SurgeDL automatically cleans and canonicalizes the URL into a standardized direct media address.

13.3 Starting a Video Download & Quality Options #

To download a streaming video:

1. Copy the web link of any supported video.
2. Click ➕ Add Download (or click Download Video on the floating clipboard notification).
3. If SurgeDL identifies the link as a media platform, it displays quality format choices:

• Highest Available (Up to 4K / 2160p): Downloads the highest available stream resolution provided by the host.
• 1440p (2K Quad HD): Optimal for high-resolution monitors.
• 1080p (Full HD): Industry standard high-definition video.
• 720p (HD): Balanced resolution with smaller file size.
• 480p / 360p (Mobile): Minimal bandwidth consumption.
• Extract Audio (320kbps MP3): Discards the video track and produces a studio-quality 320kbps MP3 file.

1. Metadata & Thumbnail Embedding: SurgeDL automatically embeds the original video title, uploader name, creation date, and cover thumbnail image directly into the file's ID3 or MP4 metadata tags.

14. BitTorrent Swarm Engine #

SurgeDL includes a built-in BitTorrent client powered by WebTorrent, enabling high-speed peer-to-peer file transfers and on-demand sequential video streaming.

14.1 Adding Torrents & Magnet Links #

SurgeDL supports both .torrent metadata files and magnet: URI links:

[SCREENSHOT S11 — Add BitTorrent Swarm Modal]

Caption: The BitTorrent Swarm modal with drag-and-drop file zone, magnet URI textarea, and legal test swarm presets.

1. Via Drag and Drop: Drag any .torrent file into the SurgeDL window. The drop overlay will appear, immediately loading the torrent.
2. Via the Swarm Toolbar Button: Click 🧲 Swarm on the top toolbar.

• Drop Zone: Drag a .torrent file or click 📂 Browse to locate the file on your computer.
• Magnet Link Input: Paste any magnet:?xt=urn:btih:... link into the text box.
• Legal Test Swarms: Click 🎬 Sintel 1080p or 🐰 Big Buck Bunny to test your peer connectivity using open-source, Creative Commons media.

1. Click Add to Swarm. SurgeDL immediately registers the info-hash and initiates peer discovery across global DHT networks and public tracker swarms.

Pre-Configured High-Performance Trackers: #

SurgeDL automatically announces to top global BitTorrent trackers for maximum peer availability:

• udp://tracker.opentrackr.org:1337/announce
• udp://tracker.openbittorrent.com:6969/announce
• udp://open.stealth.si:80/announce
• udp://tracker.torrent.eu.org:451/announce
• udp://explodie.org:6969/announce

14.2 Live Swarm Telemetry & Piece Maps #

When you select a torrent download, the Inspector Panel and Floating Download Dialog display detailed peer metrics:

+---------------------------------------------------------------------------------+
|  Torrent Swarm Telemetry:                                                       |
|  Seeds: 48 (Active)  |  Leechers: 12  |  Peers: 60  |  Share Ratio: 1.42        |
|  Pieces: 840 / 1200 Completed (70%)                                            |
|  [████████████████████████████████░░░░░░░░░░░░░░] Piece Availability Heatmap    |
+---------------------------------------------------------------------------------+

[SCREENSHOT S12 — Torrent Swarm Inspector with Peers and Piece Map]

Caption: The Torrent Inspector displaying live seed counts, connected peer IP addresses, client software, and piece availability.

• Seeds & Leechers: Differentiates between complete seeders (100% file holders) and active leechers downloading along with you.
• Share Ratio: Displays your upload-to-download ratio (uploadedBytes / downloadedBytes).
• Peers Tab (#inspTabPeers): Lists remote peer IP addresses, client software (e.g., qBittorrent, Transmission, libtorrent), and real-time upload/download speeds.
• Files Tab (#inspTabFiles): For multi-file torrents, lists every individual file with its respective progress bar.

14.3 Sequential Video Streaming (Watch While Downloading) #

Standard torrent clients download file pieces in random order to maximize swarm availability. However, this prevents you from opening video files until the transfer reaches 100%.

SurgeDL solves this with an integrated Sequential HTTP Range Streaming Bridge:

[BitTorrent Swarm] ──▶ [SurgeDL WebTorrent Client]
                             ↓
              [Sequential Piece Prioritizer]
              (Requests Bytes 0-5MB first, then streams sequentially)
                             ↓
              [Internal HTTP Range Server] (`/api/torrent/:id/stream`)
                             ↓
              [Built-in HTML5 Video Player] (Plays immediately!)

[SCREENSHOT S13 — Live Torrent Video Player Modal]

Caption: The Sequential Torrent Player streaming 1080p video with range seeking while the swarm continues downloading.

How to Stream a Torrent Video: #

1. Add any torrent containing a video file (.mp4, .mkv, .webm, .avi, or .mov).
2. Once the download reaches 1% to 2% (sufficient to buffer the media container header), click the ▶ Stream Video button in the floating dialog or context menu.
3. The Live Media Stream player modal opens.
4. The video starts playing immediately in full high definition with full audio.
5. Seeking Support: You can jump forward or backward on the video timeline; SurgeDL's sequential prioritizer will immediately adjust piece requests to buffer the requested time position.

SurgeDL User Guide — Chapter 8: Studio Media Processor & Tools #

SurgeDL includes a built-in Studio Media Processor & Converter powered by bundled FFmpeg binaries and automated GPU hardware acceleration detection.

Rather than requiring separate third-party video converters or audio transcoders, SurgeDL allows you to remux containers, compress video for messaging apps, trim clips, extract high-bitrate audio, and create animated GIFs directly from your download list.

+-------------------------------------------------------------------------------+
| 🎬 Studio Media Processor & Converter        [⚡ GPU HW Acceleration Active]  |
+-------------------------------------------------------------------------------+
| Select Media File: [ Big_Buck_Bunny_1080p.mkv                             ▾ ]|
| ℹ️ Duration: 00:09:56 | Resolution: 1920x1080 | Video: h264 | Audio: aac       |
|                                                                               |
| Processing Action / Mode:                                                     |
| [ 🚀 Instant Lossless Remux (MKV ↔ MP4 ↔ WebM in 1-2s, 0% Loss)           ▾ ]|
|                                                                               |
| Container Options:                                                            |
| Target Container: [ MP4 (.mp4) — Maximum device & web compatibility       ▾ ]|
| 💡 Stream-copy mode: Copies packets directly without re-encoding. 100% loss-free|
|                                                                               |
|                                                     [Close] [⚡ Start Conversion]|
+-------------------------------------------------------------------------------+

[SCREENSHOT S14 — Studio Media Processor Modal]

Caption: The Studio Media Processor modal showing selected video metadata, GPU acceleration status badge, and mode selection.

8.1 How to Access the Media Tools #

You can open the Studio Media Processor through two convenient methods:

1. Toolbar Button: Click 🎬 Converter in the top titlebar.
2. Context Menu: In the main download table, right-click any completed media file and select 🎬 Media Tools & Converter... (or select 🎵 Extract Audio (320k MP3) for one-click audio extraction).

When opened, SurgeDL queries the target file using FFmpeg probe instruments, displaying the file's duration, resolution, video codec, audio codec, and subtitle tracks.

8.2 GPU Hardware Acceleration Auto-Detection #

SurgeDL automatically detects and engages available graphics processing unit (GPU) hardware encoders:

• NVIDIA NVENC (h264_nvenc): High-speed encoding on GeForce and Quadro GPUs with custom p4 preset tuning.
• Intel QuickSync (h264_qsv): Hardware encoding on Intel Core processors with integrated graphics.
• Apple VideoToolbox (h264_videotoolbox): Native hardware acceleration on Apple Silicon (M1/M2/M3/M4) and Intel Macs.
• AMD AMF (h264_amf): Hardware encoding on AMD Radeon graphics cards.
• CPU Fallback (libx264): High-efficiency software encoding if no supported GPU encoder is present.

The ⚡ GPU HW Acceleration Active badge at the top of the dialog confirms when hardware acceleration is active.

8.3 The 7 Media Processing Modes #

Mode 1: Instant Lossless Remux (remux) #

• Purpose: Converts video container formats without re-encoding video or audio data.
• Supported Containers: MP4 (.mp4), MKV (.mkv), WebM (.webm), MOV (.mov), AVI (.avi), TS (.ts).
• Execution Speed: 1 to 2 seconds for a full movie or episode.
• Quality Loss: 0% (Bit-Perfect). Because video and audio packets are copied directly (-c copy), there is zero compression artifacting, zero generation loss, and zero CPU overheating.

Mode 2: Multi-Format Audio Extractor (extractAudio) #

• Purpose: Strips video tracks to produce standalone music tracks or speech recordings.
• Supported Audio Formats:
• MP3 (Studio Master): True 320 kbps Constant Bitrate (CBR) encoded with libmp3lame and ID3v2.3 tagging.
• M4A / AAC: Native Apple-compatible audio at 256 kbps.
• FLAC: Bit-perfect lossless Free Audio Codec.
• WAV: Uncompressed studio 16-bit PCM audio.
• Opus: Ultra-high-efficiency audio at 64 kbps (ideal for podcasts and voice notes).

Mode 3: Discord & WhatsApp Smart Compressor (compress) #

• Purpose: Compresses large videos to fit exactly within messaging platform upload limits.
• Presets:
• 25 MB: Standard upload limit for Discord Free users.
• 50 MB: WhatsApp, Telegram, and Discord Nitro Basic upload limit.
• 10 MB: Email attachments and web forums.
• Custom MB: Specify any target file size in megabytes.
• How It Works: SurgeDL uses two-pass bitrate mathematics:

$$\text{Target Bitrate} = \frac{\text{Target Size (MB)} \times 8 \times 1024 \times 1024}{\text{Duration (seconds)}} - 128\text{ kbps audio}$$

It then encodes the video using your detected GPU accelerator with strict peak bitrate buffers and +faststart web streaming flags.

Mode 4: Lossless Video Trimmer (trim) #

• Purpose: Cuts out unwanted introductions, credits, or commercial breaks without re-encoding.
• How to Use:

1. Enter the Start Time (e.g., 00:01:30 or 90).
2. Enter the End Time (e.g., 00:04:15 or 255).
3. Click ⚡ Start Conversion.

• Result: Extracts the exact video segment in seconds while retaining original quality.

Mode 5: High-FPS Animated GIF Maker (gif) #

• Purpose: Converts short video highlights into smooth, vibrant animated GIFs.
• Two-Pass Quality Engine: Uses FFmpeg's palettegen and paletteuse filters with Lanczos scaling, eliminating the grainy color banding typical of basic converters.
• Customization:
• Start Time: Timestamp to begin the clip.
• Duration: Length of the animation in seconds (default: 5s).
• Width: Pixel width (default: 480px).
• Frame Rate (FPS): Choose between 5 and 30 FPS for silky-smooth motion.

Mode 6: Lossless Subtitle Extraction (subtitles) #

• Purpose: Extracts embedded subtitle tracks from MKV or MP4 movies.
• Formats: Outputs clean SubRip (.srt) or WebVTT (.vtt) subtitle files that can be loaded into external media players or translated.

Mode 7: Universal Transcode (transcode) #

• Purpose: Re-encodes unusual or legacy video formats into standardized, web-ready H.264 / AAC MP4 files.
• Features: Incorporates faststart metadata placement, enabling instant playback buffering on web players and mobile devices.

8.4 Automatic Library Registration #

When any conversion, compression, or audio extraction completes:

1. The new file is saved directly into the same directory as the source media (or your default downloads folder) with an informative suffix (e.g., _audio.mp3, _compressed_25MB.mp4, or _clip.gif).
2. SurgeDL automatically registers the new file in your Completed Downloads table under its appropriate category (Music, Video, or Documents), allowing you to immediately play it, copy its path, or reveal it in Finder or Explorer.

SurgeDL User Guide — Chapters 15 & 16: Queues, Scheduling, Speed & Power #

15. Download Queues and Scheduling #

SurgeDL includes an intelligent queue manager and an automated off-peak scheduler designed to respect bandwidth limits, manage concurrent transfers, and take advantage of unmetered overnight ISP windows.

15.1 Queue Concurrency & Priority Rules #

SurgeDL manages active downloads using an automated slot allocation queue:

• Configurable Concurrency Slider (1 to 10 Simultaneous Downloads): You can precisely dictate how many files download concurrently by adjusting the concurrency slider in Options ➔ Downloads (default is 3). Set to 1 for pure sequential downloads (ideal for slow connections or limited disk IOPS), or up to 10 for high-bandwidth fiber setups.
• Queued State: If your concurrency is set to 3 and you add 10 files, the first 3 will transition to DOWNLOADING, while the remaining 7 will wait in the QUEUED state.
• Automatic Progression: The moment any download reaches 100% completion (or is paused), the queue manager immediately activates the next queued item in sequence.
• Priority Escalation: Tasks marked with High priority bypass lower-priority items when an active download slot becomes vacant.

15.2 Multiple Named Queues Manager #

SurgeDL provides a robust multi-queue architecture allowing you to organize, categorize, and schedule transfers into separate groups:

+-------------------------------------------------------------------------+
| 📂 Create Download Queue                                             ✕  |
+-------------------------------------------------------------------------+
| Queue Name:                                                             |
| [ Night Queue - Large ISOs                                            ] |
|                                                                         |
| Maximum Concurrent Downloads for This Queue:                            |
| [ 2 Simultaneous Downloads                                          ▾ ] |
|                                                                         |
|                                            [Cancel]     [Create Queue]  |
+-------------------------------------------------------------------------+

Key Capabilities: #

1. Default Download Queue: The primary queue created out of the box for standard downloads.
2. Creating Custom Queues: Click + New Queue in the sidebar navigation or select from ≡ Menu ➔ Queue & Controls to create queues like "Work Files", "Movies & Shows", or "Overnight ISOs".
3. Independent Queue Control: Each queue features its own ▶ Start Queue and ⏸ Pause Queue buttons in the sidebar, allowing you to pause or resume an entire set of downloads with one click.
4. Moving Tasks Between Queues: Right-click any download in the table and choose 📂 Move to Queue... to reassign it instantly.
5. Queue Deletion: Right-clicking any custom queue allows you to delete it; SurgeDL offers to move any contained downloads back to the Default Queue safely.

15.3 The Off-Peak Download Scheduler #

Many ISPs offer unmetered or higher-speed internet during overnight off-peak hours (e.g., between 2:00 AM and 6:00 AM). SurgeDL's built-in scheduler automates this entire workflow:

+-------------------------------------------------------------------------+
| ⏰ Off-Peak Download Scheduler                         [Active Window]  |
+-------------------------------------------------------------------------+
| [x] Enable Time-of-Day Bandwidth Scheduling                             |
| SurgeDL will start queued downloads during your active window and pause  |
| them outside the window.                                                |
|                                                                         |
| Start Downloading At:                  Stop / Pause At:                 |
| [ 02:00                              ] [ 06:00                        ] |
|                                                                         |
| Action When All Scheduled Tasks Finish:                                 |
| [ Turn Off / Shutdown PC (with 30s countdown)                         ▾ ]|
|                                                                         |
|                                            [Cancel]     [Save Schedule] |
+-------------------------------------------------------------------------+

[SCREENSHOT S15 — Download Scheduler Modal]

The Off-Peak Scheduler modal configuring start/stop times and post-completion power actions.

How to Configure the Scheduler: #

1. Click ⏰ Scheduler in the Global UniMenu (≡ Menu ➔ Queue & Controls ➔ Off-Peak Scheduler...).
2. Check the box labeled Enable Time-of-Day Bandwidth Scheduling.
3. Start Downloading At: Set your off-peak start time (e.g., 02:00).
4. Stop / Pause At: Set your off-peak end time (e.g., 06:00).

• Overnight Windows Supported: The scheduler natively supports overnight time spans that cross midnight (e.g., 23:00 to 07:00).

1. Action When All Scheduled Tasks Finish: Select what SurgeDL should do when the queue is completed:

• Do Nothing (Stay Idle): Leave your computer running.
• Pause All Remaining Tasks: Ensure all downloads stop.
• Put PC into Sleep Mode: Suspend the computer to save electricity.
• Turn Off / Shutdown PC: Completely shut down the computer.

1. Click Save Schedule.

Automated Scheduler Behavior: #

• A background ticker checks the time every 5 seconds.
• When your clock enters the scheduled window, SurgeDL automatically wakes and resumes all queued downloads.
• When your clock reaches the stop time, SurgeDL cleanly pauses all running downloads, saves checkpoints, and releases network sockets until the next scheduled window.

16. Speed and Power Management #

SurgeDL gives you precise control over your internet bandwidth consumption and computer power state.

16.1 Global and Per-Task Bandwidth Throttling #

If you need to share your internet connection with other household members, stream movies, or play online games while downloading, you can throttle SurgeDL's bandwidth globally or on a per-task basis:

[SCREENSHOT S16 — Speed Limiter Dropdown Menu]

The Speed Limiter menu showing presets (Unlimited, 512 KB/s, 1 MB/s, 2 MB/s, 5 MB/s, Custom).

1. Global Speed Presets: #

• Unlimited (MAX): Default setting. Maximizes throughput to the full capacity of your connection.
• 512 KB/s (Eco): Minimal bandwidth usage.
• 1.0 MB/s (Normal): Allows smooth web browsing and standard HD video streaming on other devices.
• 2.0 MB/s (Fast): Moderate throttling.
• 5.0 MB/s (Turbo): High-speed throttling.
• Custom... (KB/s): Enter an exact numeric limit (e.g., enter 3500 for 3.5 MB/s).

2. Per-Task Speed Limits: #

• Right-click any active download task in the table and choose ⚡ Set Speed Limit...
• Specify an individual ceiling in KB/s (e.g., 250 for 250 KB/s).
• The task will be capped at that exact throughput without restricting other downloads or the global pool.

Dual-Engine Throttling: #

When you apply a speed limit, SurgeDL throttles both:

1. Multi-part HTTP range downloads via the token-bucket bandwidth limiter.
2. Active BitTorrent swarms via WebTorrent's internal client rate limiter.

16.2 Automated Sleep & Shutdown on Queue Completion #

SurgeDL allows you to leave large downloads running overnight without wasting electricity once they finish.

Quick Power Selector: #

On the right side of the main titlebar, click the ⚡ Done: selector to choose:

• ⚡ Done: Stay Idle (Default): Leaves your PC running normally.
• ⚡ Done: Sleep PC: Puts your computer into Sleep mode when the queue is done.
• ⚡ Done: Shut Down: Shuts down your computer completely when the queue is done.

The 30-Second Abort Countdown Modal: #

To prevent accidental shutdowns if you are still working at your computer, SurgeDL displays a prominent safety countdown modal when the last download finishes:

+-----------------------------------------------------+
|                         ⚡                          |
|             Download Queue Completed                |
|                                                     |
|             Putting PC to SLEEP in:                 |
|                                                     |
|                       24s                           |
|                                                     |
|              [ 🛑 Cancel & Abort ]                  |
+-----------------------------------------------------+

[SCREENSHOT S17 — Power Countdown Abort Modal]

The 30-second power countdown modal with prominent Cancel & Abort button.

• Audible Alert: SurgeDL chimes and starts a visible 30-second countdown.
• 1-Click Abort: Click 🛑 Cancel & Abort to cancel the power action immediately and keep your computer running.
• Activity Sensor: If a new download is added or started while the countdown is active, SurgeDL automatically aborts the countdown immediately.
• System Commands Executed:
• Windows Sleep: rundll32.exe powrprof.dll,SetSuspendState 0,1,0
• Windows Shutdown: shutdown /s /t 0
• macOS Sleep: pmset sleepnow
• macOS Shutdown: AppleScript tell app "System Events" to shut down

16.3 OS Sleep Prevention During Active Downloads #

Operating systems routinely put computers to sleep after 15 to 30 minutes of user inactivity. If your computer sleeps while downloading, connections drop and transfers halt.

SurgeDL actively prevents this:

• Whenever any download is actively receiving data (DOWNLOADING) or muxing video (MUXING), SurgeDL engages the Electron PowerSaveBlocker subsystem (prevent-app-suspension).
• Your operating system will keep the CPU and network interfaces fully powered until the queue is finished.
• The moment all downloads finish or are paused, SurgeDL immediately releases the power blocker, allowing your computer's normal power-saving schedule to resume.

SurgeDL User Guide — Chapter 17: Configuration & Settings Reference #

SurgeDL provides a centralized Configuration & Options dialog accessed by clicking ≡ Menu ➔ Settings ➔ Options & Preferences... (or pressing Ctrl+, on Windows / Cmd+, on macOS).

This chapter serves as an exhaustive reference dictionary for every user-facing setting, its verified default value, operational consequences, and recommended configurations across all seven configuration tabs.

+---------------------------------------------------------------------------------------------------+
| ⚙️ Configuration & Options                                                                     ✕  |
+---------------------------------------------------------------------------------------------------+
| [ General ] [ Downloads ] [ Save To ] [ File Types ] [ Site Logins ] [ Proxy ] [ Antivirus ]      |
|                                                                                                   |
| [ ] Launch SurgeDL on system startup                                                              |
| [ ] Automatically capture download links copied to clipboard                                      |
| [x] Show system notification banners when downloads finish                                       |
| [x] Play audio chimes on completion and download errors                                           |
| [ ] Show floating desktop drop target widget                                                      |
| Language: [ English (US)                                                                        ▾ ]|
|                                                                                                   |
|                                                                    [Cancel]     [Save Settings]   |
+---------------------------------------------------------------------------------------------------+

[SCREENSHOT S18 — Options Dialog with Tabs]

The Configuration & Options dialog displaying the seven primary configuration tabs: General, Downloads, Save To, File Types, Site Logins, Proxy, and Antivirus.

17.1 General Settings #

Accessed under ⚙️ Options ➔ General.

17.2 Downloads Settings #

Accessed under ⚙️ Options ➔ Downloads.

17.3 Save To Settings #

Accessed under ⚙️ Options ➔ Save To.

17.4 File Types Settings #

Accessed under ⚙️ Options ➔ File Types.

17.4.1 Automatically Capture File Extensions #

• Internal Key: fileTypes.extensions
• Default Verified Value:

3GP 7Z AAC ACE AIF APK ARJ ASF AVI BIN BZ2 DMG DOC DOCX EXE GZ GZIP ISO LZH M4A M4V MKV MOV MP3 MP4 MPA MPE MPEG MPG MSI MSU OGG OGV PDF PLJ PPS PPT PPTX QT R0 R1 RA RAR RTF SEA SIT SITX TAR TIF TIFF TAZ TBZ TGZ TS VOB WAV WEBM WMA WMV XLS XLSX Z ZIP

• Purpose: Space-separated list of file extensions that the SurgeDL browser extension will automatically intercept when clicked on any web page.
• Customization: You can add custom file extensions (e.g., add OVA or VDI for virtual machine disk images, or NSP for game archives) simply by typing the extension separated by a space.

17.4.2 Site Bypass List (Ignore Addresses) #

• Internal Key: fileTypes.ignoreAddresses
• Default Verified Value: [] (Empty)
• Purpose: A list of web domains or URL patterns that SurgeDL should never intercept.
• Format: Enter one domain pattern per line (e.g., internal-bank.com, *.mycompany.corp, intranet.local).
• Effect: When clicking download links on any listed domain, SurgeDL remains completely dormant, allowing your web browser to download the file natively.

17.5 Site Logins Settings (Basic Auth Vault) #

Accessed under ⚙️ Options ➔ Site Logins.

SurgeDL includes an integrated credential vault for sites requiring HTTP Basic Authentication:

• How It Works: When SurgeDL initiates a download from any matching site, it automatically injects standard Authorization: Basic <base64> headers into all 16 to 32 connection sockets, allowing multi-part accelerated downloads on restricted portals without manual header pasting.

17.6 Proxy / SOCKS5 Settings #

Accessed under ⚙️ Options ➔ Proxy.

SurgeDL provides universal proxy routing support to navigate enterprise firewalls, geoblocks, or private network gateways:

17.7 Antivirus Integration Settings #

Accessed under ⚙️ Options ➔ Antivirus.

SurgeDL provides automated post-download malware defense by scanning downloaded files with your preferred antivirus suite the instant they reach 100% completion:

SurgeDL User Guide — Chapters 18 to 21: Notifications, Shortcuts & Platform Guides #

18. Desktop Notifications #

SurgeDL integrates with native operating system notification frameworks to keep you informed of task progress when working in other applications.

18.1 Notification Triggers #

• Download Completed: Fires when a task successfully finishes 100% of data transfer, verifies byte integrity, and publishes the final file to your hard drive:
• Title: ⚡ SurgeDL: Download Complete!
• Body: <filename> finished downloading successfully. Click to show in folder.
• Icon: SurgeDL brand icon.
• Click Action: Clicking the notification banner immediately opens Finder (macOS) or File Explorer (Windows) with the specific completed file highlighted.
• Minimized to Tray Notice: When active downloads are running and you close the main window, SurgeDL minimizes to the system tray and displays:

Minimized to system tray. Active downloads continue in background.

• Pairing Code Copy Notices: Triggered when copying the Dashboard or Extension pairing keys from the Help menu.

18.2 System Permissions #

• macOS: Ensure SurgeDL is allowed to deliver alerts under System Settings ➔ Notifications ➔ SurgeDL.
• Windows: Verify that Focus Assist or Do Not Disturb is not silencing banner notifications from SurgeDL.

19. Keyboard Shortcut Reference #

SurgeDL implements native keyboard shortcuts tailored to each operating system's standard conventions:

20. SurgeDL on macOS #

SurgeDL is designed as a first-class macOS desktop citizen, incorporating modern macOS Human Interface Guidelines.

[SCREENSHOT S20 — SurgeDL on macOS]

Caption: SurgeDL running on macOS Sonoma showing hiddenInset titlebar, traffic light positioning, and menu bar speed monitor.

20.1 Apple Silicon & Intel Universal Support #

• Apple Silicon Native: Compiled natively for ARM64 architecture, SurgeDL executes with optimal CPU and memory efficiency on M1, M2, M3, and M4 Macs.
• Intel Mac Parity: Identical functionality and stability on 64-bit Intel processors.

20.2 Window Design & Vibrancy #

• hiddenInset Titlebar: Blends the traffic light buttons directly into the top toolbar with calibrated offsets ({ x: 18, y: 18 }), providing clean vertical alignment.
• under-window Vibrancy: Translucent background blurring behind the main window that harmonizes with your macOS wallpaper.

20.3 Menu Bar Live Speed Readout #

• When downloads are active, SurgeDL displays your live cumulative transfer speed directly in the macOS Menu Bar adjacent to the menu bar icon:

⚡ 12.4 MB/s

• When idle, the text clears automatically to maintain a tidy menu bar.

20.4 Native Finder Integration #

• Completed files are revealed using macOS open -R, instantly focusing the Finder window and selecting the exact downloaded file.

21. SurgeDL on Windows #

On Windows 10 and 11, SurgeDL integrates deeply with the Windows shell, notification tray, and filesystem drivers.

[SCREENSHOT S21 — SurgeDL on Windows System Tray]

Caption: SurgeDL running on Windows 11 showing the system tray context menu, tooltip speed monitor, and Explorer file reveal.

21.1 Windows System Tray Integration #

• Tray Icon: When downloads are in progress and you close the main window, SurgeDL minimizes to the system tray notification area (near the system clock).
• Dynamic Tooltip: Hovering over the tray icon displays live queue metrics:

SurgeDL: 2 active downloads (8.4 MB/s)

• Tray Context Menu:
• ⚡ Open SurgeDL: Restores the main window to the foreground.
• 📂 Open Downloads Folder: Opens %USERPROFILE%\Downloads\SurgeDL in Explorer.
• Quit: Gracefully stops active downloads, saves checkpoints, and exits the process.

21.2 Explorer Integration #

• SurgeDL uses explorer.exe /select,"<filepath>" to open the target folder and highlight the downloaded file without requiring manual searching.

21.3 Windows FAT32 4 GB Limit Safeguard #

• The Risk: Legacy USB flash drives and external hard drives formatted with the FAT32 filesystem have an architectural limit: no individual file can exceed 4,294,967,295 bytes (4 GB - 1 byte). Attempting to download a 10 GB ISO or movie to a FAT32 drive causes unhandled filesystem crashes in generic downloaders.
• SurgeDL's Automated Probe: When a download exceeds 4 GB, SurgeDL queries the target drive's filesystem format using Windows [System.IO.DriveInfo]. If a FAT32 or FAT volume is detected, SurgeDL cleanly halts the download before wasting bandwidth, displaying a clear advisory:

File size (7.8 GB) exceeds the 4 GB single-file limit of the FAT32 filesystem on drive E:\. Please choose an NTFS or exFAT drive to download this file.

SurgeDL User Guide — Chapters 22 to 24: Recovery, Troubleshooting & FAQ #

22. Interrupted Download Recovery #

Network dropouts, power outages, and server disconnects are facts of life. SurgeDL is engineered from the ground up to protect your time and bandwidth when unexpected interruptions occur.

22.1 What SurgeDL Can and Cannot Recover #

Scenario                                Can SurgeDL Recover?   Recovery Action
────────────────────────────────────    ────────────────────   ─────────────────────────────────────────────
Wi-Fi drops or internet disconnects     ✅ 100% Recoverable    Click ▶ Resume once connectivity returns.
Computer goes to sleep or restarts      ✅ 100% Recoverable    Relaunch SurgeDL; click ▶ Resume.
SurgeDL application abruptly closed     ✅ 100% Recoverable    Progress preserved in .surgedl.json checkpoint.
Temporary server 502/503/504 errors     ✅ 100% Recoverable    SurgeDL retries automatically or click ▶ Resume.
Server returns HTML login page          ⚠️ Re-auth Required    Send fresh URL from browser with session cookies.
Expiring CDN tokens (e.g. 1-hr links)   ⚠️ Re-auth Required    Copy fresh link from source and update URL.
Server does NOT support byte ranges     ❌ Non-Recoverable     Server forces restart from byte 0.
Remote file modified on server          ❌ Non-Recoverable     ETag mismatch; requires clean re-download.

22.2 Detailed Interruption Scenarios #

Scenario 1: Wi-Fi Disconnects or Router Restarts #

• What Happens: When your connection drops, active worker threads stop receiving data. If no packets arrive within 30 seconds (timeoutMs = 30000), the connection aborts.
• Data State: The .part file on disk contains all complete segments, and the .surgedl.json file contains exact byte offsets.
• How to Recover: Once your Wi-Fi reconnects, select the task and click ▶ Resume. SurgeDL probes the server with If-Range validators and resumes downloading without loss.

Scenario 2: Computer Restarts or Loses Power #

• What Happens: If your computer shuts down unexpectedly, partial transfers are preserved.
• Data State: Upon relaunching SurgeDL, the database loads all previous tasks. Any transfer that was interrupted transitions to the PAUSED state.
• How to Recover: Highlight the paused download and click ▶ Resume.

Scenario 3: Expired Session URLs & HTML Login Pages #

• The Problem: Many file hosting sites generate temporary URLs that expire after an hour. If a download pauses and you attempt to resume it hours later, the remote host serves an HTML error page ("Link Expired" or "Sign In to Continue") instead of the actual file.
• SurgeDL's Smart Payload Inspector: Unlike basic download managers that blindly append HTML error text to your .part file (permanently corrupting your movie or archive), SurgeDL actively inspects incoming bytes. If an HTML or XML login response is detected on a binary download, SurgeDL halts immediately, protects your existing .part bytes, and displays:

Session expired or authentication required: server returned an HTML webpage instead of the requested file.

• How to Recover: Return to your browser, refresh the page to generate a fresh download link, and paste it into SurgeDL.

Scenario 4: Servers Lacking Range Support #

• If a server returns HTTP 200 OK instead of HTTP 206 Partial Content in response to byte range requests, the server does not support segmented downloading. If interrupted, the server will not accept range resumption and will force the download to restart from byte 0.

23. Troubleshooting Guide #

Practical solutions for common questions and operational issues.

23.1 Application Launch & Display Issues #

Issue: SurgeDL Won't Open #

• Possible Causes:

1. A secondary instance is already running in the background or minimized to the system tray.
2. Port 3000 is occupied by another local development server.

• Solutions:
• Check your system tray (Windows) or menu bar (macOS) for the SurgeDL lightning bolt icon. Double-click it to bring the interface to the foreground.
• On Windows, press Ctrl + Shift + Esc to open Task Manager, locate any lingering SurgeDL.exe background processes, and click End Task. Then relaunch the app.

23.2 Download Transfer Issues #

Issue: Download Won't Start or Immediately Shows "ERROR" #

• Possible Causes:

1. The URL has expired, is malformed, or requires user login.
2. Target drive has insufficient free disk space.
3. Destination file path is invalid or points to a protected system folder.

• Solutions:
• Open the link in your web browser to verify that the file is publicly accessible.
• Check the Macintosh HD / Drive card in SurgeDL's sidebar to ensure your drive has sufficient free space.
• If the file is on a private forum, open ➕ Add Download, expand Authenticated downloads, and paste your session cookie.

Issue: Download Speed is Slower Than Expected #

• Possible Causes:

1. Global speed limiter is enabled.
2. The hosting server enforces per-IP bandwidth throttling.
3. Single-connection server (does not support multi-part ranges).

• Solutions:
• Click the speed pill (⚡ ... ▾) on the top toolbar and select Unlimited (MAX).
• In the download row, check the Engine column: if it reads Single, the server does not support parallel range acceleration.
• Try increasing connections from 8 to 16 or 24 in the Add Download dialog.

Issue: Download Pauses and Fails Near 99% #

• Possible Causes:

1. For video streams, the final phase involves FFmpeg multiplexing. If your computer's CPU is heavily loaded, muxing may take 10–30 seconds.
2. Antivirus scanner is locking the .part file while running a heuristic scan.

• Solutions:
• Wait 30 seconds; the status will display MUXING while FFmpeg losslessly combines audio and video tracks.
• If the file is a massive ISO, whitelist the Downloads/SurgeDL directory in your antivirus software to prevent scan contention.

23.3 Browser & Video Issues #

Issue: Browser Integration Isn't Capturing Downloads #

• Possible Causes:

1. The SurgeDL browser extension is disabled or missing native messaging permissions.
2. The file extension is not listed in SurgeDL's capture settings.

• Solutions:
• Navigate to your browser's extensions page (chrome://extensions or about:addons) and ensure the SurgeDL Integration Module is active.
• Open ⚙️ Options ➔ File Types in SurgeDL and ensure your target file extension (e.g., ZIP, EXE, MP4) is present.
• On Windows, open a command prompt in the SurgeDL directory and run:

node scripts/register-native-host.cjs

Issue: "Insufficient Disk Space" Error #

• Cause: SurgeDL pre-allocates total file space before downloading to eliminate fragmentation. If your target volume does not have enough free space for the complete file, SurgeDL halts before transferring data.
• Solution: Free up space on the drive or select a different drive volume with adequate capacity in the Save As dialog.

24. Frequently Asked Questions (FAQ) #

General Questions #

What is SurgeDL? #

SurgeDL is a high-speed commercial download manager and acceleration engine for macOS and Windows. It features multi-part HTTP range downloading (up to 32 parallel connections), dynamic work-stealing, a BitTorrent swarm engine with video streaming, an automated universal web stream resolver, and a built-in Studio Media Processor.

Does SurgeDL work on macOS and Windows? #

Yes. SurgeDL is fully supported on macOS (Apple Silicon M1/M2/M3/M4 and Intel x64) and Windows 10/11 (64-bit).

Does SurgeDL support Apple Silicon natively? #

Yes. SurgeDL includes native ARM64 binaries for macOS, running with full performance and optimal energy efficiency without requiring Rosetta 2 translation.

Download & Acceleration Questions #

Can SurgeDL resume interrupted downloads? #

Yes. Any download from a web server that supports standard HTTP byte ranges can be paused and resumed without loss of data. SurgeDL continuously saves byte offsets to a companion .surgedl.json checkpoint file.

Can downloads resume after restarting my computer? #

Yes. When you restart your computer and launch SurgeDL, previous incomplete tasks will appear in the PAUSED state. Simply click ▶ Resume to continue from the exact byte where the transfer stopped.

Where are downloaded files stored? #

By default, files are saved in your user profile under Downloads/SurgeDL/. Files are automatically sorted into subfolders: Video, Compressed, Programs, Music, Documents, and Torrents. You can customize these locations under ⚙️ Options ➔ Save To.

Can I limit download speed? #

Yes. Click the ⚡ Unlimited ▾ button on the top toolbar or inside the floating download dialog to choose presets (512 KB/s, 1.0 MB/s, 2.0 MB/s, 5.0 MB/s) or specify a custom speed limit in KB/s.

How many downloads can run simultaneously? #

By default, SurgeDL processes 3 active downloads simultaneously. Additional tasks wait in the QUEUED state and activate automatically as running tasks complete.

Media, Streaming & Torrents #

Does SurgeDL support video downloads from public web media platforms? #

Yes. SurgeDL incorporates a bundled media resolver paired with FFmpeg. It resolves and downloads video streams from supported public web media platforms and direct stream links with quality options up to 4K and 1-click 320kbps MP3 audio extraction.

Does SurgeDL support BitTorrent and magnet links? #

Yes. SurgeDL features a native WebTorrent swarm engine supporting .torrent files and magnet: links with DHT peer discovery, seed/peer telemetry, piece heatmaps, and sequential video playback while downloading.

Does SurgeDL continue downloading when the main window is closed? #

Yes. If active downloads are running and you close the main window, SurgeDL minimizes to the system tray (Windows) or continues in the background (macOS). To completely terminate the application, select Quit SurgeDL from the tray or application menu.

SurgeDL User Guide — Chapters 25 to 28: Privacy, Licensing, Updates & Support #

25. Privacy and Security #

SurgeDL is designed with an uncompromising commitment to user privacy, local data ownership, and robust application security.

25.1 Local Data Storage & Credential Hygiene #

SurgeDL operates as a local-first desktop application:

• Storage Location: All application configuration, download history, and licensing files are stored locally within your private user profile directory:
• macOS: ~/.surgedl/
• Windows: %USERPROFILE%\.surgedl\ (e.g., C:\Users\<username>\.surgedl\)
• Core Data Files:
• downloads.json: Task history, file sizes, and completion states.
• settings.json: User preferences, category paths, and speed limits.
• pairing.json: Cryptographically generated pairing credentials for local communication.
• license.json: Offline license signature and trial status.

Sensitive Credential Scrubbing: #

When you download authenticated files using custom cookies or authorization tokens, SurgeDL strictly sanitizes the data before saving:

• Active session headers (cookie, authorization) are held in volatile memory only while the download worker is running.
• When tasks are serialized to downloads.json, sensitive authentication headers are automatically purged (publicTask() sanitization).
• If SurgeDL restarts, authenticated tasks prompt the user to re-authorize rather than storing plain-text login passwords on your hard drive.

25.2 Telemetry & Network Activity Analysis #

Based on code-level audit of the SurgeDL codebase:

• Zero Telemetry SDKs: SurgeDL contains no third-party tracking scripts, no Google Analytics, no telemetry beacons, and no background user profiling.
• No Account Required: You do not need to create an online cloud account, provide a phone number, or sign into external servers to use SurgeDL.
• Outbound Network Traffic: SurgeDL communicates over the internet exclusively for:

1. Direct file and media downloads initiated by the user.
2. BitTorrent swarm peer-to-peer data transfers on user-added torrents.
3. Release manifest queries to check for software updates when requested.

25.3 Local Loopback Security & Pairing Tokens #

SurgeDL's desktop interface, background engine daemon, and browser extensions communicate over local loopback (127.0.0.1:3000).

To prevent unauthorized local software or malicious web scripts from hijacking your download manager:

1. Host Header Validation: The internal server rejects any HTTP request whose Host header does not match 127.0.0.1 or localhost.
2. Cryptographic Pairing Tokens: On first launch, SurgeDL generates two 256-bit (64-character hexadecimal) cryptographically random pairing tokens in pairing.json:

• credentials.admin: Authorizes desktop dashboard commands and configuration changes.
• credentials.extension: Authorizes browser extensions to hand off download tasks.

1. Cross-Origin Protection: Cross-site web scripts running on random websites cannot query or trigger downloads inside SurgeDL.

26. 30-Day Evaluation & Commercial Licensing #

SurgeDL is distributed as a commercial software product backed by a full-featured 30-day evaluation trial.

26.1 The 30-Day Evaluation Period #

• Full Capabilities Unlocked: During your 30-day trial, 100% of SurgeDL features are fully accessible, including 32-connection multi-part acceleration, the BitTorrent swarm engine, universal web media resolving, and the Studio Media Processor.
• Days Remaining Badge: The titlebar displays your remaining evaluation days (e.g., Trial: 30 days left).
• Anti-Rollback Protection: SurgeDL includes tamper detection against computer clock rollback to ensure fair evaluation tracking.

26.2 Offline Cryptographic Key Verification #

Unlike software requiring mandatory cloud DRM that stops working when your internet drops, SurgeDL uses Offline Cryptographic Signature Verification:

• Serial Key Format: SRGDL-XXXX-XXXX-XXXX-XXXX (24 characters).
• Offline HMAC Validation: SurgeDL verifies the serial key against your registration email using an internal HMAC-SHA256 signature algorithm.
• Air-Gapped Operation: Once licensed, SurgeDL activates permanently without requiring constant internet check-ins or calling home to a license server.

26.3 How to Register Your License #

[SCREENSHOT S22 — License Registration Modal]

Caption: The License Registration modal allowing users to enter their Name, Email, and Serial Key.

1. Click 🔑 Register on the top toolbar (or click the Trial: X days left badge).
2. Enter your Full Name / Company Name.
3. Enter your Email Address (the email used during your purchase).
4. Enter your 24-character Serial Key.
5. Click Activate Now.
6. The titlebar badge immediately transitions to green: Licensed, unlocking permanent lifetime access.

27. Updating SurgeDL #

SurgeDL includes an automated update system modeled after classic commercial desktop utilities.

27.1 Software Updates #

[SCREENSHOT S23 — Update Prompt Modal]

Caption: The Update Available modal showing current vs new version numbers, release changelog, and Update Now action.

1. Manual Check: Click 🔄 Updates on the top toolbar or select Help ➔ Check for Updates....
2. Version Comparison: SurgeDL queries the official release manifest at https://surgedl.com/updates/version.json (with fallback to the official GitHub releases repository).
3. Changelog Display: If a new version is available, the update modal displays:

• Current version vs. new version.
• A categorized list of new features, bug fixes, and performance improvements.

1. SHA-256 Checksum Verification: When you click Update Now, SurgeDL downloads the installer and verifies its 64-character SHA-256 cryptographic hash against the release manifest before launching the installer, guaranteeing that executable files cannot be tampered with.

27.2 Media Resolver Engine Updates (yt-dlp) #

Streaming platforms frequently update their website code, which can temporarily disrupt stream downloads. SurgeDL allows you to update its internal media engine independently of the main application:

1. Select Help ➔ Update Media Resolver (yt-dlp)... from the top application menu.
2. SurgeDL executes a background update command (yt-dlp -U) directly within its unpacked binary directory.
3. Once updated, web media stream downloading is restored immediately without requiring a full desktop app reinstallation.

28. Uninstallation and Support #

28.1 Uninstalling SurgeDL #

Uninstalling on macOS: #

1. Quit SurgeDL if it is running (Cmd + Q).
2. Open Finder and navigate to the Applications folder.
3. Drag SurgeDL to the Trash (or right-click and select Move to Trash).
4. Empty your Trash.
5. (Optional Complete Data Purge): To delete settings, download history, and pairing keys, delete the hidden folder:

rm -rf ~/.surgedl

Uninstalling on Windows: #

1. Open Windows Settings (press Win + I).
2. Navigate to Apps ➔ Installed apps (or Apps & features).
3. Locate SurgeDL in the list, click the three dots menu (⋯), and select Uninstall.
4. The SurgeDL uninstaller will remove all application executables, binary resources, start menu shortcuts, desktop icons, and browser native messaging registry keys.
5. (Optional Complete Data Purge): Delete %USERPROFILE%\.surgedl to remove historical queue records and custom settings.

28.2 Getting Support #

If you encounter technical difficulties or wish to report an unexpected behavior:

1. Official Support Portal: Visit bizmolabs.com or surgedl.com.
2. What Information to Include:

• SurgeDL Version: Found in the lower-left footer (e.g., v2.3.0).
• Operating System & Architecture: E.g., Windows 11 64-bit, or macOS Sonoma 14.5 Apple Silicon (M2).
• Exact Error Message: Copy the text displayed in the task status or dialog.
• Target File Information: File format, size, or public URL (if non-confidential).

1. Application Log Files: SurgeDL writes diagnostic execution logs to:

• macOS: ~/.surgedl/surgedl.log or console output.
• Windows: %USERPROFILE%\.surgedl\