jim60105/bgutil-pot repository overview

⁠BgUtils POT Provider (Rust Implementation)

A high-performance YouTube POT (Proof-of-Origin Token) provider implemented in Rust, designed to help yt-dlp bypass the "Sign in to confirm you're not a bot" restrictions with improved performance and reliability.

This Rust implementation uses LuanRT's BotGuard interfacing library⁠ through the rustypipe-botguard crate⁠ to generate authentic POT tokens, helping bypass YouTube's bot detection when using yt-dlp from flagged IP addresses. See the PO Token Guide⁠ for technical details.

⁠Why Rust?

This Rust rewrite offers significant improvements over the original TypeScript version:

• 🚀 Performance: Sub-second token generation with optimized caching
• 💾 Memory Efficiency: Lower memory footprint and better resource management
• 🔒 Reliability: Memory safety and robust error handling
• 📦 Easy Deployment: Single binary with no runtime dependencies
• 🌐 Cross-Platform: Native support for Linux, Windows, and macOS

⁠Architecture Overview

The system consists of two main components working together:

yt-dlp
  ↓ (via POT plugin)
Python Plugin
  ↓ HTTP API calls or CLI calls
Rust POT Provider
  ↓ BotGuard integration
YouTube BotGuard API
  ↓ returns POT Token
yt-dlp (bypasses bot check)

⁠Core Components

1. Rust POT Provider (this project): Two operation modes:

   • HTTP Server Mode (bgutil-pot server): Always-running REST API service (recommended)
   • Script Mode (bgutil-pot): Per-request command-line execution

2. Python Plugin: Integrates with yt-dlp's POT framework to automatically fetch tokens from the provider.

⁠Installation

⁠Prerequisites

1. yt-dlp: Version 2025.05.22 or above
2. System Requirements:
   • Linux (x86_64), Windows (x86_64), or macOS (Intel/Apple Silicon)
   • 512MB available memory
   • Stable internet connection

⁠Step 1: Install the Rust POT Provider

⁠Option A: Pre-compiled Binaries (Recommended)

Download the latest release from GitHub Releases⁠:

# Download the binary for your platform
# Example for Linux x86_64:
wget https://github.com/jim60105/bgutil-ytdlp-pot-provider-rs/releases/latest/download/bgutil-pot-linux-x86_64

# Make executable and move to PATH
chmod +x bgutil-pot-linux-x86_64
sudo mv bgutil-pot-linux-x86_64 /usr/local/bin/bgutil-pot

⁠Option B: Build from Source

Requirements: Rust 1.85+ (edition 2024) and Cargo

git clone https://github.com/jim60105/bgutil-ytdlp-pot-provider-rs.git
cd bgutil-ytdlp-pot-provider-rs

# Option 1: Build only (binaries in target/release/)
cargo build --release

# Option 2: Build and install to ~/.cargo/bin (recommended)
cargo install --path .

⁠Option C: Container (Docker/Podman)

# Build the container image
podman build -f Containerfile -t bgutil-pot .

# Run the container (basic usage)
podman run -p 4416:4416 bgutil-pot

# Run with custom configuration
podman run -p 8080:4416 -e RUST_LOG=debug bgutil-pot server --host 0.0.0.0 --port 4416

# Using Docker instead of Podman
docker build -f Containerfile -t bgutil-pot .
docker run -p 4416:4416 bgutil-pot

⁠Step 2: Install the yt-dlp Plugin

1. Download the latest plugin zip from GitHub Releases⁠ (bgutil-ytdlp-pot-provider-rs.zip)
2. Extract to one of the yt-dlp plugin directories⁠

~/yt-dlp-plugins
└── bgutil-ytdlp-pot-provider
    ├── pyproject.toml
    └── yt_dlp_plugins
        └── extractor
            ├── getpot_bgutil_cli.py
            ├── getpot_bgutil_http.py
            └── getpot_bgutil.py

⁠Usage

⁠HTTP Server Mode (Recommended)

The HTTP server mode provides the best performance and user experience.

⁠1. Start the POT Provider Server

# Using default settings (binds to [::]:4416, IPv6 with IPv4 fallback)
./bgutil-pot server

# Custom port
./bgutil-pot server --port 8080

# Custom host address
./bgutil-pot server --host 127.0.0.1 --port 4416

# With verbose logging
./bgutil-pot server --verbose

Server Command Line Options:

• --host <HOST>: Host address to bind to (default: ::)
• --port <PORT>: Listen port (default: 4416)
• --verbose: Enable verbose logging

⁠Server API Endpoints

The HTTP server provides the following REST API endpoints:

• POST /get_pot: Generate a new POT token
• GET /ping: Health check endpoint
• POST /invalidate_caches: Clear all internal caches
• POST /invalidate_it: Invalidate integrity tokens
• GET /minter_cache: Get minter cache status

⁠2. Use with yt-dlp

Once the server is running, yt-dlp will automatically detect and use it:

# Standard usage - works automatically with default settings
yt-dlp "https://www.youtube.com/watch?v=VIDEO_ID"

# If using a custom port, specify the base URL
yt-dlp --extractor-args "youtubepot-bgutilhttp:base_url=http://127.0.0.1:8080" "VIDEO_URL"

# If tokens stop working, try legacy mode
yt-dlp --extractor-args "youtubepot-bgutilhttp:base_url=http://127.0.0.1:4416;disable_innertube=1" "VIDEO_URL"

⁠Script Mode

For occasional use or environments where running a persistent service is not desired:

⁠1. Generate POT Token Manually

# Generate token for a specific video
./bgutil-pot --content-binding "VIDEO_ID"

# With proxy support
./bgutil-pot --content-binding "VIDEO_ID" --proxy "http://proxy.example.com:8080"

# Bypass cache to force new token generation
./bgutil-pot --content-binding "VIDEO_ID" --bypass-cache

# With verbose logging
./bgutil-pot --content-binding "VIDEO_ID" --verbose

Generate Command Line Options:

• --content-binding <CONTENT_BINDING>: Content binding (video ID, visitor data, etc.)
• --proxy <PROXY>: Proxy server URL (format: http://host:port, socks5://host:port, etc.)
• --bypass-cache: Bypass cache and force new token generation
• --source-address <SOURCE_ADDRESS>: Source IP address for outbound connections
• --disable-tls-verification: Disable TLS certificate verification
• --verbose: Enable verbose logging
• --version: Show version information

⁠2. Integrate with yt-dlp

# Specify the script path for yt-dlp integration
yt-dlp --extractor-args "youtubepot-bgutilscript:script_path=/path/to/bgutil-pot" "VIDEO_URL"

⁠Configuration

Both modes support comprehensive configuration via:

1. Command line arguments (highest priority)
2. Environment variables
3. Configuration file
4. Default values (lowest priority)

Environment Variables:

Configuration File Example (config.toml):

[server]
host = "::"
port = 4416
timeout = 30
enable_cors = true

[token]
ttl_hours = 6
enable_cache = true
max_cache_entries = 1000

[botguard]
request_key = "O43z0dpjhgX20SCx4KAo"
enable_vm = true
vm_timeout = 30
disable_innertube = false

[network]
connect_timeout = 30
request_timeout = 60
max_retries = 3
user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"

[logging]
level = "info"
verbose = false
format = "text"

[cache]
enable_file_cache = true
memory_cache_size = 100
enable_compression = false

Example usage with environment variables:

# Set logging level
export RUST_LOG=debug
./bgutil-pot server

# Multiple settings
RUST_LOG=debug ./bgutil-pot --content-binding "VIDEO_ID"

⁠Proxy Support

Both modes support proxy configuration:

# HTTP/HTTPS proxy
--proxy "http://proxy.example.com:8080"

# SOCKS5 proxy
--proxy "socks5://proxy.example.com:1080"

# Proxy with authentication
--proxy "http://user:[email protected]:8080"

⁠Verification

To verify the plugin installation, check yt-dlp's verbose output:

yt-dlp -v "https://www.youtube.com/watch?v=VIDEO_ID"

You should see output similar to:

[debug] [youtube] [pot] PO Token Providers: bgutil:http-1.2.2 (external), bgutil:script-1.2.2 (external)

⁠Troubleshooting

⁠Common Issues

⁠POT tokens not working

If tokens stop working, try the following in order:

1. Restart the provider: Stop and restart the HTTP server or regenerate tokens with --bypass-cache
2. Check your IP: Your IP might be flagged. Try using a different network or proxy
3. Legacy mode: Add disable_innertube=1 to extractor arguments
4. Update software: Ensure you're using the latest versions of both this provider and yt-dlp

⁠Connection issues

# Check if the server is running (HTTP mode)
curl http://127.0.0.1:4416/ping

# Test with verbose logging
./bgutil-pot server --verbose

# Test script mode
./bgutil-pot --content-binding "test" --verbose

⁠Plugin not detected

Verify the plugin installation:

yt-dlp -v "https://www.youtube.com/watch?v=dQw4w9WgXcQ" 2>&1 | grep -i "pot"

Should show: [debug] [youtube] [pot] PO Token Providers: bgutil:http-...

⁠Performance Tips

• Use HTTP server mode for better performance and resource usage
• Configure appropriate cache TTL (default 6 hours) based on your usage patterns
• Use proxy rotation if making many requests from the same IP
• Monitor memory usage - the server typically uses <50MB RAM

⁠Environment Variables

⁠Contributing

This project welcomes contributions! Please see CONTRIBUTING.md⁠ for guidelines.

⁠Development Setup

git clone https://github.com/jim60105/bgutil-ytdlp-pot-provider-rs.git
cd bgutil-ytdlp-pot-provider-rs

# Install development dependencies
cargo build

# Run tests
cargo nextest run

# Run quality checks
./scripts/quality_check.sh

⁠License

This project is licensed under the GPL-3.0-or-later License. See LICENSE⁠ for details.

⁠Acknowledgments

• LuanRT⁠ for the BgUtils library⁠
• Brainicism⁠ for the original TypeScript implementation⁠
• The yt-dlp team⁠ for the excellent POT provider framework