# pixeltris/twitchadsolutions architecture

> Architecture diagram of the GitHub repository pixeltris/twitchadsolutions, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pixeltris/twitchadsolutions
- Repository: https://github.com/pixeltris/twitchadsolutions

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Environment"
        Browser["Browser (Chrome, Firefox, Brave)"]:::user
        UBO["uBlock Origin"]:::user
        USM["Userscript Manager"]:::user
    end

    subgraph "Distribution & CI/CD"
        CI["CI/CD Pipeline"]:::infra
        DOC1["README.md"]:::infra
        DOC2["full-list.md"]:::infra
        CDN["GitHub Raw CDN"]:::infra
    end

    subgraph "Strategies"
        direction TB
        subgraph "VAFT"
            V_US["vaft.user.js"]:::script
            V_UO["vaft-ublock-origin.js"]:::script
        end
        subgraph "Video-Swap-New"
            VS_US["video-swap-new.user.js"]:::script
            VS_UO["video-swap-new-ublock-origin.js"]:::script
        end
    end

    subgraph "Script Logic"
        AD["Ad Detector"]:::script
        SS["Stream Switcher"]:::script
    end

    subgraph "Twitch Services"
        TF["Twitch Front-end (HTML5 player)"]:::external
        TB["Twitch Backend (HLS endpoints)"]:::external
        AS["Ad Servers (HLS)"]:::external
    end

    PROXY["Optional Proxy Services"]:::external

    CI -->|"updates scripts"| CDN
    CDN -->|"raw scripts"| UBO
    CDN -->|"raw scripts"| USM
    CDN --> V_US
    CDN --> V_UO
    CDN --> VS_US
    CDN --> VS_UO

    UBO -->|injects resource| V_UO
    UBO -->|injects resource| VS_UO
    USM -->|injects script| V_US
    USM -->|injects script| VS_US

    V_US --> AD
    V_UO --> AD
    VS_US --> AD
    VS_UO --> AD

    V_US --> SS
    V_UO --> SS
    VS_US --> SS
    VS_UO --> SS

    Browser -->|"loads page"| TF
    TF -->|"GET m3u8"| TB
    TB -->|"interleaved ads"| AS

    Browser -->|"hooks XHR/fetch"| AD
    AD -->|"detect ad"| SS
    SS -->|"GET alt m3u8"| PROXY
    SS -->|"or Twitch HLS"| TB
    SS -->|"switch source"| Browser
    Browser -->|"resume stream"| TB

    DOC1 --> CI
    DOC2 --> CI

    click CI "https://github.com/pixeltris/twitchadsolutions/blob/master/.github/workflows/release.yml"
    click DOC1 "https://github.com/pixeltris/twitchadsolutions/blob/master/README.md"
    click DOC2 "https://github.com/pixeltris/twitchadsolutions/blob/master/full-list.md"
    click V_US "https://github.com/pixeltris/twitchadsolutions/blob/master/vaft/vaft.user.js"
    click V_UO "https://github.com/pixeltris/twitchadsolutions/blob/master/vaft/vaft-ublock-origin.js"
    click VS_US "https://github.com/pixeltris/twitchadsolutions/blob/master/video-swap-new/video-swap-new.user.js"
    click VS_UO "https://github.com/pixeltris/twitchadsolutions/blob/master/video-swap-new/video-swap-new-ublock-origin.js"

    classDef user fill:#ccffcc,stroke:#006600
    classDef script fill:#cce5ff,stroke:#004080
    classDef external fill:#ffe5cc,stroke:#cc6600
    classDef infra fill:#eeeeee,stroke:#666666
```
