### Install Deno Script

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/README.md

Install the Deno script for the provider if you prefer using Deno.

```shell
deno install --allow-scripts=npm:canvas --frozen
```

--------------------------------

### Install bgutil-ytdlp-pot-provider Repository

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/README.md

Clone the repository to set up the provider. Replace '1.3.1' with the desired version.

```shell
git clone --single-branch --branch 1.3.1 https://github.com/Brainicism/bgutil-ytdlp-pot-provider.git
cd bgutil-ytdlp-pot-provider/server/
```

--------------------------------

### Setup Script Provider

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Clone the repository and build the server for the script provider option. This is a simpler but slower alternative to the HTTP server.

```shell
# Clone repository to home directory (default expected location: ~/bgutil-ytdlp-pot-provider)
git clone --single-branch --branch 1.3.1 https://github.com/Brainicism/bgutil-ytdlp-pot-provider.git ~/bgutil-ytdlp-pot-provider
cd ~/bgutil-ytdlp-pot-provider/server
npm ci && npx tsc    # build for Node.js
# OR: deno install --allow-scripts=npm:canvas --frozen   # for Deno
```

--------------------------------

### Install Plugin Development

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/CONTRIBUTING.md

Run this script to automatically copy the current working directory's plugin to a default yt-dlp plugin directory and install dependencies.

```shell
bash install_plugin_dev.sh
```

--------------------------------

### Install bgutil-ytdlp-pot-provider via pip

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/README.md

Use this command to install or upgrade the plugin if yt-dlp is installed via pip or pipx.

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

--------------------------------

### Install yt-dlp Plugin

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Install the yt-dlp plugin via pip or manually by downloading the zip file.

```shell
# Via PyPI (if yt-dlp was installed via pip/pipx)
python3 -m pip install -U bgutil-ytdlp-pot-provider

# Manual: download and place zip in yt-dlp plugin directory
# https://github.com/Brainicism/bgutil-ytdlp-pot-provider/releases/latest/download/bgutil-ytdlp-pot-provider.zip
```

--------------------------------

### Verify plugin installation with verbose output

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/README.md

Run yt-dlp with the -v flag to check if the bgutil providers are listed in the verbose output, confirming successful installation.

```shell
[debug] [youtube] [pot] PO Token Providers: bgutil:http-1.3.1 (external), bgutil:script-node-1.3.1 (external), bgutil:script-deno-1.3.1 (external, unavailable)
```

--------------------------------

### Setup Termux dependencies for canvas

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/README.md

Run these commands in Termux to install missing dependencies required for the 'canvas' package, which may cause issues during 'npm ci' for provider versions >=1.2.0.

```shell
mkdir ~/.gyp && echo "{'variables':{'android_ndk_path':''}}" > ~/.gyp/include.gypi
```

```shell
pkg install libvips xorgproto
```

--------------------------------

### Run HTTP Server Provider Natively with Deno

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Install and run the HTTP server provider natively using Deno. Requires Deno version 2.0.0 or higher.

```shell
# --- Native Deno ---
deno install --allow-scripts=npm:canvas --frozen
cd node_modules
deno run --allow-env --allow-net --allow-ffi=. --allow-read=. ../src/main.ts --port 8080
```

--------------------------------

### Install Node.js Dependencies and Transpile TypeScript

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/README.md

Install Node.js dependencies and transpile TypeScript to JavaScript if using Node.js.

```shell
npm ci
npx tsc
```

--------------------------------

### Configure yt-dlp with custom script server home

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/README.md

Specify the custom installation path for the script provider using the server_home argument when the script is not in the default location.

```shell
--extractor-args "youtubepot-bgutilscript:server_home=/path/to/bgutil-ytdlp-pot-provider/server"
```

--------------------------------

### Run HTTP Server Provider Natively with Node.js

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Install and run the HTTP server provider natively using Node.js. Requires Node.js version 20 or higher.

```shell
# --- Native Node.js ---
git clone --single-branch --branch 1.3.1 https://github.com/Brainicism/bgutil-ytdlp-pot-provider.git
cd bgutil-ytdlp-pot-provider/server/
npm ci
npx tsc
node build/main.js               # start on default port 4416
node build/main.js --port 8080   # start on custom port
```

--------------------------------

### yt-dlp: Use HTTP Server Provider Plugin

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Configure yt-dlp to use the HTTP server provider plugin. Specify the server's base URL or use default settings. This example shows how to verify the plugin is loaded.

```shell
# Default usage — server at http://127.0.0.1:4416
yt-dlp https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Custom server address
yt-dlp --extractor-args "youtubepot-bgutilhttp:base_url=http://192.168.1.10:8080" \
  https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Combined with other yt-dlp extractor args (semicolon separator)
yt-dlp --extractor-args "youtubepot-bgutilhttp:base_url=http://127.0.0.1:8080" \
  -f bestvideo+bestaudio \
  https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Verify plugin is loaded correctly
yt-dlp -v https://www.youtube.com/watch?v=dQw4w9WgXcQ 2>&1 | grep "bgutil"
# Expected output includes:
# [debug] [youtube] [pot] PO Token Providers: bgutil:http-1.3.1 (external), ...
```

--------------------------------

### GET /ping

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/server/README.md

Pings the server to check its status and retrieve uptime and version information. This endpoint is unstable and may change without notice.

```APIDOC
## GET /ping

### Description
Pings the server to check its status and retrieve uptime and version information. This endpoint is unstable and may change without notice.

### Method
GET

### Endpoint
/ping

### Response
#### Success Response (200)
- **server_uptime** (integer) - Uptime of the server process in seconds.
- **version** (string) - Current server version.

### Response Example
```json
{
  "server_uptime": 3600,
  "version": "1.0.0"
}
```
```

--------------------------------

### GET /ping

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Checks the health status of the BgUtils POT Provider server. It returns the server's uptime and version, which can be used by the yt-dlp plugin to verify connectivity and detect version mismatches.

```APIDOC
## GET /ping — Server Health Check

Returns the server uptime and version. Used by the plugin to verify connectivity and check for version mismatches before attempting POT generation.

### Method
GET

### Endpoint
/ping

### Response
#### Success Response (200)
- **server_uptime** (number) - The uptime of the server in seconds.
- **version** (string) - The current version of the provider server.

### Request Example
```shell
curl http://127.0.0.1:4416/ping
```

### Response Example
```json
{
  "server_uptime": 342.187,
  "version": "1.3.1"
}
```
```

--------------------------------

### Check HTTP Server Health

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Use curl to send a GET request to the /ping endpoint to check server health, uptime, and version.

```shell
curl http://127.0.0.1:4416/ping

# Expected response:
# {
#   "server_uptime": 342.187,
#   "version": "1.3.1"
# }
```

--------------------------------

### GET /minter_cache

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Returns the list of current cache keys in the minter cache. Each key represents a unique proxy/source-address combination for which an integrity token has been generated.

```APIDOC
## GET /minter_cache

### Description
Returns the list of current cache keys in the minter cache. Each key represents a unique proxy/source-address combination for which an integrity token has been generated.

### Method
GET

### Endpoint
/minter_cache

### Response
#### Success Response (200)
- **keys** (array) - List of cache keys.

#### Response Example
```json
["null"]
```

```json
["[\"http://proxy.example.com:8080\",null]"]
```
```

--------------------------------

### Run POT Provider Server Natively with Deno

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/README.md

Execute the POT provider server using Deno. Ensure you are in the correct directory and specify options.

```shell
cd node_modules
deno run --allow-env --allow-net --allow-ffi=. --allow-read=. ../src/main.ts [OPTIONS]
```

--------------------------------

### Run POT Provider Server Natively with Node.js

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/README.md

Execute the POT provider server using Node.js. Specify options like port using '[OPTIONS]'.

```shell
node build/main.js [OPTIONS]
```

--------------------------------

### yt-dlp: Use Script Provider Plugin

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Configure yt-dlp to use the script provider plugin. Customize the server home directory, script path, or JavaScript runtime. The script provider is preferred over Deno but less preferred than the HTTP server.

```shell
# Default usage — expects server cloned to ~/bgutil-ytdlp-pot-provider
yt-dlp https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Custom server_home location
yt-dlp --extractor-args "youtubepot-bgutilscript:server_home=/opt/bgutil-ytdlp-pot-provider/server" \
  https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Tilde expansion is supported
yt-dlp --extractor-args "youtubepot-bgutilscript:server_home=~/bgutil-server" \
  https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Custom script_path (resolves server_home as two directories up from the script)
yt-dlp --extractor-args "youtubepot-bgutilscript:script_path=/opt/bgutil/server/build/generate_once.js" \
  https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Specify a non-default JS runtime path
yt-dlp --js-runtimes "node:/usr/local/bin/node20" \
  --extractor-args "youtubepot-bgutilscript:server_home=~/bgutil-ytdlp-pot-provider/server" \
  https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

--------------------------------

### Run HTTP Server Provider with Docker

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Simplest way to run the HTTP server provider using Docker. You can also publish to a custom host port.

```shell
# --- Docker (simplest) ---
docker run --name bgutil-provider -d --init brainicism/bgutil-ytdlp-pot-provider
# Custom port: publish container port 4416 to host port 8080
docker run --name bgutil-provider -d --init -p 8080:4416 brainicism/bgutil-ytdlp-pot-provider
```

```shell
# Node.js (Deno) specific image tags
docker run -d --init brainicism/bgutil-ytdlp-pot-provider:1.3.1-deno
```

--------------------------------

### Generate POT with generate_once.js

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

The generate_once script reads/writes a JSON cache file and prints the result to stdout. It supports various options for content binding, proxy usage, and cache control.

```shell
# Basic usage — auto-generate content binding
node build/generate_once.js
```

```shell
# With explicit content binding
node build/generate_once.js --content-binding "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D"
```

```shell
# With proxy and source address
node build/generate_once.js \
  --content-binding "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D" \
  --proxy "http://proxy.example.com:3128" \
  --source-address "203.0.113.5"
```

```shell
# Force bypass cache, verbose output
node build/generate_once.js \
  --content-binding "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D" \
  --bypass-cache \
  --verbose
```

```shell
# With custom Innertube context
node build/generate_once.js \
  --innertube-context '{"client":{"clientName":"WEB","clientVersion":"2.20260227.01.00"}}'
```

```shell
# Disable TLS verification (e.g., when using a MITM proxy)
node build/generate_once.js --disable-tls-verification
```

```shell
# Print version and exit
node build/generate_once.js --version
# Output: 1.3.1
```

```shell
# Deno equivalent
deno run --allow-env --allow-net \
  --allow-ffi=./node_modules \
  --allow-write=~/.cache/bgutil-ytdlp-pot-provider \
  --allow-read=~/.cache/bgutil-ytdlp-pot-provider,./node_modules \
  src/generate_once.ts --content-binding "Cgt..."
```

```shell
# Stdout on success (last line is always the JSON result):
# {"poToken":"MnRhQWJj...","contentBinding":"CgtabXh3...","expiresAt":"2025-10-15T14:32:00.000Z"}
```

```shell
# Stdout on failure (non-zero exit code):
# Failed while generating POT. err.name = Error. err.message = ...
# {}
```

--------------------------------

### Configure yt-dlp with custom HTTP server URL

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/README.md

Pass the custom base URL to yt-dlp using the --extractor-args option when the provider server is running on a different IP or port.

```shell
--extractor-args "youtubepot-bgutilhttp:base_url=http://127.0.0.1:8080"
```

--------------------------------

### Generate PO Token with Minimal Request

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Send a POST request to the /get_pot endpoint with an empty JSON body to generate a PO token. The server will auto-generate the content binding.

```shell
# Minimal request (server auto-generates content binding)
curl -s -X POST http://127.0.0.1:4416/get_pot \
  -H 'Content-Type: application/json' \
  -d '{}'
```

--------------------------------

### Generate PO Token with Full Request

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Send a POST request to the /get_pot endpoint with all optional fields to generate a PO token. This allows specifying proxy, source address, and Innertube context.

```shell
# Full request with all optional fields
curl -s -X POST http://127.0.0.1:4416/get_pot \
  -H 'Content-Type: application/json' \
  -d '{
    "content_binding": "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D",
    "proxy": "http://user:pass@proxy.example.com:8080",
    "source_address": "203.0.113.5",
    "bypass_cache": false,
    "disable_tls_verification": false,
    "innertube_context": {
      "client": {
        "clientName": "WEB",
        "clientVersion": "2.20260227.01.00",
        "visitorData": "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D"
      }
    }
  }'

# Success response:
# {
#   "poToken": "MnRhQWJjRGVGZ0hpSmpLbExNbk9wUXJTdFV2V3hZeloA...",
#   "contentBinding": "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D",
#   "expiresAt": "2025-10-15T14:32:00.000Z"
# }

# Error response (e.g., deprecated field used):
# HTTP 400
# { "error": "data_sync_id is deprecated, use content_binding instead" }

# Error response (token generation failure):
# HTTP 500
# { "error": "BGError(3): Could not get BotGuard challenge (caused by ...)" }
```

--------------------------------

### Run Dockerized POT Provider Server

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/README.md

Run the POT provider as a Docker container. The default port is 4416, but can be remapped using '-p'.

```shell
docker run --name bgutil-provider -d --init brainicism/bgutil-ytdlp-pot-provider [OPTIONS]
```

--------------------------------

### Set Custom Token TTL for yt-dlp

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Set the POT cache time-to-live in hours using the TOKEN_TTL environment variable when running yt-dlp.

```bash
TOKEN_TTL=12 yt-dlp https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

--------------------------------

### Format Code (Fix)

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/CONTRIBUTING.md

Execute this script to automatically format both the Python plugin and the TypeScript server code using ruff, autopep8, eslint, and prettier.

```shell
# Make sure you have ruff, autopep8, eslint and prettier installed already
ruff check --fix plugin/
autopep8 --in-place plugin/

cd server
npx eslint --fix --max-warnings=0 src/
npx prettier --check --write "src/**/*.{js,ts}"
cd ..
```

--------------------------------

### POST /get_pot

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Generates a proof-of-origin (PO) token. This is the primary endpoint for obtaining tokens that yt-dlp uses to bypass YouTube's bot detection. It accepts optional parameters to customize the token generation process.

```APIDOC
## POST /get_pot — Generate a PO Token

The primary endpoint. Accepts a JSON body and returns a `poToken` along with the `contentBinding` and expiry. All fields except `content_binding` are optional; if `content_binding` is omitted the server will generate visitor data automatically via Innertube.

### Method
POST

### Endpoint
/get_pot

### Parameters
#### Request Body
- **content_binding** (string) - Optional. A base64 encoded string representing content binding. If omitted, visitor data is generated automatically.
- **proxy** (string) - Optional. The proxy server to use for the request (e.g., "http://user:pass@proxy.example.com:8080").
- **source_address** (string) - Optional. The source IP address to use for the request.
- **bypass_cache** (boolean) - Optional. If true, bypasses the cache for token generation. Defaults to false.
- **disable_tls_verification** (boolean) - Optional. If true, disables TLS verification for the connection. Defaults to false.
- **innertube_context** (object) - Optional. An object containing context information for Innertube.
  - **client** (object) - Innertube client information.
    - **clientName** (string) - The name of the client (e.g., "WEB").
    - **clientVersion** (string) - The version of the client (e.g., "2.20260227.01.00").
    - **visitorData** (string) - The visitor data string.

### Request Example
```shell
# Minimal request (server auto-generates content binding)
curl -s -X POST http://127.0.0.1:4416/get_pot \
  -H 'Content-Type: application/json' \
  -d '{}'

# Full request with all optional fields
curl -s -X POST http://127.0.0.1:4416/get_pot \
  -H 'Content-Type: application/json' \
  -d '{ 
    "content_binding": "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D",
    "proxy": "http://user:pass@proxy.example.com:8080",
    "source_address": "203.0.113.5",
    "bypass_cache": false,
    "disable_tls_verification": false,
    "innertube_context": {
      "client": {
        "clientName": "WEB",
        "clientVersion": "2.20260227.01.00",
        "visitorData": "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D"
      }
    }
  }'
```

### Response
#### Success Response (200)
- **poToken** (string) - The generated proof-of-origin token.
- **contentBinding** (string) - The content binding used for the token generation.
- **expiresAt** (string) - The ISO 8601 timestamp indicating when the token expires.

#### Response Example
```json
{
  "poToken": "MnRhQWJjRGVGZ0hpSmpLbExNbk9wUXJTdFV2V3hZeloA...",
  "contentBinding": "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D",
  "expiresAt": "2025-10-15T14:32:00.000Z"
}
```

#### Error Response
- **HTTP 400** - Bad Request (e.g., deprecated field used).
  ```json
  { "error": "data_sync_id is deprecated, use content_binding instead" }
  ```
- **HTTP 500** - Internal Server Error (e.g., token generation failure).
  ```json
  { "error": "BGError(3): Could not get BotGuard challenge (caused by ...)" }
  ```
```

--------------------------------

### Initialize and Use SessionManager in TypeScript

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Demonstrates initializing SessionManager for HTTP server or script mode. For script mode, provide pre-loaded caches. For HTTP server mode, caches are managed internally.

```typescript
import { SessionManager, YoutubeSessionDataCaches } from "./session_manager.ts";

// --- HTTP server usage (persistent session, no pre-seeded cache) ---
const sessionManager = new SessionManager(/*shouldLog=*/ true);

// Generate a POT — minimal call (auto-generates content binding)
const sessionData = await sessionManager.generatePoToken(
    undefined,   // contentBinding — auto-generated via Innertube
    "",          // proxy — empty string = use env HTTPS_PROXY/HTTP_PROXY/ALL_PROXY
    false,       // bypassCache
    undefined,   // sourceAddress
    false,       // disableTlsVerification
);
// sessionData: { poToken: "...", contentBinding: "Cgt...", expiresAt: Date }

// Generate a POT with all options
const sessionData2 = await sessionManager.generatePoToken(
    "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D",
    "http://user:pass@proxy.example.com:8080",
    true,                          // bypassCache — skip cached token
    "203.0.113.5",                 // sourceAddress (IPv4 → AF_INET; IPv6 → AF_INET6)
    false,                         // disableTlsVerification
    undefined,                     // challenge — undefined = fetch from /att/get
    {
        client: {
            clientName: "WEB",
            clientVersion: "2.20260227.01.00",
            visitorData: "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D",
            remoteHost: "203.0.113.5",
        },
    },
);

// --- Script mode usage (persistent cache loaded from disk) ---
const cache: YoutubeSessionDataCaches = {
    "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D": {
        poToken: "MnRhQWJjRGVGZ0...",
        contentBinding: "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D",
        expiresAt: new Date("2025-10-15T14:32:00.000Z"),
    },
};
const sm = new SessionManager(false, cache); // shouldLog=false for script mode

// Read back current caches (with optional cleanup of expired entries)
const caches = sm.getYoutubeSessionDataCaches(/*cleanup=*/ true);

// Invalidate everything (clears both POT cache and minter cache)
sm.invalidateCaches();

// Expire integrity tokens only (forces minter refresh on next call, keeps POT cache)
sm.invalidateIT();

// Inspect minter cache keys
console.log([...sm.minterCache.keys()]);
// e.g., ["null", "[\"http://proxy.example.com:8080\",null]"]
```

--------------------------------

### POST /get_pot

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/server/README.md

Generates a new PO token. This endpoint is unstable and may change without notice.

```APIDOC
## POST /get_pot

### Description
Generates a new PO token. This endpoint is unstable and may change without notice.

### Method
POST

### Endpoint
/get_pot

### Parameters
#### Request Body
- **content_binding** (string) - Optional - The content binding to use for token generation.
- **proxy** (string) - Optional - The proxy to use for the requests.
- **bypass_cache** (boolean) - Optional - When set to true, bypasses any cache if present.
- **challenge** (string or null) - Optional - The BotGuard challenge from Innertube.
- **disable_tls_verification** (boolean) - Optional - When set to true, disables TLS certificate verification.
- **innertube_context** (object) - Optional - The innertube context to be sent in the innertube request if `challenge` is not present. The public IP in the innertube context is used as the cache key for POTs.
- **source_address** (string) - Optional - The client-side IP address to bind to.

### Response
#### Success Response (200)
- **poToken** (string) - The generated PO token.
- **contentBinding** (string) - The generated or passed content binding.
- **expiresAt** (timestamp) - The expiry timestamp of the POT entry.

### Request Example
```json
{
  "content_binding": "some_content_binding",
  "proxy": "http://proxy.example.com:8080",
  "bypass_cache": true,
  "challenge": null,
  "disable_tls_verification": false,
  "innertube_context": {
    "client": {
      "clientName": "WEB_MUSIC",
      "clientVersion": "2.20231026.01.00"
    }
  },
  "source_address": "192.168.1.100"
}
```

### Response Example
```json
{
  "poToken": "generated_po_token_string",
  "contentBinding": "some_content_binding",
  "expiresAt": 1700000000
}
```
```

--------------------------------

### generate_once Script

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

The generate_once.ts / generate_once.js script is invoked by the plugin when using Option B (script mode). It reads/writes a JSON cache file following the XDG Base Directory spec (`~/.cache/bgutil-ytdlp-pot-provider/cache.json`) and prints the result as JSON on stdout.

```APIDOC
## generate_once Script

### Description
The `generate_once.ts` / `generate_once.js` script is invoked by the plugin when using Option B (script mode). It reads/writes a JSON cache file following the XDG Base Directory spec (`~/.cache/bgutil-ytdlp-pot-provider/cache.json`) and prints the result as JSON on stdout.

### Usage
```shell
# Basic usage — auto-generate content binding
node build/generate_once.js

# With explicit content binding
node build/generate_once.js --content-binding "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D"

# With proxy and source address
node build/generate_once.js \
  --content-binding "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D" \
  --proxy "http://proxy.example.com:3128" \
  --source-address "203.0.113.5"

# Force bypass cache, verbose output
node build/generate_once.js \
  --content-binding "CgtabXh3OHpkOWt3OCjX1rq7BjIKCgJVUxIEGgAgYQ%3D%3D" \
  --bypass-cache \
  --verbose

# With custom Innertube context
node build/generate_once.js \
  --innertube-context '{"client":{"clientName":"WEB","clientVersion":"2.20260227.01.00"}}'

# Disable TLS verification (e.g., when using a MITM proxy)
node build/generate_once.js --disable-tls-verification

# Print version and exit
node build/generate_once.js --version
# Output: 1.3.1

# Deno equivalent
deno run --allow-env --allow-net \
  --allow-ffi=./node_modules \
  --allow-write=~/.cache/bgutil-ytdlp-pot-provider \
  --allow-read=~/.cache/bgutil-ytdlp-pot-provider,./node_modules \
  src/generate_once.ts --content-binding "Cgt..."
```

### Environment Variables
- `TOKEN_TTL`: Controls cache lifetime in hours (default: 6).

### Example Environment Variable Usage
```shell
TOKEN_TTL=12 node build/generate_once.js --content-binding "Cgt..."
```

### Stdout on Success
```
{"poToken":"MnRhQWJj...","contentBinding":"CgtabXh3...","expiresAt":"2025-10-15T14:32:00.000Z"}
```

### Stdout on Failure
```
Failed while generating POT. err.name = Error. err.message = ...
{}
```
```

--------------------------------

### Check Code (Lint)

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/CONTRIBUTING.md

Run this script to check for code quality issues in the Python plugin and TypeScript server code without automatically fixing them.

```shell
# Make sure you have ruff, autopep8, eslint and prettier installed already
ruff check plugin/
autopep8 plugin/

cd server
npx eslint --max-warnings=0 src/
npx prettier --check "src/**/*.{js,ts}"
cd ..
```

--------------------------------

### Inspect Minter Cache Keys

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Retrieves a list of current cache keys in the minter cache. Each key represents a unique proxy/source-address combination.

```shell
curl -s http://127.0.0.1:4416/minter_cache

# Example response (no proxy):
# ["null"]

# Example response (with proxy):
# ["[\"http://proxy.example.com:8080\",null]"]
```

--------------------------------

### Set custom token TTL for script provider

Source: https://github.com/brainicism/bgutil-ytdlp-pot-provider/blob/master/README.md

Use the TOKEN_TTL environment variable to set a custom time-to-live for PO Tokens when using the script provider. The value is in hours and defaults to 6.

```shell
TOKEN_TTL=12 yt-dlp ...
```

--------------------------------

### Clear All POT Caches

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Use this endpoint to clear both POT session data and minter caches. It is useful when tokens appear stale or invalid.

```shell
curl -s -X POST http://127.0.0.1:4416/invalidate_caches
# HTTP 204 No Content (empty body)
```

--------------------------------

### Set Token TTL with Environment Variable

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

The TOKEN_TTL environment variable controls the cache lifetime in hours. The default value is 6 hours.

```shell
TOKEN_TTL=12 node build/generate_once.js --content-binding "Cgt..."
```

--------------------------------

### POST /invalidate_caches

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Clears both the POT session data cache and the minter (integrity token) cache. Useful when tokens appear stale or invalid without waiting for natural expiry.

```APIDOC
## POST /invalidate_caches

### Description
Clears both the POT session data cache and the minter (integrity token) cache. Useful when tokens appear stale or invalid without waiting for natural expiry.

### Method
POST

### Endpoint
/invalidate_caches

### Request Example
```shell
curl -s -X POST http://127.0.0.1:4416/invalidate_caches
```

### Response
#### Success Response (204)
No Content (empty body)
```

--------------------------------

### POST /invalidate_it

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

Marks all cached integrity tokens (minters) as expired without deleting them, forcing regeneration on the next /get_pot call while preserving the cache structure.

```APIDOC
## POST /invalidate_it

### Description
Marks all cached integrity tokens (minters) as expired without deleting them, forcing regeneration on the next `/get_pot` call while preserving the cache structure.

### Method
POST

### Endpoint
/invalidate_it

### Request Example
```shell
curl -s -X POST http://127.0.0.1:4416/invalidate_it
```

### Response
#### Success Response (204)
No Content (empty body)
```

--------------------------------

### Expire Integrity Token Cache

Source: https://context7.com/brainicism/bgutil-ytdlp-pot-provider/llms.txt

This endpoint marks all cached integrity tokens as expired, forcing regeneration on the next /get_pot call without deleting the cache structure.

```shell
curl -s -X POST http://127.0.0.1:4416/invalidate_it
# HTTP 204 No Content (empty body)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.