SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsyt-dlp

yt-dlp

General & other

View repository

Updated 10-16 09:53

About this skill

Yt-dlp

<when_to_use>

  • Scenario 1: Download video or audio from platforms such as YouTube, Bilibili, Twitch, Twitter, Instagram, etc.
  • Scenario 2: Need a specific format, quality, or audio-video separation/merging
  • Scenario 3: Download subtitles, embed metadata, use SponsorBlock to remove ad segments
  • Scenario 4: Use cookies/authentication to access protected or login-required content
  • Scenario 5: Handle playlists, live streams, or channel content
  • Scenario 6: Understand, modify, or extend the yt-dlp source code
  • Scenario 7: Write custom extractors to support new websites
  • Scenario 8: Integrate yt-dlp into a Python project

When not to use:

  • Downloading ordinary files (use wget/curl)
  • Playing videos (use players such as mpv/vlc)
  • Pure video transcoding and editing (use FFmpeg directly)
  • Simple YouTube downloads (GUI tools such as 4K Video Downloader already exist) </when_to_use>

This skill uses the Router Pattern, with SKILL.md as the navigation hub, and the detailed content distributed across:

  • workflows/ - Complete workflows (download, format selection, development)
  • references/ - Core architecture, API documentation, best practices
  • scripts/ - Practical script tools
  • templates/ - Code templates and configuration examples
  • assets/ - Architecture diagrams and flowcharts
yt-dlp-skill/
├── SKILL.md (你在这里)
├── workflows/
│   ├── basic-download.md        # 基础下载流程
│   ├── format-selection.md      # 格式选择工作流
│   ├── authentication.md        # 认证处理流程
│   ├── xhs-download.md          # 小红书下载实战案例
│   └── extractor-development.md # 提取器开发指南
├── references/
│   ├── architecture.md          # 核心架构说明
│   ├── format-selector.md       # 格式选择语法
│   ├── postprocessors.md        # 后处理器参考
│   └── extractor-guide.md       # 提取器开发指南
├── scripts/
│   ├── batch-download.py        # 批量下载脚本
│   ├── format-analyzer.py       # 格式分析工具
│   └── cookie-extractor.py      # Cookies 提取工具
├── templates/
│   ├── extractor-template.py    # 提取器模板
│   ├── config-template.conf     # 配置文件模板
│   └── python-api-template.py   # Python API 模板
└── assets/
    └── architecture-diagram.txt # 架构图

<quick_start>

Quick Start

Basic Download (30 seconds)

# 安装
pip install yt-dlp

# 下载视频（最佳质量）
yt-dlp "https://www.youtube.com/watch?v=VIDEO_ID"

# 只下载音频
yt-dlp -x --audio-format mp3 "URL"

# 选择格式
yt-dlp -f "bestvideo[height<=1080]+bestaudio" "URL"

Python API (1 minute)

import yt_dlp

# 下载
ydl_opts = {'outtmpl': '%(title)s.%(ext)s'}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(['VIDEO_URL'])

# 只获取信息
ydl_opts = {'quiet': True}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    info = ydl.extract_info('URL', download=False)
    print(info['title'])

</quick_start>

Usage-Type Workflows

Development-Type Workflows

Recommended path: Basic Download → Format Selection → Authentication Handling → Extractor Development

Core Concepts

Development Guide

Troubleshooting

Practical Script Tools (located in scripts/）：

  • batch-download.py - Batch download URLs from a file
  • format-analyzer.py - Analyze available formats for a video
  • cookie-extractor.py - Extract cookies from a browser
  • playlist-tools.py - Playlist management tool

Run python scripts/<script-name>.py --help to view detailed usage.

<core_concepts>

Core Concepts at a Glance

Extractors

Each website has an independent extractor class, inheriting from InfoExtractor：

class MySiteIE(InfoExtractor):
    _VALID_URL = r'https?://(?:www\.)?mysite\.com/watch/(?P<id>[^/]+)'

    def _real_extract(self, url):
        # 提取视频信息的逻辑
        video_id = self._match_id(url)
        webpage = self._download_webpage(url, video_id)
        # ... 返回 info_dict

Location:yt_dlp/extractor/*.py

Format Selection

Powerful format selection language:

# 基础
-f best                 # 最佳质量
-f "bestvideo+bestaudio" # 最佳视频+音频

# 过滤
-f "bestvideo[height<=1080]"  # 不高于 1080p
-f "mp4"                      # 只要 MP4

# 排序
-S "res:1080,fmt:mp4,size"    # 按分辨率、格式、大小排序

Postprocessors

Chained processing pipeline:

ydl_opts = {
    'format': 'bestvideo+bestaudio',
    'outtmpl': '%(title)s.%(ext)s',
    'postprocessors': [
        {'key': 'FFmpegVideoConvertor', 'preferedformat': 'mp4'},
        {'key': 'FFmpegMetadata'},
        {'key': 'EmbedThumbnail'},
    ]
}

</core_concepts>

<failure_analysis>

Known Issues and Solutions

Issue 1: FFmpeg-related errors

Symptoms: ffmpeg not found, postprocessor failed Solution:

  • Windows: Download from https://ffmpeg.org and add to PATH
  • Linux: sudo apt install ffmpeg
  • macOS: brew install ffmpeg

Issue 2: Format merge failure

Symptoms: WARNING: Requested formats are incompatible for merge Solution:

yt-dlp --merge-output-format mp4 "URL"
# 或
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]" "URL"

Issue 3: Geo-restricted content

Solution:

yt-dlp --proxy socks5://127.0.0.1:1080 "URL"

Issue 4: Content accessible only after login

Solution:

yt-dlp --cookies-from-browser chrome "URL"
# 或使用 cookies.txt
yt-dlp --cookies cookies.txt "URL"

Issue 5: YouTube rate limiting

Solution:

# 使用 aria2 外部下载器
yt-dlp --external-downloader aria2 --external-downloader-args "-x 8 -k 1M" "URL"

# 或限制速率避免被封
yt-dlp --limit-rate 1M "URL"

</failure_analysis>

<success_criteria> Criteria for successfully using this skill:

  • Able to download videos/audio from various websites
  • Understand and use format selection syntax
  • Able to handle subtitles, metadata, and authentication
  • Able to navigate and understand the yt-dlp source code
  • Able to solve common download issues
  • Able to write simple custom extractors
  • Able to integrate yt-dlp into Python projects </success_criteria>