SmartDL v3.19.0

bad connection? hold my retry loop.

A resilient, multi-threaded media downloader built for unstable networks. Designed for users behind weak connections and VPNs — SmartDL never gives up.

If SmartDL saved you from a broken download at 3am — you know what to do. ☕
buymeacoffee.com/alisadeghil

---

Features

Capability matrix (honest)

Area	Status	Notes
YouTube	Native	Format menu, playlists, thumbnails, yt-dlp engine
Aparat	Native	Videos + playlists
Podcasts / RSS / Castbox	Native	Feed discovery, episode batch download
Maktabkhooneh / Faradars / Coursera	Partial native	Outline parse + yt-dlp per lesson; cookies required for paid content
Persian platforms (Namava, Filimo, …)	Partial	Detection + yt-dlp fallback
Udemy / Hotmart / Teachable / …	Detection only	Falls back to yt-dlp; no DRM bypass
Torrent / magnet	External tools	Needs aria2c, transmission, or qBittorrent
1800+ other sites	yt-dlp passthrough	Not native extractors
Persian UI	Partial	Interactive strings localized; large parts of CLI still English

Core

• YouTube — full format list (all resolutions, all audio tracks), video info panel
• Aparat, Maktabkhooneh & Faradars — support for Iranian video & education platforms (see matrix)
• 1800+ sites via yt-dlp — TikTok, Instagram, Twitter/X, Reddit, Twitch, Vimeo, SoundCloud, and more
• Podcasts — direct MP3/M4A links, RSS feeds, SoundCloud, Castbox, and more

Network Resilience

• Infinite retry with backoff — waits and retries on network failure; never fails silently
• Resume downloads — picks up exactly where it left off after a disconnect
• Multi-threaded fragments — up to 16 concurrent fragment downloads
• Smart error diagnosis — explains what went wrong and how to fix it
• Proxy support — configure HTTP/SOCKS5 proxy at runtime (v2ray, Clash, Hiddify, Nekoray)

Download Features

• Video clipping — download only a segment (--clip 00:01:30-00:05:00)
• SponsorBlock — skip sponsor segments automatically
• Subtitles — download, search, and embed subtitles in 50+ languages
• Thumbnails — download and embed video thumbnails
• Metadata — embed title, artist, and other metadata
• Audio extraction — MP3, M4A, Opus, FLAC, WAV with quality control
• Multiple formats — MP4, MKV, WebM, AVI output

Smart Mode

• Save preferences — set default quality, format, audio settings once
• Auto-apply — all downloads use your saved preferences

Queue & History

• Download queue — add multiple URLs, process sequentially or in parallel
• Download history — SQLite database with search, filter, and export
• Subscriptions — follow channels; auto-download when a subscription has auto_download enabled or SMARTDL_SUBS_AUTODL=1

Extra Features

• Image galleries — download from Pixiv, DeviantArt, ArtStation, Flickr, Imgur
• Torrent/magnet — download torrents via aria2c, transmission, or qBittorrent
• Portable mode — run from USB stick without touching system directories
• 12 CLI themes — Dracula, Catppuccin, Nord, Tokyo Night, and more
• Persian/Farsi UI — full Persian language support (see matrix)
• CLI automation — 40+ flags for scripting and automation

---

Requirements

• Python 3.9+
• ffmpeg — required for HD video (merge) and MP3 conversion

Install ffmpeg (Windows)

winget install Gyan.FFmpeg

Then close and reopen your terminal.

---

Installation

Option 1: pip (recommended)

pip install smart-dl

Option 2: Windows portable EXE (no Python install)

Two formats are published on the Releases page — verify either with SHA256SUMS.txt:

• SmartDL-v*-win-x64.zip (recommended) — an onedir bundle: extract, run SmartDL.exe. Starts fast and is the friendliest to SmartScreen/antivirus heuristics.
• SmartDL-v*-win-x64-onefile.exe — a single fully self-contained EXE: Python runtime, yt-dlp, all modules and the external tools (ffmpeg, Node.js, aria2c) are embedded. Just run it — no Python, ffmpeg, or Node install needed. Larger file, slower first start, and more likely to trip AV heuristics than the zip.

If Windows SmartScreen appears: the EXE is not code-signed. Choose More info → Run anyway, or install via pip instead. Antivirus false positives on PyInstaller bundles are common; the hash on the release page lets you confirm the file you downloaded.

Option 3: clone and run

git clone https://github.com/alisadeghiaghili/smart-dl.git
cd smart-dl
python smart_dl.py

Python dependencies (yt-dlp, rich, requests) are declared in pyproject.toml. Install with pip install -e . (or pip install smart-dl). Optional auto-install on first interactive run is available via SMARTDL_AUTO_DEPS=1.

---

Usage

Interactive Mode

python smart_dl.py

On startup:

1. Choose your output folder (default: ~/Downloads/SmartDL)
2. Configure a proxy if needed (or press Enter to skip)
3. Paste a URL (YouTube, Aparat, podcast, or any supported site)
4. Select quality/format from the menu
5. Download starts — with resume, retry, and progress bar

URL Prompt Shortcuts

Key	Action
q	Quit
p	Proxy settings
s	Download settings (retries, fragment threads)
c	Cookie settings (browser auth)
i	Install dependencies (ffmpeg, Node.js)

CLI Mode

# Basic download
smart-dl "https://youtube.com/watch?v=abc123"

# Quality and format (presets: worst, 360, 480, 720, 1080, 1440, 4k, 8k, best)
smart-dl URL -q 1080 -o ~/Downloads
smart-dl URL -q 4k --format mkv
smart-dl URL --limit-rate 2M
smart-dl --update-ytdlp
smart-dl --set-cookie-browser firefox
smart-dl --export-config backup.json
smart-dl --import-config backup.json
smart-dl --watch-clipboard --watch-max 5
smart-dl --set-telegram-token BOT_TOKEN --set-telegram-chat CHAT_ID
smart-dl --notify-test
smart-dl --schedule add "https://youtube.com/watch?v=abc" --at 02:30
smart-dl --schedule list
smart-dl --schedule start --once
smart-dl --subs-check
smart-dl --aria2-rpc "https://example.com/file.zip"
smart-dl --api --api-port 8765

# Video clipping
smart-dl URL --clip 00:01:30-00:05:00

# Audio extraction
smart-dl URL --audio-only --audio-format flac --audio-quality 320

# SponsorBlock
smart-dl URL --sponsorblock

# Subtitles
smart-dl URL --subtitles en,fa --embed-subs

# Thumbnails and metadata
smart-dl URL --thumbnail --embed-thumbnail --embed-metadata

# Batch download
smart-dl --batch urls.txt -o ~/Downloads

# Queue management
smart-dl --queue add URL1 URL2
smart-dl --queue start

# Night scheduler + unattended subscription check
# Windows Task Scheduler example (PowerShell):
#   smart-dl --schedule start --once
#   smart-dl --subs-check
smart-dl --schedule add "https://youtube.com/watch?v=abc" --at 02:30
smart-dl --schedule start --once
smart-dl --subs-check

smart-dl --queue add URL1 URL2 URL3
smart-dl --queue start
smart-dl --queue pause
smart-dl --queue resume
smart-dl --queue list
smart-dl --queue stats

# Download history
smart-dl --history list --sort date
smart-dl --history search "keyword"
smart-dl --history stats

# Subscriptions
smart-dl --subscribe https://youtube.com/@channel
smart-dl --check-updates          # list new uploads
# SMARTDL_SUBS_AUTODL=1 smart-dl --check-updates  # also download them
smart-dl --my-subs

# Smart Mode
smart-dl --smart-mode on
smart-dl --smart-mode config  # interactive settings

# Image galleries
smart-dl https://www.pixiv.net/artworks/12345

# Education courses (Maktabkhooneh / Faradars / Coursera)
smart-dl "https://www.coursera.org/learn/machine-learning"
smart-dl "https://www.coursera.org/learn/machine-learning" --max-lessons 5
smart-dl "https://maktabkhooneh.org/course/..." --all   # remove the 20-lesson default cap

# Torrent
smart-dl --torrent magnet:?xt=urn:btih:...

# Themes
smart-dl --theme catppuccin
smart-dl --list-themes

# Persian UI
smart-dl --lang fa

# Proxy
smart-dl --proxy socks5://127.0.0.1:10808

# Portable mode
smart-dl --portable

# Podcasts
smart-dl "https://feeds.npr.org/510289/podcast.xml"
smart-dl "https://example.com/show.xml" --all-episodes
smart-dl "https://castbox.fm/channel/id2386830" --all-episodes
smart-dl "https://soundcloud.com/user/track"

# Quiet mode with file logging
smart-dl URL --quiet --log download.log

Notes

• Failed downloads exit with code 1 and do not print a success message.
• History records every download outcome (--history list / --history stats).
• Portable mode (--portable or a portable.txt next to the app) stores config and databases under ./data.
• Dependency auto-install is off by default. Set SMARTDL_AUTO_DEPS=1 only if you want first-run pip install.

Authenticated courses (Maktabkhooneh / Coursera / Faradars)

Paid or enrolled lessons need a logged-in browser session:

1. Sign in to the site in Firefox/Edge/Chrome.
2. In SmartDL interactive mode press c and pick that browser (or set cookie browser in config).
3. Re-run the course URL. yt-dlp and the Coursera items API will reuse those cookies.

Faradars does not publish public lesson lists for most courses — use a course URL after login.

Alternative: export a Netscape cookies.txt from an extension and pass it:

smart-dl --cookies-file path/to/cookies.txt "https://www.youtube.com/watch?v=..."

---

Supported Platforms

Platform	Support
YouTube (videos, playlists, channels, Shorts)	✅
Aparat (videos, playlists)	✅
TikTok / Instagram / Twitter / Reddit / Twitch / Vimeo / …	via yt-dlp
1800+ yt-dlp sites	via yt-dlp
Direct MP3/M4A links	✅
RSS podcast feeds	✅
Filimo / Namasha / Radio Javan	metadata + yt-dlp
Maktabkhooneh / Faradars	course outline + lessons via cookies (paid = your logged-in session)
Coursera	course title + weekly modules (public); lecture items when browser cookies are available
Udemy / Hotmart / Teachable / …	public metadata only — paid/DRM content is not downloadable without your own authorized access and will usually fail

---

Network Resilience

Built specifically for unstable connections:

• Resumes partial downloads automatically (no re-downloading from scratch)
• Exponential backoff retry (5s → 7s → 11s → ... up to 5 min)
• 30-minute retry duration cap (configurable)
• Fatal errors (ffmpeg missing, private video, copyright block) fail immediately
• Connection drops are silently handled; download continues when network returns

---

Disclaimer

SmartDL is intended for personal use only. Downloading copyrighted content without permission may violate YouTube's Terms of Service and applicable laws in your country. The author is not responsible for any misuse of this tool. Always respect content creators and copyright holders.

---

☕ Support

SmartDL is free and always will be.
Sponsorships fund faster releases, better diagnostics, and long-term maintenance.

---

License

Apache-2.0 — permissive with an explicit patent grant; proprietary tools may link without copyleft.

See ROADMAP.md for planned features.