Skip to content

GuruDevvv/my-claude-skills / external/youtube-downloader

youtube-downloader

Verified

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

FileKindSize
README.mdmarkdown1.3 KB
SKILL.mdskill md18.4 KB
references/internal-sop.mdmarkdown1.0 KB
references/po-token-setup.mdmarkdown6.5 KB
scripts/download_video.pyscript37.5 KB
КАК_ИСПОЛЬЗОВАТЬ.mdmarkdown526 B

references/po-token-setup.md

View on GitHub
# PO Token Setup Guide

## What are PO Tokens?

Proof of Origin (PO) Tokens are cryptographic attestations required by YouTube for certain clients and request types. Without them, requests for affected format URLs may return HTTP Error 403 or result in restricted format access.

## Why PO Tokens Matter

As of late 2024/early 2025, YouTube increasingly requires PO tokens for high-quality video formats (1080p, 1440p, 4K). Without PO token support:

- **Android client**: Only 360p available (format 18)
- **Web client**: nsig extraction failures, missing formats
- **iOS client**: Similar restrictions

With PO token provider: **Full access** to all quality levels including 4K.

## Recommended Solution: PO Token Provider Plugin

## Operational SOP (Internal)

Use this checklist to prevent common failures:

1. Quote URLs in shell commands to avoid zsh globbing (`'https://www.youtube.com/watch?v=VIDEO_ID'`).
2. Ensure proxy is active for yt-dlp and token providers (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY).
3. If YouTube asks to confirm you’re not a bot, use browser cookies. Do not proceed without cookies.
4. Start the PO token provider before downloading.
   - Prefer Docker bgutil when available.
   - Fall back to WPC (browser) if Docker is missing or fails.
5. Use `web_safari` when cookies are present; use `mweb` otherwise for PO tokens.
6. Keep the browser window open during WPC token minting.
7. If you see “Only images are available” or “Requested format is not available”, treat it as PO token failure and retry after fixing provider/browser state.
8. If you see SSL EOF/fragment errors, treat it as proxy instability and retry with progressive formats or a better proxy.

### Automatic Setup (Preferred for non-technical users)

If Docker is available, you can start the PO token provider automatically:

1. Install the plugin into yt-dlp's Python environment (one-time):
```bash
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider
```
In China, prefer a local PyPI mirror:
```bash
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider -i https://pypi.tuna.tsinghua.edu.cn/simple
```

2. Start the provider (Docker):
```bash
docker run -d --name bgutil-pot-provider -p 4416:4416 --init brainicism/bgutil-ytdlp-pot-provider
```

3. Retry yt-dlp downloads using a web client (e.g., `mweb`) so PO tokens apply.

### Installation

Install a PO token provider plugin to handle token generation automatically. The plugin must be installed into yt-dlp's own Python environment.

**Step 1: Locate yt-dlp's Python**

```bash
head -1 $(which yt-dlp)
# Output example: #!/opt/homebrew/Cellar/yt-dlp/2025.10.22/libexec/bin/python
```

**Step 2: Install Plugin**

```bash
# For Homebrew-installed yt-dlp (macOS)
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider

# For pip-installed yt-dlp
python3 -m pip install bgutil-ytdlp-pot-provider --user
```

**Step 3: Verify Installation**

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

Look for high-quality formats (137, 248, 271, 313) in the output. If present, the plugin is working.

## Available PO Token Provider Plugins

### 1. bgutil-ytdlp-pot-provider (Recommended)

- **Installation**: `pip install bgutil-ytdlp-pot-provider`
- **Requires**: yt-dlp 2025.05.22 or above
- **Automatic**: Works transparently once installed
- **Best for**: General use, most reliable

### 2. yt-dlp-get-pot

- **Installation**: `pip install yt-dlp-get-pot`
- **Requires**: yt-dlp 2025.01.15 or above
- **Method**: Launches browser to mint tokens
- **Best for**: Users comfortable with browser automation

### 3. yt-dlp-getpot-wpc (Browser-based, no Docker)

- **Installation**: `pip install yt-dlp-getpot-wpc`
- **Requires**: yt-dlp 2025.09.26 or above
- **Method**: Uses a browser window to mint tokens
- **Best for**: Environments without Docker or restricted networks

In China, prefer a local PyPI mirror:
```bash
pip install yt-dlp-getpot-wpc -i https://pypi.tuna.tsinghua.edu.cn/simple
```

### 4. yt-dlp-get-pot-rustypipe

- **Installation**: `pip install yt-dlp-get-pot-rustypipe`
- **Method**: Uses rustypipe-botguard
- **Supports**: All web-based YouTube clients
- **Best for**: Advanced users, specific client requirements

## Verification Workflow

### Check Available Formats

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

**Without PO token provider:**
```
ID  EXT   RESOLUTION
18  mp4   640x360     # Only low quality
```

**With PO token provider:**
```
ID  EXT   RESOLUTION
137 mp4   1920x1080   # 1080p available
248 webm  1920x1080
271 webm  2560x1440   # 1440p available
313 webm  3840x2160   # 4K available
```

### Download Best Quality

```bash
# 1080p max
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"

# Best available (4K if available)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"
```

### Verify Downloaded Quality

```bash
# Check resolution
ffprobe -v error -select_streams v:0 -show_entries stream=width,height -of default=noprint_wrappers=1 video.mp4
```

## Troubleshooting

### Plugin Not Working

**Symptom**: Still only seeing format 18 after plugin installation

**Solution**:
1. Verify yt-dlp version: `yt-dlp --version` (need 2025.05.22+)
2. Check plugin installation: `pip list | grep bgutil`
3. Ensure plugin installed in correct Python environment
4. Try reinstalling: `pip uninstall bgutil-ytdlp-pot-provider && pip install bgutil-ytdlp-pot-provider`

### Warning Messages

```
WARNING: [youtube] [pot:bgutil:http] Error reaching GET http://127.0.0.1:4416/ping
```

**Impact**: This warning is usually harmless if formats are available. The plugin uses HTTP as fallback.

**Action**: No action needed if download succeeds with high-quality formats.

## Alternative: Browser Cookies Method

If PO token providers don't work, use browser cookies for authentication:

```bash
# Firefox
yt-dlp --cookies-from-browser firefox "VIDEO_URL"

# Chrome
yt-dlp --cookies-from-browser chrome "VIDEO_URL"
```

**Benefits**:
- Access age-restricted content
- Access members-only content
- Better quality selection

**Requirements**:
- Must be logged into YouTube in the browser
- Browser and yt-dlp must use same IP address

## Quality Comparison

| Method | 360p | 720p | 1080p | 1440p | 4K |
|--------|------|------|-------|-------|-----|
| Default (no workaround) | ✗ | ✗ | ✗ | ✗ | ✗ |
| Android client only | ✓ | ✗ | ✗ | ✗ | ✗ |
| PO token provider | ✓ | ✓ | ✓ | ✓ | ✓ |
| Browser cookies | ✓ | ✓ | ✓ | ✓ | ✓ |

## References

- [yt-dlp PO Token Guide](https://github.com/yt-dlp/yt-dlp/wiki/PO-Token-Guide)
- [bgutil-ytdlp-pot-provider](https://github.com/Brainicism/bgutil-ytdlp-pot-provider)
- [yt-dlp GitHub](https://github.com/yt-dlp/yt-dlp)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall