# AdBlock-Maxxer — YouTube Companion

A tiny local helper that makes YouTube **ad-free even on accounts/IPs that YouTube has put
into strict server-side ad enforcement** (where the video black-screens unless an ad plays,
and no in-browser blocker — ours, uBlock, anything — can help).

## Why it's needed

On enforced accounts YouTube's media servers (`googlevideo.com`) refuse to send the video
bytes unless an ad plays or a BotGuard attestation token is present. That happens *server
side*, so there is nothing a page-level blocker can strip. The only way around it is to fetch
the video a different way.

This companion uses **yt-dlp** to pull the exact same video **anonymously** through YouTube's
app client (`android_vr`) — which is *not* ad-enforced — and streams the bytes back to your
browser on `127.0.0.1`. The AdBlock-Maxxer extension then hides YouTube's own player and plays
that ad-free stream in its place. The rest of youtube.com (search, comments, recommendations)
stays exactly as normal.

Because the extraction is anonymous, it never touches your logged-in account's enforcement.

## Easiest: the prebuilt app (nothing to install)

Download **`adblockmaxxer-companion.zip`** from https://dl.maxxtopia.com/adblockmaxxer-companion.zip
(Python + yt-dlp are baked in — you don't need anything else).

- **Unzip it** anywhere (it extracts an `abm-companion` folder), then **double-click
  `abm-companion\abm-companion.exe`** — it runs invisibly in the background and starts
  serving. That's it. Keep the whole folder together; the exe needs its `_internal\` files.
- To make it **start automatically every login**, run `install-companion-autostart.ps1`
  once (right-click → Run with PowerShell). It finds the unzipped exe, drops a hidden
  startup shortcut, and launches it.

It listens only on `127.0.0.1:47823` (localhost) — nothing is exposed to your network.
A log is written to `%TEMP%\abm-companion.log` if you ever need to check on it.

## Alternative: run from Python (for devs)

If you'd rather run the script directly you'll need **Python 3.8+** and
**yt-dlp** (`pip install -U yt-dlp`). Then double-click **`start-companion.bat`** or run
`python abm_companion.py`. Use a custom port with `python abm_companion.py 50000` (also change
`PORT` in `src/content/youtube-reclaim.js`).

## How the extension finds it

The extension's **YouTube Reclaim** toggle (popup, default ON) probes `http://127.0.0.1:47823/health`.
- Companion **running** → ad-free Reclaim player.
- Companion **not running** → silent no-op; the normal safeguard takes over (videos still play,
  with ads, instead of black-screening).

## Endpoints (for debugging)

- `GET /health` → `{ok:true,...}`
- `GET /resolve?v=VIDEOID` → JSON of chosen ad-free formats
- `GET /proxy?u=<googlevideo url>` → range-proxied media bytes (only `*.googlevideo.com` allowed)

## Honest limitations

- It relies on YouTube's app clients staying tokenless. Google is slowly tightening these; if
  this ever stops working, yt-dlp updates are the first thing to try.
- True stitched server-side ads (SSAI), estimated 6–12 months out, would eventually break this
  and every other client-side approach.
