YouTube 视频下载器
> 下载YouTube只需一步：输入视频地址即可下载，纯净视频与字幕文本，不需要付费账号，不需要录屏，不会带广告。
一句话原理
YouTube 网页播放时会在视频流中插入广告，但接口层返回的媒体流里没有广告。
本技能直接向接口取流，所以拿到的就是纯净的原始视频——广告、付费墙、录屏重编码这些问题一次性消失。
| 你的顾虑 | 本技能的做法 |
|---|---|
| 要不要绑定 YouTube 付费账号 | 不需要。公开视频一律可下 |
| 电脑录屏行不行 | 不需要。录屏会带广告、掉帧、音画不同步 |
| 广告要手动点关闭 | 不存在这个问题。接口层拿不到广告 |
| 要不要装一堆软件 | 缺什么自动装什么，doctor 一键体检 |
| 字幕能不能给我 | 自动抓取并转成 TXT，可直接全文检索 |
执行清单
拿到 YouTube 链接后，按这个顺序做：
| # | 步骤 | 命令 | 完成标志 |
|---|---|---|---|
| 1 | 确认链接有效 | python scripts/ytdl.py probe <URL> |
输出标题、时长、字幕轨 |
| 2 | 下载视频 + 生成字幕 | python scripts/ytdl.py fetch <URL> |
输出 已生成：xxx.mp4 与 字幕.zh.txt |
| 3 | 交付 | 把 mp4 与 txt 一起给用户 | 路径可见、文件可打开 |
只需要第 2 步就能完成绝大多数任务。第 1 步仅在用户问「这个视频多长」「有没有字幕」时才需要。
字幕转文本是默认行为
fetch 跑完会自动产出两个字幕文件：
| 文件 | 用途 |
|---|---|
字幕.zh.srt |
带时间轴，给播放器挂载或做双语翻译 |
字幕.zh.txt |
纯文本，已剥离时间轴，适合全文检索、提炼要点、做笔记 |
用户要「字幕」「文案」「文字稿」「总结这个视频讲了什么」→ 直接给 TXT。
脚本命令
# 环境自检与自动修复（首次使用或报错时先跑这个）
python scripts/ytdl.py doctor
# 探测视频信息（标题、时长、可用字幕轨），不下载
python scripts/ytdl.py probe "https://youtu.be/VIDEO_ID"
# 下载视频 + 自动抓字幕并转文本（主力命令）
python scripts/ytdl.py fetch "https://youtu.be/VIDEO_ID" -o "~/Downloads"
# 只抓字幕转文本，不下视频
python scripts/ytdl.py subs "https://youtu.be/VIDEO_ID" -o "~/Downloads"
# 只要音频（通勤听）
python scripts/ytdl.py fetch "https://youtu.be/VIDEO_ID" -q best --no-subs
常用参数
| 参数 | 取值 | 说明 |
|---|---|---|
-o, --output |
目录路径 | 输出目录，默认 ~/Downloads/YouTube |
-q, --quality |
best 1080p 720p 480p 360p |
清晰度，默认 1080p |
--no-subs |
无 | 跳过字幕，只要视频 |
--skip-sub-if-exists |
无 | 字幕文件已存在则不重复抓 |
-v, --verbose |
无 | 打印调试日志 |
--log |
文件路径 | 同时写入日志文件 |
应避免的用法
| 不要这样做 | 原因 | 应该怎么做 |
|---|---|---|
| 用录屏软件抓 YouTube 视频 | 会录进广告、掉帧、音画不同步、体积翻倍 | 用 fetch 直取接口流 |
| 为了下载去开 YouTube Premium | 公开视频根本不需要付费账号 | 直接 fetch，不需要任何账号 |
在脚本里手写 -f 137+140 这类格式号 |
格式号会随平台调整失效，选错会下载 2GB+ 的 m3u8 流 | 用脚本默认策略，或只用 -q 传清晰度 |
手动 pip install 到系统 Python |
可能污染系统环境、触发权限错误 | 脚本自动装到用户级目录 |
手工写 pip install yt-dlp 后再 ffmpeg 单独装 |
ffmpeg 装不上会导致合并失败 | doctor 会自动补齐 imageio-ffmpeg |
| 下载后手工删时间轴造文本 | 容易漏行、错行 | 用 subs 子命令，脚本已实现 SRT→TXT |
| 把字幕接口 429 当成视频失败 | 字幕与视频是两条独立链路 | 429 时用 --no-subs 先拿视频，字幕稍后补 |
批量下载时用 bv* 不限制清晰度 |
会选中 VP9 Premium 的 m3u8 流，体积暴涨 | 保持脚本默认的 https 直连策略 |
| 在受限地区强行重试 | 反复重试只会加深限流 | 换网络环境或等待限流窗口过去 |
常见问题速查
Q：真的不用付费账号吗？
A：不用。公开可观看的视频一律可下，Premium 只影响网页端的广告策略，不影响接口取流。
Q：广告会自动跳过吗？
A：不需要"跳过"这个动作。广告是网页播放器插入的，接口返回的流里本来就没有广告。
Q：字幕是繁体还是简体？
A：优先取简体（zh-Hans）；没有简体则取繁体。中文轨常常是「人工校对」版本，质量优于自动生成。
Q：字幕能拿到但质量一般怎么办？
A：TXT 已做相邻重复行合并。可以直接让我基于 TXT 提炼要点、翻译、或整理成结构化笔记。
Q：为什么强制限制 1080p？
A：超过 1080p 的 YouTube 源多为 VP9/AV1 的 m3u8 分片流，体积可达 2.3GB 且下载极慢。1080p H.264 是画质、速度、体积的最优解。需要 4K 时用 -q best。
Q：视频很长会超时吗？
A：不会。下载阶段超时为 3600 秒（1 小时），且 yt-dlp 自身带 10 次重试。
Q：报错 429 怎么办？
A：接口限流。等 10–30 分钟重试；或先用 --no-subs 把视频拿到，字幕单独用 subs 补。
Q：Windows 上能跑吗？
A：能。脚本会自动定位 imageio-ffmpeg 自带的 ffmpeg，无需手动安装。
能力边界
支持
| 维度 | 范围 |
|---|---|
| 输入 | YouTube 公开视频链接（watch?v= / youtu.be/ / shorts/ / embed/） |
| 输出格式 | MP4（H.264 + AAC，通用兼容）、SRT 字幕、TXT 纯文本 |
| 清晰度 | 144p 至 1080p，best 为自动挑最高 |
| 字幕语言 | 中文（简体 → 繁体 → 原声）、英文 |
| 视频长度 | 无上限（超时 1 小时） |
| 批量 | 可循环调用，单次一条 |
不支持 / 会失败
| 情况 | 结果 | 应对 |
|---|---|---|
| 地区限制视频 | 无法获取 | 需在可正常访问 YouTube 的地区使用 |
| 私有 / 已删除视频 | 无法获取 | 需所有者授权 |
| 年龄限制视频 | 可能触发验证 | 在浏览器完成一次验证后重试 |
| 会员专属 / 付费内容 | 无法获取 | 不绕过付费墙 |
| 直播（正在进行的） | 抓不到完整流 | 等结束后再下；或用 --live-from-start |
| 播放列表 | 默认只下第一个 | 用 --yes-playlist 处理整张列表 |
| 已下架但有存档的链接 | 无法获取 | 换来源 |
地区要求：本技能依赖 YouTube 接口的可达性，需在 YouTube 可正常访问的地区使用。若 probe 报「网页抓取失败」或反复 429，通常是当前网络环境无法正常访问 YouTube——换网络环境即可，无需改脚本。
失败兜底策略
按这个顺序处理，不要跳步：
- 先跑
doctor—— 缺依赖是最高频的失败原因，doctor会自动修复。 - 区分是视频失败还是字幕失败 —— 两者是独立链路。字幕 429 时视频照常下，加
--no-subs即可。 - 换清晰度重试 —— 报「格式不可用」时用
-q 720p或-q best。 - 等限流窗口 —— 429 是服务端限流，重试无益，等 10–30 分钟。
- 输出可执行建议 —— 任何失败都必须给出「原因 + 怎么办」，不允许只甩英文报错。
深入阅读索引
| 文档 | 内容 | 何时看 |
|---|---|---|
references/execution-guide.md |
完整参数表、输出文件说明、批量下载、只要音频 | 需要精细控制参数时 |
references/troubleshooting.md |
按症状组织的排错手册 + 高频问题索引表 | 报错时 |
README.md |
方法论手册：原理详解、完整案例、成本拆解、进阶用法 | 想理解原理或举一反三时 |
目录结构
youtube-video-downloader/
├── SKILL.md ← 本文件（执行卡）
├── README.md ← 方法论手册（给人读）
├── scripts/
│ └── ytdl.py ← 核心脚本（零第三方依赖起步）
├── tests/
│ ├── test_ytdl.py ← 50 项单元测试
│ └── verify_independent.py ← 四层独立验证器
├── references/
│ ├── execution-guide.md ← 完整参数与用法
│ └── troubleshooting.md ← 排错手册
└── assets/
└── icon.png ← 图标（不进包）
