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
• Spotify Tracks - Fetch and Download Spotify tracks.
• 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/
• ffplay (optional, bundled with ffmpeg) - Fallback playback backend
  • Used automatically when mpv is not installed
  • Set player: ffplay in config to use it explicitly (see Configuration below)

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
spotify_download_path: ~/Music # Spotify 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
embed_thumbnail: false # Embed thumbnail 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)
thumbnail_protocol: "" # Override thumbnail protocol: kitty, sixel, iterm2, halfblocks, auto (optional, default: halfblocks)
thumbnail_quality: max # Thumbnail quality: max, high, medium, low (optional, default: max)
js_runtime: "" # JS runtime for yt-dlp: deno, node, bun, quickjs (optional)
js_runtime_path: "" # Custom path to JS runtime executable (optional)
player: mpv # Playback backend: mpv, ffplay (falls back to ffplay if mpv isn't installed)
background_playback: false # Keep player running when leaving the player view (background playback)

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

YouTube serves thumbnails at multiple resolutions. You can control which quality xytz tries to fetch:

thumbnail_quality: max # max, high, medium, low

If the preferred quality isn't available for a video, xytz automatically falls back through lower tiers.

By default, xytz uses halfblocks rendering to avoid terminal detection queries that can steal the first few keystrokes. If you want xytz to auto-detect your terminal's graphics protocol (Kitty, Sixel, iTerm2), set thumbnail_protocol: auto. Note this may cause the keystroke issue in some terminals.

# Option 1: Disable thumbnails entirely
thumbnail_preview: false
# Option 2: Explicitly pick your terminal's protocol
thumbnail_protocol: kitty # kitty, sixel, iterm2, halfblocks
# Option 3: Let the library detect (may cause keystroke issue)
thumbnail_protocol: auto

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

By xdagiz