YT-DataDownloader

批量读取标签文件中的 YouTube 视频 ID，并通过 yt-dlp 下载视频。使用V2R数据作为示范，默认读取 v2r-labels/ 下的 JSON 标签，支持同目录中的 CSV 标签。

功能

• 合并并去重 train、val、test 等标签中的视频 ID
• 并发下载，可从已完成文件和 SQLite 状态库恢复
• 将已确认不可用的视频标记为终态；网络、限流和 bot challenge 失败会在下次运行时重试
• 每个下载线程在请求前后随机等待 15–20 秒；连续遇到 bot challenge 会额外退避
• 正式下载前尝试从 Chrome Default profile 刷新 YouTube Cookie；刷新失败时使用已有的 Cookie，或无 Cookie 继续执行
• 记录成功、失败及本次运行摘要到输出目录

环境

• Python 3.11+
• uv
• ffmpeg
• Node.js：供 yt-dlp 的 EJS challenge solver 使用

安装 Python 依赖：

uv sync

使用

先校验标签而不下载：

env -u PYTHONPATH uv run python main.py --dry-run

防止屏幕息屏关机，可以在 tmux 中运行，此处使用了 caffeinate； 以四个工作线程开始下载，可以逐渐增加线程数量，8 以上很快会被限制：

caffeinate -i env -u PYTHONPATH uv run python main.py --workers 4

常用参数：

--labels PATH    标签目录；默认 v2r-labels
--output PATH    下载和运行状态的输出目录；默认 video2reaction
--cookies PATH   Cookie 文件路径；默认 cookies.txt
--workers N      并发下载线程数；默认 4
--limit N        仅处理前 N 个去重后的视频 ID
--dry-run        校验标签，不创建下载任务

例如，只下载前 20 个视频到指定目录：

env -u PYTHONPATH uv run python main.py --output ./downloads --workers 2 --limit 20

标签格式

标签目录可同时包含：

• JSON：顶层对象的键为 11 位 YouTube 视频 ID。
• CSV：首列列名为 YouTube ID 或 Video ID，每行首列为视频 ID。

无效 ID 和无法解析的标签文件会写入 failures.jsonl；--dry-run 在出现这类错误时返回非零状态。

输出与恢复

默认输出目录为 video2reaction/，其中包括：

• <video-id>.mp4：已下载的视频文件
• download-state.sqlite3：视频状态和重试信息
• successes.jsonl、failures.jsonl：逐条下载结果
• run-summary.json：本次运行汇总

重复运行会跳过已下载和已确认不可用的视频；未完成的 .part 文件会由 yt-dlp 续传。

Cookie

下载时会尝试从本机 Chrome 的 Default profile 导出并验证 YouTube Cookie，写入 cookies.txt。该文件及工作线程产生的临时副本均已被 Git 忽略，切勿提交或分享。

请仅下载你有权访问、保存和使用的内容，并遵守服务条款及适用法律。

测试

env -u PYTHONPATH uv run python -m unittest -v