video-catcher

面向 Codex、Claude Code 等本地 Agent 的视频资源发现与下载 Skill。

它的目标很简单：用户只提供一个视频或网页链接，Agent 自动尝试解析、嗅探、下载、合并和验证，不要求用户理解 yt-dlp、Cookie、HLS/DASH、浏览器请求或 FFmpeg。

用户：下载这个视频：https://example.com/watch/123
                         ↓
                   video-catcher
                         ↓
        解析 → 发现 → 下载 → 合并 → 验证 → 报告

[!IMPORTANT] 使用与免责声明：请仅使用 video-catcher 处理你有权访问、复制和保存的内容。本项目不用于绕过 DRM、付费墙、会员/账号权限或其他访问控制，也不授予任何第三方内容的版权或再分发权。能够访问某个视频，不等于自动拥有下载、转载或传播该内容的权利。使用者应自行遵守适用法律法规、平台服务条款和内容许可。完整说明见 DISCLAIMER.md。

本项目不会绕过 Widevine、FairPlay、PlayReady 等 DRM，也不能替代账号权限、会员权限或人工验证码。

主要能力

• 一句话下载：网页链接、平台视频链接、MP4/WebM/MOV/MKV 直链、HLS m3u8、DASH mpd
• 平台解析：优先使用 yt-dlp，覆盖 YouTube、Bilibili、Vimeo、X、TikTok、抖音、Instagram、Facebook 等其支持的平台
• 网页视频发现：解析 <video>、<source>、meta、JSON 媒体字段和常见媒体 URL
• 浏览器嗅探：Playwright 监听网络请求，并结合 DOM / Performance Resource 发现动态媒体
• 清晰度探测：读取 yt-dlp formats、HLS master playlist、DASH Representation 和浏览器实际视频尺寸
• 精确画质下载：支持 360p / 720p / 1080p / 2K / 4K / best，可选择精确画质或最高不超过指定画质
• 分离音视频合并：自动处理 video-only / audio-only 轨道并调用 FFmpeg 合并
• 断点续传与重试：直链 .part + HTTP Range、yt-dlp continue、分片重试
• YouTube 专用恢复路线：普通解析失败后可自动尝试 PO Token Provider、浏览器指纹模拟和 web_safari client
• 隔离浏览器 Profile：默认不依赖用户正在运行的 Chrome/Edge Cookie 数据库
• DRM 检测：区分 protected / clear / unknown / not-checked
• 下载验证：使用 ffprobe 检查最终媒体文件
• 任务报告：输出 Markdown / JSON 下载报告和 formats 报告

安装

1. Python 依赖

建议使用 Python 3.11+：

python -m pip install -U -r requirements.txt

2. Playwright 浏览器

python -m playwright install chromium

3. FFmpeg

确保 ffmpeg 和 ffprobe 已加入 PATH：

ffmpeg -version
ffprobe -version

4. YouTube PO Token 可选依赖

完整启用 YouTube PO Token 自动路线时，建议安装 Node.js 20+，并确保以下命令可用：

node --version
npm --version
npx --version

5. 环境检查

python scripts/doctor.py

重点关注：

core-ready
browser-sniff-ready
youtube-pot-capable
autonomous-ready

autonomous-ready=true 表示主要自动下载链路所需依赖已经就绪。

最简单的用法

下载一个视频或网页里的视频

python scripts/video_catcher.py download "URL"

默认行为：

• 单视频模式
• 最高不超过 1080p
• 自动执行 fallback chain
• 自动验证最终文件
• 自动生成下载报告

查看网页里有哪些媒体资源

python scripts/video_catcher.py inspect "URL" --sniff

查看可下载清晰度

python scripts/video_catcher.py formats "URL"

会尽量返回：

• 清晰度 / 分辨率
• FPS
• 视频编码 / 音频编码
• 容器
• 码率
• 预计大小
• 可用于后续下载的 format / selector 信息

精确下载 1080p

python scripts/video_catcher.py download "URL" \
  --quality 1080p \
  --quality-mode exact

如果目标没有 1080p，exact 模式会明确失败，不会偷偷降到 720p。

最高不超过 1080p

python scripts/video_catcher.py download "URL" \
  --quality 1080p \
  --quality-mode at-most

最高画质

python scripts/video_catcher.py download "URL" --quality best

字幕和封面

python scripts/video_catcher.py download "URL" \
  --subtitles \
  --sub-langs "zh.*,en.*" \
  --embed-thumbnail

批量下载

python scripts/video_catcher.py download \
  --url-file video-urls.txt \
  --title "批量素材"

下载整个播放列表

默认不会意外下载整个列表。只有明确需要时：

python scripts/video_catcher.py download "PLAYLIST_URL" --playlist

恢复中断任务

python scripts/video_catcher.py resume "Video/Downloads/任务目录"

Agent 应如何使用

对于普通用户请求：

帮我下载这个视频：URL

Agent 应直接执行：

python scripts/video_catcher.py download "URL"

不要在第一条路线失败后立刻询问用户“要不要换浏览器”“要不要关 Chrome”“要不要导 Cookie”。脚本本身会自动执行后续恢复路线。

如果用户先问：

这个视频有哪些清晰度？

先执行：

python scripts/video_catcher.py formats "URL"

如果用户随后说：

下 1080p。

应复用上一条 URL，并执行：

python scripts/video_catcher.py download "URL" \
  --quality 1080p \
  --quality-mode exact

更完整的 Agent 行为约束见 SKILL.md。

自动下载链路

video-catcher 会根据 URL 和失败原因选择路线，而不是固定调用一个下载器：

URL
 ↓
显式媒体直链？
 ├─ MP4/WebM/... → HTTP Range 下载
 └─ m3u8/mpd → DRM 检测 → yt-dlp / ffmpeg
 ↓
yt-dlp 常规解析
 ↓失败
YouTube 专用 PO Token（仅匹配的 YouTube 风控错误）
 ↓失败
curl_cffi 浏览器/TLS 指纹模拟
 ↓失败
YouTube web_safari retry
 ↓失败
静态网页媒体发现
 ↓失败
Managed Browser Sniff
 ↓
候选评分 + 请求上下文继承
 ↓
音视频下载 / 合并
 ↓
ffprobe 验证
 ↓
报告

Managed Browser

浏览器嗅探默认使用 video-catcher 自己的持久 Profile：

~/.video-catcher/profiles/

这样做的目的，是避免把用户日常 Chrome/Edge Profile 作为正常下载的必要条件。

在 Windows 上，--cookies-from-browser chrome 可能受到 Cookie SQLite 锁、DPAPI 或 Chromium App-Bound Encryption 影响。video-catcher 因此默认优先使用自己的隔离浏览器环境，而不是要求用户关闭浏览器。

如果用户明确提供 cookies.txt，仍可使用：

python scripts/video_catcher.py download "URL" --cookies-file cookies.txt

--browser-cookies 保留兼容用途，但不是默认路线。

YouTube

YouTube 对自动化请求可能同时使用 IP 风控、客户端校验、登录验证和 PO Token 等机制。

当普通 yt-dlp 命中典型 YouTube 风控错误时，video-catcher 可自动：

1. 启动本地 bgutil-ytdlp-pot-provider；
2. 使用 mweb client + PO Token 重试；
3. 失败后继续浏览器/TLS 指纹模拟；
4. 再尝试 web_safari；
5. 最后进入网页发现与浏览器嗅探。

PO Token Provider 只监听本机 127.0.0.1，并在任务结束后关闭。

需要注意：如果出口 IP 已被 YouTube 强制 429 / CAPTCHA / sorry/index 风控，或者内容本身要求账户权限，任何本地下载器都无法保证仅靠代码自动恢复。

输出目录

默认输出：

Video/Downloads/YYYY-MM-DD-任务名/
├── video.mp4
├── video.info.json
├── download-report.md
├── download-report.json
└── task.json

清晰度探测会另外生成：

formats-report.md
formats-report.json

隐私与安全

• 不绕过 Widevine、FairPlay、PlayReady 等 DRM。
• 不把 Cookie 上传到第三方视频解析服务。
• Cookie、Authorization 等敏感 Header 不写入公开报告。
• Authorization 不通过系统进程命令行参数明文传递。
• Managed Browser 使用独立 Profile，不默认读取用户主 Chrome/Edge Cookie 数据库。
• 浏览器会话产生的临时 Cookie 文件任务结束后删除。
• ~/.video-catcher/profiles/ 可能包含登录状态，不要上传到 Git、网盘或共享给他人。

自测

项目提供两类测试。

回归测试：

python -m unittest discover -s tests -v

真实本地端到端自测：

python scripts/selftest.py

selftest.py 会生成真实 MP4/HLS 测试素材、启动本地 HTTP 服务、调用 video-catcher 实际下载，并使用 ffprobe 验证结果。它用于验证下载执行链，而不是模拟函数返回值。

实时第三方平台能否下载还会受到目标网站规则、账号权限、网络出口和风控变化影响，因此不能仅用本地自测替代真实站点验证。

项目结构

video-catcher/
├── SKILL.md
├── README.md
├── LICENSE.txt
├── THIRD_PARTY_NOTICES.md
├── requirements.txt
├── scripts/
│   ├── video_catcher.py
│   ├── direct_downloader.py
│   ├── stream_downloader.py
│   ├── ytdlp_downloader.py
│   ├── browser_sniffer.py
│   ├── static_resolver.py
│   ├── format_inspector.py
│   ├── media_detector.py
│   ├── media_muxer.py
│   ├── verifier.py
│   ├── youtube_pot.py
│   ├── doctor.py
│   └── selftest.py
├── references/
├── tests/
└── evals/

开源许可

video-catcher 以 GNU General Public License v3.0 only（GPL-3.0-only） 发布，完整条款见 LICENSE.txt。

本项目依赖或调用多个独立开源项目，它们各自适用自己的许可证；详细列表见 THIRD_PARTY_NOTICES.md。

使用、修改或重新发布时，请同时遵守目标网站的服务条款、适用法律法规以及内容创作者的权利。

使用边界与免责声明

video-catcher 面向合法、授权的视频保存场景。请特别注意：

• 只下载你拥有、获授权或依法允许保存的内容；
• 不将工具用于绕过 DRM、付费墙、会员/账号权限或其他访问控制；
• 不公开或提交 Cookie、Token、Authorization 等敏感凭据；
• 不因“技术上可以下载”而推定“法律或平台规则允许下载/传播”；
• 软件的 GPL 许可只适用于 video-catcher 代码，不延伸到下载得到的第三方内容。

完整条款与说明见 DISCLAIMER.md。该说明不构成法律意见。