From 2283901dc2907ee6132b2903e6dc6439a3483ff8 Mon Sep 17 00:00:00 2001
From: jj <log@riseup.net>
Date: Sat, 7 Mar 2026 14:20:38 +0000
Subject: [PATCH] youtube: introduce `YOUTUBE_PLAYER_ID` envvar

---
 api/src/core/env.js                    | 1 +
 api/src/processing/services/youtube.js | 8 ++++++++
 docs/api-env-variables.md              | 8 ++++++++
 3 files changed, 17 insertions(+)

diff --git a/api/src/core/env.js b/api/src/core/env.js
index e504a8dc..4afaa175 100644
--- a/api/src/core/env.js
+++ b/api/src/core/env.js
@@ -121,6 +121,7 @@ export const loadEnvs = (env = process.env) => {
         ytSessionReloadInterval: 300,
         ytSessionInnertubeClient: env.YOUTUBE_SESSION_INNERTUBE_CLIENT,
         ytAllowBetterAudio: env.YOUTUBE_ALLOW_BETTER_AUDIO !== "0",
+        ytPlayerIds: env.YOUTUBE_PLAYER_ID?.split(',')?.map(p => p.trim()),
 
         // "never" | "session" | "always"
         forceLocalProcessing: env.FORCE_LOCAL_PROCESSING ?? "never",
diff --git a/api/src/processing/services/youtube.js b/api/src/processing/services/youtube.js
index c1df46a6..f38b2762 100644
--- a/api/src/processing/services/youtube.js
+++ b/api/src/processing/services/youtube.js
@@ -77,12 +77,20 @@ const cloneInnertube = async (customFetch, useSession) => {
     }
 
     if (!innertube || shouldRefreshPlayer) {
+        let player_id;
+        if (env.ytPlayerIds) {
+            player_id = env.ytPlayerIds[
+                Math.floor(Math.random() * env.ytPlayerIds.length)
+            ];
+        }
+
         innertube = await Innertube.create({
             fetch: customFetch,
             retrieve_player,
             cookie,
             po_token: useSession ? sessionTokens?.potoken : undefined,
             visitor_data: useSession ? sessionTokens?.visitor_data : undefined,
+            player_id,
         });
         lastRefreshedAt = +new Date();
     }
diff --git a/docs/api-env-variables.md b/docs/api-env-variables.md
index 59cc0df7..113b667e 100644
--- a/docs/api-env-variables.md
+++ b/docs/api-env-variables.md
@@ -68,6 +68,7 @@ this document is not final and will expand over time. feel free to improve it!
 | YOUTUBE_SESSION_INNERTUBE_CLIENT | `WEB_EMBEDDED`           |
 | YOUTUBE_ALLOW_BETTER_AUDIO       | `1`                      |
 | ENABLE_DEPRECATED_YOUTUBE_HLS    | `key`                    |
+| YOUTUBE_PLAYER_ID                | `abcdefff`               |
 
 [*view details*](#service-specific)
 
@@ -271,6 +272,13 @@ innertube client that's compatible with botguard's (web) `poToken` and `visitor_
 
 the value is a string.
 
+### YOUTUBE_PLAYER_ID
+a comma-separated-list of player IDs to use for youtube fetching.
+if defined, cobalt chooses one of them at each client initialization, otherwise
+defaults to the current latest player ID.
+
+the value is a string.
+
 ### YOUTUBE_ALLOW_BETTER_AUDIO
 when set to `1`, cobalt will try to use higher quality audio if user requests it via `youtubeBetterAudio`. will negatively impact the rate limit of a secondary youtube client with a session.