A beautiful TUI app for searching and downloading videos from YouTube and Other sites, built with Go and Bubble Tea.

• Features
• Installation
• Configuration
• Usage
• Contributing
• Troubleshooting
• Acknowledgments
• Star History

• Interactive Search - Search YouTube videos directly from your terminal
• Direct URL Downloads - Paste a URL from any yt-dlp supported site
• Channel Browsing - View all videos from a specific channel with /channel @username
• Channel Search - Find YouTube channels with /channels <query>
• Playlist Support - Browse and download videos from playlists with /playlist <id>
• Format Selection - Choose from available video/audio formats with quality indicators
• Batch Downloads - Select multiple videos and download them all at once
• Download Queue Management - Pause, resume, skip, and retry downloads in queue
• Resume Downloads - Resume unfinished downloads with /resume
• Save for Later - Save videos to download later and come back to them with /later
• Video Playback - Play videos directly with mpv without downloading using /play <url>
• Search History - Persistent search history for quick access (use ↑/↓ to navigate)
• Thumbnail Preview - View video thumbnails inline in the terminal
• Theme Switching - Switch between themes at runtime with /theme <name>
• Cookie Authentication - Load cookies from browser or file for authenticated content
• Keyboard Navigation - Vim-style keybindings and intuitive shortcuts
• Cross-Platform - Works on Linux, macOS, and Windows

• yt-dlp: Core video downloader
  • Installation: https://github.com/yt-dlp/yt-dlp#installation
• ffmpeg - Required for full features
  • Installation: https://ffmpeg.org/download.html
• mpv (optional) - For playing videos directly without downloading
  • Installation: https://mpv.io/installation/

curl -fsSL https://raw.githubusercontent.com/xdagiz/xytz/main/install.sh | bash

brew install xdagiz/tap/xytz

paru -S xytz-bin # or yay -S xytz-bin

scoop bucket add xdagiz https://github.com/xdagiz/scoop-bucket.git
scoop install xdagiz/xytz

go install github.com/xdagiz/xytz@latest

# Run without installing
nix run github:xdagiz/xytz

# Build in the current repo
nix build

# Enter a development shell (Go, gopls, yt-dlp, ffmpeg, mpv)
nix develop

Requirements:

• Go 1.25+ - For building from source

# Clone the repository
git clone https://github.com/xdagiz/xytz.git
cd xytz

# Build
go build -o xytz .

# Move to your PATH (optional)
sudo mv xytz /usr/local/bin/

The config file location varies by operating system:

On first run, xytz will create the config file with default values if it doesn't exist.

search_limit: 25 # Number of search results
default_download_path: ~/Videos # Download destination
default_quality: best # Default format selection (480p, 720p, 1080p, 4k...)
sort_by_default: relevance # Default sort: relevance, date, views, rating
theme: catppuccin-mocha # Preset theme name
video_format: mp4 # The format which videos are downloaded
audio_format: mp3 # The format which audio files are downloaded
embed_subtitles: false # Embed subtitles in downloads
embed_metadata: true # Embed metadata in downloads
embed_chapters: true # Embed chapters in downloads
ffmpeg_path: "" # Custom ffmpeg path (optional)
yt_dlp_path: "" # Custom yt-dlp path (optional)
cookies_browser: "" # Browser for cookies: chrome, firefox, etc (optional)
cookies_file: "" # Path to cookies.txt file for authentication (optional)
thumbnail_preview: true # Enable thumbnail preview in video list
thumbnail_timeout_ms: 2500 # Timeout for fetching thumbnails (ms)
js_runtime: "" # JS runtime for yt-dlp: deno, node, bun, quickjs (optional)
js_runtime_path: "" # Custom path to JS runtime executable (optional)

xytz supports command-line arguments for quick access to search, channels, and playlists. Run xytz --help to see all available flags.

# Direct video search
xytz -q "golang tutorial"

# Browse a specific channel
xytz -u @username

# Browse a playlist
xytz -p PLplaylistId

# search for a channel
xytz -c "linux"

# Custom search results and sorting
xytz -n 50 -s date

# Combined: Search with custom options
xytz -q "rust programming" -n 10 -s views

Contributions are welcome. Please ensure your fork is synced with the upstream repository before submitting pull requests.

<type>(<scope>): <description>

[optional body]
[optional footer]

• Keep changes focused and minimal
• Ensure all tests pass before submitting
• Update documentation if needed
• Follow the existing code style

Ensure yt-dlp is installed and available in your PATH:

yt-dlp --version

If installed in a non-standard location, set yt_dlp_path in your config.

ffmpeg is required for most of features to work. Install it and ensure it's in your PATH, or set ffmpeg_path in your config.

• Check your internet connection
• Verify the video is available in your region
• Ensure you have sufficient disk space
• Check the download path is writable
• Make sure you have yt-dlp and ffmpeg installed

• Update yt-dlp to the latest version

• Bubble Tea - TUI framework
• yt-dlp - Download engine
• Lipgloss - Styling library
• Bubbles - TUI components

By xdagiz