A macOS terminal downloader built on yt-dlp, featuring a full-screen terminal user interface (TUI) implemented with Bubble Tea and Lip Gloss, and concurrent multi-task download support.
Queen is a self-contained, single-install command-line front end for yt-dlp. It abstracts the configuration and invocation of yt-dlp behind an interactive menu, and renders per-task progress (percentage, size, throughput, and remaining time) with fixed-width alignment so that numeric updates do not cause layout jitter. Multiple links are downloaded concurrently, each isolated in its own worker, so a stalled task does not block the remainder of the batch.
- Full-screen terminal user interface (Bubble Tea / Lip Gloss).
- Concurrent multi-task downloads: independent worker per link, non-blocking progress.
- Real-time per-task progress: percentage, size, throughput, and estimated time remaining.
- Batch progress: aggregated progress bar, elapsed time, and projected total time.
- Automatic recording of failed links, with one-key retry.
- Configurable playlist mode, audio-only extraction (mp3), subtitles, metadata embedding, and cookie browser selection.
- Best-quality support for X.com / Twitter: X (or
t.co) links are downloaded at the highest available quality by automatically passing the logged-in browser cookies to yt-dlp (X caps quality for anonymous requests and gates many videos behind "Requires authentication"). - Bilingual interface (Chinese / English).
- Native macOS notifications upon batch completion and per-task failure.
- Multiple visual themes (the interface style borrows heavily from Mole).
| Requirement | Purpose |
|---|---|
GNU/BSD yt-dlp |
Core download engine |
ffmpeg |
Merging, transcoding, and thumbnail embedding |
| macOS | Target platform |
| Homebrew | Optional, for automatic dependency installation / upgrades |
yt-dlp and ffmpeg are detected at startup; if either is missing, Queen offers to install them
via Homebrew.
Prebuilt binaries are attached to each release for both
Apple Silicon (darwin/arm64) and Intel (darwin/amd64) Macs. Download the matching zip, unpack it,
and run queen from the extracted folder:
arch=$(uname -m); [ "$arch" = "x86_64" ] && arch=amd64
curl -fsSL -o queen.zip \
https://github.com/kesonglab/queen/releases/latest/download/queen-darwin-$arch.zip
unzip queen.zip
./queenBecause the binary is not signed, macOS may block the first launch. If it does, open System Settings → Privacy & Security and choose Open Anyway, or right-click the file and select Open.
git clone https://github.com/kesonglab/queen.git
cd queen
make buildThe equivalent explicit command is:
go build -ldflags "-X main.version=$(git describe --tags --always)" -o queen .make install # equivalent to: go install ./...The application version is injected at build time via -ldflags "-X main.version=..." and is
therefore not duplicated in source.
queenFrom the main menu:
| Key | Action |
|---|---|
1 / ↑↓ / Enter |
Select a menu item |
2 |
Read links from the clipboard |
3 |
Retry previously failed links |
Ctrl+D |
Start the download (inside the input area) |
q / Esc |
Go back / quit |
←→ |
Toggle an option (on the settings page) |
Paste one link per line, then press Ctrl+D to begin a batch download.
The configuration file lives at ~/.config/videodl/config.json. It can be edited through the
application's settings page or by hand:
| Field | Description |
|---|---|
download_dir |
Download directory (default ~/Downloads) |
cookie_browser |
Cookie browser to use (auto-detect / chrome / firefox / safari / edge) |
playlist |
Whether to download as a playlist |
audio_only |
Extract audio only and transcode to mp3 |
subs |
Download subtitles (zh/en) and embed them |
embed |
Embed title / thumbnail metadata |
retry_times |
Retries per link (0–5) |
concurrency |
Maximum concurrent downloads (1–16) |
format |
yt-dlp format selector (default bestvideo*+bestaudio/best) |
merge_format |
Output container format (default mp4) |
lang |
Interface language (zh / en) |
Failed links are recorded to ~/Downloads/视频失败链接-failed_links.txt.
| Command | Description |
|---|---|
make dev |
Run lint and tests |
make build |
Build the binary |
make lint |
Run go vet static analysis |
make test |
Run the test suite |
make release VERSION=1.3.0 |
Produce a versioned release artifact |
See CHANGELOG.md, or browse it from the in-application "Changelog" menu.
Issues and pull requests are welcome. Before submitting, ensure that the working tree passes
make lint and make test.
The overall visual style and terminal interface design of Queen are inspired by, and borrow heavily from, the excellent open-source project Mole. Many thanks to the Mole authors for their great work.
Released under the MIT license.
Maintained by kesonglab.