Twitch inserts ads directly into the video stream (server-side ad insertion, "SSAI"), so the classic "block the ad request" approach does not work. blockmaxxing runs inside the Twitch player's media worker, inspects each HLS playlist, and transparently swaps ad-stitched segments for an ad-free stream requested with a player type that Twitch does not serve mid-rolls to.
Everything happens on your device. The extension makes no network calls except to Twitch's own APIs, stores no personal data, and ships no analytics or remote code.
Honest expectations. No Twitch ad blocker is perfect. Twitch changes its ad delivery frequently, so any blocker will occasionally let an ad through until it is updated. blockmaxxing blocks the large majority of ads and is built to be easy to patch. See Limitations.
- Stream-level ad removal via HLS playlist interception — the technique that works against SSAI.
- Per-channel whitelist — support your favorite streamers by letting their ads play.
- Blocked-ad counter and an optional, opt-in on-device diagnostic log.
- Mute-through-ad option that silences the player while the clean stream loads.
- Chrome + Firefox, both on Manifest V3, from a single codebase.
- 100% local — no backend, no telemetry, no account access.
From your browser's store (recommended):
- Chrome / Edge: Add to Chrome
- Firefox: Add to Firefox
npm install
npm run extension:buildThen load the unpacked build:
- Chrome / Edge — open
chrome://extensions, enable Developer mode, click Load unpacked, selectbuild/chromium. - Firefox — open
about:debugging#/runtime/this-firefox, click Load Temporary Add-on, selectbuild/firefox/manifest.json.
npm run pack:chromium # -> artifacts/blockmaxxing-chromium.zip
npm run pack:firefox # -> artifacts/blockmaxxing-firefox.zip| Layer | Responsibility |
|---|---|
vendor/twitch-adblock-engine.js |
The ad-block engine — hooks the Twitch player's HLS worker, detects stitched ad segments, and swaps to a clean backup stream. Vendored from TwitchAdSolutions (video-swap-new), MIT-licensed. |
content.ts |
Injects the engine at document_start when ad blocking is enabled and the channel is not whitelisted, and counts real block events. |
background.ts |
Persists settings + the blocked-ad counter and fans setting changes out to open tabs. |
packages/core |
Shared, framework-free logic (settings, storage, privacy rules) used by both browser targets. |
blockmaxxing stands on the shoulders of the open-source Twitch-adblock community — the engine is the well-maintained TwitchAdSolutions script (the same core VAFT and PurpleAdblock build on), vendored with its MIT license.
npm run lint # TypeScript strict type-check + ESLint
npm test # unit (privacy) + build-integrity tests
npm run extension:build # build Chromium + Firefox into build/
npm run test:smoke:chromium # load the extension and open popup/options
npm run test:firefox:lint # validate the Firefox build with web-extCI runs the full suite on every push and pull request.
Twitch breaks ad blockers regularly, so updates are automated:
- Weekly, the Update ad-block engine workflow refreshes the vendored engine from upstream, bumps the patch version, runs the full suite, and — if anything changed — opens a PR.
- You review and merge that PR.
- On merge, the Release workflow sees the new version,
builds and validates, and publishes a GitHub release with
blockmaxxing-chromium.zipandblockmaxxing-firefox.zipattached. - You download those two zips from the release and upload them to the Chrome Web Store and Firefox AMO (see docs/SUBMISSION.md).
To ship a manual update, bump and push:
node scripts/bump-version.mjs patch # or an explicit x.y.z
git commit -am "release: vX.Y.Z" && git push # Release workflow does the restRefresh the engine locally any time with npm run update:engine, and verify against a
live channel with RUN_LIVE=1 TWITCH_CHANNEL=<channel> npm run test:live:adblock.
If the built-in client-side engine is ever temporarily broken, the dashboard has an experimental proxy option: point it at your own luminous-ttv-compatible proxy and the playlist request is routed through it instead. It is off by default, sends only the channel name to the proxy you configure, may be blocked by Twitch's page CSP, and falls back to the normal request on error. Recommended only for advanced users who run a proxy — the default engine needs no setup.
- Effectiveness depends on Twitch's current ad delivery; expect occasional breakage until updated.
- Brief buffering can occur at ad boundaries while the clean stream is fetched.
- Live-ad effectiveness is not asserted in CI (non-deterministic); spot-check before releasing.
- No cookies, tokens, headers, full URLs, account data, chat, or page snapshots are ever stored.
- The on-device activity log is local-only, capped, clearable, and never leaves your device — the extension has no backend or telemetry.
- Network requests go only to Twitch's own APIs (
gql.twitch.tv,usher.ttvnw.net) — except the opt-in proxy fallback, which (when you enable it) sends the channel name to the proxy URL you configure. - Host permissions are limited to
*://*.twitch.tv/*.
MIT · © wpggLabs. Not affiliated with or endorsed by Twitch Interactive, Inc.