{"id":43779832,"url":"https://github.com/xdagiz/xytz","last_synced_at":"2026-03-12T14:32:47.623Z","repository":{"id":336523226,"uuid":"1141266566","full_name":"xdagiz/xytz","owner":"xdagiz","description":"A Beautiful TUI YouTube Downloader app","archived":false,"fork":false,"pushed_at":"2026-02-15T00:12:57.000Z","size":211,"stargazers_count":206,"open_issues_count":0,"forks_count":18,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-15T06:54:00.784Z","etag":null,"topics":["bubbletea","charmbracelet","cli","ffmpeg","go","golang","tui","tui-go","youtube-downloader","yt-dlp","yt-dlp-wrapper"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xdagiz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-24T15:00:50.000Z","updated_at":"2026-02-15T00:13:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/xdagiz/xytz","commit_stats":null,"previous_names":["xdagiz/xytz"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/xdagiz/xytz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdagiz%2Fxytz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdagiz%2Fxytz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdagiz%2Fxytz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdagiz%2Fxytz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xdagiz","download_url":"https://codeload.github.com/xdagiz/xytz/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xdagiz%2Fxytz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29636040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T22:32:43.237Z","status":"ssl_error","status_checked_at":"2026-02-19T22:32:38.330Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bubbletea","charmbracelet","cli","ffmpeg","go","golang","tui","tui-go","youtube-downloader","yt-dlp","yt-dlp-wrapper"],"created_at":"2026-02-05T18:05:05.048Z","updated_at":"2026-03-12T14:32:47.598Z","avatar_url":"https://github.com/xdagiz.png","language":"Go","funding_links":[],"categories":["Table of Contents"],"sub_categories":[],"readme":"# xytz - YouTube from your terminal\n\nA beautiful TUI app for searching and downloading YouTube videos, built with Go and [Bubble Tea](https://github.com/charmbracelet/bubbletea).\n\n[![License: MIT](https://img.shields.io/github/license/xdagiz/xytz?style=flat)](https://github.com/xdagiz/xytz/blob/main/LICENSE)\n[![Stars](https://img.shields.io/github/stars/xdagiz/xytz?style=flat)](https://github.com/xdagiz/xytz/stargazers)\n[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/rothgar/awesome-tuis#multimedia)\n[![Release](https://img.shields.io/github/v/release/xdagiz/xytz?display_name=tag\u0026sort=semver\u0026style=flat)](https://github.com/xdagiz/xytz/releases)\n\u003cbr /\u003e\n[![Downloads](https://img.shields.io/github/downloads/xdagiz/xytz/total?style=flat)](https://github.com/xdagiz/xytz/releases)\n[![AUR](https://img.shields.io/aur/version/xytz-bin?style=flat\u0026label=AUR)](https://aur.archlinux.org/packages/xytz-bin)\n[![Contributions](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/xdagiz/xytz/issues)\n[![Go Report Card](https://goreportcard.com/badge/github.com/xdagiz/xytz?style=flat)](https://goreportcard.com/report/github.com/xdagiz/xytz)\n\nhttps://github.com/user-attachments/assets/4e3f98c7-554f-4b9e-adac-52511ae69f32\n\n## ✨ Features\n\n- **Interactive Search** - Search YouTube videos directly from your terminal\n- **Channel Browsing** - View all videos from a specific channel with `/channel @username`\n- **Channel Search** - Find YouTube channels with `/channels \u003cquery\u003e`\n- **Playlist Support** - Browse and download videos from playlists with `/playlist \u003cid\u003e`\n- **Format Selection** - Choose from available video/audio formats with quality indicators\n- **Batch Downloads** - Queue multiple videos for sequential download\n- **Download Queue Management** - Pause, resume, skip, and retry downloads in queue\n- **Resume Downloads** - Resume unfinished downloads with `/resume`\n- **Video Playback** - Play videos directly with mpv without downloading using `/play \u003curl\u003e`\n- **Search History** - Persistent search history for quick access (use ↑/↓ to navigate)\n- **Thumbnail Preview** - View video thumbnails inline in the terminal\n- **Theme Switching** - Switch between themes at runtime with `/theme \u003cname\u003e`\n- **Cookie Authentication** - Load cookies from browser or file for authenticated content\n- **Keyboard Navigation** - Vim-style keybindings and intuitive shortcuts\n- **Cross-Platform** - Works on Linux, macOS, and Windows\n\n**Requirements:**\n\n- **yt-dlp**: Core video downloader\n  - Installation: https://github.com/yt-dlp/yt-dlp#installation\n- **ffmpeg** - Required for full features\n  - Installation: https://ffmpeg.org/download.html\n- **mpv** (optional) - For playing videos directly without downloading\n  - Installation: https://mpv.io/installation/\n\n## Installation\n\n### Installer Script (Linux/MacOS)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/xdagiz/xytz/main/install.sh | bash\n```\n\n### Homebrew (MacOS/Linux)\n\n```bash\nbrew install xdagiz/tap/xytz\n```\n\n### AUR (Arch Linux)\n\n```bash\nparu -S xytz-bin # or yay -S xytz-bin\n```\n\n### Scoop (Windows)\n\n```pwsh\nscoop bucket add xdagiz https://github.com/xdagiz/scoop-bucket.git\nscoop install xdagiz/xytz\n```\n\n### Go Install\n\n```bash\ngo install github.com/xdagiz/xytz@latest\n```\n\n### Nix (Flakes)\n\n```bash\n# Run without installing\nnix run github:xdagiz/xytz\n\n# Build in the current repo\nnix build\n\n# Enter a development shell (Go, gopls, yt-dlp, ffmpeg, mpv)\nnix develop\n```\n\n### Build from Source\n\n**Requirements:**\n\n- **Go 1.25+** - For building from source\n\n```bash\n# Clone the repository\ngit clone https://github.com/xdagiz/xytz.git\ncd xytz\n\n# Build\ngo build -o xytz .\n\n# Move to your PATH (optional)\nsudo mv xytz /usr/local/bin/\n```\n\n## Getting Started\n\nLaunch xytz by running:\n\n```bash\nxytz\n```\n\n### Basic Workflow\n\n1. **Search** - Type your query and press `Enter` to search\n2. **Select** - Use `↑/↓` or `j/k` to navigate results, `Enter` to select\n3. **Choose Format** - Select your preferred video/audio format\n4. **Download** - The download starts automatically\n\n## Configuration\n\nThe config file location varies by operating system:\n\n| OS      | Config Location                                                                                                      |\n| ------- | -------------------------------------------------------------------------------------------------------------------- |\n| Linux   | `~/.config/xytz/config.yaml` (or `$XDG_CONFIG_HOME/xytz/config.yaml`)                                                |\n| macOS   | `~/.config/xytz/config.yaml` if `XDG_CONFIG_HOME` is set, otherwise `~/Library/Application Support/xytz/config.yaml` |\n| Windows | `%APPDATA%/xytz/config.yaml`                                                                                         |\n\nOn first run, xytz will create the config file with default values if it doesn't exist.\n\n## CLI Arguments\n\nxytz supports command-line arguments for quick access to search, channels, and playlists.\n\n### Quick Reference\n\n| Flag                     | Short | Description                                          |\n| ------------------------ | ----- | ---------------------------------------------------- |\n| `--number`               | `-n`  | Number of search results                             |\n| `--sort-by`              | `-s`  | Sort results: `relevance`, `date`, `views`, `rating` |\n| `--query`                | `-q`  | Direct search query                                  |\n| `--channel`              | `-u`  | Browse channel (use `@username` format)              |\n| `--channels`             | `-c`  | Search for channels                                  |\n| `--playlist`             | `-p`  | Browse playlist (use playlist ID)                    |\n| `--help`                 | `-h`  | Show help message                                    |\n| `--cookies-from-browser` |       | The browser name to load cookies from                |\n| `--cookies`              |       | Path to a `cookies.txt` file to read cookies from    |\n\n\u003e **Note:** Default values for these flags are grabbed from the configuration file.\n\n### Usage Examples\n\n```bash\n# Direct video search\nxytz -q \"golang tutorial\"\n\n# Browse a specific channel\nxytz -u @username\n\n# Browse a playlist\nxytz -p PLplaylistId\n\n# search for a channel\nxytz -c \"linux\"\n\n# Custom search results and sorting\nxytz -n 50 -s date\n\n# Combined: Search with custom options\nxytz -q \"rust programming\" -n 10 -s views\n```\n\n## Configuration\n\nxytz uses a YAML configuration file located at `~/.config/xytz/config.yaml`.\n\n### Default Configuration\n\n```yaml\nsearch_limit: 25 # Number of search results\ndefault_download_path: ~/Videos # Download destination\ndefault_quality: best # Default format selection (480p, 720p, 1080p, 4k...)\nsort_by_default: relevance # Default sort: relevance, date, views, rating\ntheme: catppuccin-mocha # Preset theme name\nvideo_format: mp4 # The format which videos are downloaded\naudio_format: mp3 # The format which audio files are downloaded\nembed_subtitles: false # Embed subtitles in downloads\nembed_metadata: true # Embed metadata in downloads\nembed_chapters: true # Embed chapters in downloads\nffmpeg_path: \"\" # Custom ffmpeg path (optional)\nyt_dlp_path: \"\" # Custom yt-dlp path (optional)\ncookies_browser: \"\" # Browser for cookies: chrome, firefox, etc (optional)\ncookies_file: \"\" # Path to cookies.txt file for authentication (optional)\nthumbnail_preview: true # Enable thumbnail preview in video list\nthumbnail_timeout_ms: 2500 # Timeout for fetching thumbnails (ms)\n```\n\nThe configuration file is created automatically on first run with sensible defaults.\n\nAvailable theme presets: `catppuccin-mocha` (default), `catppuccin-macchiato`, `rose-pine`, `tokyo-night`, `dracula`, `vesper`.\n\n## Slash Commands\n\nxytz supports slash commands for quick access to various features. Type any of these commands in the search bar:\n\n| Command | Description |\n| ------- | ------------ |\n| `/channel \u003cusername\u003e` | Browse videos from a specific channel |\n| `/channels \u003cquery\u003e` | Search for YouTube channels |\n| `/playlist \u003cid\u003e` | Browse videos in a playlist |\n| `/play \u003curl\u003e` | Play a video directly with mpv (no download) |\n| `/resume` | Resume unfinished downloads |\n| `/theme \u003cname\u003e` | Switch to a different theme |\n| `/help` | Show help and keyboard shortcuts |\n\n## Contributing\n\nContributions are welcome. Please ensure your fork is synced with the upstream repository before submitting pull requests.\n\n### Commit Style\n\n```\n\u003ctype\u003e(\u003cscope\u003e): \u003cdescription\u003e\n\n[optional body]\n[optional footer]\n```\n\n### Pull Request Guidelines\n\n- Keep changes focused and minimal\n- Ensure all tests pass before submitting\n- Update documentation if needed\n- Follow the existing code style\n\n## Troubleshooting\n\n### yt-dlp not found\n\nEnsure yt-dlp is installed and available in your PATH:\n\n```bash\nyt-dlp --version\n```\n\nIf installed in a non-standard location, set `yt_dlp_path` in your config.\n\n### ffmpeg not found\n\nffmpeg is required for most of features to work. Install it and ensure it's in your PATH, or set `ffmpeg_path` in your config.\n\n### Downloads failing\n\n- Check your internet connection\n- Verify the video is available in your region\n- Ensure you have sufficient disk space\n- Check the download path is writable\n- Make sure you have `yt-dlp` and `ffmpeg` installed\n\n## Not seeing enough formats\n- Update `yt-dlp` to the latest version\n\n## Acknowledgments\n\n- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - TUI framework\n- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - YouTube download engine\n- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Styling library\n- [Bubbles](https://github.com/charmbracelet/bubbles) - TUI components\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/#xdagiz/xytz\u0026type=date\u0026legend=top-left\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=xdagiz/xytz\u0026type=date\u0026theme=dark\u0026legend=top-left\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=xdagiz/xytz\u0026type=date\u0026legend=top-left\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=xdagiz/xytz\u0026type=date\u0026legend=top-left\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\nBy [xdagiz](https://github.com/xdagiz)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdagiz%2Fxytz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxdagiz%2Fxytz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxdagiz%2Fxytz/lists"}