小鹅通视频批量下载工具 (XET Video Downloader)

一个基于 Playwright 和 yt-dlp 的自动化视频下载工具，专门用于批量下载小鹅通平台的视频课程。

✨ 特性

• 🎯 自动捕获 - 使用 Playwright 自动拦截并捕获 m3u8 视频地址
• 🔐 登录保持 - 使用持久化浏览器会话，首次登录后自动保存状态
• 📦 批量下载 - 支持批量处理多个视频URL
• 🎬 高清优先 - 自动捕获最高清晰度版本 (f421220)
• 📊 友好界面 - 使用 Rich 库提供美观的终端界面
• 💾 信息保存 - 可选保存捕获的视频信息为 JSON 文件
• ⚡ 并发下载 - 使用 yt-dlp 的并发分片下载加速

📋 系统要求

• Python 3.10 或更高版本
• macOS / Linux / Windows
• uv - Python 包管理工具
• yt-dlp - 视频下载工具
• ffmpeg - 视频处理工具（推荐）

🚀 快速开始

1. 安装系统依赖

macOS (使用 Homebrew):

brew install yt-dlp ffmpeg

Linux (Ubuntu/Debian):

sudo apt install yt-dlp ffmpeg

Windows (使用 Scoop):

scoop install yt-dlp ffmpeg

或者使用 pip:

pip install yt-dlp

2. 安装 uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

3. 安装项目依赖

# 克隆或进入项目目录
cd fetch-video

# 使用 uv 安装依赖
uv sync

# 安装 Playwright 浏览器驱动
uv run playwright install chromium

4. 运行程序

uv run python main.py

📖 使用指南

交互式使用

运行程序后，按照提示操作：

1. 输入 URL

   • 选项 1: 手动输入单个或多个URL（用逗号分隔）
   • 选项 2: 从文本文件读取URL列表

2. 选择浏览器模式

   • 首次运行建议显示浏览器窗口，以便完成登录
   • 后续可以使用无头模式（后台运行）

3. 等待捕获

   • 程序会自动访问每个URL并捕获 m3u8 地址
   • 捕获成功后会显示视频列表

4. 下载视频

   • 确认下载后，程序会自动下载所有视频
   • 视频保存在 downloads 目录

从文件批量下载

创建 urls.txt 文件，每行一个URL：

https://appezrn4igg1968.h5.xet.citv.cn/p/course/video/v_xxx1
https://appezrn4igg1968.h5.xet.citv.cn/p/course/video/v_xxx2
https://appezrn4igg1968.h5.xet.citv.cn/p/course/video/v_xxx3

然后运行程序，选择选项 2，输入文件路径。

🔧 配置说明

目录结构

fetch-video/
├── main.py                    # 主程序
├── pyproject.toml            # 项目配置（uv 管理）
├── README.md                 # 说明文档
├── .gitignore               # Git 忽略文件
├── browser_session/         # 浏览器会话数据（自动生成）
├── downloads/               # 视频下载目录（自动生成）
└── captured_videos.json     # 捕获的视频信息（可选生成）

自定义配置

您可以在代码中修改以下参数：

# main.py 中的 VideoDownloader 类初始化
downloader = VideoDownloader(
    user_data_dir="./browser_session",  # 浏览器会话目录
    output_dir="./downloads"             # 视频输出目录
)

🛠️ 高级用法

仅捕获不下载

程序支持先捕获视频信息，保存为 JSON，稍后再下载：

from main import VideoDownloader

downloader = VideoDownloader()
urls = ["https://..."]
downloader.capture_video_urls(urls, headless=True)
downloader.save_captured_info("videos.json")

自定义下载参数

修改 download_video 方法中的 yt-dlp 参数：

cmd = [
    "yt-dlp",
    "--referer", referer,
    "--concurrent-fragments", "10",  # 增加并发数
    "--format", "best",               # 指定格式
    "--merge-output-format", "mp4",  # 合并格式
    "-o", output_template,
    media_url
]

⚠️ 注意事项

1. 首次登录

   • 首次运行请选择"显示浏览器窗口"
   • 在弹出的浏览器中完成微信/手机号登录
   • 登录后会自动保存在 browser_session 目录

2. 多清晰度

   • 程序默认捕获最高清版本（v.f421220）
   • 如需其他清晰度，可修改 setup_request_handler 中的过滤条件

3. 网络问题

   • 确保网络稳定
   • 下载失败可以重新运行程序，已下载的视频不会重复下载

4. 法律声明

   • 仅用于下载您已购买/有权访问的课程
   • 请勿用于侵权目的

🐛 故障排除

问题: 未捕获到视频地址

解决方案:

• 确保已登录（使用显示浏览器模式）
• 增加等待时间（修改 page.wait_for_timeout(5000) 的值）
• 检查 URL 是否正确

问题: 下载失败

解决方案:

• 检查 yt-dlp 和 ffmpeg 是否正确安装
• 查看错误信息，可能是网络问题
• 尝试手动使用 yt-dlp 下载测试

问题: Playwright 浏览器未安装

解决方案:

uv run playwright install chromium

📝 示例

示例 1: 下载单个视频

$ uv run python main.py
# 选择选项 1: 手动输入
# 输入 URL: https://appezrn4igg1968.h5.xet.citv.cn/p/course/video/v_xxx
# 选择显示浏览器: 是
# 等待捕获...
# 确认下载: 是

示例 2: 批量下载

创建 urls.txt:

https://appezrn4igg1968.h5.xet.citv.cn/p/course/video/v_xxx1
https://appezrn4igg1968.h5.xet.citv.cn/p/course/video/v_xxx2

运行:

$ uv run python main.py
# 选择选项 2: 从文件读取
# 输入文件路径: urls.txt
# 选择显示浏览器: 否（如已登录）
# 等待捕获...
# 确认下载: 是

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

🙏 致谢

• Playwright - 浏览器自动化
• yt-dlp - 视频下载
• Rich - 终端美化

📧 联系方式

如有问题或建议，请提交 Issue。

---

Happy Downloading! 🎉