diff --git a/README.md b/README.md index 60ecdfb..3afd749 100644 --- a/README.md +++ b/README.md @@ -1,306 +1,165 @@ # YouTube Downloader Pro -一个基于 Python、yt-dlp 和 FFmpeg 开发的现代化 YouTube 视频下载工具。 +一个基于 PySide6 + yt-dlp 的跨平台桌面 YouTube 视频下载工具,支持视频、播放列表、字幕和封面下载,内置 FFmpeg 音视频合并。 -![Version](https://img.shields.io/badge/version-1.0.0-blue) -![Python](https://img.shields.io/badge/python-3.12+-green) -![License](https://img.shields.io/badge/license-MIT-yellow) +

+ 🎬 视频下载 · 📋 播放列表 · 💬 字幕 · 🖼️ 封面 · 🔗 自动合并 +

--- ## ✨ 功能特性 -### 核心功能 +- **单视频下载** — 支持多种分辨率/格式选择,从 144p 到 8K +- **播放列表批量下载** — 自动解析播放列表,支持选择性下载 +- **字幕下载** — 支持手动/自动字幕,多种语言,可导出 SRT/VTT 格式 +- **封面下载** — 自动下载视频封面,多级清晰度回退(maxresdefault → default) +- **音视频合并** — 自动调用 FFmpeg 将分离视频/音频流合并为高质量 MP4 +- **Cookie 认证** — 支持导入浏览器 cookies.txt 或自动读取浏览器 cookie +- **多线程下载** — 可配置 1-32 个并行下载,线程池管理 +- **主题切换** — 内置暗色/亮色主题,支持跟随系统 +- **暂停/取消** — 单个任务支持暂停恢复和取消操作 +- **反检测** — 50 个真实浏览器 User-Agent 轮换,模拟浏览器请求头 +- **格式智能分类** — 自动区分合并流、纯视频、纯音频,UI 清晰展示 -- 🎬 **单视频下载** — 支持多种清晰度选择,从 144P 到 8K -- 📋 **播放列表下载** — 批量解析播放列表,支持选择性下载 -- 🔗 **高清视频自动合并** — 自动下载音视频流并使用 FFmpeg 合并 -- 📝 **字幕下载** — 支持自动字幕和官方字幕(SRT/VTT 格式) -- 🖼 **封面下载** — 高质量封面图保存(JPG/PNG) -- ⚡ **多线程下载** — 可配置 1-32 线程并发,充分利用带宽 -- 📊 **下载队列管理** — 支持暂停、恢复、取消和失败重试 -- 🎨 **深色/浅色主题** — 支持跟随系统主题自动切换 +## 📋 系统要求 -### 特色亮点 +- **操作系统**: Windows / macOS / Linux +- **Python**: 3.9+ +- **外部工具**: [FFmpeg](https://ffmpeg.org/download.html)(可选,用于音视频合并) -- 现代化 PySide6 界面,操作流畅 -- 实时下载进度显示(速度、进度条、剩余时间) -- 批量下载设置自由组合(视频/音频/字幕/封面) -- 完整日志系统,方便问题排查 -- 自动检测 FFmpeg,无需手动配置 +## 🚀 快速开始 ---- - -## 📸 界面截图 - -> 截图位置预留 — 请在应用运行后截图替换 - -``` -┌──────────────────────────────────────────────────────┐ -│ 🔗 [YouTube URL 输入框..................] [获取信息] [下载] │ -├──────────────────────────────────────────────────────┤ -│ ┌─────────┐ │ -│ │ 封面图 │ 视频标题 │ -│ │ │ 👤 作者 ⏱ 时长 📅 上传日期 │ -│ └─────────┘ │ -├──────────────────────────────────────────────────────┤ -│ 格式选择 │ -│ 🎬 视频格式: [1080p | MP4 | AVC1 | 60FPS | 1.2GB ▾] │ -│ 🎵 音频格式: [MP3 192kbps ▾] │ -├──────────────────────────────────────────────────────┤ -│ ☑ 下载字幕 [中文 ▾] ☐ 下载封面 ☑ 自动合并音视频 │ -├──────────────────────────────────────────────────────┤ -│ 下载队列 [暂停] [恢复]│ -│ 任务 │ 状态 │ 速度 │ 已下载/总大小 │ 进度 │ 操作 │ -│ ... │ 下载中│ 5MB/s│ 45M/300M │ [=== ]│ [取消] │ -└──────────────────────────────────────────────────────┘ -``` - ---- - -## 🔧 安装教程 - -### 环境要求 - -| 组件 | 要求 | -|------|------| -| Python | 3.12 或更高版本 | -| pip | 最新版本 | -| FFmpeg | 用于高清视频音视频合并(可选但推荐) | - -### 步骤 1: 克隆项目 - -```bash -git clone https://github.com/xiaohui/youtube-downloader-pro.git -cd youtube-downloader-pro -``` - -### 步骤 2: 创建虚拟环境(推荐) - -```bash -# Windows -python -m venv venv -venv\Scripts\activate - -# macOS / Linux -python3 -m venv venv -source venv/bin/activate -``` - -### 步骤 3: 安装依赖 +### 1. 安装 Python 依赖 ```bash pip install -r requirements.txt ``` -### 步骤 4: 运行应用 +### 2. 安装 FFmpeg(推荐) + +- **Windows**: 下载 [gyan.dev FFmpeg](https://www.gyan.dev/ffmpeg/builds/) essentials 版本,将 `ffmpeg.exe` 加入 PATH +- **macOS**: `brew install ffmpeg` +- **Linux**: `sudo apt install ffmpeg` (Debian/Ubuntu) 或 `sudo dnf install ffmpeg` (Fedora) + +也可以启动应用后通过 **帮助 → 检查 FFmpeg 状态** 自动下载安装。 + +### 3. 运行应用 ```bash python main.py ``` ---- +### 4. (可选)配置 Cookie -## 🎬 FFmpeg 配置教程 +如果遇到 YouTube 反爬验证,可配置 Cookie 绕过: -高清视频(1080P 及以上)通常音频和视频流分离,需要 FFmpeg 合并。 +1. 安装浏览器扩展 [Get cookies.txt LOCALLY](https://chrome.google.com/webstore/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc) +2. 导出 `cookies.txt` 并在应用设置中指定路径 -### Windows 安装 - -1. 访问 [FFmpeg 官网](https://ffmpeg.org/download.html) -2. 下载 Windows 版本(推荐 gyan.dev 或 BtbN 构建版) -3. 解压到 `C:\ffmpeg\` -4. 将 `C:\ffmpeg\bin\` 添加到系统环境变量 PATH -5. 或直接在应用设置中手动指定 `ffmpeg.exe` 路径 - -### macOS 安装 +## 📦 打包为 EXE ```bash -brew install ffmpeg +# 使用 spec 文件打包 +pyinstaller "YouTube Downloader Pro.spec" + +# 或使用命令行 +pyinstaller --onefile --windowed --name "YouTube Downloader Pro" main.py ``` -### Linux 安装 - -```bash -# Ubuntu/Debian -sudo apt install ffmpeg - -# Fedora -sudo dnf install ffmpeg - -# Arch -sudo pacman -S ffmpeg -``` - -### 验证安装 - -```bash -ffmpeg -version -``` - -应用会自动检测 FFmpeg,也可在 **设置 → 高级 → FFmpeg 路径** 中手动指定。 - ---- - -## 📖 使用方法 - -### 下载单个视频 - -1. 复制 YouTube 视频链接 -2. 粘贴到应用顶部输入框 -3. 点击 **获取信息** 查看视频详情 -4. 选择需要的清晰度和格式 -5. 可选勾选字幕、封面下载 -6. 点击 **下载** - -### 下载播放列表 - -1. 复制播放列表链接(如 `https://www.youtube.com/playlist?list=xxx`) -2. 粘贴并点击 **获取信息** -3. 在列表中勾选需要下载的视频(支持全选/取消全选) -4. 点击 **下载选中** - -### 批量下载设置 - -在下载选项区域可自由组合: -- ✅ 下载视频 + ✅ 下载字幕 + ✅ 下载封面 -- ✅ 仅下载音频(选择音频格式) -- 任意组合 - -### 下载队列管理 - -- **暂停/恢复**: 控制下载进程 -- **取消**: 取消单个或全部任务 -- **重试失败**: 一键重试所有失败任务 -- **清空已完成**: 清理已完成的任务记录 - ---- +输出文件位于 `dist/YouTube Downloader Pro.exe`。 ## 📁 项目结构 ``` youtube_downloader/ -├── main.py # 应用入口 -├── __init__.py # 包初始化 +├── main.py # 应用入口,初始化日志/配置/窗口 +├── requirements.txt # Python 依赖清单 +├── YouTube Downloader Pro.spec # PyInstaller 打包配置 +├── __init__.py │ -├── ui/ # UI 层 -│ ├── __init__.py -│ ├── main_window.py # 主窗口 -│ ├── settings_window.py # 设置窗口 -│ ├── about_window.py # 关于窗口 -│ └── widgets/ # 可复用组件 -│ └── __init__.py +├── ui/ # 用户界面层 +│ ├── main_window.py # 主窗口(~1860 行),QStackedWidget 三页面 +│ ├── settings_window.py # 设置对话框(通用/格式/高级/外观) +│ ├── about_window.py # 关于窗口 +│ ├── theme.py # 暗色/亮色 QSS 主题 +│ └── widgets/ # 可复用组件(预留) │ -├── downloader/ # 下载器核心 -│ ├── __init__.py -│ ├── video_downloader.py # 视频下载逻辑 -│ ├── playlist_downloader.py # 播放列表解析 -│ ├── subtitle_downloader.py # 字幕下载 -│ ├── thumbnail_downloader.py # 封面下载 -│ ├── ffmpeg_merger.py # FFmpeg 合并 -│ ├── format_parser.py # 格式解析 -│ └── download_queue.py # 下载队列管理 +├── downloader/ # 下载引擎层 +│ ├── video_downloader.py # yt-dlp 封装,独立实例保证线程安全 +│ ├── download_queue.py # ThreadPoolExecutor 队列管理器 +│ ├── format_parser.py # 视频信息/格式/字幕提取 +│ ├── playlist_downloader.py # 播放列表解析 +│ ├── subtitle_downloader.py # 字幕下载(yt-dlp / HTTP 直连) +│ ├── thumbnail_downloader.py # 封面下载(多级清晰度回退) +│ ├── ffmpeg_merger.py # FFmpeg 子进程合并音视频 +│ └── ffmpeg_installer.py # FFmpeg 自动下载安装 │ -├── models/ # 数据模型 -│ ├── __init__.py -│ ├── task.py # 下载任务模型 -│ └── settings.py # 设置模型 +├── models/ # 数据模型层 +│ ├── task.py # DownloadTask, VideoInfo, VideoFormat 等 +│ └── settings.py # Settings 数据类,ThemeMode 枚举 │ -├── config/ # 配置管理 -│ ├── __init__.py -│ └── settings_manager.py # 设置持久化 +├── config/ # 配置管理层 +│ └── settings_manager.py # 单例 SettingsManager,原子写入 │ -├── utils/ # 工具模块 -│ ├── __init__.py -│ ├── logger.py # 日志系统 -│ └── validators.py # URL 验证 -│ -├── resources/ # 资源文件 -│ ├── icons/ -│ └── images/ -│ -├── requirements.txt # 依赖清单 -└── README.md # 项目文档 +└── utils/ # 工具层 + ├── logger.py # RotatingFileHandler 日志系统 + ├── validators.py # YouTube URL 正则验证 + └── user_agents.py # 50 个真实 UA 轮换池 ``` ---- +## 🧵 线程模型 -## 📦 打包为 EXE +| 线程类型 | 实现方式 | 说明 | +|---------|---------|------| +| 主线程 | Qt 事件循环 | 所有 UI 更新 | +| 下载线程 | `ThreadPoolExecutor` | 1-32 个工作线程,每个任务独立 `VideoDownloader` 实例 | +| 信息获取 | `QThread` 子类 | 格式解析、播放列表获取 | +| 队列监控 | `threading.Thread` 守护线程 | 每秒轮询检测全部完成 | +| UI 刷新 | `QTimer` 500ms | 主线程定时器轮询进度 | -### 使用 PyInstaller 打包为单文件 EXE +## ⚙️ 配置说明 -```bash -# 安装 PyInstaller -pip install pyinstaller +配置文件存储在 `~/.youtube_downloader_pro/settings.json`,支持以下设置: -# 打包 -pyinstaller --onefile --windowed --name "YouTube Downloader Pro" main.py -``` +- **下载目录** — 自定义保存路径 +- **并行下载数** — 1-32 个并发任务 +- **主题模式** — 暗色 / 亮色 / 跟随系统 +- **Cookie 配置** — cookies.txt 路径或浏览器自动提取 +- **FFmpeg 路径** — 自定义 FFmpeg 可执行文件路径 +- **字幕语言** — 默认下载语言 +- **自动合并** — 启用/禁用 FFmpeg 音视频合并 -或使用提供的 spec 文件: +## 🛠️ 技术栈 -```bash -pyinstaller "YouTube Downloader Pro.spec" -``` +| 组件 | 技术 | +|------|------| +| GUI 框架 | PySide6 ≥ 6.5.0 | +| 下载引擎 | yt-dlp ≥ 2024.1.1 | +| HTTP 请求 | requests ≥ 2.28.0 | +| 音视频处理 | FFmpeg | +| 打包工具 | PyInstaller | +| 主题检测 | darkdetect(可选) | -打包后的 EXE 文件位于 `dist/` 目录,用户无需安装 Python 即可运行。 +## 📝 开发笔记 ---- - -## ❓ 常见问题 - -### Q: 下载失败:`ERROR: Unable to download webpage` - -**A:** 这通常是网络问题: -- 检查网络连接是否正常 -- 尝试使用代理(设置 → 高级 → 代理服务器) -- yt-dlp 会自动处理大部分 YouTube 变更,保持版本更新 - -### Q: 高清视频没有声音 - -**A:** 需要 FFmpeg 合并音视频流: -- 确认 FFmpeg 已安装(状态栏可查看) -- 勾选"自动合并音视频"选项 -- yt-dlp 会自动下载音视频流并调用 FFmpeg 合并 - -### Q: 字幕下载失败 - -**A:** -- 检查视频是否有对应语言的字幕 -- 尝试切换自动字幕/官方字幕 -- 部分视频可能没有特定语言的字幕 - -### Q: 如何更新 yt-dlp? - -```bash -pip install --upgrade yt-dlp -``` - -### Q: 下载速度慢 - -**A:** -- 在设置中增加下载线程数 -- 检查是否启用了下载限速 -- 使用代理服务器可能改善连接 - ---- - -## 👨‍💻 开发者 - -- **开发者:** xiaohui -- **网站:** [https://www.itxiaohui.top](https://www.itxiaohui.top) -- **GitHub:** [https://github.com/xiaohui/youtube-downloader-pro](https://github.com/xiaohui/youtube-downloader-pro) - ---- +- 无单元测试框架(待添加) +- UI 文本为中文(zh_CN) +- 配置采用原子写入(先写 `.tmp` 再重命名),防止写入中断导致配置损坏 +- 日志轮转:单文件 5 MB,保留 3 个备份 +- 每个下载任务创建独立 `VideoDownloader` 实例,避免多线程状态交叉 +- `_active_downloaders` 字典受 `threading.Lock` 保护 ## 📄 许可证 -MIT License — 详见 LICENSE 文件 +本项目仅供个人学习和研究使用。请遵守 YouTube 服务条款,尊重版权。 ---- +## 🔗 开发者 -## ⚠️ 免责声明 +- 网站:[https://www.itxiaohui.top/](https://www.itxiaohui.top/) -本工具仅供个人学习和研究使用。请遵守 YouTube 服务条款和当地法律法规。下载受版权保护的内容需获得权利人授权。 -# YouTube-Downloader-Pro - \ No newline at end of file +## 🤝 致谢 + +- [yt-dlp](https://github.com/yt-dlp/yt-dlp) — 强大的 YouTube 下载核心库 +- [FFmpeg](https://ffmpeg.org/) — 音视频处理利器 +- [PySide6](https://wiki.qt.io/Qt_for_Python) — Qt for Python 官方绑定