Communitygithub.com

YouTube下载器

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

YouTube下载器 是什么?

这是一个AI代理技能,旨在通过yt-dlp和ffmpeg实现可靠的高质量视频和音频下载。它支持YouTube(最高4K)以及基于HLS的流媒体平台(如Mux、Vimeo等)。该技能封装了处理受保护内容、绕过机器人检查以及解决常见下载故障(如nsig提取失败、403错误和仅限360p格式等)的完整工作流。该过程对非技术用户完全透明:代理会自行执行命令,通过自然语言报告进度,并以用户友好的术语提供选项(如“下载最佳质量视频”或“仅提取MP3音频”)。在底层,它包含一个详细的内部SOP,以确保可靠性:自动启动PO令牌提供程序(优先使用Docker,必要时回退到基于浏览器的WPC提供程序),处理cookie验证,并智能管理代理/网络问题。该技能在提供高质量下载方面表现出色,解决了许多用户遇到的标准yt-dlp设置中仅限360p的问题。它包含一个方便的Python脚本(scripts/download_video.py),该脚本封装了大部分逻辑,支持格式选择、字幕、播放列表和合并格式选项。对于开发者而言,该技能提供了清晰的故障排除指南和预期质量标准表,使其成为在代理环境中或对无法访问高质量格式用户的强大解决方案。

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

在你喜欢的 AI 中提问

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

预览

来自技能 README

Thumbnail
Thumbnail

文档

YouTube下载器 是做什么的?

概述

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

  • 使用PO令牌提供程序或浏览器cookie进行YouTube下载(最高4K)
  • 使用认证头进行HLS流下载
  • 处理受保护内容并解决常见下载故障

非技术用户体验(默认)

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

默认流程:

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

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

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

始终在可用时渲染缩略图:

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

在进行额外工作前询问:

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

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

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

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

![Thumbnail](THUMBNAIL_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令牌提供程序均处于活动状态(HTTP_PROXY/HTTPS_PROXY/ALL_PROXY)。
  3. 如果看到“登录以确认你不是机器人”,请求权限并使用浏览器cookie。在没有cookie的情况下不要继续。
  4. 在下载前启动PO令牌提供程序(如果无法启动则快速失败)。
    • 当可用时使用Docker bgutil提供程序。
    • 如果Docker缺失或失败,切换到基于浏览器的WPC提供程序。
  5. 如果正在使用cookie,优先使用web_safari播放器客户端。否则,对于PO令牌优先使用mweb。
  6. 在WPC铸造令牌时保持浏览器窗口打开。确保Chrome可以通过同一代理访问YouTube。
  7. 如果遇到“仅图像可用”或“请求的格式不可用”,将其视为PO令牌失败,并在修复令牌提供程序/浏览器状态后重试。
  8. 如果遇到SSL EOF或片段错误,将其视为代理/网络问题。使用渐进格式和/或更好的代理重试。

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

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

高质量下载工作流

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

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

# 查找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令牌提供程序后:

# 以最高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。
  • 浏览器和yt-dlp必须使用相同的IP/代理。
  • 不要将Android客户端与cookie一起使用(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令牌提供程序或yt-dlp过时。

解决方案:

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

登录以确认你不是机器人

原因:YouTube需要身份验证才能继续。

解决方案:

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

仅图像可用 / 请求的格式不可用

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

解决方案:

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

nsig提取失败

症状:

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

解决方案:

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

SSL EOF / 片段错误

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

解决方案:

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

下载慢或网络错误

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

  • 由于网络条件,下载可能较慢
  • 允许足够的时间完成
  • yt-dlp会自动重试临时故障

PO令牌警告(无害)

WARNING: android client https formats require a GVS PO Token

操作:如果下载成功则忽略。这表示没有PO令牌时Android客户端对格式访问受限。

捆绑脚本参考

scripts/download_video.py

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

基本用法:

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令牌提供程序(默认;如果可用则使用Docker,否则切换到基于浏览器的提供程序)
  • --no-auto-po-token - 禁用自动PO令牌设置
  • --proxy - yt-dlp和PO令牌提供程序的代理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令牌禁用时使用Android客户端。保持PO令牌启用以获得高质量。

质量预期

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

Individual skills in this repo

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

Biznomad/agent-skills

Landing page quality assessment for paid advertising campaigns. Evaluates message match, page speed, mobile experience, trust signals, form optimization, and conversion rate potential. Use when user says "landing page", "post-click experience", "landing page audit", "conversion rate", or "landing page optimization".

Biznomad/agent-skills

TikTok Ads deep analysis covering creative quality, tracking, bidding, campaign structure, and TikTok Shop. Evaluates 25 checks with emphasis on creative-first strategy, safe zone compliance, and Smart+ campaigns. Use when user says "TikTok Ads", "TikTok marketing", "TikTok Shop", "Spark Ads", "Smart+", or "TikTok campaign".

Biznomad/agent-skills

YouTube Ads specific analysis covering campaign types, creative quality, audience targeting, and measurement. Evaluates video ad performance across skippable, non-skippable, bumper, Shorts, and Demand Gen formats. Use when user says "YouTube Ads", "video ads", "pre-roll", "bumper ads", "YouTube campaign", or "Shorts ads".

Biznomad/agent-skills

Help users get promoted at work. Use when someone is preparing for a promotion conversation, building their case for advancement, trying to understand what's blocking their promotion, or figuring out how to get to the next level in their career.

Biznomad/agent-skills

CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

Biznomad/agent-skills

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Biznomad/agent-skills

Read-only queue dashboard for workspace-aware ship. Shows which VERSION slots are currently claimed by open PRs, which sibling Conductor workspaces have WIP work likely to ship soon, and what slot /ship would pick next. No mutations — just a snapshot. Use when asked to "landing report", "what's in the queue", "show me open PRs", or "which version do I claim next". (gstack)

Biznomad/agent-skills

HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

Biznomad/agent-skills

Asset preprocessing for HyperFrames compositions — text-to-speech narration (Kokoro), audio/video transcription (Whisper), and background removal for transparent overlays (u2net). Use when generating voiceover from text, transcribing speech for captions, removing the background from a video or image to use as a transparent overlay, choosing a TTS voice or whisper model, or chaining these (TTS → transcribe → captions). Each command downloads its own model on first run.

Biznomad/agent-skills

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

Biznomad/agent-skills

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill.

Biznomad/agent-skills

Still-to-video conversion guide: model selection, motion prompting, and camera movement. Covers Wan 2.5 i2v, Seedance, Fabric, Grok Video with when to use each. Use for: animating images, creating video from stills, adding motion, product animations. Triggers: image to video, i2v, animate image, still to video, add motion to image, image animation, photo to video, animate still, wan i2v, image2video, bring image to life, animate photo, motion from image

Biznomad/agent-skills

>- The Landing Page Audit skill performs comprehensive evaluations of post-click experiences, combining technical performance analysis with conversion rate optimization (CRO) assessment.

Biznomad/agent-skills

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.

Biznomad/agent-skills

Optimize landing pages for higher conversion rates using proven frameworks and design patterns. Use when designing, reviewing, or improving landing pages, hero sections, pricing pages, CTAs, or when the user asks about conversion optimization.

Biznomad/agent-skills

Read-only queue dashboard for workspace-aware ship. (gstack)

Biznomad/agent-skills

Building promotion cases, brag documents, tracking wins, and self-advocacy for career advancement. Use when preparing for promotions, documenting accomplishments, or building your case for advancement.

Biznomad/agent-skills

Best practices for Remotion - Video creation in React

Biznomad/agent-skills

Translate an existing Remotion (React-based) video composition into a HyperFrames HTML composition. Use ONLY when the user explicitly asks to port, convert, migrate, translate, or rewrite a Remotion composition as HyperFrames (e.g. "port my Remotion project to HyperFrames"). Do NOT use when (a) authoring a NEW HyperFrames composition (even if A/B-testing a Remotion video); (b) Remotion is mentioned in passing; (c) Remotion code is shared as reference, not for translation; (d) the user wants "the same video as my Remotion one" without explicitly asking to migrate the source — treat as a fresh HyperFrames build. When in doubt, default to the `hyperframes` skill. Detects unsupported patterns (useState, useEffect side effects, async calculateMetadata, third-party React component libraries, `@remotion/lambda`) and recommends the runtime interop escape hatch instead of a lossy translation.

Biznomad/agent-skills

Produce programmable videos with Remotion using scene planning, asset orchestration, and validation gates for automated, brand-consistent video content.

相关技能