Youtube Downloader

Security scan passed
Scanned at: 2025-11-19T01:20:50.532287
Tool: gitleaks + pattern-based validation
Content hash: 6dc9ae011eb2d8ca1ba73ceb2c6d8aa031979f7e3bb9b31bfe78fdb7283f7f66


# YouTube Downloader Internal SOP

Use this SOP to avoid common yt-dlp failures and confusion:

1. Quote YouTube URLs in shell commands (zsh treats `?` as glob). Example: `'https://www.youtube.com/watch?v=VIDEO_ID'`.
2. Ensure proxy is active for both yt-dlp and PO Token providers (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY).
3. If you see "Sign in to confirm you're not a bot", request cookie permission and use browser cookies.
4. Start the PO Token provider before downloading. Prefer Docker bgutil; fall back to browser-based WPC when Docker is unavailable or fails.
5. Use `web_safari` client when cookies are present; otherwise use `mweb` for PO tokens.
6. Keep the browser window open while WPC is minting tokens and make sure it can reach YouTube through the same proxy.
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 or fragment errors, treat it as proxy instability. Retry with progressive formats or switch to a more stable proxy.


# 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