BgUtils yt-dlp Proof-of-Origin Token Provider Plugin

Common errors

• Error fetching PO Token from "bgutil:http" provider: Failed to connect to <IP>:<PORT>

  cause The external POT provider (Node.js/Deno server or Rust server) is not running, is running on a different port/IP, or a firewall is blocking the connection.
  fix Ensure the POT provider server is running and accessible from where `yt-dlp` is executed. Verify the `base_url` in your `yt-dlp` extractor arguments matches the provider's address and port (default 4416). Check firewall settings if necessary.

• POT tokens not working / Downloads failing with 403 Forbidden

  cause YouTube has updated its bot detection, your IP might be flagged, or the provider/plugin versions are outdated.
  fix 1. Restart the POT provider. 2. Update `bgutil-ytdlp-pot-provider` and `yt-dlp` to their latest versions. 3. Consider using a different IP address or proxy. 4. If applicable, try regenerating tokens with `--bypass-cache` on the provider.

• yt-dlp: error: unrecognized arguments: --extractor-args youtubepot-bgutilhttp:base_url=...

  cause The `bgutil-ytdlp-pot-provider` plugin is not correctly installed or `yt-dlp` is not finding it. This can also happen if `yt-dlp` is too old.
  fix Ensure `bgutil-ytdlp-pot-provider` is installed via `pip install -U bgutil-ytdlp-pot-provider`. Verify `yt-dlp` is version 2025.05.22 or newer (`yt-dlp --version`). If installed manually, confirm the plugin zip is in one of `yt-dlp`'s plugin directories.

• Failed to extract initial attestation from the webpage

  cause YouTube changes may have impacted the attestation extraction process, potentially related to the `InnerTube` API or web_music client if a webpage is unavailable.
  fix Ensure you are using the latest versions of both the POT provider and `yt-dlp`. If this error persists, it might indicate a more fundamental change by YouTube requiring further updates to the provider/plugin. Check the GitHub issues for the latest solutions.

Warnings

• breaking Major breaking changes occurred in version 1.0.0. Both the external POT provider (Node.js/Deno/Rust) and the Python plugin must be updated in sync. Extractor arguments changed significantly.
  Fix: Update both the plugin and your POT provider to the latest versions. Adjust `yt-dlp` extractor arguments: `youtube:getpot_bgutil_baseurl` became `youtubepot-bgutilhttp:base_url` and `youtube:getpot_bgutil_script` became `youtubepot-bgutilscript:script_path`.
• breaking The `yt-dlp` dependency requires version 2025.05.22 or above for compatibility with the plugin's features and to address YouTube changes.
  Fix: Update `yt-dlp` to the latest version using `pip install -U yt-dlp`.
• deprecated When using the standalone provider (server or script), passing `visitor_data` or `data_sync_id` is deprecated. YouTube changes also led to the removal of `disable_innertube`.
  Fix: Use `--content-binding` instead of `--visitor-data` or `--data-sync-id` for script methods. Be aware that `disable_innertube` is no longer supported and may break POT generation for certain clients if no webpage is available.
• gotcha Providing a POT token does not guarantee bypassing all 403 errors or bot checks, as YouTube's detection mechanisms are constantly evolving. It may only help your traffic appear more legitimate.
  Fix: Monitor `yt-dlp` and `bgutil-ytdlp-pot-provider` releases for updates, which often include fixes for new YouTube changes. Consider alternative proxies or networks if issues persist.
• gotcha If using a local proxy server with the Dockerized POT provider, the Docker container's network isolation will prevent access unless `--net=host` is added to the `docker run` command.
  Fix: When running the Docker container for the POT provider, add `--net=host` to the `docker run` command if the provider needs to access a proxy running on the host machine.
• gotcha The JavaScript-based POT generation script (as opposed to the HTTP server option or Rust implementation) is not recommended for high-concurrency usage. Each `yt-dlp` call incurs the overhead of spawning a new Node.js process.
  Fix: Use the HTTP server option (Node.js/Deno) or, preferably, the Rust POT provider in HTTP server mode for better performance and concurrency.

Install

• pip install -U bgutil-ytdlp-pot-provider Install Python Plugin

Imports

• Not applicable for direct import

  This library is a yt-dlp plugin and is used via yt-dlp's command-line interface. Direct Python imports for end-user code are not typically needed or exposed.

  The functionality is integrated into yt-dlp, and you interact with it by configuring yt-dlp parameters or ensuring the external provider is running.

Quickstart

This quickstart demonstrates how to use `yt-dlp` from Python to download a video, leveraging the `bgutil-ytdlp-pot-provider` plugin. It assumes the Rust POT Provider server is already running, which is the recommended setup. The Python code executes `yt-dlp` as a subprocess with the necessary extractor arguments to direct it to the POT provider.

# Step 1: Install and start the Rust POT Provider (recommended)
# Download the appropriate binary from https://github.com/jim60105/bgutil-ytdlp-pot-provider-rs/releases
# For example, for Linux x86_64:
# wget https://github.com/jim60105/bgutil-ytdlp-pot-provider-rs/releases/latest/download/bgutil-pot-linux-x86_64
# chmod +x bgutil-pot-linux-x86_64
# mv bgutil-pot-linux-x86_64 /usr/local/bin/bgutil-pot
# Start the provider (e.g., in a separate terminal or as a service):
# bgutil-pot server --port 4416

# Step 2: Install the Python plugin
# pip install -U bgutil-ytdlp-pot-provider

import subprocess
import os

# Example: Download a YouTube video using yt-dlp with the POT provider
# Ensure the Rust POT server is running on the default port 4416 or configured correctly.

def download_video_with_pot(video_url):
    try:
        # yt-dlp automatically detects and uses the running POT provider.
        # The 'youtubepot-bgutilhttp:' prefix is used by yt-dlp to specify
        # using the bgutil-ytdlp-pot-provider HTTP mode.
        command = [
            "yt-dlp",
            "--extractor-args", "youtubepot-bgutilhttp:base_url=http://127.0.0.1:4416",
            video_url
        ]
        
        print(f"Attempting to download {video_url} with POT...")
        result = subprocess.run(command, check=True, capture_output=True, text=True)
        print("Download successful!")
        print(result.stdout)
    except subprocess.CalledProcessError as e:
        print(f"Error during download: {e}")
        print(f"Stdout: {e.stdout}")
        print(f"Stderr: {e.stderr}")
    except FileNotFoundError:
        print("Error: yt-dlp command not found. Please ensure yt-dlp is installed and in your PATH.")

# Replace with your desired YouTube video URL
video_to_download = "https://www.youtube.com/watch?v=dQw4w9WgXcQ" 

download_video_with_pot(video_to_download)