[](https://www.python.org/downloads/)
[](https://pepy.tech/project/ytsage)
[](https://github.com/oop7/YTSage/releases)
[](https://opensource.org/licenses/MIT)
[](https://github.com/oop7/YTSage/releases)
[](https://github.com/oop7/YTSage/stargazers)
[](https://pypi.org/project/ytsage/)
[](https://github.com/sponsors/oop7)
**一款现代、整洁、基于 PySide6 的 YouTube 下载器。**
支持下载任意质量的视频、提取音频、获取字幕等更多功能。
### 🌍 README 语言
英语: [EN](../README.md)
| 阿拉伯语: [AR](README.ar.md)
| 德语: [DE](README.de.md)
| 西班牙语: [ES](README.es.md)
| 法语: [FR](README.fr.md)
| 印地语: [HI](README.hi.md)
| 印尼语: [ID](README.id.md)
| 意大利语: [IT](README.it.md)
| 日语: [JA](README.ja.md)
| 波兰语: [PL](README.pl.md)
| 葡萄牙语: [PT](README.pt.md)
| 俄语: [RU](README.ru.md)
| 土耳其语: [TR](README.tr.md)
| 中文: [ZH](README.zh.md)
安装 •
功能 •
使用说明 •
屏幕截图 •
故障排除 •
赞助支持 •
贡献
---
## ❓ 为什么选择 YTSage?
YTSage 专为寻找 **简单但强大** 的 YouTube 下载器的用户而设计。与其他工具不同，它提供：
- 现代、整洁的 PySide6 用户界面
- 一键下载视频、音频和字幕
- 支持 SponsorBlock、字幕合并和播放列表选择等高级功能
- 可选的“通用模式”，支持 yt-dlp 兼容的其他非 YouTube 网站
- 跨平台支持，安装简单
## ✨ 功能
| 核心功能 | 高级功能 | 更多功能 |
|-----------------------------------|-----------------------------------------|------------------------------------|
| 🎥 格式选择列表 | 🚫 集成 SponsorBlock | 🎞️ FPS / HDR 显示 |
| 🎵 音频提取 | 📝 字幕选择与合并 | 🔄 yt-dlp 自动更新 |
| ✨ 现代 UI 体验 | 💾 保存描述与缩略图 | 🛠️ FFmpeg/yt-dlp/Deno 检测 |
| 📋 播放列表支持与选择 | 🚀 下载限速 | ⚙️ 自定义参数支持 |
| 📑 视频列表集成 | ✂️ 视频剪辑 | 🍪 Cookie 登录集成 |
| 📜 下载历史记录 | 🔄 更新版本分支选择 | 🌐 代理支持 |
| 🎚️ 音频格式转换 | 🎬 视频格式设置 | 🆙 内置更新页签 |
| 🌍 通用模式 | 🔊 音频归一化 (EBU R128) | 🌍 支持 14 种语言 |
| 💾 播放列表导出 | ⚙️ 默认质量与字幕设置 | |
## 🚀 安装
### ⚡ 快速安装 (推荐)
通过 PyPI 安装 YTSage：
```bash
pip install ytsage
```
🔄 更新现有安装
```bash
pip install --upgrade ytsage
```
然后通过以下命令运行：
```bash
ytsage
```
### 📦 独立可执行文件
> [👉 下载最新版本](https://github.com/oop7/YTSage/releases/latest)
#### 🪟 Windows
| 格式 | 说明 |
|--------|-------------|
|  | 标准安装程序 |
|  | 包含 FFmpeg 的安装程序 |
|  | 便携版 (无需安装) |
|  | 包含 FFmpeg 的便携版 (ZIP) |
🛠️ 安装步骤
1. **EXE 安装程序 (`.exe`)**: 双击并按照安装向导进行操作。
2. **便携版 (`.zip`)**: 解压到所需位置并运行 `ytsage.exe`。
3. **内置 FFmpeg**: 如果系统没有安装 FFmpeg，请选择带 `-ffmpeg` 的版本。
#### 🐧 Linux
| 格式 | 说明 |
|--------|-------------|
|  | Debian 软件包 |
|  | 便携 AppImage |
|  | RPM 软件包 |
|  | Flatpak 软件包 |
🛠️ 安装步骤
- **DEB (`.deb`)**:
```bash
sudo dpkg -i ytsage_*.deb
sudo apt-get install -f # 如有依赖问题请运行
```
- **RPM (`.rpm`)**:
```bash
sudo rpm -i ytsage-*.rpm
```
- **AppImage (`.AppImage`)**:
```bash
chmod +x YTSage-*.AppImage
./YTSage-*.AppImage
```
- **Flatpak**: 按照 Flathub 的说明或运行：
```bash
flatpak install flathub io.github.oop7.ytsage
```
#### 🍎 macOS
| 格式 | 说明 |
|--------|-------------|
|  | Apple Silicon 专用 ZIP 压缩包 |
|  | Apple Silicon 专用 DMG 安装程序 |
🛠️ 安装步骤
- **DMG 安装程序 (`.dmg`)**: 双击挂载，然后将 `YTSage.app` 拖入 Applications 文件夹。
- **ZIP 应用包 (`.zip`)**: 解压并移动 `YTSage.app` 到 Applications 文件夹。
*注意：如果遇到“应用已损坏”的提示，请参阅下方的 macOS 解决办法。*
---
💻 从源码手动安装
### 1. 克隆仓库
```bash
git clone https://github.com/oop7/YTSage.git
cd YTSage
```
### 2. 安装依赖
#### ⚡ 使用 uv
```bash
uv pip install .
```
#### 📦 或使用标准 pip
```bash
pip install .
```
### 3. 运行程序
```bash
python -m ytsage.main
```
## 📸 屏幕截图
## 📖 使用说明
🎯 基本使用方法
1. **运行 YTSage**
2. **粘贴 YouTube 地址** (或点击 "Paste URL")
3. **点击 "Analyze" (分析)**
4. **选择下载模式:**
- `Video` 下载视频
- `Audio Only` 仅提取音频
5. **配置下载项:**
- 启用字幕并选择语言
- 启用字幕合并 (Merge)
- 保存缩略图 (Save Thumbnail)
- 启用赞助内容跳过 (SponsorBlock)
- 下载描述文本 (Save Description)
- 嵌入视频章节 (Embed Chapters)
6. **选择路径**
7. **点击 "Download" (下载)**
> 💡 默认下载到系统的“下载”文件夹。
📋 下载播放列表
1. **粘贴播放列表地址**
2. **添加并分析**
3. **在弹出窗口中选择视频 (默认全选)**
4. **设置质量方案**
5. **开始下载**
> 💡 程序会自动管理下载队列。您可以将列表导出为 `.txt`, `.csv`, `.m3u` 或 `.json` 格式。
🌍 非 YouTube 网站 (通用模式)
当您想从被 yt-dlp 支持的其他网站（如 TikTok、Dailymotion 等）下载时，请开启通用模式。
如何使用：
1. 打开 `Download Settings` (下载设置)。
2. 启用 `Generic Mode` (通用模式)。
3. 输入非 YouTube 的支持网站链接。
4. 点击 `Analyze` (分析)。
5. 正常下载。
说明：
- 通用模式仅关闭了 YTSage 内部的 URL 类型检查。网站支持程度仍取决于您安装的 yt-dlp。
- 有些站点可能需要特定的 Cookie 或代理配置。
- 如果某个网站无法分析，请先在内置更新程序中更新 yt-dlp。
🧰 媒体与下载选项
- **字幕选项:** 过滤特定语言并支持嵌入到视频中。
- **字幕合并:** 将字幕“烧录”到视频中（硬字幕）。
- **保存描述:** 将视频描述保存为独立的文本文档。
- **保存缩略图:** 下载视频的高清封面。
- **嵌入章节:** 允许将视频章节标记写入媒体元数据。
- **赞助商跳过:** 配合 SponsorBlock 自动跳过或剪辑掉广告段落。
- **视频剪裁:** 输入 `HH:MM:SS` 时间点来实现部分下载。
⚙️ 文件与输出设置
- **下载限速:** 输入如 `500K` 表示限制为 500 KB/s。
- **保存路径:** 在 **Download Settings → Download Path** 中保存您的默认位置。
- **默认分辨率:** 设置您首选的清晰度（如 1080p, 720p）。
- **默认字幕语言:** 输入语言代码（如 `zh,en`）来自动选择默认字幕。
- **文件命名模板:** 通过 `%(title)s` 等变量自定义文件名格式。
- **强制输出格式:** 强制转换输出容器，如 `mp4`, `webm` 或 `mkv`。
- **音频转换:** 将音频转换为 `AAC`, `MP3`, `FLAC` 等格式。
- **音量归一化:** 使用 EBU R128 标准使下载的音量均衡。
- **多线程连接:** 设置 **Concurrent Connections** 为 8-10 以最大化下载速度。
🌐 进阶访问与网络
- **Cookie 登录:** 允许通过 Cookie 下载私人内容或绕过限制。
推荐方法：
1. 在设置中点击 `Extract cookies from browser`，选择您的浏览器。
2. 或：导出 Netscape 格式的 `cookies.txt` 文件并手动载入。
- **代理支持:** 支持设置 HTTP 代理，例如 `http://127.0.0.1:8080`。
🛠️ 系统工具与维护
- **自定义参数:** 为 yt-dlp 传递特定的命令行参数。
- **内置更新器:** (在 Custom Options 中)
- **yt-dlp 更新:** 在稳定版和测试版之间切换。
- **FFmpeg 检测:** 验证安装路劲。
- **Deno 更新:** 维护相关的集成环境。
- **下载历史:** 管理您的所有下载历史记录，包含缩略图和状态。
🌍 语言支持
YTSage 支持 **14 种语言**。您可以在 **Custom Options → Language** 中更改。
### 支持的界面语言
| 语言 | 代码 | 语言 | 代码 |
|----------|------|----------|------|
| 🇺🇸 英语 | `en` | 🇪🇸 西班牙语 | `es` |
| 🇸🇦 阿拉伯语 | `ar` | 🇫🇷 法语 | `fr` |
| 🇩🇪 德语 | `de` | 🇮🇳 印地语 | `hi` |
| 🇮🇩 印尼语 | `id` | 🇮🇹 意大利语 | `it` |
| 🇯🇵 日语 | `ja` | 🇵🇱 波兰语 | `pl` |
| 🇧🇷 葡萄牙语 | `pt` | 🇷🇺 俄语 | `ru` |
| 🇹🇷 土耳其语 | `tr` | 🇨🇳 中文 | `zh` |
### README 翻译版
| 语言 | 文件 | 语言 | 文件 |
|----------|------|----------|------|
| 🇺🇸 英语 | [README.md](../README.md) | 🇪🇸 西班牙语 | [README.es.md](README.es.md) |
| 🇸🇦 阿拉伯语 | [README.ar.md](README.ar.md) | 🇫🇷 法语 | [README.fr.md](README.fr.md) |
| 🇩🇪 德语 | [README.de.md](README.de.md) | 🇮🇳 印地语 | [README.hi.md](README.hi.md) |
| 🇮🇩 印尼语 | [README.id.md](README.id.md) | 🇮🇹 意大利语 | [README.it.md](README.it.md) |
| 🇯🇵 日语 | [README.ja.md](README.ja.md) | 🇵🇱 波兰语 | [README.pl.md](README.pl.md) |
| 🇧🇷 葡萄牙语 | [README.pt.md](README.pt.md) | 🇷🇺 俄语 | [README.ru.md](README.ru.md) |
| 🇹🇷 土耳其语 | [README.tr.md](README.tr.md) | 🇨🇳 中文 | [README.zh.md](README.zh.md) |
> 💡 **想要贡献翻译?** 欢迎查看 [贡献指南](#贡献) 部分！
## 🛠️ 故障排除
常见问题解答
- **没有显示格式表格:** 请更新 yt-dlp。如果仍无效，请尝试切换到测试版 (Nightly) 分支。
- **下载失败:** 请检查网络连接或该地区视频是否可用。
- **常见特定的错误提示:**
- **私有视频:** 需提供 Cookie 登录。
- **内容受限:** 部分视频需登录账号。
- **地理锁定:** 需使用代理或 VPN。
- **视频已删除:** 视频已不存在。
- **直播内容:** YTSage 目前不支持实时直播下载，请等直播结束后再试。
- **下载后画面和声音分离:** 意味着系统中未安装或未检测到 FFmpeg。
- **解决方法:** 确保 FFmpeg 已安装并加入 PATH，或下载带 `-ffmpeg` 版本的 Windows 程序。
---
#### 🛡️ Windows Defender / 杀毒软件警告
某些杀毒软件可能会误报。这是打包程序的常见现象。
**原因:**
- 启发式查杀可能会误认为打包的可执行文件是恶意软件。
**安全建议:**
- ✅ **通过 pip 安装:** `pip install ytsage`（推荐）
- ✅ **自行构建**: 参照 [CI_CD 指南](../.github/CI_CD_README.md)
- ✅ **添加排除项**。
#### 🍎 macOS: "应用已损坏，无法打开"
在 macOS Sonoma 及以后版本：
1. 打开 **终端 (Terminal)**。
2. 输入命令 (结尾有一个空格):
```bash
xattr -d com.apple.quarantine
```
3. 从 Finder 中将 **YTSage.app** 拖入终端窗口。
4. 按回车。
5. 再次打开应用。
---
#### **配置存放路径**
- **Windows:** `%LOCALAPPDATA%\YTSage`
- **macOS:** `~/Library/Application Support/YTSage`
- **Linux:** `~/.local/share/YTSage`
## 💖 赞助支持
如果 YTSage 节省了您的时间，请考虑资助本项目。赞助收入将用于多平台测试环境的维护和新功能开发。
- GitHub Sponsors: https://github.com/sponsors/oop7
- 您也可以通过应用内的“About (关于)”窗口找到捐赠链接。
[](https://github.com/sponsors/oop7)
## 👥 贡献
感谢所有帮助！
1. 🍴 Fork 仓库
2. 🌿 创建特性分支: `git checkout -b feature/NewFeature`
3. 💾 提交更改: `git commit -m 'Add NewFeature'`
4. 📤 推送分支: `git push origin feature/NewFeature`
5. 🔄 开启 Pull Request
### 🌍 翻译贡献
- 您可以更新各语种 README (例如 `readme-translations/README.zh.md`)。
- 也可以翻译界面词条：`ytsage/languages/<语言代码>.json`。
📂 项目结构
## YTSage - 项目结构
### 📁 目录概览
```
YTSage/
├── 📁 .github/ # GitHub 设置
│ ├── 📁 ISSUE_TEMPLATE/ # 问题模板
│ ├─── 📁 workflows/ # GitHub Actions 流程
├── 📁 branding/ # 品牌资源 (截图, SVG)
│ ├── 📁 icons/ # 图标
│ ├── 📁 screenshots/ # 截图说明
│ └── 📁 svg/ # SVG 素材
├── 📄 LICENSE # 许可证
├── 📄 pyproject.toml # 项目元数据与依赖
├── 📄 README.md # 英语 README
├── 📄 requirements.txt # 开发依赖
└── 📁 ytsage/ # 源代码
├── 📁 assets/ # 运行时资源 (音频, 图标)
├── 📁 languages/ # 多语言 JSON 文件
├── 📁 core/ # 下载与集成核心逻辑
├── 📁 gui/ # UI 组件
├── 📁 utils/ # 工具类
├── 📄 __init__.py
└── 📄 main.py # 程序入口
```
## ⭐️ 关注趋势
## Star History
查看致谢名单
特别鸣谢所有通过反馈、建议或代码合并来完善此工具的贡献者。
## ⚠️ 免责声明
本工具仅供个人学习与研究使用。请尊重 YouTube 服务条款及创作者版权。
---
由 [oop7](https://github.com/oop7) 倾力协作 ❤️
