BgUtils POT Provider

Caution

Passing PO tokens no longer bypasses the bot check for majority of cases. See #37 for more details.

A proof-of-origin token (POT) provider to be used alongside coletdjnz's POT plugin framework. We use LuanRT's Botguard interfacing library to generate the token.

This is used to bypass the 'Sign in to confirm you're not a bot' message when invoking yt-dlp from an IP address flagged by YouTube. See What is a PO Token? for more details.

The provider comes in two parts:

1. Provider: Two options -
   • (a) An HTTP server that generates the POT, and has interfaces for the plugin to retrieve data from (easy setup + docker image provided)
   • (b) A POT generation script, and has command line options for the plugin to invoke (needs to transpile the script)
2. Provider plugin: uses POT plugin framework to retrieve data from the provider, allowing yt-dlp to simulate having passed the 'bot check'.

Installation

Base Requirements

1. Requires yt-dlp 2024.09.27 or above.

2. If using Docker image for option (a) for the provider, the Docker runtime is required.
   Otherwise, Node.js (>= 18) and Yarn are required. You will also need git to clone the repository.

1. Set up the provider

There are two options for the provider, an always running POT generation HTTP server, and a POT generation script invoked when needed. The HTTP server option is simpler, and comes with a prebuilt Docker image. You only need to choose one option.

(a) HTTP Server Option

The provider is a Node.js HTTP server. You have two options for running it: as a prebuilt docker image, or manually as a node application.

Docker:

docker run --name bgutil-provider -d -p 4416:4416 brainicism/bgutil-ytdlp-pot-provider

Native:

# Replace 0.6.0 with the latest version or the one that matches the plugin
git clone --single-branch --branch 0.6.0 https://github.com/Brainicism/bgutil-ytdlp-pot-provider.git
cd bgutil-ytdlp-pot-provider/server/
yarn install --frozen-lockfile
npx tsc
node build/main.js

Server Endpoints/Environment Variables

Environment Variables

• TOKEN_TTL: The time in hours for a PO token to be considered valid. While there are no definitive answers on how long a token is valid, it has been observed to be valid for atleast a couple of days. Default: 6

Endpoints

• POST /get_pot: Accepts a visitor_data (unauthenticated), data_sync_id (authenticated) or an empty body in the request body. If no identifier is passed, a new unauthenticated visitor_data will be generated. Returns po_token and the associated identifier visit_identifier.
• POST /invalidate_caches: Resets the PO token cache, forcing new tokens to be generated on next fetch.
• GET /ping: Ping the server. The response includes:
  • logging: Logging verbosity(normal or verbose)
  • token_ttl_hours: The current applied TOKEN_TTL value, defaults to 6.
  • server_uptime: Uptime of the server process.
  • version: Current server version.

(b) Generation Script Option

1. Transpile the generation script to Javascript:

# If you want to use this method without specifying `getpot_bgutil_script` extractor argument
# on each yt-dlp invocation, clone/extract the source code into your home directory.
# Replace `~` with `%USERPROFILE%` if using Windows
cd ~
# Replace 0.6.0 with the latest version or the one that matches the plugin
git clone --single-branch --branch 0.6.0 https://github.com/Brainicism/bgutil-ytdlp-pot-provider.git
cd bgutil-ytdlp-pot-provider/server/
yarn install --frozen-lockfile
npx tsc

2. Make sure node is available in your PATH.

2. Install the plugin

PyPI:

python3 -m pip install -U bgutil-ytdlp-pot-provider

This will automatically install coletdjnz's POT plugin framework if haven't installed it yet.

Manual:

1. Make sure you have coletdjnz's POT plugin framework installed already (must be at least version 0.1.1 or newer).
2. Download the latest release zip from releases. Install it by placing the zip into one of the plugin folders.

Usage

If using option (a) HTTP Server for the provider, and the default IP/port number, you can use yt-dlp like normal 🙂.

If you want to change the port number used by the provider server, use the --port option.

node build/main.js --port 8080

If changing the port or IP used for the provider server, pass it to yt-dlp via getpot_bgutil_baseurl

--extractor-args "youtube:getpot_bgutil_baseurl=http://127.0.0.1:8080"

---

If using option (b) script for the provider, with the default script location in your home directory (i.e: ~/bgutil-ytdlp-pot-provider or %USERPROFILE%\bgutil-ytdlp-pot-provider), you can also use yt-dlp like normal.

If you installed the script in a different location, pass it as the extractor argument getpot_bgutil_script to youtube for each yt-dlp call.

--extractor-args "youtube:getpot_bgutil_script=$WORKSPACE/bgutil-ytdlp-pot-provider/server/build/generate_once.js"

---

If both methods are available for use, the option (b) script will be prioritized.