Video Catcher

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`](DISCLAIMER.md)。

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

主要能力

• 一句话下载：网页链接、平台视频链接、MP4/WebM/MOV/MKV 直链、HLS m3u8、DASH mpd
• 平台解析：优先使用 yt-dlp，覆盖 YouTube、Bilibili、Vimeo、X、TikTok、抖音、Instagram、Facebook 等其支持的平台
• 网页视频发现：解析 、、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