claude-code-skills-reference/youtube-downloader/references/po-token-setup.md

# 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)