Communitygithub.com

YouTube 下载器

使用 yt-dlp 和 ffmpeg 从 YouTube 及 HLS 流媒体平台(Mux、Vimeo 等)下载视频和音频。当用户请求下载视频、提取音频、处理需要认证头的受保护流,或解决类似 nsig 提取失败、403 错误、cookie 提取问题等下载故障时,使用此技能。

YouTube 下载器 是什么?

该技能提供了一个可靠且用户友好的解决方案,用于从 YouTube 和 HLS 流媒体平台(如 Mux、Vimeo)下载内容。它利用 yt-dlp 和 ffmpeg,支持最高 4K 分辨率的高质量下载、仅提取音频以及字幕下载。其核心功能包括自动处理 YouTube 的反机器人验证(使用 PO Token 提供程序或浏览器 cookie)、智能故障排除(如遇到 nsig 提取失败或 403 错误时自动重试),以及一个用于自动管理 PO Token 的便捷包装脚本。该技能专为非技术用户设计,以友好语言引导操作,避免直接暴露命令,同时也为开发者提供了详细的内部 SOP 和技术参考。支持 Claude、Cursor 等主流 AI 编码代理。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/daymade/claude-code-skills/tree/HEAD/youtube-downloader

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

预览

来自技能 README

缩略图
缩略图

文档

YouTube 下载器 是做什么的?

概述

使用 yt-dlp 和 ffmpeg,从 YouTube 和 HLS 流媒体平台(Mux、Vimeo 等)可靠地下载视频和音频。此技能提供以下工作流程:

  • YouTube 下载(最高 4K),使用 PO Token 提供程序或浏览器 cookie
  • 带认证头的 HLS 流下载
  • 处理受保护内容并排查常见下载故障

非技术用户交互体验(默认)

假设用户是非技术用户。不要要求他们运行命令。由你自己执行所有操作,并用通俗语言报告进度。除非用户询问,否则避免提及工具。

默认流程:

  1. 询问 URL(如果未提供)。
  2. 获取视频元数据(标题/上传者/时长/缩略图)并确认与用户意图相符。
    • 如果 yt-dlp 被“确认你不是机器人”拦截,则回退到 YouTube oEmbed 获取标题/上传者/缩略图(时长可能未知)。
  3. 提供简单的选择(视频 vs. 仅音频、质量、字幕、保存位置)。
  4. 如果用户未指定,则使用合理的默认值:
    • 以最佳质量下载视频
    • MP4 合并输出
    • 仅单个视频(非播放列表)
  5. 下载并报告最终文件路径、文件大小和分辨率(如果是视频)。

以用户友好的术语提供选择:

  • “以最佳质量下载视频(默认)”
  • “仅下载音频(MP3)”
  • “选择质量:1080p / 720p / 480p / 360p”
  • “包含字幕(如果有的话)”
  • “保存到下载文件夹(默认)或告诉我另一个文件夹”

始终渲染缩略图(如果可用):

  • 如果元数据包含缩略图 URL,请使用 Markdown 图片语法包含它:![缩略图](URL)。

在执行额外工作前询问:

  • 确认播放列表下载(可能很大)。
  • 如果缺少依赖项,确认安装/升级。
  • 在提取浏览器 cookie 前询问。
  • 如果使用 cookie,切勿在面向用户的响应中提及 cookie 数量或原始 cookie 详情。说“使用了你的 Chrome 登录会话”。
  • 如果需要验证,自动设置本地 PO Token 助手(无需用户操作)。如果 Docker 缺失或失败,则不要尝试安装 Docker——切换到基于浏览器的 PO Token 提供程序。

法律/安全提醒(简短):

  • 仅当用户拥有下载内容的权利或许可时才继续。

响应模板(使用通俗语言,无命令):

![缩略图](缩略图_URL)

标题:...
频道:...
时长:...

我可以帮你:
1) 下载视频(最佳质量,MP4)
2) 仅下载音频(MP3)
3) 选择特定质量(1080p/720p/480p/360p)
4) 包含字幕(如果有的话)

我应该保存在哪里?(默认:下载文件夹)

如果用户说“直接下载”:

  • 使用默认值继续,并在下载完成时确认。
    • 如果被 403 拦截,自动设置验证助手并重试。

可靠下载 SOP(内部)

遵循此 SOP 以避免常见故障和混淆:

  1. 在 shell 命令中将 URL 括在引号中(zsh 将 ? 视为通配符)。示例:'https://www.youtube.com/watch?v=VIDEO_ID'。
  2. 确保代理对于 yt-dlp 和 PO Token 提供程序都处于活动状态(HTTP_PROXY/HTTPS_PROXY/ALL_PROXY)。
  3. 如果看到“登录以确认你不是机器人”,请求许可并使用浏览器 cookie。没有 cookie 不要继续。
  4. 在下载前启动 PO Token 提供程序(如果无法启动则快速失败)。
    • 如果可用,使用 Docker bgutil 提供程序。
    • 如果 Docker 缺失或失败,切换到基于浏览器的 WPC 提供程序。
  5. 如果使用 cookie,优先选择 web_safari 播放器客户端。否则对于 PO Token,优先选择 mweb。
  6. 当 WPC 在铸造 token 时,保持浏览器窗口打开。确保 Chrome 可以通过同一代理访问 YouTube。
  7. 如果收到“仅提供图片”或“请求的格式不可用”,将其视为 PO Token 故障,并在修复 token 提供程序/浏览器状态后重试。
  8. 如果收到 SSL EOF 或片段错误,将其视为代理/网络问题。使用渐进式格式和/或更好的代理重试。

代理执行检查清单(内部)

  • 运行 scripts/download_video.py URL --info(如果获得许可,添加 --cookies-from-browser chrome)以获取元数据和缩略图。
  • 如果 yt-dlp 元数据失败,依赖脚本的 oEmbed 回退来获取标题/上传者/缩略图,并注意时长可能不可用。
  • 如果存在缩略图 URL,在响应中使用 Markdown 图片语法渲染它。
  • 要求用户选择视频 vs. 仅音频,以及(可选)质量标准。
  • 使用友好的默认保存位置(下载文件夹),除非用户指定了文件夹。
  • 对于字幕,使用 --subtitles 和请求的 --sub-lang 运行。
  • 下载后,用通俗语言报告文件名、大小和分辨率(如果是视频)。
  • 如果下载失败并返回 403/片段错误,使用非 m3u8 的渐进式格式重试一次。
  • 如果出现“登录以确认你不是机器人”,请求 cookie 访问并使用 cookie + web_safari 重试。
  • 如果出现“仅提供图片”,将其视为 PO Token 故障,并在修复提供程序/浏览器状态后重试。
  • 在下载前启动 PO Token 提供程序(默认 --auto-po-token)。如果无法启动则快速失败。
  • 如果基于 Docker 的提供程序失败(在中国常见),自动回退到基于浏览器的 WPC 提供程序(它可能会短暂打开一个浏览器窗口)。
  • 如果使用 WPC 提供程序,保持浏览器窗口打开直到下载开始。如果浏览器无法启动,明确设置 Chrome 路径。
  • 如果 PO Token 提供程序超时,重启一次并重试。
  • 如果配置了系统代理,将其传递给提供程序容器。如果代理指向 127.0.0.1/localhost,将其重写为 host.docker.internal(针对 Docker)。

何时使用此技能

当用户出现以下情况时,应调用此技能:

  • 请求下载 YouTube 视频或播放列表
  • 想从 YouTube 视频中提取音频
  • 遇到 yt-dlp 下载失败或格式有限的问题
  • 需要格式选择或质量选项方面的帮助
  • 报告仅提供低质量(360p)格式
  • 询问以特定质量(1080p、4K 等)下载 YouTube 内容
  • 需要将下载的 WebM 视频转换为 MP4 格式以获得更广泛的兼容性
  • 请求从 Mux、Vimeo 或其他流媒体服务下载 HLS 流(m3u8)
  • 需要下载需要认证头的受保护流

先决条件

1. 验证 yt-dlp 安装(你自己运行)

which yt-dlp
yt-dlp --version

如果未安装或版本过旧(< 2025.10.22):

brew upgrade yt-dlp  # macOS
# 或
pip install --upgrade yt-dlp  # 跨平台

关键:过时的 yt-dlp 版本会导致 nsig 提取失败和格式缺失。

2. 检查当前质量访问权限(你自己运行)

在下载前,检查可用格式:

yt-dlp -F "https://youtu.be/VIDEO_ID"

如果只显示格式 18(360p):需要设置 PO Token 提供程序才能访问高质量。

高质量下载工作流程

步骤 1:安装 PO Token 提供程序(一次性设置)

为了获得 1080p/1440p/4K 访问权限,在 yt-dlp 的 Python 环境中安装 PO Token 提供程序插件:

# 找到 yt-dlp 的 Python 路径(yt-dlp 使用的解释器)
head -1 $(which yt-dlp)

# 使用上面一行的解释器安装插件
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider

验证:再次运行 yt-dlp -F "VIDEO_URL"。查找格式 137(1080p)、271(1440p)或 313(4K)。

有关详细设置说明和故障排除,请参阅 references/po-token-setup.md。

步骤 2:以最佳质量下载

安装 PO Token 提供程序后:

# 下载最高 1080p 的最佳质量
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"

# 下载可用的最佳质量(如果有 4K)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"

步骤 3:验证下载质量

# 检查视频分辨率
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,codec_name -of default=noprint_wrappers=1 video.mp4

1080p 的预期输出:

codec_name=vp9
width=1920
height=1080

替代方法:浏览器 Cookie 方法

如果 PO Token 提供程序设置有问题,请使用浏览器 cookie:

# Firefox
yt-dlp --cookies-from-browser firefox -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"

# Chrome
yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"

优点:可以访问年龄限制和会员专属内容。 要求:

  • 必须在指定浏览器中登录 YouTube。
  • 浏览器和 yt-dlp 必须使用相同的 IP/代理。
  • 不要将 cookie 与 Android 客户端一起使用(Android 客户端不支持 cookie)。

常见任务

仅下载音频(你自己运行)

以 MP3 格式提取音频:

yt-dlp -x --audio-format mp3 "VIDEO_URL"

自定义输出目录(你自己运行)

yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"

带字幕下载(你自己运行)

yt-dlp --write-subs --sub-lang en "VIDEO_URL"

下载播放列表(你自己运行)

yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"

将 WebM 转换为 MP4(你自己运行)

YouTube 高质量下载通常使用 WebM 格式(VP9 编解码器)。转换为 MP4 以获得更广泛的兼容性:

# 检查是否安装了 ffmpeg
which ffmpeg || brew install ffmpeg  # macOS

# 使用良好的质量设置将 WebM 转换为 MP4
ffmpeg -i "video.webm" -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "video.mp4"

参数说明:

  • -c:v libx264:使用 H.264 视频编解码器(广泛兼容)
  • -preset medium:在编码速度和文件大小之间取得平衡
  • -crf 23:恒定速率因子,用于质量控制(18-28 范围,越低质量越好)
  • -c:a aac:使用 AAC 音频编解码器
  • -b:a 128k:音频比特率 128 kbps

提示:转换能保持 1080p 分辨率,并在现代硬件上提供约 6 倍的编码速度。

快速故障排除参考

仅提供 360p(格式 18)

原因:缺少 PO Token 提供程序或 yt-dlp 版本过旧。

解决方案:

  1. 更新 yt-dlp:brew upgrade yt-dlp
  2. 安装 PO Token 提供程序(参见上面的步骤 1)
  3. 或使用浏览器 cookie 方法

登录以确认你不是机器人

原因:YouTube 要求进行身份验证。

解决方案:

  1. 请求许可并使用浏览器 cookie(--cookies-from-browser chrome)。
  2. 确保浏览器和 yt-dlp 使用相同的 IP/代理。
  3. 如果需要,使用 web_safari 客户端重试。

仅提供图片 / 请求的格式不可用

原因:未应用 PO Token 或提供程序/浏览器验证失败。

解决方案:

  1. 在下载前验证 PO Token 提供程序是否在运行。
  2. 如果使用 WPC,保持浏览器窗口打开。
  3. 如果使用 cookie,优先选择 web_safari 客户端并重试。

nsig 提取失败

症状:

警告:[youtube] nsig 提取失败:某些格式可能缺失

解决方案:

  1. 将 yt-dlp 更新到最新版本
  2. 安装 PO Token 提供程序
  3. 如果仍然失败且 PO Token 已禁用,使用 Android 客户端:yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"

SSL EOF / 片段错误

原因:代理或网络不稳定。

解决方案:

  1. 使用渐进式格式(非 m3u8)重试。
  2. 切换到更稳定的代理/节点。
  3. 避免在下载过程中关闭 PO Token 浏览器窗口。

下载速度慢或网络错误

对于中国用户或位于限制性代理后面的用户:

  • 由于网络状况,下载可能很慢
  • 留出足够的时间完成
  • yt-dlp 会在临时故障时自动重试

PO Token 警告(无害)

警告:android 客户端 https 格式需要 GVS PO Token

操作:如果下载成功,请忽略。这表明 Android 客户端在没有 PO Token 的情况下格式访问受限。

捆绑脚本参考

scripts/download_video.py

使用此便捷包装脚本默认自动启动 PO Token 提供程序,以实现高质量下载。你自己使用它并向用户报告结果,无需要求他们运行命令。

基本用法:

scripts/download_video.py "VIDEO_URL"

参数:

  • url - YouTube 视频 URL(必需)
  • -o, --output-dir - 输出目录
  • --output-template - 输出文件名模板(yt-dlp 语法)
  • -f, --format - 格式规范
  • -q, --quality - 质量标准(best, 1080p, 720p, 480p, 360p, worst)。默认:best(对于 --audio-only 跳过)
  • -a, --audio-only - 以 MP3 格式提取音频
  • --subtitles - 如果可用,下载字幕
  • --sub-lang - 字幕语言(逗号分隔,默认:en)
  • --cookies-from-browser - 从浏览器加载 cookie(例如 chrome, firefox)
  • --cookies-file - 从 cookies.txt 文件加载 cookie
  • --player-client - 使用特定的 YouTube 播放器客户端(例如 web_safari)
  • --auto-po-token - 自动启动 PO Token 提供程序(默认;如果可用则使用 Docker,否则切换到基于浏览器的提供程序)
  • --no-auto-po-token - 禁用自动 PO Token 设置
  • --proxy - 用于 yt-dlp 和 PO Token 提供程序的代理 URL(例如 http://127.0.0.1:1082)
  • --wpc-browser-path - WPC 提供程序的浏览器可执行文件路径
  • -F, --list-formats - 列出可用格式
  • --merge-format - 合并输出容器(例如 mp4, mkv)。默认:mp4
  • --playlist - 允许下载播放列表(默认:仅单个视频)
  • --info - 打印标题/上传者/时长/缩略图并退出
  • --no-android-client - 禁用 Android 客户端回退

注意:仅在 PO Token 禁用时使用 Android 客户端。保持 PO Token 启用以获得高质量。

质量预期

设置360p720p1080p1440p4K
自动 PO token(默认)✓✓✓✓✓
仅 Android 客户端✓✗✗✗✗
PO token 提供程序(手动)✓✓✓✓✓
浏览器 cookie✓✓✓

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

daymade/claude-code-skills

>- Generates Chinese/Japanese speech with StepFun's Contextual TTS — default stepaudio-2.5-tts, stepaudio-3-tts for whisper/inline-() prosody. Replaces step-tts-2's voice_label with natural-language instruction. Use for emotional/prosody-controlled synthesis, batch voice lines, migrating from step-tts-2, or cloned voices (2.5/step-tts-2, not v3). Triggers on 阶跃 TTS, 语音合成, 配音. Not for transcription (use stepfun-asr).

daymade/claude-code-skills

This skill should be used when comparing two videos to analyze compression results or quality differences. Generates interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Triggers when users mention "compare videos", "video quality", "compression analysis", "before/after compression", or request quality assessment of compressed videos.

daymade/local-conversation-history

Entry point for local AI conversation history across providers. Routes a request to the one skill that owns it, by platform (Claude Code, OpenAI Codex, Kimi CLI) and action (read evidence vs continue interrupted work), and owns the one job none of them own alone: a single inventory spanning all three providers. Use when the provider is unknown or plural ("our history", "what have I been working on", "which chats did I have"), when the user wants Kimi CLI history at all, when it is unclear whether they need evidence or resumption, or when they ask for this skill by name. Vague recall that names no platform ("we discussed this once, when was it?") belongs here rather than to a single-provider reader, because a Claude-only answer to an unscoped question cannot support an absence claim. When the platform and the action are both already clear, load that executor skill directly instead — except Kimi CLI, which has no reader or continuation skill of its own and always routes through here.

daymade/ppt-creator

Create professional slide decks from topics or documents. Generates structured content with data-driven charts, speaker notes, and complete PPTX files. Applies persuasive storytelling principles (Pyramid Principle, assertion-evidence). Supports multiple formats (Marp, PowerPoint). Use for presentations, pitches, slide decks, or keynotes.

daymade/prompt-optimizer

Transform vague prompts into precise, well-structured specifications using EARS (Easy Approach to Requirements Syntax) methodology. This skill should be used when users provide loose requirements, ambiguous feature descriptions, or need to enhance prompts for AI-generated code, products, or documents. Triggers include requests to "optimize my prompt", "improve this requirement", "make this more specific", or when raw requirements lack detail and structure.

daymade/qa-expert

This skill should be used when establishing comprehensive QA testing processes for any software project. Use when creating test strategies, writing test cases following Google Testing Standards, executing test plans, tracking bugs with P0-P4 classification, calculating quality metrics, or generating progress reports. Includes autonomous execution capability via master prompts and complete documentation templates for third-party QA team handoffs. Implements OWASP security testing and achieves 90% coverage targets.

daymade/read-claude-code-history

Reads, searches, and exports local Claude Code history without resuming work. Covers recent session inventory, exact session timelines, verbatim human input including queued mid-turn prompts, full-event keyword search, hybrid recall when wording changed, end-state triage, and deleted-file recovery across active Claude homes plus registered archives. Use whenever the user asks what they or Claude said, wants a Claude Code session ID or original context, remembers prior work vaguely, needs an old file from a transcript, or must prove what a Claude session contained before continuing it. Also owns the only Kimi CLI surface, via its Kimi inventory and search flags. For Codex history use read-codex-history; when the request names no platform at all or spans providers, start at local-conversation-history.

daymade/read-codex-history

Reads, searches, and exports local OpenAI Codex history without continuing the old task. Lists recent Codex sessions, extracts exact prompt-ledger inputs by Session, locates a rollout by verified session_meta identity, reconstructs one chronological user/assistant timeline with fork and compaction lineage, and performs bounded keyword search across live and archived rollouts. Use whenever the user asks what they told Codex, wants recent original inputs, a Codex Session ID, full prior context, fork ancestry, or evidence of what a Codex run did. For Claude Code history use read-claude-code-history.

daymade/twitter-reader

Fetch Twitter/X post content including long-form Articles with full images and metadata. Use when Claude needs to retrieve tweet/article content, author info, engagement metrics, and embedded media. Supports individual posts and X Articles (long-form content). Automatically downloads all images to local attachments folder and generates complete Markdown with proper image references. Preferred over Jina for X Articles with images.

相关技能