video-download

视频下载技能

封装 yt-dlp，并在遇到 YouTube 反机器人验证时自动恢复。

工具

scripts/download.py — 首次运行时安装 yt-dlp，将视频和音频合并为 MP4，检测到机器人时自动轮换策略，并使用下载归档安全续传。

工作流

1. 收集用户请求中的所有 URL。
2. 确定输出目录（未指定时使用当前工作目录）。
3. 确定使用单视频模式还是播放列表模式：
   • 用户说“这个视频”／提供单个 URL → 保持默认设置（单视频）。
   • 用户说“播放列表”／“所有视频”／提供 playlist?list= URL → 添加 --playlist。
4. 运行脚本。如果触发 YouTube 机器人检测，脚本会自动轮换策略。
5. 告知用户保存了哪些文件，以及哪种策略奏效。

用法

# Single video, current directory
python scripts/download.py "https://www.youtube.com/watch?v=..."

# Multiple URLs to a folder
python scripts/download.py "URL1" "URL2" -o "/path/to/output"

# Full playlist as 720p MP4
python scripts/download.py "https://www.youtube.com/playlist?list=..." --playlist -o "./out"

# Force a specific browser for cookies (skips auto-rotation)
python scripts/download.py "URL" --cookies-from-browser chrome

# Force a manual cookies.txt file
python scripts/download.py "URL" --cookies "~/Downloads/www.youtube.com_cookies.txt"

# Higher quality
python scripts/download.py "URL" --max-height 1080

标志

标志	默认值	说明
-o、--output	cwd	输出目录
--max-height	720	视频最大高度（例如 1080、480）
--playlist	关闭	下载整个播放列表；默认仅下载单个视频
--cookies-from-browser	自动	强制使用一个浏览器；跳过自动轮换
--cookies	自动	强制使用一个 cookies.txt 文件；跳过自动轮换
--no-archive	关闭	禁用 .download-archive.txt 续传跟踪

自动恢复策略链

当请求因机器人检测标记（Sign in to confirm、 LOGIN_REQUIRED）而失败时，脚本会自动按以下顺序尝试策略， 并在首个成功的策略处停止：

1. 无身份验证 + 限流 — 默认策略。在请求之间设置休眠间隔。
2. 播放器客户端轮换 — default,tv,mweb,web_safari。绕过较轻度的拦截。
3. 浏览器 Cookie 轮换 — 依次尝试 chrome → edge → firefox → brave → vivaldi → opera， 仅尝试系统上实际安装的浏览器。
4. 发现 Cookie 文件 — 从以下位置选取最新的有效 Cookie 文件： ~/Downloads/www.youtube.com_cookies.txt、youtube*cookies*.txt、 cookies.txt（文件需在 7 天以内才视为有效）。

如果 4 种策略均失败，脚本会打印一份结合当前情况的恢复指南 （见下文“向用户提供的恢复说明”）。

如果用户明确传入 --cookies-from-browser 或 --cookies，则会跳过策略链， 仅使用指定来源（适用于用户已知哪种方式有效的情况）。

向用户提供的恢复说明

所有策略均失败时，脚本会自动打印分步指南。原样向用户展示最相关的部分 ——内容具体且可执行。

指南会根据脚本检测到的情况分支：

• 找到 Cookie 文件但文件被拒绝（文件已过期）：告诉用户立即 重新导出 Cookie，因为触发机器人拦截后，YouTube 会迅速使 Cookie 失效。
• 未找到 Cookie 文件：指导用户完成首次导出。
• 其他情况：仅列出替代方案（关闭浏览器、更换网络、等待）。

Cookie 导出指南（用户最可能需要的部分）

1. 安装 Cookie 导出浏览器扩展：

   • Chrome / Edge / Brave / Vivaldi / Opera：“Get cookies.txt LOCALLY” — https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc
   • Firefox：“cookies.txt” — https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/

2. 在该浏览器中打开 https://www.youtube.com，并登录 Google 账号。

3. 点击扩展程序的工具栏图标：

   • “Get cookies.txt LOCALLY” → “Export As” → Netscape 格式 → 选择 “Current Site”选项，仅包含 youtube.com Cookie。
   • Firefox 的“cookies.txt” → “Current Site” → 保存。

4. 将文件保存到操作系统默认的 Downloads 文件夹。以下名称均可用 （会自动检测，优先使用最新文件）：

   • www.youtube.com_cookies.txt（扩展默认名称，最简单）
   • youtube.com_cookies.txt
   • cookies.txt

5. 重新运行相同的下载命令。策略 4 会自动选取该文件。

何时推荐各替代方案

• 关闭浏览器（Chrome / Edge）：在 Windows 上是最快的解决办法，因为浏览器运行时，App-Bound Encryption 会锁定 Cookie 数据库。若未启用“继续上次离开的位置”，用户会失去已打开的标签页。
• 更换网络（移动热点、VPN）：绕过 IP 级别的屏蔽。如果用户已有 VPN，这是最快的办法。
• 等待解封：YouTube 的 IP 屏蔽会自行解除，通常在 24 h 内。仅在没有其他合适方案时推荐。

恢复 / 重新运行安全性

默认启用 --download-archive .download-archive.txt。重新运行时会跳过已下载的视频，因此部分失败后重新运行，或向同一文件夹添加更多 URL，都是安全的。传入 --no-archive 可禁用此功能。

输出文件名格式

• 单个视频：{title} [{id}].mp4
• 播放列表：{NNN} - {title} [{id}].mp4（带前导零的索引可让文件管理器按顺序排列）

始终启用 --windows-filenames，确保文件名在各操作系统上都安全。

身份验证说明

• 自动轮换可处理大多数情况，无需用户输入。
• 在 Windows 上，--cookies-from-browser chrome 要求 Chrome 已关闭（Chrome 运行时，App-Bound Encryption 会锁定 Cookie 数据库）。
• 如果 Chrome 必须保持打开状态，建议用户通过 "Get cookies.txt LOCALLY" Chrome 扩展导出 Cookie，并将文件放入 ~/Downloads/。脚本会在下次运行时自动获取该文件。

支持的平台

YouTube（单个视频 + 播放列表）、Instagram、TikTok、Twitter/X、Facebook、Vimeo、Reddit，以及通过 yt-dlp 支持的 1000 多个平台。