Purple-adblock

About

Purple Adblock blocks the ads Twitch puts in live streams. It runs inside the Twitch player's worker and edits the HLS playlists the player receives: a playlist without ads goes to the player untouched, and one with ads is replaced or edited before the player loads any ad segment.

It ships as a Firefox add-on (Manifest V2), a Chromium extension (Manifest V3: Chrome, Edge, Brave, Opera) and a userscript.

Install

Browser	Install from ...	Browser	Install from ...
	Firefox Add-ons		Chrome Web Store
	Chrome Web Store, after Allow extensions from other stores		Chrome Web Store
	Chrome Web Store, with Opera's Install Chrome Extensions		Userscript, in a userscript manager that runs scripts at document-start (Tampermonkey, Violentmonkey)

The extension's popup turns Purple off and on for the channel in the current tab (a per-channel allow list). The userscript has no popup and uses the default settings.

Releases and pre-releases on the releases page come with a Firefox build signed by Mozilla (purple-adblock-<version>-firefox-signed.xpi), which Firefox installs from about:addons (gear menu, Install Add-on From File...) and keeps after a restart.

Manual installation

The releases page has purple-adblock-<version>-firefox.zip and purple-adblock-<version>-chromium.zip.

Firefox:

1. Unzip the Firefox release.
2. Open about:debugging#/runtime/this-firefox.
3. Click Load Temporary Add-on... and select manifest.json in the unzipped folder.

Firefox removes a temporary add-on when it closes; the Firefox Add-ons version stays installed.

Chrome, Edge and other Chromium browsers:

1. Unzip the Chromium release.
2. Open chrome://extensions/ (edge://extensions/ in Edge).
3. Turn on Developer mode.
4. Click Load unpacked and select the unzipped folder.

To build from source, see CONTRIBUTING.md.

How it works

1. A script in the page replaces window.Worker before Twitch creates its player workers, so Purple's code runs in each worker ahead of Twitch's own script.
2. In the worker, Purple intercepts the requests for the stream's master and media playlists and reads each media playlist for ad markers and ad segments.
3. With ad segments, Purple asks Twitch for the same stream under other player types (site, popout, frontpage, mobile_web, embed, picture-by-picture, autoplay) and gives the player the first one without ads, in the quality the player is on.
4. When no backup is free of ads, each ad segment is swapped for a backup's live segment of the same moment, and the ad segments left are answered with an empty segment inside the worker: their media is never downloaded.
5. In the page, requests to Twitch's client-side ad server (edge.ads.twitch.tv) get an empty answer.

Details: docs/architecture.md. Every strategy and setting, with its default: docs/feat.md.

Blocking use cases

The IDs point to docs/feat.md; B-xxx are Twitch server behaviors in docs/server/behaviors.md.

Case	What Twitch sends	What Purple does	IDs
Midroll	Ad segments stitched into the live playlist (MIDROLL)	Replaces the playlist with a backup without ads, in the player's quality and codec, the types that give 720p first. The backup's segments get the numbers the page's playlist gives the same moment, so the player goes on without waiting. The type that worked is tried first at the next break	E3, E4, F-09, F-10, F-11, F-23
Preroll	The channel opens with ad segments (PREROLL); backup tokens asked during it get a preroll of their own, except autoplay (B-052)	Asks the first backup type, then all the others at once, and plays the first one without ads (usually autoplay, 360p) until the preroll ends. The page's playlist then numbers from 0: the player is restarted once, about 1 s	E3, E4, F-09, F-24, F-26
Break already running when the channel opens	Ad segments from the first playlist, as in a preroll	As in a preroll	F-22, F-26
Midroll in the first seconds after the channel opens	A break before any backup was asked	Backup tokens are requested when the channel loads, and again at each picture-by-picture request of the page, 3 to 14 s before most midrolls (B-044)	F-19, F-22
Break announced before its ad segments	A twitch-stitched-ad marker after the last live segment, with prefetch lines to the first ad segments (B-034)	Removes those prefetch lines and answers their URIs with an empty segment	F-03, F-14
Backup with a break of its own	A backup playlist with ad segments, or announcing its own break	Skips that type for 5 s, asks a new token for it and takes the next type	F-10
Backup behind the player	A backup token asked a moment ago lists nothing newer than what the player has	Takes a later type that is ahead; uses the one behind only when none is	F-25
Ad segments without an ad title	Segments titled with a number or FT|… inside an ad range (B-035)	Detects them by the twitch-stitched-ad range and the stream source, not only by the title	F-02, F-03
No backup without ads	Every backup type has ads at that moment	Swaps each ad segment for a backup's live segment of the same ; the ad segments left are answered with an empty segment in the worker, so no ad media is downloaded or shown

Not covered

• VODs and clips.
• Banner and display ads on the page: a general blocker such as uBlock Origin covers them.
• Ad-watched reporting to Twitch.

Recommendations

1. Do not run another Twitch ad blocker or script with the same purpose next to Purple: both replace the player's worker.
2. Use a general blocker, such as uBlock Origin, for the rest of the page.
3. Other approaches to Twitch ads: ryanbr/TwitchAdSolutions.

Documentation

File	Content
docs/architecture.md	flow and messages between page, worker and content script
docs/feat.md	strategies, fixes, features, settings and defaults
docs/tests.md	test levels, fixtures, harness and test matrix
docs/task.md	backlog, acceptance criteria and tests per task
docs/server/	Twitch's server behaviors, endpoints, playlists and tokens
docs/findings/	dated findings and the probes behind them
docs/research.md	Brave's Twitch scriptlet, used as reference

Contributing and support

CONTRIBUTING.md has the setup, the commands, the tests and the rules for changes. Ads that got through go in the pinned issue #111; other bugs and feature requests to the issues; help on the Discord server.

Credits

• TwitchAdSolutions by pixeltris, the original project, and its maintained fork ryanbr/TwitchAdSolutions by ryanbr: the backup access tokens by player type, the blank segment for ad segments and the player reload come from their scripts, and part of their code is in Purple (MIT License, Copyright (c) 2020-present TwitchAdSolutions Contributors).
• brave/adblock-resources, which ships the same script in Brave and is Purple's reference implementation (docs/research.md).

License and third-party notices

Apache License 2.0 (LICENSE, NOTICE), from version 2.7.0; earlier versions were released under the GNU General Public License v3.0. Third-party code and its notices: THIRD-PARTY-NOTICES.md. The three files are in every extension package, and the userscript carries their notices.