xytz - 美观的 TUI YouTube 下载工具

xytz 是一款美观的终端界面（TUI）YouTube 下载工具，基于 Go 语言和 Bubble Tea 框架开发。它提供了交互式的搜索、浏览和下载体验，让用户无需离开终端即可完成 YouTube 视频的搜索、预览和下载操作。

项目简介

xytz 由开发者 xdagiz 创建并维护，是一个开源的 YouTube 下载器，采用终端用户界面（TUI）设计。截至目前，该项目在 GitHub 上已获得 272+ stars 和 21 个 forks。项目使用 Go 语言编写，遵循 MIT 开源协议。

核心特性

• 交互式搜索 - 直接在终端中搜索 YouTube 视频
• 频道浏览 - 使用 /channel @username 查看特定频道的所有视频
• 播放列表支持 - 使用 /playlist <id> 浏览和下载播放列表中的视频
• 格式选择 - 可选择可用的视频/音频格式，并显示质量指示器
• 下载管理 - 实时跟踪下载进度，显示速度和预计完成时间
• 断点续传 - 使用 /resume 恢复未完成的下载
• 视频播放 - 无需下载即可使用 mpv 直接播放视频
• 搜索历史 - 持久化的搜索历史，方便快速访问
• 键盘导航 - 支持 Vim 风格的键绑定和直观的快捷键
• 跨平台 - 支持 Linux、macOS 和 Windows

技术栈

• Go 1.25+ - 主要编程语言
• Bubble Tea - TUI 框架（Charm 生态系统）
• Lipgloss - 样式库
• Bubbles - TUI 组件库
• yt-dlp - 核心视频下载引擎
• ffmpeg - 音视频处理
• mpv（可选）- 视频播放器

安装指南

前置要求

• yt-dlp: 核心视频下载器
• ffmpeg: 完整功能所需
• mpv（可选）: 用于直接播放视频

安装方式

方式一：安装脚本（Linux/macOS）

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

方式二：Homebrew（macOS）

brew install xdagiz/tap/xytz

方式三：AUR（Arch Linux）

yay -S xytz-bin

方式四：Go Install

go install github.com/xdagiz/xytz@latest

方式五：源码编译

# 克隆仓库
git clone https://github.com/xdagiz/xytz.git
cd xytz

# 编译
go build -o xytz .

# 移动到 PATH（可选）
sudo mv xytz /usr/local/bin/

快速开始

启动 xytz：

xytz

基本工作流程

1. 搜索 - 输入查询内容，按 Enter 搜索
2. 选择 - 使用 ↑/↓ 或 j/k 导航结果，按 Enter 选择
3. 选择格式 - 选择偏好的视频/音频格式
4. 下载 - 自动开始下载

CLI 参数

xytz 支持命令行参数，方便快速访问搜索、频道和播放列表：

使用示例

# 直接搜索视频
xytz -q "golang tutorial"

# 浏览特定频道
xytz -c @username

# 浏览播放列表
xytz -p PLplaylistId

# 自定义搜索结果数量和排序
xytz -n 50 -s date

# 组合使用：搜索并自定义选项
xytz -q "rust programming" -n 10 -s views

配置文件

xytz 使用 YAML 格式的配置文件，位置因操作系统而异：

• Linux: ~/.config/xytz/config.yaml
• macOS: ~/.config/xytz/config.yaml（如果设置了 XDG_CONFIG_HOME），否则为 ~/Library/Application Support/xytz/config.yaml
• Windows: %APPDATA%/xytz/config.yaml

默认配置

search_limit: 25                    # 默认搜索结果数量
default_download_path: ~/Videos     # 下载目标路径
default_quality: best               # 默认格式选择 (480p, 720p, 1080p, 4k...)
sort_by_default: relevance          # 默认排序: relevance, date, views, rating
video_format: mp4                   # 视频下载格式
audio_format: mp3                   # 音频下载格式
embed_subtitles: false              # 是否在下载中嵌入字幕
embed_metadata: true                # 是否在下载中嵌入元数据
embed_chapters: true                # 是否在下载中嵌入章节
ffmpeg_path: ""                     # 自定义 ffmpeg 路径（可选）
yt_dlp_path: ""                     # 自定义 yt-dlp 路径（可选）
cookies_browser: ""                 # 用于 cookies 的浏览器: chrome, firefox 等（可选）
cookies_file: ""                    # 用于认证的 cookies.txt 文件路径（可选）

首次运行时会自动创建配置文件并使用默认值。

键盘快捷键

• ↑/↓ 或 j/k - 导航搜索结果
• Enter - 选择/确认
• /channel @username - 浏览频道
• /playlist <id> - 浏览播放列表
• /resume - 恢复未完成的下载

故障排除

yt-dlp 未找到

确保 yt-dlp 已安装并在 PATH 中：

yt-dlp --version

如果安装在非标准位置，请在配置中设置 yt_dlp_path。

ffmpeg 未找到

ffmpeg 是大多数功能正常工作所必需的。请安装并确保它在 PATH 中，或在配置中设置 ffmpeg_path。

下载失败

• 检查网络连接
• 验证视频在您所在地区可用
• 确保有足够的磁盘空间
• 检查下载路径是否可写
• 确保已安装 yt-dlp 和 ffmpeg

项目链接

• GitHub 仓库: https://github.com/xdagiz/xytz
• AUR 包: https://aur.archlinux.org/packages/xytz-bin
• Star History: https://www.star-history.com/#xdagiz/xytz

致谢

• Bubble Tea - TUI 框架
• yt-dlp - YouTube 下载引擎
• Lipgloss - 样式库
• Bubbles - TUI 组件