# Yt Dlp Downloader

> Download videos and audio from YouTube and 1000+ websites using yt-dlp. Use when the user provides a video URL, asks to download videos, or mentions downloading content from video platforms like YouTube, Bilibili, Vimeo, etc.

- **Type:** Skill
- **Install:** `agentstack add skill-demondamon-agenticx-agentskills-yt-dlp-downloader`
- **Verified:** Pending review
- **Seller:** [DemonDamon](https://agentstack.voostack.com/s/demondamon)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [DemonDamon](https://github.com/DemonDamon)
- **Source:** https://github.com/DemonDamon/AgenticX-AgentSkills/tree/main/skills/yt-dlp-downloader

## Install

```sh
agentstack add skill-demondamon-agenticx-agentskills-yt-dlp-downloader
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# yt-dlp Video Downloader

Download videos and audio from YouTube, Bilibili, Vimeo, and 1000+ other websites using yt-dlp.

## Quick Start

When the user provides a video URL, automatically:

1. **检测环境**
   - 检测操作系统（macOS/Linux/Windows）
   - 检测 Python 和 pip 是否可用
   - 检测包管理器（brew/apt-get 等）

2. **检查 yt-dlp 是否已安装**
   ```bash
   yt-dlp --version
   ```
   如果已安装，会显示版本号；如果未安装，继续下一步。

3. **如果未安装，根据环境自动安装**
   ```bash
   # macOS/Linux: 优先使用 pip3
   pip3 install yt-dlp
   
   # 如果没有 pip3，使用 pip
   pip install yt-dlp
   
   # macOS 也可以使用 Homebrew
   brew install yt-dlp
   ```

4. **（可选）检查并安装 FFmpeg**
   ```bash
   # 检查 FFmpeg
   ffmpeg -version
   
   # macOS
   brew install ffmpeg
   
   # Linux (Debian/Ubuntu)
   sudo apt-get install ffmpeg
   ```

5. **检测代理配置（如果需要）**
   ```bash
   # 安装脚本会自动检测代理
   python3 .cursor/skills/yt-dlp-downloader/install_yt_dlp.py
   
   # 或手动检测
   echo $HTTP_PROXY  # 检查环境变量
   networksetup -getwebproxy Wi-Fi  # macOS 系统代理
   ```

6. **下载视频**
   ```bash
   # 基本下载
   yt-dlp 
   
   # 如果需要代理
   yt-dlp --proxy http://127.0.0.1:33210 
   
   # 如果需要 cookies
   yt-dlp --cookies cookies.txt 
   
   # 代理 + cookies
   yt-dlp --proxy http://127.0.0.1:33210 --cookies cookies.txt 
   ```

**完整自动化流程示例：**

```python
# 1. 检测环境
import platform
import subprocess
import shutil

os_name = platform.system()
has_pip3 = shutil.which("pip3") is not None
has_pip = shutil.which("pip") is not None

# 2. 检查安装
try:
    version = subprocess.check_output(["yt-dlp", "--version"], text=True).strip()
    print(f"yt-dlp 已安装: {version}")
except FileNotFoundError:
    # 3. 自动安装
    pip_cmd = "pip3" if has_pip3 else "pip"
    subprocess.run([pip_cmd, "install", "yt-dlp"], check=True)
    print("yt-dlp 安装完成")

# 4. 下载视频
subprocess.run(["yt-dlp", video_url])
```

## Installation

### 快速安装（推荐）

**使用提供的安装脚本：**

```bash
# Python 脚本（跨平台）
python3 .cursor/skills/yt-dlp-downloader/install_yt_dlp.py

# Shell 脚本（macOS/Linux）
bash .cursor/skills/yt-dlp-downloader/install_yt_dlp.sh
# 或
chmod +x .cursor/skills/yt-dlp-downloader/install_yt_dlp.sh
./.cursor/skills/yt-dlp-downloader/install_yt_dlp.sh
```

安装脚本会自动：
1. 检测操作系统和 Python 环境
2. 检查 yt-dlp 是否已安装
3. 如果未安装，根据环境自动选择安装方式
4. 可选：检查并安装 FFmpeg

### 环境检测和自动安装流程

在使用 yt-dlp 之前，应该：

1. **检测操作系统和 Python 环境**
2. **检查 yt-dlp 是否已安装**
3. **如果未安装，根据环境自动安装**
4. **检查并安装 FFmpeg（可选但推荐）**

### 环境检测脚本

**Python 脚本示例：**

```python
import sys
import platform
import subprocess
import shutil

def detect_environment():
    """检测当前环境"""
    os_name = platform.system()
    os_version = platform.release()
    python_version = sys.version_info
    is_mac = os_name == "Darwin"
    is_linux = os_name == "Linux"
    is_windows = os_name == "Windows"
    
    # 检测包管理器
    has_brew = shutil.which("brew") is not None
    has_apt = shutil.which("apt-get") is not None
    has_pip = shutil.which("pip") is not None
    has_pip3 = shutil.which("pip3") is not None
    
    return {
        "os": os_name,
        "os_version": os_version,
        "python_version": f"{python_version.major}.{python_version.minor}.{python_version.micro}",
        "is_mac": is_mac,
        "is_linux": is_linux,
        "is_windows": is_windows,
        "has_brew": has_brew,
        "has_apt": has_apt,
        "has_pip": has_pip,
        "has_pip3": has_pip3,
    }

def check_yt_dlp_installed():
    """检查 yt-dlp 是否已安装"""
    try:
        result = subprocess.run(
            ["yt-dlp", "--version"],
            capture_output=True,
            text=True,
            timeout=5
        )
        if result.returncode == 0:
            return True, result.stdout.strip()
        return False, None
    except (FileNotFoundError, subprocess.TimeoutExpired):
        return False, None

def install_yt_dlp(env_info):
    """根据环境安装 yt-dlp"""
    # 优先使用 pip3，其次 pip
    pip_cmd = "pip3" if env_info["has_pip3"] else "pip"
    
    if not env_info["has_pip"] and not env_info["has_pip3"]:
        raise RuntimeError("未找到 pip 或 pip3，请先安装 Python 包管理器")
    
    print(f"使用 {pip_cmd} 安装 yt-dlp...")
    result = subprocess.run(
        [pip_cmd, "install", "yt-dlp"],
        capture_output=True,
        text=True
    )
    
    if result.returncode == 0:
        print("yt-dlp 安装成功！")
        return True
    else:
        print(f"安装失败: {result.stderr}")
        return False

def check_ffmpeg_installed():
    """检查 FFmpeg 是否已安装"""
    try:
        result = subprocess.run(
            ["ffmpeg", "-version"],
            capture_output=True,
            text=True,
            timeout=5
        )
        if result.returncode == 0:
            return True
        return False
    except (FileNotFoundError, subprocess.TimeoutExpired):
        return False

def install_ffmpeg(env_info):
    """根据环境安装 FFmpeg"""
    if env_info["is_mac"] and env_info["has_brew"]:
        print("使用 Homebrew 安装 FFmpeg...")
        subprocess.run(["brew", "install", "ffmpeg"])
    elif env_info["is_linux"] and env_info["has_apt"]:
        print("使用 apt-get 安装 FFmpeg...")
        subprocess.run(["sudo", "apt-get", "update"])
        subprocess.run(["sudo", "apt-get", "install", "-y", "ffmpeg"])
    elif env_info["is_windows"]:
        print("Windows 请手动安装 FFmpeg:")
        print("1. 访问 https://www.gyan.dev/ffmpeg/builds")
        print("2. 下载并解压")
        print("3. 将 bin 目录添加到 PATH 环境变量")
    else:
        print("无法自动安装 FFmpeg，请手动安装")

# 使用示例
if __name__ == "__main__":
    # 1. 检测环境
    env = detect_environment()
    print(f"操作系统: {env['os']} {env['os_version']}")
    print(f"Python 版本: {env['python_version']}")
    
    # 2. 检查 yt-dlp
    is_installed, version = check_yt_dlp_installed()
    if is_installed:
        print(f"yt-dlp 已安装，版本: {version}")
    else:
        print("yt-dlp 未安装，开始安装...")
        install_yt_dlp(env)
    
    # 3. 检查 FFmpeg（可选）
    if check_ffmpeg_installed():
        print("FFmpeg 已安装")
    else:
        print("FFmpeg 未安装（可选，但推荐安装）")
        install_ffmpeg(env)
```

**Shell 脚本示例（bash/zsh）：**

```bash
#!/bin/bash

# 检测环境
detect_env() {
    OS="$(uname -s)"
    case "${OS}" in
        Linux*)     MACHINE=Linux;;
        Darwin*)    MACHINE=Mac;;
        CYGWIN*)    MACHINE=Cygwin;;
        MINGW*)     MACHINE=MinGW;;
        *)          MACHINE="UNKNOWN:${OS}"
    esac
    echo "检测到操作系统: $MACHINE"
}

# 检查 yt-dlp 是否安装
check_yt_dlp() {
    if command -v yt-dlp &> /dev/null; then
        VERSION=$(yt-dlp --version)
        echo "yt-dlp 已安装，版本: $VERSION"
        return 0
    else
        echo "yt-dlp 未安装"
        return 1
    fi
}

# 安装 yt-dlp
install_yt_dlp() {
    echo "开始安装 yt-dlp..."
    
    # 优先使用 pip3
    if command -v pip3 &> /dev/null; then
        pip3 install yt-dlp
    elif command -v pip &> /dev/null; then
        pip install yt-dlp
    else
        echo "错误: 未找到 pip 或 pip3"
        exit 1
    fi
}

# 检查 FFmpeg
check_ffmpeg() {
    if command -v ffmpeg &> /dev/null; then
        echo "FFmpeg 已安装"
        return 0
    else
        echo "FFmpeg 未安装（可选）"
        return 1
    fi
}

# 安装 FFmpeg
install_ffmpeg() {
    case "${MACHINE}" in
        Mac)
            if command -v brew &> /dev/null; then
                echo "使用 Homebrew 安装 FFmpeg..."
                brew install ffmpeg
            else
                echo "请先安装 Homebrew: https://brew.sh"
            fi
            ;;
        Linux)
            if command -v apt-get &> /dev/null; then
                echo "使用 apt-get 安装 FFmpeg..."
                sudo apt-get update
                sudo apt-get install -y ffmpeg
            else
                echo "请使用系统包管理器安装 FFmpeg"
            fi
            ;;
        *)
            echo "请手动安装 FFmpeg"
            ;;
    esac
}

# 主流程
detect_env
if ! check_yt_dlp; then
    install_yt_dlp
fi

if ! check_ffmpeg; then
    read -p "是否安装 FFmpeg? (y/n) " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        install_ffmpeg
    fi
fi
```

### 手动安装方法

#### Check Installation
```bash
yt-dlp --version
```

#### Install via pip (recommended)
```bash
# 优先使用 pip3
pip3 install yt-dlp

# 如果没有 pip3，使用 pip
pip install yt-dlp

# 如果使用 Python 虚拟环境
python3 -m pip install yt-dlp
```

#### Install via Homebrew (macOS)
```bash
brew install yt-dlp
```

#### Install FFmpeg (strongly recommended)
Required for merging video/audio and format conversion.

**macOS:**
```bash
brew install ffmpeg
```

**Linux (Debian/Ubuntu):**
```bash
sudo apt-get update
sudo apt-get install ffmpeg
```

**Linux (Fedora/RHEL):**
```bash
sudo dnf install ffmpeg
```

**Windows:**
1. 访问 https://www.gyan.dev/ffmpeg/builds
2. 下载 FFmpeg 构建版本
3. 解压到目录（如 `C:\ffmpeg`）
4. 将 `bin` 目录添加到系统 PATH 环境变量
5. 重启终端验证：`ffmpeg -version`

## Common Usage Patterns

### Download Best Quality Video
```bash
yt-dlp 
```

### Download Specific Format
```bash
# List available formats
yt-dlp -F 

# Download specific format ID
yt-dlp -f  
```

### Download Audio Only
```bash
# Extract audio as MP3
yt-dlp -x --audio-format mp3 

# Best audio quality
yt-dlp -x --audio-format mp3 --audio-quality 0 
```

### Download with Subtitles
```bash
# Download video with Chinese subtitles
yt-dlp --write-subs --sub-langs zh-Hans 

# Download subtitles only
yt-dlp --write-subs --skip-download 
```

### Download Playlist
```bash
yt-dlp 
```

### Use Proxy
```bash
yt-dlp --proxy socks5://127.0.0.1:1080 
```

### Use Browser Cookies (for login-required content)
```bash
yt-dlp --cookies-from-browser chrome 
```

## Python API Usage

When integrating into Python code:

```python
import yt_dlp

url = ''

# Basic download
ydl_opts = {
    'format': 'bestvideo+bestaudio/best',
    'outtmpl': '%(title)s.%(ext)s',
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download([url])
```

### Extract Info Without Downloading
```python
import yt_dlp
import json

ydl_opts = {}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    info = ydl.extract_info(url, download=False)
    print(json.dumps(ydl.sanitize_info(info), indent=2))
```

## Output Format Options

### Save to Specific Directory
```bash
yt-dlp -o "~/Downloads/%(title)s.%(ext)s" 
```

### Merge as MP4
```bash
yt-dlp --merge-output-format mp4 
```

## Supported Sites

yt-dlp supports 1000+ sites including:
- YouTube
- Bilibili
- Vimeo
- TikTok
- Instagram
- Twitter
- Twitch
- SoundCloud
- And many more...

## Cookies 使用指南

### ⚠️ 安全警告

**重要：不要分享你的 cookies.txt 文件！**

- Cookies 包含你的登录凭证和会话信息，相当于你的账户密码
- 泄露 cookies 可能导致账户被盗用、隐私泄露
- 每个用户必须使用自己的 cookies，不能共享
- 本 skill 中的 `cookies-example.txt` 仅为格式示例，不能直接使用
- 请将 `cookies.txt` 添加到 `.gitignore`，避免误提交到代码仓库

### 为什么需要 Cookies？

- 访问需要登录的内容
- 绕过 "Sign in to confirm you're not a bot" 错误
- 下载年龄限制的视频
- 访问订阅内容

### 导出 Cookies（推荐方法）

**方法1：使用浏览器扩展（最简单）**

1. **安装扩展**：
   - Chrome/Edge: 访问 `chrome://extensions/`
   - 搜索并安装 "Get cookies.txt LOCALLY"
   - 扩展地址：https://chromewebstore.google.com/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc

2. **导出 Cookies**：
   - 在 YouTube 页面确保已登录
   - 点击扩展图标
   - 点击 "Export" 或 "Copy"
   - 将内容保存为 `cookies.txt` 文件

3. **使用 Cookies 下载**：
   ```bash
   yt-dlp --cookies cookies.txt 
   ```

**方法2：从浏览器开发者工具手动导出**

1. 打开 Chrome 开发者工具（F12）
2. 切换到 "Application" 标签页
3. 左侧找到 "Storage" → "Cookies" → `https://www.youtube.com`
4. 查看所有 cookies（关键 cookies：`LOGIN_INFO`、`VISITOR_INFO1_LIVE`、`YSC` 等）
5. 使用扩展导出（推荐）或手动创建 cookies.txt 文件

**方法3：使用 yt-dlp 直接从浏览器读取（macOS 可能失败）**

```bash
# Chrome (macOS 上可能无法解密 cookies)
yt-dlp --cookies-from-browser chrome 

# Firefox
yt-dlp --cookies-from-browser firefox 
```

**注意**：macOS 上 Chrome 的 cookies 是加密存储的，`--cookies-from-browser chrome` 可能失败并提示 "cannot decrypt v10 cookies"。此时必须使用扩展导出。

### Cookies 文件格式

Cookies.txt 使用 Netscape 格式：
```
# Netscape HTTP Cookie File
# This file is generated by yt-dlp.  Do not edit.

域名	标志	路径	安全标志	过期时间	名称	值
```

示例：
```
.youtube.com	TRUE	/	TRUE	1802063871	LOGIN_INFO	AFmmF2swRQIhALvq...
.youtube.com	TRUE	/	TRUE	1784781038	VISITOR_INFO1_LIVE	KYjZnvuRYg8
```

### Cookies 文件位置

建议将 `cookies.txt` 放在项目目录或用户目录：
- 项目目录：`/path/to/project/cookies.txt`
- 用户目录：`~/cookies.txt`

## 网络和代理配置

### 代理检测和自动配置

**使用代理检测脚本**：
```bash
# 独立的代理检测工具
python3 .cursor/skills/yt-dlp-downloader/check_proxy.py
```

**使用安装脚本自动检测代理**（包含代理检测）：
```bash
python3 .cursor/skills/yt-dlp-downloader/install_yt_dlp.py
```

安装脚本会自动检测：
1. 环境变量中的代理配置（`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`）
2. macOS 系统代理设置
3. 本地常见代理端口（33210, 7890, 10808, 1080, 8080, 8888）
4. 网络连接测试（测试是否能访问 YouTube）

**Python 代码检测代理**：

```python
import os
import socket
import subprocess
import platform

def detect_proxy():
    """检测代理配置"""
    proxy_info = {
        "env_proxy": None,
        "system_proxy": None,
        "common_ports": [],
    }
    
    # 1. 检测环境变量
    http_proxy = os.environ.get("HTTP_PROXY") or os.environ.get("http_proxy")
    https_proxy = os.environ.get("HTTPS_PROXY") or os.environ.get("https_proxy")
    all_proxy = os.environ.get("ALL_PROXY") or os.environ.get("all_proxy")
    
    if http_proxy or https_proxy or all_proxy:
        proxy_info["env_proxy"] = http_proxy or https_proxy or all_proxy
        print(f"检测到环境变量代理: {proxy_info['env_proxy']}")
    
    # 2. 检测 macOS 系统代理
    if platform.system() == "Darwin":
        try:
            result = subprocess.run(
                ["networksetup", "-getwebproxy", "Wi-Fi"],
                capture_output=True,
                text=True,
                timeout=2
            )
            if result.returncode == 0 and "Enabled: Yes" in result.stdout:
                # 解析代理信息
                lines = result.stdout.split("\n")
                server = port = None
                for line in lines:
                    if "Server:" in line:
                        server = line.split("Server:")[1].strip()
                    if "Port:" in line:
                        port = line.split("Port:")[1].strip()
                if server and port:
                    proxy_info["system_proxy"] = f"http://{server}:{port}"
                    print(f"检测到系统代理: {proxy_info['system_proxy']}")
        except:
            pass
    
    # 3. 检测常见代理端口
    common_ports = [33210, 7890, 10808, 1080, 8080, 8888]
    for port in common_ports:
        try:
            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
            sock.settimeout(0.5)
            result = sock.connect_ex(("127.0.0.1", port))
            sock.close()
            if result == 0:
                proxy_info["common_ports"].append(port)
        except:
            pass
    
    if proxy_info["common_ports"]:
        print(f"检测到本地代理端口: {proxy_info['common_ports']}")
    
    return proxy_info

# 使用示例
proxy_info = detect_proxy()
if proxy_info["env_proxy"]:
    proxy_url = proxy_info["env_proxy"]
elif proxy_info["system_proxy"]:
    proxy_url = proxy_info["system_proxy"]
elif proxy_info["common_ports"]:
    proxy_url = f"http://127.0.0.1:{proxy_info['common_ports'][0]}"
else:
    proxy_url = None
```

**Shell 脚本检测代理**：

```bash
#!/bin/bash

# 检测环境变量代理
if [ -n "$HTTP_PROXY" ] || [ -n "$HTTPS_PROXY" ] || [ -n "$ALL_PROXY" ]; then
    PROXY="${HTTP_PROXY:-${HTTPS_PROXY:-$ALL_PROXY}}"
    echo "检测到环境变量代理: $PROXY"
fi

# 检测 macOS 系统代理
if [[ "$OSTYPE" == "darwin"* ]]; then
    SYSTEM_PROXY=$(networksetup -getwebproxy Wi-Fi 2>/dev/null | grep "Server:" | awk '{print $2}')
    SYSTEM_PORT=$(networksetup -getwebproxy Wi-Fi 2>/dev/null | grep "Port:" | awk '{print $2}')
    if [ -n "$SYSTEM_PROXY" ] && [ -n "$SYSTEM_PORT" ]; then
        echo "检测到系统代理: http://$SYSTEM_PROXY:$SYSTEM_PORT"
    fi
fi

# 检测常见代理端口
COMMON_PORTS=(33210 7890 10808 1080 8080 8888)
for port in "${COMMON_PORTS[@]}"; do
    if timeout 0.5 bash -c "echo > /dev/tcp/127.0.0.1/$port" 2>/dev/null; then
        echo "检测到本地代理端口: $port"
    fi
done
```

### 代理设置

**使用代理下载**：
```bash
yt-dlp --proxy http://127.0.0.1:33210 --cookies cookies.txt 
```

**代理类型**：
- HTTP: `--proxy http://127.0.0.1:33210`
- HTTPS: `--proxy https://127.0.0.1:33210`
- SOCKS5: `--proxy socks5://127.0.0.1:1080`

**自动选择代理**：

```python
import subprocess
import os

def download_with_auto_proxy(url, cookies_file=None):
    """自动检测并使用代理下载"""
    # 检测代理
    proxy_url = None
    
    # 1. 优先使用环境变量
    proxy_url = os.e

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [DemonDamon](https://github.com/DemonDamon)
- **Source:** [DemonDamon/AgenticX-AgentSkills](https://github.com/DemonDamon/AgenticX-AgentSkills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** yes
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-demondamon-agenticx-agentskills-yt-dlp-downloader
- Seller: https://agentstack.voostack.com/s/demondamon
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.