# shxnqzu/ears-bass-boost-eq-any-audio-for-firefox architecture

> Architecture diagram of the GitHub repository shxnqzu/ears-bass-boost-eq-any-audio-for-firefox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox
- Repository: https://github.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox

## Overview

Ears is a Firefox WebExtension prototype for equalizing HTML audio/video media in the current tab. The main workflow is: a user opens the popup and enables EQ; the background process injects and commands a content script; that script configures page-world Web Audio processing, which attaches filters to media elements. The popup also manages presets, filter settings, themes, and spectrum display. The sampled sources show the messaging and audio path; the README documents product limits and behaviors. The older offscreen files are excluded because the README says they are not part of Firefox audio processing.

Main entry points: [`extension/bg.js`](https://github.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox/blob/main/extension/bg.js) (Background controller), [`extension/content.js`](https://github.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox/blob/main/extension/content.js) (Content bridge), [`extension/main-world.js`](https://github.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox/blob/main/extension/main-world.js) (Web Audio processor), [`extension/popup.js`](https://github.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox/blob/main/extension/popup.js) (EQ popup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Popup interface"]
  node_popup["EQ popup<br/>[popup.js]"]
end

subgraph group_coordination["Extension coordination"]
  node_background["Background controller<br/>[bg.js]"]
end

subgraph group_audio["Page audio processing"]
  node_content["Content bridge<br/>[content.js]"]
  node_processor["Web Audio processor<br/>[main-world.js]"]
end

subgraph group_presets["Preset persistence"]
  node_preset_store[("Preset storage")]
end

node_user(("User"))
node_media["Page media elements"]
node_downloads["Browser downloads"]

node_user -->|"opens and controls"| node_popup
node_popup -->|"sends commands"| node_background
node_background -->|"injects and commands"| node_content
node_content -->|"injects and configures"| node_processor
node_processor -->|"processes audio"| node_media
node_background -->|"publishes status"| node_popup
node_background -->|"requests FFT"| node_content
node_content -->|"requests FFT"| node_processor
node_processor -->|"returns FFT"| node_content
node_background -->|"loads and saves"| node_preset_store
node_background -->|"exports presets"| node_downloads

click node_popup "https://github.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox/blob/main/extension/popup.js"
click node_background "https://github.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox/blob/main/extension/bg.js"
click node_content "https://github.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox/blob/main/extension/content.js"
click node_processor "https://github.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox/blob/main/extension/main-world.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_popup,node_user,node_downloads toneBlue
class node_background toneAmber
class node_content,node_processor toneMint
class node_preset_store toneRose
class node_media toneIndigo
```

## Components

### Popup interface

- [EQ popup](https://github.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox/blob/main/extension/popup.js): `extension/popup.js`

### Extension coordination

- [Background controller](https://github.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox/blob/main/extension/bg.js): `extension/bg.js`

### Page audio processing

- [Content bridge](https://github.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox/blob/main/extension/content.js): `extension/content.js`
- [Web Audio processor](https://github.com/shxnqzu/ears-bass-boost-eq-any-audio-for-firefox/blob/main/extension/main-world.js): `extension/main-world.js`

### Preset persistence

- **Preset storage**

### Other components

- **User**
- **Page media elements**
- **Browser downloads**

## Connections

- User → EQ popup: opens and controls (evidence: `README.md`)
- EQ popup → Background controller: sends commands (evidence: `extension/popup.js`)
- Background controller → Content bridge: injects and commands (evidence: `extension/bg.js`)
- Content bridge → Web Audio processor: injects and configures (evidence: `extension/content.js`)
- Web Audio processor → Page media elements: processes audio (evidence: `extension/main-world.js`)
- Background controller → EQ popup: publishes status (evidence: `extension/bg.js`)
- Background controller → Content bridge: requests FFT (evidence: `extension/bg.js`)
- Content bridge → Web Audio processor: requests FFT (evidence: `extension/content.js`)
- Web Audio processor → Content bridge: returns FFT (evidence: `extension/main-world.js`)
- Background controller → Preset storage: loads and saves (evidence: `extension/bg.js`)
- Background controller → Browser downloads: exports presets (evidence: `extension/bg.js`)
