A Charmbracelet-based TUI wrapper around the yt-dlp project with form-driven configuration, video/audio format conversion via ffmpeg, a directory picker, and a live animated progress view.
- Guided, conditional form: pick video or audio-only, then the relevant options for that mode.
- Video: quality presets (4K/1080p/720p/best) and an output container — MP4 (fast merge) or MKV/WebM/MOV/AVI (real ffmpeg re-encode).
- Audio-only: extract to MP3, FLAC, WAV, OGG (Vorbis), M4A (AAC), Opus, ALAC, or keep the original best audio codec — all via yt-dlp's ffmpeg-backed audio extractor.
- Live animated, gradient progress bar and speed/ETA/size stats parsed from yt-dlp's own output, plus the full raw log.
- Keyboard controls: quit, back, clear logs.
- Cross-platform notification sound on completion.
- Go 1.21+ (module target is 1.26.1).
yt-dlpinstalled and onPATH— required; the app checks at startup and shows an OS/arch-specific install command if it's missing.ffmpegonPATHfor format conversion (merging, MKV/WebM/MOV/AVI re-encoding, MP3/FLAC/WAV/etc. audio extraction). Also checked at startup: if missing, the app still works but only offers the original, unconverted format, with an install hint shown on screen.
go mod tidy
go run .
# or build
go build -o yt-dlp-gui
./yt-dlp-gui
make install # builds and installs to /usr/local/bin/yt-dlp-gui (prompts for sudo)
make uninstall # removes itCheck the installed version with yt-dlp-gui --version.
- Form screen: fill fields, Enter to submit, Ctrl+C to quit.
- Download screen:
qquit •bback to form •cclear logs • Ctrl+C quit.
- Quality: 4K (2160p), 1080p, 720p, or best available (
bestvideo[height<=N]+bestaudio/best). - Format: MP4 merges the downloaded streams losslessly (
--merge-output-format mp4); MKV/WebM/MOV/AVI trigger a real ffmpeg re-encode (--recode-video) so the conversion always succeeds, even across incompatible codec/container pairs; "Original" skips conversion entirely.
Selecting "Audio only" downloads the best audio stream, then optionally converts it with yt-dlp's --extract-audio --audio-format <fmt> --audio-quality 0 (ffmpeg under the hood): MP3, FLAC, WAV, OGG (Vorbis), M4A (AAC), Opus, ALAC, or "Best (original)" to skip conversion and keep the source codec/container.
yt-dlp GUI/
├─ main.go # app entry (form-based TUI)
├─ go.mod / go.sum
├─ Makefile # build/install targets
├─ scripts/build-all.sh # cross-platform build script
└─ .github/workflows/ # CI: build + auto-release
main.go:
- Uses
huhfor form. bubbletea+viewportfor logs.lipglossfor styling.- Completion sound per OS.
- “yt-dlp not found”: install
yt-dlpand ensure it’s onPATH. - Merge fails: verify FFmpeg on
PATH. - Terminal too small: resize; viewport auto-resizes on
WindowSizeMsg.
This project aims to be cross-platform (macOS, Linux, Windows). A few runtime behaviors depend on external system utilities; here's what to expect and how to prepare each platform.
External dependencies
yt-dlp(preferred) oryoutube-dlmust be installed and available on PATH. The program will attempt to findyt-dlp, thenyt_dlp, thenyoutube-dl.ffmpegshould be installed if you want yt-dlp to merge video + audio.- Notifications & sounds:
- The app uses the
beeeplibrary for cross-platform desktop notifications and a short beep where supported. - If
beeepcannot deliver a notification on a system, the binary will attempt a series of platform-specific players/commands (e.g.,afplayon macOS,paplay/aplay/playon Linux, PowerShell on Windows) and finally fall back to the terminal bell.
- The app uses the
Installing useful packages per platform
- macOS (Homebrew):
brew install yt-dlp ffmpeg sox- Ubuntu/Debian:
sudo apt update
sudo apt install -y yt-dlp ffmpeg libasound2-utils sox libcanberra-gtk-module libcanberra-gtk3-module- Windows:
- Install
yt-dlp.exe(winget or manual download) andffmpeg, and add them to PATH. PowerShell is typically available on modern Windows and is used for a simple notification sound.
- Install
This repository's main package is located at the repository root (there is no ./yt-dlp-GUI subpackage). Build from the repo root (.). Example builds:
- Build for Linux x86_64:
GOOS=linux GOARCH=amd64 go build -o yt-dlp-gui-linux .- Build for Windows x86_64:
GOOS=windows GOARCH=amd64 go build -o yt-dlp-gui.exe .- Build for macOS (native build or from macOS):
go build -o yt-dlp-gui .Notes:
- Build from
.(the repository root) — do not use./yt-dlp-GUIunless you move the entrypoint into that subdirectory. - The binary is pure Go and generally cross-compiles, but runtime behaviour (notifications, sounds, merge steps) depends on the target OS utilities being present.
- When packaging, include a short README or installer notes that recommend installing
yt-dlpandffmpeg.
Where to get builds
- Stable releases: check this repository's "Releases" page for published release assets (these are intended to be stable binaries).
- More up-to-date builds: check the "Actions" tab (GitHub Actions) for workflow runs — many workflows upload build artifacts for recent commits which you can download if you need a newer build than the latest release.
The workflow at .github/workflows/build.yml builds cross-platform binaries (linux/windows/darwin × amd64/arm64) on every push and pull request, and auto-releases:
- Push to
main: the workflow computes the next patch version from the highest existingvX.Y.Ztag (e.g.v1.0.1->v1.0.2), builds all targets with that version embedded (main.version), creates the git tag, and publishes a GitHub Release with all binaries attached — no manual tagging required. - Manual tag push (
git tag vX.Y.Z && git push --tags) orworkflow_dispatch: also produces/updates a release using that tag. - Pull requests: binaries are built and uploaded as workflow artifacts for validation only — no release is created.
Where to obtain binaries:
- Stable releases: GitHub Releases (auto-published on every
mainpush). - Latest or intermediate builds: the Actions tab, for the workflow run matching a specific commit/branch.