youtube-downloader

Name: youtube-downloader
Author: daymade

github.com/daymade创意与媒体1.5k1.5k 次安装今天更新

代码仓库

关于 youtube-downloader

youtube-downloader 是面向下载任务的技能，使用 yt-dlp 和 ffmpeg 获取 YouTube 与 HLS 平台的视频或音频。它区分媒体文件下载与文字转写需求，并提供格式选择、故障排查和授权恢复流程。

主要功能

01下载 YouTube 视频和音频
02获取 HLS 流媒体
03支持字幕与格式选择
04按授权处理受限内容
05排查下载和画质问题

适用场景

01保存 YouTube 视频供离线观看
02提取视频音频为 MP3
03下载带认证请求头的 HLS 流
04获取字幕或视频转写文本

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/daymade/claude-code-skills --skill youtube-downloader

安装后在 Claude Code 中输入/youtube-downloader确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

internal-sop.md

po-token-setup.md

text-first.md

scripts/

download_video.py

tests/

test_download_video.py

详细介绍

YouTube 下载器

概述

使用 yt-dlp 和 ffmpeg，从 YouTube 和 HLS 流媒体平台（Mux、Vimeo 等）可靠地下载视频和音频。本工具提供以下工作流：

以可用画质下载 YouTube 视频，可选使用 PO Token 和经授权的 Cookie 恢复
使用身份验证标头下载 HLS 流
处理受保护的内容，并排查常见下载失败问题

目标区分：文件还是文本（请先阅读）

开始下载前，先判断用户的请求类型：

用户要的是视频／音频文件本身（保存、编辑、离线观看）→ 按照下方下载流程继续，不作更改。
用户要的是语音内容的文本（转录文本、字幕、会议记录、存档、“说了什么”）→ 首先按照 references/text-first.md 操作：先查找现有的存档转录文本 → 平台转录文本 API → 仅使用 yt-dlp 下载字幕 → 获取经授权的音轨并进行 ASR。不要为了获取文本而下载完整视频。

文本优先流程不会阻止文件请求：如果用户要的是文件，请按照下方原样的流程下载。

面向非技术用户的体验（默认）

假设用户不懂技术。不要让用户运行命令。所有操作都由你执行，并用通俗的语言报告进度。除非用户询问，否则不要提及工具。

默认流程：

如果用户没有提供 URL，请询问。
获取视频元数据（标题／上传者／时长／缩略图），并确认内容符合用户的意图。
- 如果 yt-dlp 因“确认你不是机器人”而被拦截，则改用 YouTube oEmbed 获取标题／上传者／缩略图（时长可能未知）。
提供简单选项（视频还是仅音频、画质、字幕、保存位置）。
如果用户未指定，则采用合理的默认设置：
- 以最佳画质下载视频
- 合并输出为 MP4
- 仅下载单个视频（不下载播放列表）
下载完成后，报告最终文件路径、文件大小和分辨率（如果是视频）。

以用户易于理解的方式提供选项：

“以最佳画质下载视频（默认）”
“仅下载音频（MP3）”
“选择画质：1080p / 720p / 480p / 360p”
“添加字幕（如果有）”
“保存到 Downloads 文件夹（默认），或告诉我其他文件夹”

有缩略图时，始终显示缩略图：

如果元数据中包含缩略图 URL，请使用 Markdown 图片语法展示：![Thumbnail](URL)。

执行额外操作前先征求同意：

下载播放列表前先确认（可能会很大）。
缺少依赖项时，安装或升级前先确认。
提取浏览器 Cookie 前先询问。
如果使用 Cookie，面向用户的回复中绝不提及 Cookie 数量或原始 Cookie 详情。请说“使用了你 Chrome 的登录会话”。
仅在进行明确的 Token 诊断或用户提出请求后，才设置 PO Token 辅助工具，并且必须在现有安装／服务授权范围内。如果已有该授权，则执行恢复操作并继续下载；否则，仅请求缺少的权限。不要将安装 Docker 作为备用方案；适当时使用已授权的浏览器提供程序。

法律／安全提醒（简短）：

仅在用户拥有下载内容的权利或已获得许可时继续。

回复模板（使用通俗语言，不要包含命令）：

![Thumbnail](THUMBNAIL_URL)

Title: …
Channel: …
Duration: …

I can help you:
1) Download the video (best quality, MP4)
2) Download audio only (MP3)
3) Pick a specific quality (1080p/720p/480p/360p)
4) Include subtitles (if available)

Where should I save it? (Default: Downloads folder)

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

使用默认设置继续，并在下载完成后确认。
- 如果遭到拦截，请按照下方 SOP 判断实际诊断结果，并执行相应的授权恢复操作。

可靠下载 SOP（内部）

重试失败前，请阅读下载 SOP。从 yt-dlp 当前默认客户端和现有网络配置开始。不要仅为了开始下载就要求用户提供服务提供商、切换到 Android 或提取浏览器 Cookie。

Agent 执行清单（内部）

运行 scripts/download_video.py URL --info 获取元数据。它不会启动任何提供方；提取失败时，其 oEmbed 回退仅提供有限字段。
有缩略图时，渲染缩略图。按要求使用文件／音频、质量、字幕和保存位置；如果已指定或暗示默认值，则使用默认设置。
先执行常规下载。如果已安装 Node 运行时，且 yt-dlp 需要它，则传入 --js-runtimes node；安装运行时仍须遵循依赖授权流程。
失败时，查看实际错误和 -F 输出。请求的格式不存在、仅输出图片、出现 403 或分辨率较低，这些情况本身都不能证明是令牌问题。
如果失败的请求明确报告缺少或需要 PO Token，请阅读提供方设置。在现有设置授权范围内，执行 --auto-po-token 并完成原始下载；不要只给用户一条命令就停止。此选项会先尝试原生途径，然后允许进行有次数限制的提供方重试和 WPC 恢复。
在提供任一 Cookie 选项前，先请求浏览器 Cookie 权限。整个重试过程中，保留已授权的 Cookie 会话和兼容的客户端。
对于单独出现的 403／片段失败，封装脚本可以使用渐进式格式重试一次质量预设。请验证最终分辨率；回退结果的质量可能较低。自定义格式和纯音频请求会保留其明确指定的选择。
使用 ffprobe 验证最终文件，并报告其路径、大小以及实际分辨率或音频属性。提供方运行状态正常或格式列表存在，都不代表下载已完成。

何时使用此技能

当用户遇到以下情况时，应调用此技能：

请求下载 YouTube 视频或播放列表
想从 YouTube 视频中提取音频
遇到 yt-dlp 下载失败或可用格式有限
需要格式选择或质量选项方面的帮助
仅报告可用格式为低质量（360p）
询问如何下载特定画质（1080p、4K 等）的 YouTube 内容
需要将下载的 WebM 视频转换为 MP4 格式，以提高兼容性
请求从 Mux、Vimeo 等平台或其他流媒体服务下载 HLS 流（m3u8）
需要下载要求提供身份验证标头的受保护流

前提条件

1. 验证 yt-dlp 是否已安装（由你运行）

which yt-dlp
yt-dlp --version

如果缺少 yt-dlp，或当前提取诊断要求更新，请先取得所需的安装／升级授权，然后使用现有安装的所有者：

brew upgrade yt-dlp  # macOS
# or
pip install --upgrade yt-dlp  # Cross-platform

查看最新的 EJS 设置指南，了解已安装发行版对 JavaScript 运行时和挑战求解器的要求。已安装的 Node 二进制文件可能需要显式指定 --js-runtimes node；不要将 EJS/nsig 失败视为 PO Token 问题。

2. 检查当前画质访问情况（由你运行）

下载前，请检查可用格式：

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

将列出的媒体流与请求的画质进行比较。如果仅显示低分辨率格式，请先检查提取／运行时警告和源内容的可用情况，再选择恢复方式。

高清下载工作流

步骤 1：尝试原生客户端选择

除非存在具体诊断信息或用户明确要求，否则不要设置 player_client。官方提取器指南介绍了 yt-dlp 默认使用不需要令牌的客户端进行尝试。可用格式取决于视频、账户、客户端、网络以及 YouTube 当前的限制措施。

步骤 2：仅在需要时下载并升级处理

# Download best quality up to 1080p
scripts/download_video.py "VIDEO_URL" --quality 1080p

# Download best available quality
scripts/download_video.py "VIDEO_URL"

# After an explicit token requirement, with setup already authorized
scripts/download_video.py "VIDEO_URL" --auto-po-token

如需安装和提供方特定的恢复方式，请加载 PO Token 设置。不要仅凭分辨率推断需要使用提供方。

步骤 3：验证下载质量

# Check video resolution
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 方式

当内容需要授权账户访问，或机器人验证持续出现时，在获得 Cookie 授权后使用 Cookie。Cookie 用于验证会话；它不能替代缺失的 PO Token：

# 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/代理。
保留 yt-dlp 默认的 Cookie 兼容客户端；仅在有针对性地重试时使用 web_safari。不要将账户 Cookie 与不支持 Cookie 的 Android/iOS 客户端搭配使用。

常见任务

仅下载音频（自行运行）

提取音频并保存为 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 可获得更广泛的兼容性：

# Check if ffmpeg is installed
which ffmpeg || brew install ffmpeg  # macOS

# Convert WebM to MP4 with good quality settings
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 倍的编码速度。

故障排查速查

缺少画质 / 只有图片 / 请求的格式不可用

检查 -F、所选格式表达式、当前的 yt-dlp/EJS/运行时警告以及源是否可用。这些提示可能由多种原因导致。只有在提取或媒体请求失败时同时提示缺少/需要 PO Token，才进入提供方设置。不要仅仅因为缺少所请求的高度或格式 ID 就安装提供方。

登录以确认你不是机器人

确认正在使用预期的代理/网络。如果验证仍然出现，且需要 Cookie，请先取得 Cookie 授权，保留该会话，然后重试。如果无法获得授权，请明确说明具体的授权缺失；不要在未告知的情况下读取浏览器 Cookie。

nsig / JavaScript 验证失败

检查已安装的 yt-dlp 版本，并参阅 EJS 运行时和求解器说明。在获得授权的范围内修复已诊断出的前置条件。可以明确选择 Android 或 AndroidVR 进行有限的诊断，但它们都不是默认的恢复方式，也不保证能解决问题。

403 / SSL EOF / 分片错误

区分媒体 403 与 TLS、超时、代理和提供方健康状态错误。常见的 403 并不能证明需要 Token。对于 SSL/超时故障，请先检查网络路径；只有在相关条件发生变化后才重试。对于使用画质预设时发生的 403/分片错误，封装程序会进行一次渐进式重试，但可能会降低画质。

下载缓慢或网络错误

对于身处中国或使用限制性代理的用户：

网络状况可能导致下载缓慢
请留出充足的完成时间
yt-dlp 会在暂时性故障时自动重试

PO Token 警告（无害）

WARNING: android client https formats require a GVS PO Token

处理方式：如果下载成功且已验证，无需为未使用客户端的警告进行修复。若下载失败，请先阅读完整诊断信息和实际可用格式，再选择 Token 处理分支。

内置脚本参考

scripts/download_video.py

此包装脚本用于原生客户端下载和有限范围内的诊断恢复。默认情况下，它不会安装或启动提供方，也不会读取 Cookie。请自行执行并报告已验证的文件。

基本用法：

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 - 在明确诊断出缺少或必需令牌后，授权配置提供方；先尝试原生客户端，再尝试 Docker bgutil 或浏览器 WPC
--no-auto-po-token - 禁用提供方配置（默认）；不会禁用已安装的 yt-dlp 插件
--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 - 保留的兼容性选项；此包装脚本已保持原生客户端选择不变
--js-runtimes - 向 yt-dlp 传入已安装的运行时，例如 node 或 node:/path/to/node

画质要求

不要根据提供方／客户端／Cookie 的组合承诺分辨率。请请求所需画质、检查可用格式，并验证实际下载的文件。无需配置新的提供方即可成功下载高分辨率内容，只能证明该输入和环境可行；已安装的插件或配置仍可能发挥作用。提供方无法生成源内容中不存在的分辨率。

HLS 流下载（m3u8）

对于 Mux、Vimeo 等基于 HLS 的流媒体平台，请优先使用 ffmpeg。这些流通常需要身份验证标头，而 yt-dlp 可能无法正确处理。

识别 HLS 流

HLS 流使用 .m3u8 播放列表文件：

主播放列表：列出多个画质选项
媒体播放列表：包含实际的视频／音频分段 URL

下载工作流

第 1 步：获取流 URL

从视频源获取 m3u8 URL。对于受保护的流：

打开浏览器 DevTools → Network 标签页
播放视频
筛选 "m3u8"，查找播放列表 URL
复制媒体播放列表 URL（通常包含 "rendition.m3u8" 等画质信息）

第 2 步：确定所需标头

许多 CDN 需要身份验证标头：

Referer：来源网站（例如 https://maven.com/）
Origin：与 Referer 相同，用于 CORS
User-Agent：浏览器标识

检查 Network 标签页，查看浏览器发送了哪些标头。

第 3 步：使用 ffmpeg 下载

对于受保护的流，使用带 -headers 标记的 ffmpeg：

ffmpeg -headers "Referer: https://example.com/" \
  -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
  -i "https://cdn.example.com/path/rendition.m3u8?params" \
  -c copy -bsf:a aac_adtstoasc \
  output.mp4

关键参数：

-headers：设置 HTTP 标头（身份验证的关键）
-protocol_whitelist：启用 HLS 所需的协议
-c copy：流复制（不重新编码，速度更快）
-bsf:a aac_adtstoasc：修复 AAC 音频兼容性

常见标头模式：

# Single header
-headers "Referer: https://example.com/"

# Multiple headers
-headers "Referer: https://example.com/" \
-headers "User-Agent: Mozilla/5.0..."

# Alternative syntax
-headers $'Referer: https://example.com/\r\nUser-Agent: Mozilla/5.0...'

处理分离的音频／视频流

有些平台（如 Mux）会分别提供音频和视频：

下载音频流：

ffmpeg -headers "Referer: https://example.com/" \
  -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
  -i "https://cdn.example.com/audio/rendition.m3u8" \
  -c copy audio.m4a

下载视频流：

ffmpeg -headers "Referer: https://example.com/" \
  -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
  -i "https://cdn.example.com/video/rendition.m3u8" \
  -c copy video.mp4

合并流：

ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4

HLS 下载故障排查

403 Forbidden 错误

原因：缺少身份验证标头，或标头不正确。

解决方法：

验证 Referer 标头是否与视频来源网站匹配
检查是否需要其他标头（Origin、User-Agent）
确保 m3u8 URL 包含浏览器中的所有查询参数

yt-dlp 卡在提取 Cookie 阶段

症状：Extracting cookies from chrome 无限期卡住。

解决方法：对于 HLS 流，直接使用 ffmpeg 代替 yt-dlp。

协议未列入白名单

错误：Protocol 'https' not on whitelist 'file,crypto,data'

解决方法：添加 -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy

片段为空或没有流

原因：m3u8 URL 中的签名已过期。