Skip to content

Commit fb6c014

Browse files
coletdjnzbashonlygamer191
authored
Update PO Token Guide (#71)
Co-authored-by: bashonly <88596187+bashonly@users.noreply.github.com> Co-authored-by: gamer191 <83270075+gamer191@users.noreply.github.com>
1 parent 09be35f commit fb6c014

File tree

1 file changed

+26
-88
lines changed

1 file changed

+26
-88
lines changed

‎PO Token Guide.md‎

Lines changed: 26 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
# YouTube PO Token Guide
44

55
> [!TIP]
6-
> TL;DR recommended setup: Either use a [PO Token Provider plugin](#po-token-provider-plugins), or [manual extraction](#guide-providing-a-po-token-manually-for-use-with-mweb-client), to provide the `mweb` client with a [PO Token for GVS requests](#cases-where-a-po-token-is-required).
6+
> TL;DR recommended setup: Use a [PO Token Provider plugin](#po-token-provider-plugins) to provide the `mweb` client with a [PO Token for GVS requests](#cases-where-a-po-token-is-required).
77
>
88
> See the notice in the [YouTube Extractor Wiki](https://github.com/yt-dlp/yt-dlp/wiki/Extractors#youtube) for more information on the current state of downloading videos from YouTube.
99
@@ -15,15 +15,8 @@
1515
* [Current PO Token enforcement](#current-po-token-enforcement)
1616
* [PO Token Provider Plugins](#po-token-provider-plugins)
1717
* [Featured Plugins](#featured-plugins)
18-
* [Guide: Providing a PO Token manually (for use with `mweb` client)](#guide-providing-a-po-token-manually-for-use-with-mweb-client)
19-
* [PO Token for GVS](#po-token-for-gvs)
20-
* [No account](#no-account)
21-
* [With an account](#with-an-account)
22-
* [PO Token for Player or Subs](#po-token-for-player-or-subs)
2318
* [Other PO Token related tools](#other-po-token-related-tools)
2419
* [Technical details](#technical-details)
25-
* [PO Tokens for GVS](#po-tokens-for-gvs)
26-
* [PO Tokens for Player and Subs](#po-tokens-for-player-and-subs)
2720
<!-- TOC -->
2821

2922

@@ -50,20 +43,19 @@ The PO Tokens may be generated differently for each of these cases, depending on
5043

5144
YouTube is at present rolling out changes to enforce PO Tokens for video playback. Currently, only GVS and Subs require PO Tokens for some clients.
5245

53-
| Client | PO Token Required For | Notes |
54-
|----------------|-----------------------------|-------------------------------------------------------------------------------------------------|
55-
| `web` | Subs (rolling out), GVS | Only SABR formats available |
56-
| `web_safari` | Subs (rolling out), GVS* | Same as `web`. *Provides HLS (m3u8) formats which do not require PO Token for GVS at this time. |
57-
| `mweb` | GVS | |
58-
| `tv` | Not required | All formats may have DRM if you request too much |
59-
| `tv_simply` | Not required | Account cookies not supported |
60-
| `tv_embedded` | Not required | Requires account cookies |
61-
| `web_embedded` | Not required | Only embeddable videos available |
62-
| `web_music` | GVS | |
63-
| `web_creator` | GVS | Requires account cookies |
64-
| `android` | GVS or Player | Account cookies not supported |
65-
| `android_vr` | Not required | YouTube Kids videos are not available |
66-
| `ios` | GVS or Player (rolling out) | Account cookies not supported |
46+
| Client | PO Token Required For | Notes |
47+
|----------------|-----------------------|-------------------------------------------------------------------------------------------------------------------|
48+
| `web` | Subs, GVS | Only SABR formats available |
49+
| `web_safari` | GVS* | Same as `web`. *Provides HLS (m3u8) formats which do not require PO Token for GVS at this time. |
50+
| `mweb` | GVS | |
51+
| `tv` | Not required | All formats DRM'd if cookies (logged-in or active guest) aren't passed. Only SABR formats available in some cases |
52+
| `tv_simply` | GVS | Account cookies not supported |
53+
| `web_embedded` | Not required | Only embeddable videos available |
54+
| `web_music` | GVS | |
55+
| `web_creator` | GVS | Requires account cookies |
56+
| `android` | GVS or Player | Account cookies not supported |
57+
| `android_vr` | Not required | "Made for kids" videos are not available |
58+
| `ios` | GVS or Player | Account cookies not supported |
6759

6860
For all clients:
6961
- GVS PO Token is not required for YouTube Premium subscribers
@@ -76,62 +68,24 @@ You can select what client to use with the [`player_client` extractor argument](
7668
> [!TIP]
7769
> Recommended
7870
79-
Manually fetching PO Tokens can be a tedious process. As an alternative, you can install a PO Token Provider plugin to handle fetching PO Tokens automatically.
71+
Manually extracting PO Tokens is no longer recommended. YouTube now binds PO Tokens to the video ID, so a new token needs to be generated for each video.
72+
73+
It is recommended to use a PO Token Provider plugin to automatically fetch and provide PO Tokens to yt-dlp.
8074

8175
### Featured Plugins
8276

77+
> [!NOTE]
78+
> These plugins are not affiliated with yt-dlp
79+
8380
- [bgutil-ytdlp-pot-provider](https://github.com/Brainicism/bgutil-ytdlp-pot-provider) by [Brainicism](https://github.com/Brainicism)
84-
- A PO Token Provider which uses [BgUtils](https://github.com/LuanRT/BgUtils) to generate PO Tokens. _Not affiliated with yt-dlp._
81+
- A PO Token Provider which uses [BgUtils](https://github.com/LuanRT/BgUtils) to generate PO Tokens. _Maintained by a yt-dlp maintainer_
82+
- [yt-dlp-getpot-wpc](https://github.com/coletdjnz/yt-dlp-getpot-wpc) by [coletdjnz](https://github.com/coletdjnz)
83+
- A PO Token Provider which uses YouTube in the browser to generate PO Tokens. Useful as a fallback/alternative if the above fails. _Maintained by a yt-dlp core maintainer_
8584

8685
Check out the [yt-dlp-pot-provider GitHub topic](https://github.com/topics/yt-dlp-pot-provider) for more PO Token Provider plugins.
8786

8887
For developers, refer to the [PO Token Provider developer documentation](https://github.com/yt-dlp/yt-dlp/tree/master/yt_dlp/extractor/youtube/pot/README.md)
8988

90-
## Guide: Providing a PO Token manually (for use with `mweb` client)
91-
92-
This section provides a basic guide on extracting PO Token(s) manually from YouTube in a web browser **for use with the `mweb` client**, and manually passing it to yt-dlp via the [`po_token` extractor argument](https://github.com/yt-dlp/yt-dlp#youtube).
93-
The same PO Token extraction method _may_ work with other web browser-based clients too.
94-
95-
> [!TIP]
96-
> When supplying multiple PO Tokens, use the same extractor args option and comma-separate the PO Token configurations. For example:
97-
> `--extractor-args "youtube:po_token=mweb.gvs+GVS_PO_TOKEN_VALUE_HERE,mweb.player+PLAYER_PO_TOKEN_VALUE_HERE"`
98-
99-
100-
### PO Token for GVS
101-
102-
The PO Token used for `web` GVS requests is tied to your YouTube session, so you will need to provide cookies.
103-
104-
1. Open **[YouTube Music](https://music.youtube.com)** in a browser.
105-
2. Open the developer console (F12), then go to the "Network" tab (click the `>>` button if you don't see it)
106-
3. Filter requests by `v1/player`
107-
4. Play a video - a `player` request should appear in the network tab
108-
5. From the most recent `player` request, extract the PO Token from `serviceIntegrityDimensions.poToken` field in the JSON request body
109-
6. Pass the PO Token for GVS to yt-dlp using `--extractor-args "youtube:player-client=default,mweb;po_token=mweb.gvs+PO_TOKEN_VALUE_HERE"` with cookies (`--cookies COOKIES_FILE` or `--cookies-from-browser`)
110-
111-
If using an account, [refer to this guide on exporting account cookies](https://github.com/yt-dlp/yt-dlp/wiki/Extractors#exporting-youtube-cookies)
112-
113-
(Not recommended) If not using an account, you may also provide visitor data instead of cookies. Refer to [Passing Visitor Data without cookies](https://github.com/yt-dlp/yt-dlp/wiki/Extractors#passing-visitor-data-without-cookies).
114-
115-
### PO Token for Player or Subs
116-
117-
The PO Token for `web`/`mweb` Player or Subs requests is tied to the Video ID. This means you must generate a new PO Token for each video.
118-
119-
1. Open **[YouTube Web](https://www.youtube.com)** in a browser.
120-
2. Open the developer console (F12), then go to the "Network" tab and filter by `v1/player`
121-
3. Navigate to the video you want to download (e.g. using search - do not go to the video url directly as the page will refresh)
122-
4. In the request payload JSON, find the PO Token at `serviceIntegrityDimensions.poToken` and save that value
123-
5. Export cookies from the browser
124-
125-
**For Subs PO Token:**
126-
- Pass the PO Token for Subs to yt-dlp using `--extractor-args "youtube:po_token=web.subs+PO_TOKEN_VALUE_HERE"`
127-
128-
**For Player PO Token:**
129-
> [!NOTE]
130-
> If you are using the `web` client and have not disabled the `webpage` request, providing this PO Token is not necessary at this time.
131-
132-
- Pass the PO Token for Player to yt-dlp using `--extractor-args "youtube:player-client=default,mweb;po_token=mweb.player+PO_TOKEN_VALUE_HERE"`
133-
134-
13589
## Other PO Token related tools
13690

13791
- [BgUtils](https://github.com/LuanRT/BgUtils) by [LuanRT](https://github.com/LuanRT)
@@ -145,24 +99,8 @@ PO Tokens are still an active area of research, and at the same time YouTube is
14599

146100
A PO Token is generated by either BotGuard (Web), DroidGuard (Android), iOSGuard (iOS). A PO Token from one platform cannot be used on another (i.e., Web PO Token cannot be used on Android or iOS).
147101

148-
If you are interested, we recommend checking out the [BgUtils](https://github.com/LuanRT/BgUtils) project which does a deeper dive into the BotGuard attestation process.
149-
150-
### PO Tokens for GVS
102+
PO Tokens have a "content binding", meaning they are bound to the user session (Visitor ID or account Session ID) or to the video ID. Most PO Tokens (such as for `web` GVS/Player) are bound to the video ID, so a new token is required for each video.
151103

152-
GVS uses a PO token bound to the user session.
104+
These PO Tokens have a limited lifespan (possibly as short as 12 hours), so they will need to be refreshed periodically. However, some reports suggest that the token may be valid for several months.
153105

154-
For Web session tokens:
155-
- When logged out, are bound to a Visitor ID. This Visitor ID is found in the `VISITOR_INFO1_LIVE` cookie, in the `visitorData` value which is sent with Innertube API requests, or with `ytcfg.get('VISITOR_DATA')` in the browser console.
156-
- When logged in, are bound to the account Session ID (first part of the Data Sync ID). This can be found at `responseContext.mainAppWebResponseContext.dataSyncId` in Innertube responses, or with `ytcfg.get('DATASYNC_ID')` in the browser console.
157-
158-
If a video download fails with an HTTP 403 midway through, then the client likely requires a PO Token for GVS.
159-
160-
These PO Tokens are only valid for a limited time (usually at least 12 hours), so it will need to be refreshed periodically. However, some reports suggest that the token may be valid for many days.
161-
162-
### PO Tokens for Player and Subs
163-
164-
Web Tokens for player (and subtitles) requests are bound to the video ID the associated `/player` request is for. YouTube has only recently started generating these for some clients (e.g. `web`).
165-
166-
As of writing, some clients, such as `web_music` use a session-bound PO Token for player requests. This is likely to change.
167-
168-
For Android (and presumably iOS), the Player PO Token is bound to the user session, similar to GVS tokens. If a Player PO token is provided, the GVS PO token is not required.
106+
If you are interested, we recommend checking out the [BgUtils](https://github.com/LuanRT/BgUtils) project which does a deeper dive into the BotGuard attestation process.

0 commit comments

Comments
 (0)