Official repository: <https://github.com/Brainicism/bgutil-ytdlp-pot-provider>
# BgUtils POT Provider
> [!CAUTION]
> Providing a PO token does not guarantee bypassing 403 errors or bot checks, but it _may_ help your traffic seem more legitimate.
[](https://hub.docker.com/r/brainicism/bgutil-ytdlp-pot-provider)
[](https://github.com/Brainicism/bgutil-ytdlp-pot-provider/releases)
[](https://pypi.org/project/bgutil-ytdlp-pot-provider/)
[](https://github.com/Brainicism/bgutil-ytdlp-pot-provider/actions/workflows/test.yml)
A proof-of-origin token (POT) provider to be used alongside [coletdjnz's POT plugin framework](https://github.com/coletdjnz/yt-dlp-get-pot). We use [LuanRT's Botguard interfacing library](https://github.com/LuanRT/BgUtils) 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?](https://github.com/yt-dlp/yt-dlp/wiki/Extractors#po-token-guide)_ 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:**
```shell
docker run --name bgutil-provider -d -p 4416:4416 brainicism/bgutil-ytdlp-pot-provider
```
**Native:**
```shell
# Replace 0.7.2 with the latest version or the one that matches the plugin
git clone --single-branch --branch 0.7.2 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
```
<details>
<summary>Server Endpoints/Environment Variables</summary>
**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.
</details>
#### (b) Generation Script Option
1. Transpile the generation script to Javascript:
```shell
# 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.7.2 with the latest version or the one that matches the plugin
git clone --single-branch --branch 0.7.2 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:
```shell
python3 -m pip install -U bgutil-ytdlp-pot-provider
```
This will automatically install [coletdjnz's POT plugin framework](https://github.com/coletdjnz/yt-dlp-get-pot) if haven't installed it yet.
#### Manual:
1. Make sure you have [coletdjnz's POT plugin framework](https://github.com/coletdjnz/yt-dlp-get-pot) installed already (must be at least version 0.1.1 or newer).
2. Download the latest release zip from [releases](https://github.com/Brainicism/bgutil-ytdlp-pot-provider/releases). Install it by placing the zip into one of the [plugin folders](https://github.com/yt-dlp/yt-dlp#installing-plugins).
## 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.
```shell
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`
```shell
--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.
```shell
--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.
Raw data
{
"_id": null,
"home_page": null,
"name": "bgutil-ytdlp-pot-provider",
"maintainer": "grqz",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Brainicism <brainicism@gmail.com>",
"keywords": "yt-dlp, yt-dlp-plugin, yt-dlp-plugins-get-pot",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/8f/df/8c2ab92f7afd5f8e4f117d5161de4f19c088013c0597e5fc275e75f72349/bgutil_ytdlp_pot_provider-0.7.2.tar.gz",
"platform": null,
"description": "Official repository: <https://github.com/Brainicism/bgutil-ytdlp-pot-provider>\n\n# BgUtils POT Provider\n\n> [!CAUTION]\n> Providing a PO token does not guarantee bypassing 403 errors or bot checks, but it _may_ help your traffic seem more legitimate.\n\n[](https://hub.docker.com/r/brainicism/bgutil-ytdlp-pot-provider)\n[](https://github.com/Brainicism/bgutil-ytdlp-pot-provider/releases)\n[](https://pypi.org/project/bgutil-ytdlp-pot-provider/)\n[](https://github.com/Brainicism/bgutil-ytdlp-pot-provider/actions/workflows/test.yml)\n\nA proof-of-origin token (POT) provider to be used alongside [coletdjnz's POT plugin framework](https://github.com/coletdjnz/yt-dlp-get-pot). We use [LuanRT's Botguard interfacing library](https://github.com/LuanRT/BgUtils) to generate the token.\n\nThis 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?](https://github.com/yt-dlp/yt-dlp/wiki/Extractors#po-token-guide)_ for more details.\n\nThe provider comes in two parts:\n\n1. **Provider**: Two options -\n - (a) An HTTP server that generates the POT, and has interfaces for the plugin to retrieve data from (easy setup + docker image provided)\n - (b) A POT generation script, and has command line options for the plugin to invoke (needs to transpile the script)\n2. **Provider plugin**: uses POT plugin framework to retrieve data from the provider, allowing yt-dlp to simulate having passed the 'bot check'.\n\n## Installation\n\n### Base Requirements\n\n1. Requires yt-dlp `2024.09.27` or above.\n\n2. If using Docker image for option (a) for the provider, the Docker runtime is required. \n Otherwise, Node.js (>= 18) and Yarn are required. You will also need git to clone the repository.\n\n### 1. Set up the provider\n\nThere 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.**\n\n#### (a) HTTP Server Option\n\nThe 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.\n\n**Docker:**\n\n```shell\ndocker run --name bgutil-provider -d -p 4416:4416 brainicism/bgutil-ytdlp-pot-provider\n```\n\n**Native:**\n\n```shell\n# Replace 0.7.2 with the latest version or the one that matches the plugin\ngit clone --single-branch --branch 0.7.2 https://github.com/Brainicism/bgutil-ytdlp-pot-provider.git\ncd bgutil-ytdlp-pot-provider/server/\nyarn install --frozen-lockfile\nnpx tsc\nnode build/main.js\n```\n\n<details>\n <summary>Server Endpoints/Environment Variables</summary>\n\n**Environment Variables**\n\n- **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\n\n**Endpoints**\n\n- **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`.\n- **POST /invalidate_caches**: Resets the PO token cache, forcing new tokens to be generated on next fetch.\n- **GET /ping**: Ping the server. The response includes:\n - `logging`: Logging verbosity(`normal` or `verbose`)\n - `token_ttl_hours`: The current applied `TOKEN_TTL` value, defaults to 6.\n - `server_uptime`: Uptime of the server process.\n - `version`: Current server version.\n </details>\n\n#### (b) Generation Script Option\n\n1. Transpile the generation script to Javascript:\n\n```shell\n# If you want to use this method without specifying `getpot_bgutil_script` extractor argument\n# on each yt-dlp invocation, clone/extract the source code into your home directory.\n# Replace `~` with `%USERPROFILE%` if using Windows\ncd ~\n# Replace 0.7.2 with the latest version or the one that matches the plugin\ngit clone --single-branch --branch 0.7.2 https://github.com/Brainicism/bgutil-ytdlp-pot-provider.git\ncd bgutil-ytdlp-pot-provider/server/\nyarn install --frozen-lockfile\nnpx tsc\n```\n\n2. Make sure `node` is available in your `PATH`.\n\n### 2. Install the plugin\n\n#### PyPI:\n\n```shell\npython3 -m pip install -U bgutil-ytdlp-pot-provider\n```\n\nThis will automatically install [coletdjnz's POT plugin framework](https://github.com/coletdjnz/yt-dlp-get-pot) if haven't installed it yet.\n\n#### Manual:\n\n1. Make sure you have [coletdjnz's POT plugin framework](https://github.com/coletdjnz/yt-dlp-get-pot) installed already (must be at least version 0.1.1 or newer).\n2. Download the latest release zip from [releases](https://github.com/Brainicism/bgutil-ytdlp-pot-provider/releases). Install it by placing the zip into one of the [plugin folders](https://github.com/yt-dlp/yt-dlp#installing-plugins).\n\n## Usage\n\nIf using option (a) HTTP Server for the provider, and the default IP/port number, you can use yt-dlp like normal \ud83d\ude42.\n\nIf you want to change the port number used by the provider server, use the `--port` option.\n\n```shell\nnode build/main.js --port 8080\n```\n\nIf changing the port or IP used for the provider server, pass it to yt-dlp via `getpot_bgutil_baseurl`\n\n```shell\n--extractor-args \"youtube:getpot_bgutil_baseurl=http://127.0.0.1:8080\"\n```\n\n---\n\nIf 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.\n\nIf you installed the script in a different location, pass it as the extractor argument `getpot_bgutil_script` to `youtube` for each yt-dlp call.\n\n```shell\n--extractor-args \"youtube:getpot_bgutil_script=$WORKSPACE/bgutil-ytdlp-pot-provider/server/build/generate_once.js\"\n```\n\n---\n\nIf both methods are available for use, the option (b) script will be prioritized.\n",
"bugtrack_url": null,
"license": null,
"summary": null,
"version": "0.7.2",
"project_urls": null,
"split_keywords": [
"yt-dlp",
" yt-dlp-plugin",
" yt-dlp-plugins-get-pot"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ff89ffd2d1ec8533df8fe2edd4146248848386b06daff38ae87f8c4e494e9445",
"md5": "87e676c397d7b2ad48a5bc4bed11c83a",
"sha256": "c39ef9c6bfffb80a4d81fd6994ce479286d7242182e807289231d19c48b435f5"
},
"downloads": -1,
"filename": "bgutil_ytdlp_pot_provider-0.7.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "87e676c397d7b2ad48a5bc4bed11c83a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7424,
"upload_time": "2024-12-29T15:40:02",
"upload_time_iso_8601": "2024-12-29T15:40:02.350697Z",
"url": "https://files.pythonhosted.org/packages/ff/89/ffd2d1ec8533df8fe2edd4146248848386b06daff38ae87f8c4e494e9445/bgutil_ytdlp_pot_provider-0.7.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8fdf8c2ab92f7afd5f8e4f117d5161de4f19c088013c0597e5fc275e75f72349",
"md5": "1714bd43dfaa0fc74e0c9e597c0b5dbf",
"sha256": "afd73f488d5c3c92822e8f1b7e271c585935dc812e123ac8bd0c647e33354476"
},
"downloads": -1,
"filename": "bgutil_ytdlp_pot_provider-0.7.2.tar.gz",
"has_sig": false,
"md5_digest": "1714bd43dfaa0fc74e0c9e597c0b5dbf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6964,
"upload_time": "2024-12-29T15:40:03",
"upload_time_iso_8601": "2024-12-29T15:40:03.519381Z",
"url": "https://files.pythonhosted.org/packages/8f/df/8c2ab92f7afd5f8e4f117d5161de4f19c088013c0597e5fc275e75f72349/bgutil_ytdlp_pot_provider-0.7.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-29 15:40:03",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "bgutil-ytdlp-pot-provider"
}
JSON