videodl-download
概述
运行环境里下载视频常因两个原因失败：(1) 多数视频 CDN 对数据中心 IP 限速或中断长连接，单流下载会撞上 IncompleteRead 下到一半就断；(2) B 站等平台对裸请求做 412 风控，但 videodl 自带的 header 不一定够稳。本技能用 videodl 解析出真实流地址，再用"分块 Range 请求"下载，绕开断流，并按需 ffmpeg 合并音视频。
使用边界与免责声明
- 本技能仅供个人学习、研究使用，禁止任何商业用途（上游 videofetch 采用 PolyForm-Noncommercial 许可，商用即违约）；
- 下载内容的版权归原作者所有，请勿传播或二次分发受版权保护的内容；
- 付费/会员内容请先开通正版会员再下载，无登录态时高清资源不可得属正常；
- 脚本中的分块 Range 下载与 Referer 注入仅为解决运行环境网络兼容问题，使用者需自行确保下载行为符合目标平台服务条款及当地法律；
- 因使用本技能产生的一切纠纷由使用者自行承担。
你的工作方式
Phase 1：确认目标
用户已经给了视频链接就直接进 Phase 2。仅在以下情况追问：
- 没给链接；
- 一次给了多个链接，问下哪一个或全部下；
- 链接落在"已知不支持"范围（见底部表格）。
Phase 1.5：环境自检
执行 python3 -c "from videodl import videodl"：
- 失败：pip install videofetch（运行环境只通 PyPI，GitHub 不通）；
- 同时确认 which ffmpeg 有结果（用于音视频合并）。
Phase 2：调用脚本下载
python3 scripts/video_dl.py "<视频链接>" [客户端名]
- 不传客户端名时 videodl 自动匹配；
- 想显式指定时，常见客户端名见 references/platforms.md；
- 脚本流程概述：
1. 用 videodl 解析出download_url（视频流），必要时还有audio_download_url；
2. 对每个流先Range: bytes=0-0拿到Content-Range中的总大小；
3. 以 2 MB 为一块循环拉取，每块最多重试 30 次；
4. 音视频分离时用 ffmpeg-c copy合并；
5. 输出文件落在./<标题>.mp4。 - 详细原理与参数见 references/how-it-works.md。
Phase 3：交付
下载完成后：
- 用 ffprobe 校验时长/编码无误；
- 把视频交付交给用户；
- 简明报告：文件路径、大小、时长。
遇到错误先按 references/troubleshooting.md 排查，必要时再换客户端重试或如实告知用户。
已知限制
| 情况 | 处理 |
|---|---|
| YouTube | 受限网络下被墙；能直连可先试，不通再走 yt-dlp 本机方案 |
| X / Twitter 视频 | videodl 不在支持列表，请告知用户需走本机方案 |
| 需要登录的内容 | 运行环境无账号，通常只能下到 360p/720p；想要 1080p+ 由用户在本机用 yt-dlp + cookie |
| 大文件慢 | B 站 CDN 对运行环境限速约 135 kB/s；70 MB 视频约需 9 分钟 |
| 412 风控 | 部分平台网页解析会重试几十秒，属正常，最终一般能拿到地址 |
| 运行环境装不上 | GitHub 不通，必须 pip install videofetch（走 PyPI） |
工作流示例
示例 0：不传客户端名
脚本已修复 videodl 的一个坑：VideoClient(allowed_video_sources=None) 会 list(set(None)) 报错，必须传空列表才会 fallback 到全部客户端自动匹配。脚本内部已处理，不传第二个参数即可安全使用。
示例 1：B 站视频
用户：「帮我下 https://www.bilibili.com/video/BV1UWYe68Ed8」
→ python3 scripts/video_dl.py "https://www.bilibili.com/video/BV1UWYe68Ed8" BilibiliVideoClient
→ 输出 ./<标题>.mp4 → 把文件路径交给用户。
示例 2：抖音视频
用户：「下这个 https://v.douyin.com/xxxxx/」
→ 不传客户端让 videodl 自动匹配；解析失败再试 DouyinVideoClient。
示例 3：用户想下 YouTube
→ 先尝试一次；确实不可达再告知用户改用 yt-dlp 本机方案，不要反复重试。
资源目录
scripts/
video_dl.py：主下载脚本。
references/
platforms.md：平台/客户端名速查；how-it-works.md：脚本工作原理与可调参数；troubleshooting.md：常见报错与处理建议。
运行环境
- 脚本：
scripts/video_dl.py（相对技能根目录） - Python：3.9+
- 第三方库：
videodl（pip install videodl）、videofetch（pip install videofetch）、yt-dlp（pip install yt-dlp） - 外部命令：
ffmpeg
开工前先跑一次自检，缺什么当场补，别等跑到一半报错：
python3 -c "import videodl" 2>/dev/null || echo "缺 videodl，请执行 pip install videodl"
python3 -c "import videofetch" 2>/dev/null || echo "缺 videofetch，请执行 pip install videofetch"
python3 -c "import yt_dlp" 2>/dev/null || echo "缺 yt-dlp，请执行 pip install yt-dlp"
command -v ffmpeg >/dev/null 2>&1 || echo "缺 ffmpeg，请先安装再重试"
> 缺依赖时用中文告诉用户缺什么、装完就能用，不要把 Python 的英文 traceback 原样贴给用户。
