joeseesun/qiaomu-youtube-download
GitHub: joeseesun/qiaomu-youtube-download
一款基于 yt-dlp 的 YouTube 下载与搜索 Agent 技能，支持视频、音频、字幕和元数据获取，提供自动版本检查、文件锁和媒体验证以确保下载可靠。
Stars: 3 | Forks: 1
# qiaomu-youtube-download
[](https://github.com/joeseesun/qiaomu-youtube-download/commits/main)
[](LICENSE)
npx skills add joeseesun/qiaomu-youtube-download
## 为什么值得用
旧版 `yt-search-download` 把 YouTube Data API Key 错误地设成所有命令的前置条件，导致普通下载也可能直接退出；它还会自动尝试浏览器 Cookie，却不返回实际文件路径和媒体验证结果。
`qiaomu-youtube-download` 将 URL 下载与搜索解耦：下载不要求 API Key；配置 Key 时，搜索与统计信息优先使用 YouTube Data API v3。每次下载任务先对照 yt-dlp 官方稳定版检查并按需升级。下载默认自动读取本机浏览器 Cookie 以提高稳定性，Cookie 读取失败时自动回退公开无 Cookie 路径。长任务持续输出进度并用跨进程锁阻止重复写入；下载后只验证最终媒体、清理本次残留格式分片，并返回真实绝对路径。
## 安装
npx skills add joeseesun/qiaomu-youtube-download
本地验证：
python3 ~/.agents/skills/qiaomu-youtube-download/scripts/validate_skill.py ~/.agents/skills/qiaomu-youtube-download
python3 ~/.agents/skills/qiaomu-youtube-download/scripts/trigger_eval.py ~/.agents/skills/qiaomu-youtube-download
python3 ~/.agents/skills/qiaomu-youtube-download/scripts/test_youtube.py
python3 ~/.agents/skills/qiaomu-youtube-download/scripts/youtube.py doctor
## 你可以直接这样说
- “下载这个 Shorts：https://www.youtube.com/shorts/xxxx”
- “把这个 YouTube 视频保存到当前目录，最高画质”
- “这期播客只要 MP3：https://youtu.be/xxxx”
- “下载这个视频的中英文字幕，给我 SRT 和 TXT”
- “查一下这个 YouTube 视频的标题、时长和分辨率”
- “在 YouTube 搜索最近的 AI Agent 视频”
## 它会做什么
1. 对照 yt-dlp 官方 GitHub 最新稳定版检查本机版本，只在过期时按当前安装方式升级并复验。
2. 严格校验 YouTube URL，不接受链接内凭据、自定义端口或其他域名。
3. 默认自动检测本机浏览器 Cookie；读取失败时回退无 Cookie 下载单个视频。
4. 支持最佳画质、1080p、720p、480p、MP3、字幕及基础搜索。
5. 使用包含视频 ID 的文件名，避免不同视频重名；同一任务用文件锁阻止两个 yt-dlp 同时写入。
6. 长下载持续输出进度；超时或中断时终止整个子进程组，避免孤儿进程。
7. 排除 `.f140-7.m4a`、`.f399.mp4` 等分离格式文件，只用 `ffprobe` 验证最终媒体。
8. 最终验证成功后清理本次新产生的格式分片，并返回机器可读 JSON。
## 前置条件
- [ ] Python 3.10+：`python3 --version`
- [ ] yt-dlp：`yt-dlp --version`
- [ ] FFmpeg/ffprobe：`ffmpeg -version`、`ffprobe -version`
- [ ] 可选搜索增强：`YT_BROWSE_API_KEY` 或 `YOUTUBE_API_KEY`
- [ ] 用户有权访问并保存目标内容
下载不需要 YouTube Data API Key；Key 只增强搜索、发布时间和播放/点赞统计。
## 命令示例
# 检查并按需升级 yt-dlp（Agent 下载前默认执行）
python3 scripts/youtube.py doctor --upgrade
# 查看信息
python3 scripts/youtube.py info 'https://www.youtube.com/shorts/VIDEO_ID'
# 下载最佳画质
python3 scripts/youtube.py download 'VIDEO_URL' --dir ~/Downloads
# 限制到 1080p
python3 scripts/youtube.py download 'VIDEO_URL' --quality 1080p --dir ~/Downloads
# 提取 MP3
python3 scripts/youtube.py audio 'VIDEO_URL' --dir ~/Downloads
# 字幕：SRT + TXT
python3 scripts/youtube.py subtitles 'VIDEO_URL' --langs 'en,zh-Hans' --dir ~/Downloads
# 基础搜索
python3 scripts/youtube.py search 'AI agents' --max 10
# 禁用自动浏览器 Cookie
python3 scripts/youtube.py download 'VIDEO_URL' --cookies-from-browser none
## 输出示例
{
"ok": true,
"command": "download",
"id": "VIDEO_ID",
"title": "Video title",
"files": [
{
"path": "/Users/example/Downloads/Video title [VIDEO_ID].mp4",
"bytes": 12345678,
"video_codec": "h264",
"width": 1080,
"height": 1920,
"duration_seconds": 49.0
}
],
"cookies_from_browser": "chrome",
"data_api_used": true
}
## API、Cookie 与隐私
如果设置了 `YT_BROWSE_API_KEY` 或 `YOUTUBE_API_KEY`，搜索和统计优先使用 YouTube Data API v3；Key 不会进入命令输出或报告。没有 Key 或 API 暂时失败时自动使用 yt-dlp 搜索。
下载默认使用 `--cookies-from-browser auto`，按 Chrome、Edge、Firefox、Safari 检测本机浏览器；自动读取失败时回退无 Cookie。可明确指定或禁用：
python3 scripts/youtube.py download 'VIDEO_URL' --cookies-from-browser chrome
python3 scripts/youtube.py download 'VIDEO_URL' --cookies-from-browser none
Cookie 仅由本机 `yt-dlp` 临时读取，不复制到 Skill、不打印、不写入报告。
## yt-dlp 更新策略
`doctor` 只查询 [yt-dlp 官方 GitHub Releases](https://github.com/yt-dlp/yt-dlp/releases/latest)，API 限流时回退同一官方仓库的 latest 重定向。加 `--upgrade` 后，只有稳定版确实较新才执行更新：Homebrew 安装使用 `brew upgrade yt-dlp`，其他安装使用当前 yt-dlp 的 `-U`。更新后会重新读取版本；GitHub 暂不可达时只返回 warning，不阻断下载。
这个步骤会在必要时修改本机 yt-dlp 安装，但不会安装其他依赖、降级或执行来自视频页面的命令。
## Troubleshooting
| 症状 | 原因 | 处理 |
|---|---|---|
| `yt-dlp not found` | 未安装依赖 | `brew install yt-dlp` |
| yt-dlp 检查显示 `outdated: true` | 只运行了 `doctor`，未允许升级 | 运行 `python3 scripts/youtube.py doctor --upgrade` |
| `update-check` warning | GitHub API 暂时不可达或限流 | 继续使用现有版本下载，稍后重试 `doctor --upgrade` |
| `upgrade` 失败 | 包管理器权限、锁或安装方式不支持自更新 | 按 JSON 中的 manager 检查 Homebrew/yt-dlp，再重试 |
| 只能得到低清视频 | 缺少 ffmpeg，无法合并最佳视频与音频 | `brew install ffmpeg` |
| Data API 配额、Key 或网络错误 | 官方搜索增强不可用 | 自动回退 yt-dlp 搜索；下载不受影响 |
| 提示登录、年龄或地区限制 | 浏览器 Cookie 不存在、已过期或账号无权限 | 登录浏览器后重试，或显式指定其他浏览器 |
| 浏览器 Cookie 读取失败 | 浏览器数据库被锁、Keychain 未授权或浏览器不受支持 | 关闭相关浏览器重试，或不使用 Cookie |
| 终端暂时没有最终 JSON | 长下载仍在原会话运行 | 继续轮询同一个 session/cell；不要重复执行下载命令 |
| `another download ... is still running` | 同一视频与目录已有进程持锁 | 等待原会话，确认原进程结束后再续传 |
| `.f140-7.m4a` 被误报为“没有视频流” | 旧版把 yt-dlp 分离音轨当最终视频验证 | 升级到 v1.2.0；最终验证会排除并清理本次新格式分片 |
| 没有字幕文件 | 视频没有所选语言的人工/自动字幕 | 调整 `--langs`，或另走 ASR 转录 Skill |
| 已存在同名文件 | 默认禁止覆盖 | 保留既有文件；新视频用 ID 区分 |
## 风险与边界
- 只下载用户有权访问和保存的内容。
- 不绕过付费、登录、地域、年龄、版权或 DRM 限制。
- 默认会在本机自动读取检测到的浏览器 Cookie，可用 `--cookies-from-browser none` 禁用；Cookie 不复制、不打印、不写入报告。
- 默认单视频，不无限批量抓取频道或播放列表。
- 同一视频/目录/操作使用临时文件锁；锁不包含 URL、标题、Cookie 或 API Key。
- `doctor --upgrade` 会在检测到官方稳定新版时修改现有 yt-dlp 安装；不会升级其他 Homebrew 公式。
- 不负责重新上传、转载或规避平台政策。
## License
MIT
Copyright (c) 向阳乔木 · [X](https://x.com/vista8) · [GitHub](https://github.com/joeseesun/)
标签：逆向工具