shards.info
quark-downloader v0.5.0
|
Quark Downloader
|
Dependencies
| Dependency | Windows | macOS | Linux |
|---|---|---|---|
| yt-dlp | PATH or auto-download to tools/ |
PATH via Homebrew | PATH |
| ffmpeg | PATH or bundled | PATH via Homebrew | PATH |
| GUI (optional) | Win32 | AppKit UI | Tk / wish (apt install tk) |
Note: Distro/apt yt-dlp is often too old. Prefer pipx install yt-dlp and Node or Deno. Quark warns on stale versions and passes EJS flags when a JS runtime is on PATH.
Build: Crystal | just | Windows installer: Inno Setup 7 + packaging/quark-downloader.iss | macOS app/DMG: Xcode Command Line Tools (swiftc) + just dmg
Binaries
| Program | Purpose |
|---|---|
quark-downloader |
Full CLI - interactive in a terminal, or scriptable with flags |
quark-downloader-gui |
Thin UI that collects options and runs the CLI as a subprocess |
quark-downloader-gui-helper |
macOS only: native AppKit windows for the GUI (built with swiftc) |
The GUI queues multiple URLs (Add/Remove list) and downloads them sequentially with combined progress ("URL 2 of 5"). Playlist URLs download every item into a folder named after the playlist (see playlist_folders), with per-item progress and a failure summary.
Package maintainers can ship the CLI alone (quark-downloader on PATH) and optionally a GUI package that installs quark-downloader-gui, quark-downloader-gui.tcl (same directory), packaging/quark-downloader-gui.desktop, and depends on Tk / wish (Linux). On macOS the GUI prefers the native quark-downloader-gui-helper beside the binary and falls back to Tk when it is missing.
Windows shortcuts from the installer open the GUI; the CLI remains in the install folder as Quark Downloader (CLI). Use Check for updates in settings to compare against the latest GitHub release and open the installer download when a newer version is published.
Configuration
On first run, Quark creates quark-downloader.conf under the user config directory:
| Setting | Values |
|---|---|
download_dir |
Default output folder (~ is supported) |
yt_dlp |
auto, path, or bundled |
ffmpeg |
auto, path, or bundled |
gui_download_mode |
progress for the GUI progress dialog, or external_cli to open the CLI window after Download |
download_logs |
true or false; applies to both CLI and GUI downloads |
gui_theme |
light or dark; applies to the macOS/Linux GUI (Windows uses its native light UI) |
strip_video_ids |
true (default) drops the trailing [VIDEOID] from filenames |
sanitize_filenames |
true (default) makes filenames mostly ASCII-safe on all platforms (｜ -> -, accents transliterated, Windows-invalid characters removed) |
filename_spaces |
keep (default), underscore, dash, or remove |
playlist_folders |
true (default) saves playlist downloads into a folder named after the playlist (sanitized with the same rules) |
The download-naming settings are grouped under Download Naming in the GUI settings. The GUI gear button opens all settings without editing the file by hand. Logs are rotated in the config directory under logs/. Existing config files are updated with missing default keys on load.
Commands
just run # crystal run CLI
just run-gui # crystal run GUI
just build # release -> build/ (both binaries; UPX on Windows; AppKit helper on macOS)
just dmg # macOS: build "Quark Downloader.app" + DMG into dist/
just clean
crystal spec # run focused tests
The DMG is ad-hoc signed: after downloading, right-click > Open the first time (or xattr -dr com.apple.quarantine "Quark Downloader.app"). Inside the app bundle, downloaded tools are stored under ~/.config/quark-downloader/tools/.
Build scripts live under scripts/, grouped by platform.
CLI (non-interactive)
quark-downloader --url 'https://example.com/video' --type video --format mp4 --output-dir ~/Downloads --no-pause
quark-downloader --url 'https://a/1' --url 'https://a/2' # bulk: repeat --url; failures don't stop the queue
quark-downloader --batch-file urls.txt # one URL per line, # comments ignored
quark-downloader --url 'https://www.youtube.com/playlist?list=...' # playlist -> own folder
quark-downloader --print-default-output-dir
Run with no arguments for the interactive prompt flow.
Env (Windows)
QUARK_SKIP_YTDLP_UPDATE=1 | QUARK_SKIP_FFMPEG_DOWNLOAD=1
quark-downloader
- 0
- 0
- 0
- 0
- 0
- 9 days ago
- June 2, 2026
MIT License
Fri, 12 Jun 2026 23:52:39 GMT