Communitygithub.com

IGTA-Tech/claude-skills-research

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

claude-skills-research 是什么?

此技能为 AI 代理(如 Claude Code、Cursor、Codex)提供了一套全面的视频下载工作流,支持从 YouTube 下载高质量视频(最高 4K)以及从 Mux、Vimeo 等 HLS 流媒体平台下载受保护内容。核心依赖 yt-dlp 和 ffmpeg,通过安装 PO 令牌提供器或浏览器 cookie 方法解决 YouTube 的下载限制;对于 HLS 流,则使用 ffmpeg 配合认证头(如 Referer)来处理 CDN 鉴权。该技能涵盖了常见任务,如音频提取、格式转换(WebM 转 MP4)、字幕下载、播放列表下载,并提供了详细的故障排查指南,包括 nsig 提取失败、403 错误和 cookie 问题。它适用于 macOS 和跨平台环境,帮助开发者高效应对各种视频下载场景。

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

在你喜欢的 AI 中提问

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

文档

YouTube 下载器

概述

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

  • YouTube 下载(最高 4K),使用 PO 令牌提供器或浏览器 cookie
  • 使用认证头进行 HLS 流下载
  • 处理受保护内容并排查常见下载失败问题

何时使用此技能

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

  • 请求下载 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 令牌提供器以获得高质量访问。

高质量下载工作流

步骤 1:安装 PO 令牌提供器(一次性设置)

要访问 1080p/1440p/4K,在 yt-dlp 的 Python 环境中安装 PO 令牌提供器插件:

# 查找 yt-dlp 的 Python 路径
head -1 $(which yt-dlp)

# 安装插件(根据 yt-dlp 版本调整路径)
/opt/homebrew/Cellar/yt-dlp/$(yt-dlp --version)/libexec/bin/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 令牌提供器后:

# 下载最高 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 令牌提供器设置有问题,请使用浏览器 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。

常见任务

仅下载音频

将音频提取为 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 令牌提供器或 yt-dlp 版本过旧。

解决方案:

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

nsig 提取失败

症状:

WARNING: [youtube] nsig extraction failed: Some formats may be missing

解决方案:

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

下载缓慢或网络错误

对于在中国或受限代理后面的用户:

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

PO 令牌警告(无害)

WARNING: android client https formats require a GVS PO Token

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

捆绑脚本参考

scripts/download_video.py

一个便利封装器,默认应用 Android 客户端解决方法:

基本用法:

scripts/download_video.py "VIDEO_URL"

参数:

  • url - YouTube 视频 URL(必需)
  • -o, --output-dir - 输出目录
  • -f, --format - 格式规范
  • -a, --audio-only - 将音频提取为 MP3
  • -F, --list-formats - 列出可用格式
  • --no-android-client - 禁用 Android 客户端解决方法

注意:此脚本使用 Android 客户端(没有 PO 令牌时仅支持 360p)。要获得高质量,请直接使用带 PO 令牌提供器的 yt-dlp。

质量预期

设置360p720p1080p1440p4K
无设置(默认)✗✗✗✗✗
仅 Android 客户端✓✗✗✗✗
PO 令牌提供器✓✓✓✓✓
浏览器 cookie✓✓✓✓✓

HLS 流下载 (m3u8)

对于像 Mux、Vimeo 和其他基于 HLS 的服务等流媒体平台,请使用 ffmpeg 作为主要工具。这些流通常需要认证头,yt-dlp 可能无法正确处理。

识别 HLS 流

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

  • 主播放列表:列出多个质量选项
  • 转码播放列表:包含实际的视频/音频片段 URL

下载工作流

步骤 1:获取流 URL

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

  1. 打开浏览器开发者工具 → 网络选项卡
  2. 播放视频
  3. 过滤 "m3u8" 以查找播放列表 URL
  4. 复制转码 URL(通常包含质量信息,如 "rendition.m3u8")

步骤 2:识别所需头

许多 CDN 需要认证头:

  • Referer:来源网站(例如 https://maven.com/)
  • Origin:与 Referer 相同,用于 CORS
  • User-Agent:浏览器标识

检查网络选项卡以查看浏览器发送了哪些头。

步骤 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 音频兼容性

常见的头模式:

# 单头
-headers "Referer: https://example.com/"

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

# 替代语法
-headers $'Referer: https://example.com/\r\nUser-Agent: Mozilla/5.0...'

处理分离的音频/视频流

某些平台(如 Mux)会分别传送音频和视频:

  1. 下载音频流:
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
  1. 下载视频流:
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
  1. 合并流:
ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4

HLS 下载故障排查

403 禁止错误

原因:缺失或不正确的认证头。

解决方案:

  1. 验证 Referer 头与视频源网站匹配
  2. 检查是否需要其他头(Origin、User-Agent)
  3. 确保 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 中的签名已过期。

解决方案:

  1. 从浏览器开发者工具获取新的 URL
  2. 获取 URL 后立即下载
  3. 查找具有更新签名参数的转码 URL

性能提示

  • HLS 下载通常以 10-15 倍实时速度运行
  • 使用 -c copy 无需重新编码(最快)
  • 通过实时进度显示监控下载
  • 使用绝对输出路径以避免目录混乱

延伸阅读

Individual skills in this repo

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

IGTA-Tech/claude-skills-research

Use when localizing apps, using String Catalogs, generating type-safe symbols (Xcode 26+), handling plurals, RTL layouts, locale-aware formatting, or migrating from .strings files - comprehensive i18n patterns for Xcode 15-26

IGTA-Tech/claude-skills-research

Use when implementing SwiftUI animations, understanding VectorArithmetic, using @Animatable macro, choosing between spring and timing curve animations, or debugging animation behavior - comprehensive animation reference from iOS 13 through iOS 26

IGTA-Tech/claude-skills-research

Use when CAAnimation completion handler doesn't fire, spring physics look wrong on device, animation duration mismatches actual time, gesture + animation interaction causes jank, or timing differs between simulator and real hardware - systematic CAAnimation diagnosis with CATransaction patterns, frame rate awareness, and device-specific behavior

IGTA-Tech/claude-skills-research

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.

IGTA-Tech/claude-skills-research

Write high-converting landing page copy using proven frameworks like PAS (Problem-Agitate-Solution), AIDA, and StoryBrand. Creates headlines, value propositions, CTAs, and full page sections optimized for conversion. Use when users need landing page copy, sales page content, or marketing website text.

IGTA-Tech/claude-skills-research

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

IGTA-Tech/claude-skills-research

Download YouTube video transcripts when user provides a YouTube URL or asks to download/get/fetch a transcript from YouTube. Also use when user wants to transcribe or get captions/subtitles from a YouTube video.

相关技能