# pea1bee/hotstar-ipl-ad-mute architecture

> Architecture diagram of the GitHub repository pea1bee/hotstar-ipl-ad-mute, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pea1bee/hotstar-ipl-ad-mute
- Repository: https://github.com/pea1bee/hotstar-ipl-ad-mute

## Overview

##### Project type and purpose
- This is a browser extension (Chrome & Firefox variants) whose sole job is to intercept Hotstar ad-tracking requests in a live stream and mute the tab for the ad’s duration.
- It runs entirely in the client’s browser, requires minimal permissions, and has no external backend of its own.

##### File structure
- Top level:
– chrome/
- manifest.json (extension config & permissions)
- background.js (service worker that listens to webRequest, controls tab audio)
– firefox/
- manifest.json (Firefox-specific config)
- background.js (same logic, Firefox API calls)
- No content scripts or UI pages—purely a background/service worker that uses browser.webRequest and browser.tabs APIs.

##### README for extra details
- The extension:
– Hooks into Hotstar’s tracking-pixel URL (`https://bifrost-api.hotstar.com/v1/events/track/ct_impression`)
– Extracts `adName` query parameter
– Estimates mute duration from identifier
– Mutes/unmutes the streaming tab via browser.tabs.update
- Customization points:
– A toggle (`MUTE_ALL_ADS`)
– A list of `targetAdIds` in background.js

a. Main components
1. User’s Browser (Chrome or Firefox)
2. Browser Extension
– Manifest (declares permissions: webRequest, tabs, host permissions for hotstar.com)
– Background Script (service worker)
3. Hotstar Streaming Website (web page with video player)
4. Hotstar Ad-Tracking API (pixel requests)
b. Relationships & Interactions
– User interacts with Hotstar live-stream page → video player runs in the page context
– Video player triggers ad-tracking pixel calls to Hotstar Ad-Tracking API
– Extension’s background.js listens (via webRequest.onBeforeRequest) for matching URLs
– On match: background.js parses adName, computes duration, calls browser.tabs.update(tabId, { muted: true })
– After estimated duration: background.js calls browser.tabs.update(tabId, { muted: false })
c. Architectural patterns / principles
– Event-driven: uses browser.webRequest events
– Single-process/service worker: no UI or content scripts
– Separation of concerns:
- Manifest only for permissions/config
- Background script contains all logic
d. Key technologies / libraries
– WebExtension APIs (chrome.* or browser.*)
– JavaScript (ES6+)
– Browser webRequest & tabs modules

##### Don’t over-complicate—capture exactly
– The extension’s two variants (Chrome, Firefox) share the same design—just note the separate manifest files.
– No backend servers of our own—only Hotstar’s endpoints.
– Core flow: detect request → mute → wait → unmute.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Project Documentation
    README["Project README"]:::docs

    %% External Services
    subgraph "External Hotstar Services"
        style External fill:#e0ffe0,stroke:#2d662d,stroke-width:2px
        Site["Hotstar Site (Video Player)"]:::external
        API["Hotstar Ad-Tracking API"]:::external
    end

    %% Browser Host Environment
    subgraph "User's Browser" 
        style Browser fill:#f0f0f0,stroke:#606060,stroke-width:2px

        %% Browser Extension Variants
        subgraph "Browser Extension"
            style Extension fill:#e8f1ff,stroke:#29507a,stroke-width:2px

            subgraph "Chrome Extension"
                style ChromeExt fill:#d0e7ff,stroke:#1e4f8b,stroke-width:1px
                CManifest["Manifest (chrome/manifest.json)"]:::extension
                CBackground["Background Service Worker\n(background.js)\n- webRequest.onBeforeRequest\n- parses adName & duration\n- tabs.update(mute/unmute)"]:::extension
            end

            subgraph "Firefox Extension"
                style FirefoxExt fill:#d0e7ff,stroke:#1e4f8b,stroke-width:1px
                FManifest["Manifest (firefox/manifest.json)"]:::extension
                FBackground["Background Service Worker\n(background.js)\n- webRequest.onBeforeRequest\n- parses adName & duration\n- tabs.update(mute/unmute)"]:::extension
            end
        end

        Tab["Browser Tab\n(playing live stream)"]:::host
    end

    %% Flows
    Site -->|"Loads video player"| Tab
    Tab -->|"Sends tracking pixel"| API
    API -->|"webRequest.onBeforeRequest"| CBackground
    API -->|"webRequest.onBeforeRequest"| FBackground
    CBackground -->|"tabs.update(mute)"| Tab
    CBackground -->|"tabs.update(unmute)"| Tab
    FBackground -->|"tabs.update(mute)"| Tab
    FBackground -->|"tabs.update(unmute)"| Tab

    %% Click Events
    click CManifest "https://github.com/pea1bee/hotstar-ipl-ad-mute/blob/main/chrome/manifest.json"
    click CBackground "https://github.com/pea1bee/hotstar-ipl-ad-mute/blob/main/chrome/background.js"
    click FManifest "https://github.com/pea1bee/hotstar-ipl-ad-mute/blob/main/firefox/manifest.json"
    click FBackground "https://github.com/pea1bee/hotstar-ipl-ad-mute/blob/main/firefox/background.js"
    click README "https://github.com/pea1bee/hotstar-ipl-ad-mute/blob/main/README.md"

    %% Styles
    classDef extension fill:#cfe2ff,stroke:#2e6f9e,stroke-width:1px
    classDef external fill:#e0ffe0,stroke:#2d662d,stroke-width:1px
    classDef host fill:#f0f0f0,stroke:#606060,stroke-width:1px
    classDef docs fill:#fff3cd,stroke:#aa7700,stroke-width:1px
```
