Skip to content

README.md

Latest commit

 

History

History
187 lines (131 loc) · 11.6 KB

README.md

File metadata and controls

187 lines (131 loc) · 11.6 KB
Raw

Umbra EQ — per-tab equalizer, bass boost and volume booster for Chrome, Edge and Opera

Umbra EQ

Per-tab parametric equalizer, bass boost & volume booster for Chrome, Edge & Opera
11 bands · one global sound · site rules · 100% local

Chrome Web Store Chrome Web Store users MIT license Build status Manifest V3 Chrome 116+

Add to Chrome   Русский README

Umbra EQ — the 11-band parametric equalizer curve with live spectrum and bass boost on a browser tab   Umbra EQ per-site rules — give each site its own equalizer sound by address pattern

Why Umbra EQ

Thin bass on laptop speakers, one video mixed too quiet, another too harsh — and most EQ extensions go silent on the streaming sites you actually use. Umbra fixes the sound of the tab you're listening to, live, and keeps it 100% on your computer. Set one sound for every tab, or give specific sites their own with rules.

Install

Install from the Chrome Web Store — one click, auto-updating.

On Edge or Opera, or to run your own build, load it unpacked (about a minute):

  1. Download the latest umbra-eq-<version>.zip from Releases and unzip it (or build from source below).
  2. Open chrome://extensions (or edge://, opera://) and turn on Developer mode.
  3. Load unpacked → pick the unzipped dist folder. Chrome 116+.

Note

Icon does nothing? Make sure you picked the dist folder (build output), not the repo root, on Chrome 116+ — the audio engine needs the offscreen-document API.

Features

  • 11-band parametric EQ — drag the curve to boost or cut any frequency, live.
  • One global sound + site rules — one EQ everywhere, or per-site overrides by address pattern (first match wins). Each tab keeps its own chain.
  • Works on Netflix, Spotify and other sites where EQ extensions go silent.
  • Bass boost, volume past 100%, output limiter — big boosts stay clean, no clipping.
  • Presets — Bass Boost / Vocal / Movie / Warm + your own; export as a file or share code.
  • Live spectrum, band guide, full-window editor.
  • Keyboard + screen-reader friendly, RU/EN, four themes + a custom accent colour. No account, no network, no analytics.

How to use

  1. Play audio in a tab, click the Umbra EQ icon, press EQ This Tab.
  2. Drag a dot (or arrow keys): left/right = frequency, up/down = boost/cut, Shift = width/Q, double-click resets. Left strip is master volume.
  3. Add a rule like youtube. for a per-site sound; stop a tab under Tabs, or open Full window for a bigger graph.

The in-app Guide (More tab) walks through all of it, RU or EN.

Browser support

Browser Status Notes
Chrome Supported Chrome 116+ (offscreen document + tab capture)
Edge Supported Chromium, same package
Opera Supported Chromium, same package
Firefox Planned Needs a separate content-script engine (no tabCapture/offscreen). See FIREFOX_PORT.md.

Build from source

For developers

The popup is React + TypeScript, bundled with Vite and CRXJS. The audio engine (service worker + offscreen Web Audio document) stays vanilla. Needs Node 20+; no API keys, env vars, or services to set up.

npm install
npm run build      # → dist/  (loadable, CSP-clean MV3 extension)
npm run dev        # HMR dev build
npm test           # 64 Vitest unit tests
npm run typecheck  # tsc, also in CI

Then load the dist folder unpacked (see Install). For the store zip:

npm run build
powershell -ExecutionPolicy Bypass -File build-zip.ps1
# → release/umbra-eq-<version>.zip

The same zip is accepted by the Chrome Web Store, Edge Add-ons, and Opera.

Dev loop: npm run build → Reload on the extension card → Ctrl+R the popup. After vite dev, delete node_modules/.vite and dist before a real build, or dist/ stays a dev-mode stub.

How it works

Manifest V3. The popup (React + TypeScript) is the source of truth: it resolves each tab (rule → global profile → flat) and pushes the bands to the engine. The engine is vanilla — the service worker owns the offscreen document and mints tab-capture ids; the offscreen document holds 11 biquad filters per tab behind a brick-wall limiter, glided click-free. Pure audio/preset/rule math lives in src/lib (unit-tested); strict CSP, no remote code, no eval.

Working on Umbra? HANDOFF.md is the full developer handoff — architecture, release process, roadmap, known limitations. See also PROJECT.md, DEPLOY.md, and CONTRIBUTING.md.

How Umbra EQ compares

Most browser equalizers are a fixed set of graphic-EQ sliders that inject a content script into the page — which is why they fall silent on Spotify, YouTube Music, and other players that isolate their audio. Umbra is different on three axes:

  • True parametric, not fixed sliders. Each of the 11 bands is a full biquad filter you move in frequency, gain, and width (Q) — finer control than a locked graphic equalizer.
  • Per-tab, and it keeps working. A tabCapture-based audio engine gives every tab its own filter chain, so a music tab and a video tab can sound different at once — and it still processes sound on the streaming sites where content-script EQs go quiet.
  • 100% local and open-source. No account, no ads, no analytics, no network calls; MIT-licensed and auditable. Many free equalizer / volume-booster extensions are ad-supported or permission-hungry.

FAQ

Does it work as a YouTube or Spotify equalizer? Yes — Umbra EQ shapes the tab's own audio, so it works as a YouTube equalizer, a Spotify equalizer, and on most web players, streams, and podcasts. Sites that hand their audio to a separate process are the occasional exception.

Is it a bass booster and volume booster too? Yes. The low bands act as a one-click bass boost; the master control is a volume booster that pushes a tab past 100%, with a brick-wall limiter so loud audio stays clean instead of clipping.

What is a parametric equalizer? Unlike a graphic equalizer with fixed sliders, a parametric EQ lets you move each band in frequency, gain, and width — so you can target the exact part of the sound you want to boost or cut.

Is it really free, with no ads or tracking? Yes. Umbra EQ is free, MIT-licensed, 100% local, and makes no network calls of its own — no ads, no accounts, no analytics.

Which browsers does it support? Chrome 116+, Microsoft Edge, and Opera (the same package). A Firefox port is planned.

Is it open source? Yes — the full source is in this repository under the MIT license.

Privacy

100% local — the extension makes no network requests of its own, has no analytics, and audio is never recorded or sent. Settings stay on your device; saved presets and rules live in chrome.storage.sync, so Chrome replicates them across your own signed-in profiles. Details in PRIVACY.md.

Stack

Layer Technology
Shell Manifest V3 — service worker + offscreen document
Audio Web Audio API — 11 biquad filters per tab + brick-wall limiter
Popup React 18, TypeScript
Build Vite + CRXJS
UI Tailwind CSS, shadcn/ui, lucide icons
Tests Vitest (64)
CI/CD GitHub Actions — builds the dist/ zip on push, PR & v* tags

Stars

If Umbra fixed your sound, a star helps other people find it.

GitHub stars   Release downloads

Star History Chart

Feedback
Suggest a feature Start a discussion
Something broke? File an issue
Like it? Star the repo

Contributing

Issues and pull requests welcome — see CONTRIBUTING.md.

Credits and licenses

  • Application code: MIT (LICENSE).
  • Fonts: Inter and Geist Mono under the SIL Open Font License 1.1.
  • UI: React, Tailwind CSS, shadcn/ui (MIT), lucide-react (ISC). Full list: THIRD-PARTY-NOTICES.md.

Umbra EQ is an independent audio tool, not affiliated with or endorsed by Netflix, Spotify, YouTube, Google, or any site it processes audio on. All trademarks belong to their owners.