How pixeltris/twitchadsolutions works
Project Type and Purpose
• TwitchAdSolutions is an open-source set of client-side ad-blocking scripts and filter rules for Twitch. It provides userscripts and uBlock Origin resource files to swap or downgrade video streams during ad breaks.
• This is not a traditional full-stack app; it’s a collection of small JavaScript modules (vaft and video-swap-new) that integrate into browser extensions or userscript managers to manipulate Twitch’s playback.
File Structure Analysis
• Top level:
• .github/workflows/release.yml – CI for packaging or releasing updates.
• README.md, full-list.md – documentation and recommended solutions list.
• Directories:
• vaft/ – “video ad fast toggle” script variants:
– vaft.user.js – userscript version
– vaft-ublock-origin.js – uBlock Origin filter-resource version
• video-swap-new/ – alternative ad workaround:
– video-swap-new.user.js
– video-swap-new-ublock-origin.js
Insights from README
• Users choose between proxy-based solutions or client-side scripts.
• Clients install via uBlock Origin’s “userResourcesLocation” or via a userscript manager (Tampermonkey, Violentmonkey).
• The scripts detect when Twitch serves an ad segment (e.g., via DOM mutation or XHR hook), then redirect the player to a low-res or proxy stream.
Main Components
a. User Environment
• Browser (Chrome, Firefox, Brave)
• Browser extension (uBlock Origin) and/or Userscript Manager
b. Script Hosting
• GitHub repository (pixeltris/TwitchAdSolutions)
• Raw content delivery (raw.githubusercontent.com)
• Optional proxy servers (external, recommended by full-list.md)
c. Twitch Service
• Twitch.tv front-end (HTML5 player)
• Twitch streaming backend (m3u8 HLS endpoints)
• Ad servers (ad segments interleaved in HLS)
d. Script Logic
• Injection point (DOM XHR/fetch hook)
• Ad detection module – listens for Twitch’s ad segment events
• Stream switcher – fetches alternative stream URL (lower resolution or proxy)
• Player control – forces player to load new stream, handles resume of main stream post-ad
Relationships and Data Flows
• Browser → loads twitch.tv → Twitch front-end drive player.
• uBlock Origin / Userscript Manager → fetches script from raw CDN → injects into page.
• Injected script → hooks player events → on ad start, request alt stream from Twitch or proxy → update player source.
• After ad ends, script switches back to main stream.
• CI pipeline (.github/workflows/release.yml) → updates scripts in repo → triggers raw URLs to serve new versions.
Architectural Patterns and Design Principles
• Plugin-style integration: scripts act as middleware between player and Twitch API.
• Single responsibility: vaft and video-swap-new each handle one strategy.
• Configurable delivery: two distribution channels (uBlock userResources vs. userscript) for user flexibility.
• Minimal client footprint: no backend servers required, except optional proxies.
Essential Details to Capture
• Both distribution methods (userscript vs. uBlock resource).
• Two parallel strategies (vaft vs. video-swap-new).
• Runtime behavior: detection → fallback → restoration.
• External dependencies: Twitch’s HLS API, optional proxy services, CI/CD.