Quark Downloader

Dependencies

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

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:

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"). On macOS and Linux, install yt-dlp and ffmpeg yourself (brew install yt-dlp ffmpeg, or your distro / pipx); Quark does not bundle or auto-download them there. Do not run with sudo — that writes config and downloads into root's home.

CLI color: Interactive and TTY output uses ANSI colors when supported. Disable with NO_COLOR=1 or force with FORCE_COLOR=1.

Stall watchdog: Playlist items that go silent too long are skipped (QUARK_STALL_TIMEOUT_SEC, default ~75s after output starts, ~90s grace before first output). Single-video stalls warn instead of killing.

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 '…' --emit-result-json              # final __RESULT__ JSON line for tools/GUI
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