Metadata-Version: 2.3
Name: yt-dlp-get-pot
Version: 0.0.2
Author-email: coletdjnz <coletdjnz@protonmail.com>
License-Expression: Unlicense
License-File: LICENSE
Keywords: yt-dlp,yt-dlp-plugin
Requires-Python: >=3.8
Description-Content-Type: text/markdown

Official repository: <https://github.com/coletdjnz/yt-dlp-get-pot>

# PO Token Plugin Framework for yt-dlp

> [!CAUTION]
> This plugin is not ready for general use and is awaiting changes to be merged in yt-dlp for it to be functional.
> Follow https://github.com/yt-dlp/yt-dlp/pull/10648 for updates.

_[what is a PO Token?](https://github.com/yt-dlp/yt-dlp/wiki#po-token-guide)_

A simple plugin framework for yt-dlp that allows the YouTube extractor to request PO Tokens from an external source when needed. 
It makes use <sup>(abuse)</sup> of the yt-dlp HTTP Request Handler framework to allow multiple implementations to co-exist.

> For example, one plugin could support fetching PO Tokens for logged-out users, while another supports fetching PO Tokens for logged-in users.

To use, a user will need both the client plugin (this plugin) and one or more provider plugins installed.

## Installing

> [!IMPORTANT]
> This repository only contains the **client-side plugin** for yt-dlp!
> It does not contain an implementation to retrieve PO tokens. **You will need to install a provider plugin in addition to this plugin.**

Requires yt-dlp `2024.08.XX` or above.

If yt-dlp is installed through `pip` or `pipx`, you can install the plugin with the following:

### pip/pipx

```
pipx inject yt-dlp yt-dlp-get-pot
```
or

```
python3 -m pip install -U yt-dlp-get-pot
```


Alternatively, you can install directly from the repo with `https://github.com/coletdjnz/yt-dlp-get-pot/archive/refs/heads/master.zip`

### Manual install

1. Download the latest release zip from [releases](https://github.com/coletdjnz/yt-dlp-get-pot/releases) 

2. Add the zip to one of the [yt-dlp plugin locations](https://github.com/yt-dlp/yt-dlp#installing-plugins)

    - User Plugins
        - `${XDG_CONFIG_HOME}/yt-dlp/plugins` (recommended on Linux/macOS)
        - `~/.yt-dlp/plugins/`
        - `${APPDATA}/yt-dlp/plugins/` (recommended on Windows)
    
    - System Plugins
       -  `/etc/yt-dlp/plugins/`
       -  `/etc/yt-dlp-plugins/`
    
    - Executable location
        - Binary: where `<root-dir>/yt-dlp.exe`, `<root-dir>/yt-dlp-plugins/`

For more locations and methods, see [installing yt-dlp plugins](https://github.com/yt-dlp/yt-dlp#installing-plugins) 

If installed correctly, you should see the GetPOT YouTubeIE plugin override in `yt-dlp -v` output:

    [debug] Extractor Plugins: GetPOT (YoutubeIE)

## Developing a Provider plugin

The provider plugin assumes this plugin is installed. You can define it as a Python dependency in your plugin package, or users can install it manually.

1. Create a new plugin (you can use the [yt-dlp sample plugins template](https://github.com/yt-dlp/yt-dlp-sample-plugins)).
2. Create a new python file under `yt_dlp_plugins.extractor` (recommend naming it `getpot_<name>.py`).
3. In the plugin file, define a Provider that extends `yt_dlp_plugins.extractor.getpot.GetPOTProvider`.
4. Implement `_get_pot` method to retrieve the PO Token from your source.

It should look something like:

```python
from yt_dlp_plugins.extractor.getpot import GetPOTProvider, register_provider

@register_provider
class MyProviderRH(GetPOTProvider):
   _PROVIDER_NAME = 'myprovider'
   _SUPPORTED_CLIENTS = ('web', )
   
   def _get_pot(self, client, ydl, visitor_data=None, data_sync_id=None, **kwargs):
        # Implement your PO Token retrieval here
        return 'PO_TOKEN'
```

See [getpot_example.py](examples/getpot_example.py) for a more in-depth example.

When yt-dlp attempts to get a PO Token, it will call out to the Provider. This is the `Fetching PO Token for <client> client` line you see in the log.

### Debugging

To check that your Provider is being loaded, run yt-dlp with the `-v` flag and a YouTube video, and look for the `[debug] PO Token Providers` section in the output.
 You should see your request handler listed with the `PROVIDER_NAME`:
 
    [debug] PO Token Providers: getpot-<PROVIDER_NAME>

You can use `--print-traffic` to see if your provider request handler is being called.

For general plugin debugging tips, consult the [yt-dlp plugin development wiki](https://github.com/yt-dlp/yt-dlp/wiki/Plugin-Development).

### Tips

- Your implementation should consider caching the PO Token for the given parameters to avoid unnecessary requests.
- See the [PO Token Guide](https://github.com/yt-dlp/yt-dlp/wiki#po-token-guide) for more information on the PO Tokens.
- If publishing to GitHub, add the `yt-dlp-plugins-get-pot` topic to your repository to help users find your provider plugin.