YoutubeAdblock

A document-start YouTube ad blocker with a split-context proxy engine, remote rule support, and a premium Control Center for tuning protection.

Quick Start

Userscript (Tampermonkey / Violentmonkey)

1. Install Tampermonkey or Violentmonkey
2. Click here to install YoutubeAdblock
3. Confirm installation when prompted, then reload YouTube
4. Open your userscript menu and use the built-in commands to open the Control Center, pause or resume protection, or refresh rules on demand

Chrome / Edge / Brave (Chromium 121+, MV3 extension, unpacked)

1. Clone or download the repo, then run powershell -ExecutionPolicy Bypass -File .\Build-Extension.ps1 to regenerate extension/main.js from the userscript
2. Visit chrome://extensions, enable Developer mode, and click Load unpacked
3. Select the extension/ folder
4. Click the YoutubeAdblock toolbar button (or press Ctrl+Shift+Y) to open the Control Center

Because the MV3 manifest intentionally includes both background.service_worker and background.scripts for Chrome + Firefox compatibility, the unpacked extension target is Chromium 121 or newer.

If you need a packaged Chromium artifact for release distribution, run powershell -ExecutionPolicy Bypass -File .\Build-CRX.ps1. It writes a signed .crx plus a reusable private key into dist/, so future CRX builds keep the same extension ID. Keep in mind that Chrome generally does not allow normal local-file .crx installs outside developer-mode, Linux self-hosting, or managed-policy flows, so the unpacked install path remains the best default for most users.

Firefox (MV3 extension, temporary install)

1. Build the extension as above
2. Visit about:debugging#/runtime/this-firefox
3. Click Load Temporary Add-on and pick extension/manifest.json
4. Click the YoutubeAdblock toolbar button to open the Control Center

The extension ships the same blocking engine as the userscript plus declarativeNetRequest rules that block ad-serving endpoints (/pagead/, /api/stats/ads, /youtubei/v1/player/ad_break, googlevideo ctier=SA segments, doubleclick.net and googlesyndication.com from YouTube origins) at the browser network layer — outside the reach of any page-level anti-adblock countermeasure. If you trigger the extension while you are not already on YouTube, YoutubeAdblock opens a YouTube tab and carries the action forward there automatically.

Highlights

• Blocks ads before they render by pruning payloads in JSON.parse, fetch(), and XMLHttpRequest
• Handles anti-detection paths like abnormality callbacks, clean iframe bypasses, and playback timers
• Keeps cosmetic cleanup separate from payload blocking so the interface stays tidy after the heavy lifting is done
• Ships with a local fallback rule set, cached remote rules, and a diagnostics-friendly Control Center

Features

How It Works

┌──────────────────────────────────────────────────────────────────────┐
│                        document-start                                │
│                                                                      │
│  ┌─────────────────────┐    ┌──────────────────────────────────┐    │
│  │  PHASE 1: Page Ctx  │    │  PHASE 2: Sandbox                │    │
│  │  (injected <script>)│    │  (Tampermonkey GM_* APIs)        │    │
│  │                     │    │                                  │    │
│  │  • JSON.parse proxy │    │  • 150+ CSS cosmetic selectors   │    │
│  │  • fetch() proxy    │    │  • DOM MutationObserver cleanup  │    │
│  │  • XHR proxy        │    │  • SSAP auto-skip delegation     │    │
│  │  • appendChild proxy│    │  • GM_getValue/setValue storage   │    │
│  │  • setTimeout proxy │    │  • Remote filter list fetching   │    │
│  │  • Promise.then     │    │  • CSS re-injection protection   │    │
│  │  • Property traps   │    │  • Control Center UI             │    │
│  │  • Video ad skipper │    │                                  │    │
│  └─────────────────────┘    └──────────────────────────────────┘    │
│              │                            │                          │
│              ▼                            ▼                          │
│     Real window object            Shared DOM access                  │
│     (YouTube sees proxies)        (CSS/elements work from sandbox)   │
└──────────────────────────────────────────────────────────────────────┘

Tampermonkey's @grant GM_* directives wrap userscripts in a sandbox where window is a proxy — YouTube's scripts never see modifications made in the sandbox. YoutubeAdblock solves this by injecting the proxy engine into the real page context via a <script> element at document-start, before any YouTube scripts execute. CSS injection, DOM observers, and settings management stay in the sandbox since they operate on the shared DOM.

Each proxy installation is individually try/catch wrapped using a safeOverride() helper (direct assign → Object.defineProperty → delete+redefine fallback), so one engine failure never prevents the others from loading.

Configuration

All settings persist via GM_setValue. Open the userscript menu and choose YoutubeAdblock: Open Control Center to adjust protection without leaving YouTube.

Control Center

Filter List

The default remote filter list is hosted in this repo at `youtube-adblock-filters.txt`. It uses uBO-compatible filter syntax and is parsed on fetch. The userscript build can point the Rule Library field at any compatible raw list URL; the extension build works best with sources that allow direct browser fetches from YouTube pages, so the recommended GitHub-hosted source is the safest default there. If a refresh fails, YoutubeAdblock keeps the last working rules or the built-in fallback active so protection does not drop unexpectedly.

Pruned API Fields

The proxy engine strips these fields from YouTube API responses before they reach the player:

adPlacements · adSlots · playerAds · adBreakHeartbeatParams · auxiliaryUi.messageRenderers.upsellDialogRenderer · responseContext.adSignalsInfo · frameworkUpdates

Intercepted Endpoints

/youtubei/v1/player · /youtubei/v1/get_watch · /youtubei/v1/browse · /youtubei/v1/search · /youtubei/v1/next · /youtubei/v1/guide · /watch?

Supported Sites

FAQ / Troubleshooting

Ads still showing after install? Make sure no other YouTube ad-blocker userscripts are running simultaneously — they can conflict with the proxy engine. Disable competing scripts and reload.

YouTube detects my ad blocker? Ensure the Anti-Detect setting is enabled. If YouTube recently changed their detection, check for a script update or open an issue.

Works on Firefox? Yes, with Violentmonkey or Tampermonkey. All features are cross-browser.

How do I use a different filter list? Point the Rule Library field at a compatible raw list that includes the selectors you want, then refresh the rules from the Control Center.

How do I reset settings? Open the Control Center and use Restore Defaults. That resets the master switch and feature toggles to the recommended starting state without requiring DevTools.

Contributing

Issues and PRs welcome. When reporting bugs, include:

• Browser and version
• Userscript manager and version
• Console errors (F12 → Console, filter by YoutubeAdblock)
• Which settings are enabled

License

MIT — Matthew Parker