idiotfan/skills
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
skills/youtube-download/SKILL.md
T

5.5 KiB
Raw Permalink Blame History

name, description
name description
youtube-download Download YouTube videos at the highest available quality (up to 4K) as merged MP4 files with the best audio track (native Opus). Default spec: best video + best audio merged into one MP4 only — do not download a separate audio-only file unless the user explicitly asks for 音频/audio-only. Handles the modern yt-dlp requirements — a JS runtime (bun/deno/node) for YouTube's JS challenges, and browser cookies for videos blocked by bot detection / login / age gates. Use when asked to download, save, or grab a YouTube video, playlist item, or a high-quality/HD/4K copy of a YouTube URL.

YouTube 高清下载 (youtube-download)

用 yt-dlp 把 YouTube 视频下成本地最高画质 MP4（最高 4K），也可以只下最高音质音频。已经踩平了 2025/2026 年 yt-dlp 下 YouTube 的两个主要坑：需要 JS 运行时、以及机器人检测要 cookie。

什么时候用

用户给一个或多个 YouTube 链接，要求“下载 / 保存 / 下高清 / 下 4K / 下最高画质”时。

默认规格（每次照此执行）

  • 默认只下「视频版」：最高画质视频（最高 4K）+ 最佳音质音轨（原生 Opus），合并成单个 MP4，存到用户「下载」文件夹。
  • 除非用户明确说「只要音频 / 音频版 / 单独下音频」，否则不要额外下载 audio-only 文件。
  • 链接带 &list= / start_radio=1 时默认只下当前这一个视频（--no-playlist），除非用户要求整个播放列表/电台。

核心命令（能跑通的那条）

yt-dlp \
  --cookies "cookies.txt" \                # 仅当视频需要登录/被机器人拦时必需，见下
  --js-runtimes "bun:$(command -v bun)" \   # 必需：YouTube 现在要求解 JS 挑战（bun/deno/node 任选）
  -f "bestvideo+bestaudio/best" \
  --merge-output-format mp4 \
  --ffmpeg-location "<ffmpeg bin 目录>" \   # 合并视频+音频需要 ffmpeg
  -o "<输出目录>/%(title)s [%(height)sp].%(ext)s" \
  --no-playlist \                          # 链接带 &list= 时只下当前这一个
  "https://www.youtube.com/watch?v=VIDEO_ID"

推荐直接用打包好的脚本（自动准备工具、找 ffmpeg、带 cookie）：

  • Windows：scripts/yt-download.ps1
  • Linux/macOS：scripts/yt-download.sh
# Windows 示例：下一个或多个视频到「下载」文件夹
powershell -ExecutionPolicy Bypass -File scripts\yt-download.ps1 "https://www.youtube.com/watch?v=xxxx"
powershell -ExecutionPolicy Bypass -File scripts\yt-download.ps1 URL1 URL2 URL3

# Linux/macOS 示例
bash scripts/yt-download.sh "https://www.youtube.com/watch?v=xxxx"

脚本行为：

  • 默认就是最高画质视频 + 最佳音质音轨合并 MP4；不会单独下载音频。
  • JS 运行时自动选 bun（已装）；没有则用 deno，再退到 node。也可用环境变量 JS_RUNTIME=bun|deno|node 指定。
  • 找不到 yt-dlp（Windows 版还会找 deno）会自动下载到脚本旁的 bin/ 目录。
  • 自动探测 ffmpeg（PATH 里没有会提示安装）。
  • 如果脚本目录里存在 cookies.txt，会自动带上。
  • 输出文件名格式：标题 [1080p].mp4，默认存到当前用户「下载」文件夹（可用 -OutDir / $2 改）。

三个关键坑（务必知道）

  1. 必须有 JS 运行时。 否则报 No supported JavaScript runtime could be found 或直接 Sign in to confirm you're not a bot。装 bun / deno / node 任一即可（macOS 上已装 bun，脚本默认用 bun），或给 yt-dlp 传 --js-runtimes "bun:路径"。

    • ⚠️ yt-dlp 已把 bun 标记为 deprecated，只支持 bun 1.2.11–1.3.14（本机 1.3.13 可用）。若以后升级 bun 或 yt-dlp 报 bun 不支持，用 JS_RUNTIME=deno / JS_RUNTIME=node 切换即可（deno 已随 brew 版 yt-dlp 装好）。

  2. 机器人检测 → 需要 cookie。 如果 API 返回 LOGIN_REQUIRED / “Sign in to confirm you're not a bot” 且 0 个格式，就必须提供你 YouTube 账号的 cookie：

    • 浏览器（登录着 YouTube）装扩展 “Get cookies.txt LOCALLY”（开源、纯本地不上传）。
    • 切到 youtube.com 标签页（当前激活），点扩展图标 → Export，导出 Netscape 格式的 www.youtube.com_cookies.txt。
    • 把它改名/放成脚本目录下的 cookies.txt（或用 --cookies 指定路径）。
    • 公开视频不需要 cookie，脚本没检测到 cookie 也能下公开视频。

  3. cookie 会过期/轮换。 出现 The provided YouTube account cookies are no longer valid 时，按第 2 步重新导出覆盖 cookies.txt 即可。公开视频不受影响。

输出编码说明

YouTube 最高画质通常是 AV1 视频 + Opus 音频（封装成 mp4）。较新，VLC / PotPlayer / 新版系统播放器都能放；个别老设备放不了。需要更通用时：

  • 想要 H.264（兼容性最好，但 YouTube 上 H.264 最高只到 1080p）：把格式改成 -f "bestvideo[vcodec^=avc1]+bestaudio[ext=m4a]/best[vcodec^=avc1]"
  • 或下完后用 ffmpeg 转码成 H.264/H.265。

小抄

  • 仅当用户明确要求音频时才用：
    • 只下音频（m4a）：-f "bestaudio[ext=m4a]/bestaudio" -x --audio-format m4a
    • 只下最高音质音频（保留 YouTube 原生 Opus，不转码、音质最好）：-f "bestaudio/best" -o "%(title)s.%(ext)s"
  • 限制最高 1080p：-f "bestvideo[height<=1080]+bestaudio/best[height<=1080]"
  • 整个播放列表：去掉 --no-playlist
  • 看有哪些格式：-F
  • 下字幕：--write-subs --sub-langs "en,zh-Hans" --convert-subs srt
Reference in New Issue View Git Blame Copy Permalink