Skip to content

SABR Bypass and PO Tokens

Jump to bottom
o51r15 edited this page Jun 22, 2026 · 2 revisions

YouTube's SABR (Serverside ABR) streaming protocol can produce corrupt downloads even when indexing succeeds. Affected downloads fail with:

Postprocessing: Error opening input files: Invalid data found when processing input

This happens because the default web client uses SABR, which can deliver corrupted data to yt-dlp during the mux step. Pinchfork addresses this in two ways: a per-source Video Client override, and built-in PO Token support via the bgutil sidecar.

Video Client override

Under Source → Edit → Downloading Options, a Video Client dropdown lets you select which yt-dlp player client to use for that source. Clients fall into two categories:

  • Cookie-compatible clients (e.g. web_creator, tv) — support account cookies, so they can reach members-only, age-restricted, and private content when cookies are configured.
  • Cookie-incompatible clients (e.g. android, ios, android_vr, tv_simply) — do not support account cookies. They can be useful for routing around certain failures but cannot access content that requires sign-in.

Cookie-incompatible clients and cookies don't mix. If you select a cookie-incompatible client and also enable cookies (Cookie Behaviour) or members-only downloads on the same source, Pinchfork blocks the save with an explanatory error — the combination cannot work, since those clients reject cookies at the YouTube API level. Choosing a cookie-compatible client override has no effect on cookies; they continue to work normally.

At download time, cookies are automatically suppressed only when the selected client is cookie-incompatible. A cookie-compatible override (or no override at all) leaves cookie behavior untouched.

PO Token provider

Some yt-dlp clients require a GVS Proof-of-Origin (PO) Token to access the high-quality video formats. Without a valid token, yt-dlp may fall back to lower-quality streams or fail entirely on some content.

Pinchfork supports the bgutil POT provider, which runs as a sidecar container and mints PO tokens on demand.

The plugin is baked in

The yt-dlp plugin that talks to the bgutil sidecar is already included in every Pinchfork image — there is nothing to download, mount, or extract. Adding the sidecar service to your compose file is all that's required for PO tokens to work automatically.

If the sidecar is not running, the plugin stays idle and the app functions normally — no configuration change needed to run without PO tokens.

Enabling the sidecar

Add the bgutil-provider service to your compose file and add it as a dependency of the pinchfork service:

services:
  bgutil-provider:
    image: brainicism/bgutil-ytdlp-pot-provider:1.3.1
    container_name: bgutil-provider
    restart: unless-stopped

  pinchfork:
    depends_on:
      bgutil-provider:
        condition: service_started
    # ... rest of your pinchfork service config

Pinchfork automatically passes --extractor-args "youtubepot-bgutilhttp:base_url=http://bgutil-provider:4416" to yt-dlp when the plugin is present. No additional configuration is required.

Version pinning

The baked-in plugin is pinned to bgutil version 1.3.1. The sidecar image tag must match:

image: brainicism/bgutil-ytdlp-pot-provider:1.3.1

A mismatch between the baked-in plugin version and the running sidecar version is a known failure mode — the plugin and server negotiate a shared protocol and reject mismatches. When a new Pinchfork release updates the plugin version, the release notes will specify the matching sidecar tag.

Because the plugin ships inside the image rather than under the /config volume, it is automatically updated with each Pinchfork release and is unaffected by yt-dlp's own binary self-updates.

Summary

Scenario Recommended approach
Public content, no issues Default client, no sidecar needed
Corrupt downloads on default client Try a different Video Client override
Members-only content Cookie-compatible client + cookies configured
Best overall quality Add bgutil sidecar (tokens flow automatically)
Members-only + best quality Cookie-compatible client + cookies + bgutil sidecar

Monitoring the sidecar

The System → Status page shows the bgutil sidecar's live up/down state. It checks connectivity to bgutil-provider:4416 each time the page loads and displays a green or red indicator.

A Test Token Server button on the same page sends a real token generation request to the sidecar and shows the first 40 characters of the returned token in a flash message. Use this to confirm the sidecar is not just reachable but is actively communicating with YouTube and minting tokens correctly — useful after a compose restart or image upgrade.

Clone this wiki locally