WebGlitch 🎛️📺

Tordez des pages web avec du son. WebGlitch est une extension navigateur qui transforme n'importe quelle page web en instrument visuel : le son pilote des variables CSS en temps réel, et la page glitche, pulse, se déforme au rythme de la musique.

---

Table des matières

• Le concept
• Comment ça marche
• Les bandes
  • Le filtre
  • Le mapping
• Le CSS utilisateur
• Les sources de contrôle
  • Audio via loopback
  • Web MIDI (Ableton & co)
• L'interface
• Les presets
• Architecture technique
  • Vue d'ensemble
  • Structure du dépôt
  • Flux de données
  • Performance
• Philosophie : zéro dépendance externe
• Compatibilité navigateurs
• Développement
• Roadmap
• Conventions du projet
• Licence

---

Le concept

Une page web est une matière plastique : tailles, couleurs, positions, flous, rotations — tout est pilotable par des variables CSS (custom properties). WebGlitch injecte ces variables dans la page et les fait bouger avec le son.

Le principe en une phrase :

On découpe le son en bandes de fréquences, on mesure le volume de chaque bande, on le mappe vers une valeur CSS (px, composante RGB, booléen, nombre...), et on injecte un bout de CSS écrit par l'utilisateur qui exploite ces variables.

Cas d'usage : performances audiovisuelles live (VJing), installations artistiques, vidéoprojection d'une page web qui réagit au set d'un musicien, détournement esthétique de sites existants.

Comment ça marche

flowchart LR
    subgraph Sources
        A[🔊 Audio système<br/>via loopback] --> C
        B[🎹 Web MIDI<br/>Ableton, contrôleur...] --> D
    end
    subgraph Moteur["Moteur WebGlitch"]
        C[Filtres par bande<br/>passe-haut / bas / bande] --> E[Mesure du volume<br/>par bande]
        E --> F[Mapping<br/>bool / int / rgb / var]
        D --> F
    end
    subgraph Page["Page web cible"]
        F --> G["Variables CSS<br/>--band-a, --band-b, ..."]
        G --> H[CSS utilisateur injecté]
        H --> I[✨ La page glitche]
    end

Loading

1. Capter — l'extension reçoit le son (entrée loopback = tout le son de l'ordi) et/ou des messages MIDI.
2. Filtrer — chaque bande applique un filtre (passe-haut, passe-bas, passe-bande) pour isoler une zone du spectre : basses, médiums, aigus...
3. Mesurer — le volume de chaque bande filtrée est suivi en continu.
4. Mapper — le volume devient une valeur exploitable : un nombre entre min et max, une composante RGB, ou un booléen (au-dessus d'un seuil / en dessous d'un plancher).
5. Injecter — les valeurs sont écrites dans des variables CSS (--band-a, --band-b, ...) sur la page, et le CSS de l'utilisateur fait le reste.

Les bandes

La bande est l'unité de base de WebGlitch. On en crée autant qu'on veut. Chaque bande = un filtre + un mapping.

Le filtre

Paramètre	Rôle	Valeurs
type	Type de filtre	highpass, lowpass, bandpass, none
cutoff	Fréquence de coupure (ou centrale pour le passe-bande)	20 Hz – 20 kHz
q	Résonance / largeur du passe-bande	0.1 – 20
depth	Intensité de la réponse : combien le signal filtré pèse dans la mesure	0 – 1

Exemples de configurations classiques :

• Kick : bandpass, cutoff 60 Hz, Q élevé → la bande ne réagit qu'à la grosse caisse.
• Voix : bandpass, cutoff 1 kHz, Q moyen.
• Hi-hats : highpass, cutoff 8 kHz.
• Énergie globale : none → volume brut du signal.

Le mapping

Paramètre	Rôle
type	Type de sortie : int (nombre), float, rgb (composante 0–255), bool (seuil), var (valeur brute 0–1)
min / max	Bornes de la valeur de sortie — le volume filtré est interpolé entre les deux
center	Valeur de repos quand il n'y a pas de signal
depth	Amplitude de la modulation autour du centre
threshold	(mode bool) seuil : la variable passe à 1 quand le volume le dépasse
floor	(mode bool) plancher : la variable passe à 1 quand le volume passe en dessous
attack / release	Lissage de la réponse (montée / descente), pour éviter le tremblement ou au contraire l'assumer

Chaque bande expose sa valeur dans une variable CSS : --band-a, --band-b, --band-c, etc. (nom personnalisable).

Le CSS utilisateur

L'utilisateur écrit librement le CSS qui sera injecté dans la page. C'est là que l'art opère — WebGlitch fournit les variables, vous fournissez l'esthétique :

/* La taille du texte suit les basses, la couleur suit trois bandes */
div {
  font-size: calc(var(--band-a) * 1px);
  color: rgb(var(--band-a), var(--band-b), var(--band-c));
}

/* Glitch : la page tremble sur le kick (bande en mode bool) */
body {
  transform: translate(
    calc(var(--kick) * 8px),
    calc(var(--kick) * -5px)
  );
  filter: hue-rotate(calc(var(--band-b) * 1deg));
}

/* Les images s'inversent quand les aigus dépassent le seuil */
img {
  filter: invert(var(--hats));
}

Astuces :

• Les variables sont des nombres sans unité — utilisez calc(var(--band-a) * 1px) pour typer.
• Les bandes bool valent 0 ou 1 : parfaites dans opacity, invert(), ou multipliées dans un calc().
• transition sur les propriétés ciblées adoucit ou stylise la réponse.

Les sources de contrôle

Audio via loopback

Une extension ne peut pas capter directement « tout le son de l'ordi » : on passe par un périphérique de loopback que l'extension ouvre comme une entrée micro (getUserMedia). Une fois configuré, tout ce qui sort de vos enceintes entre dans WebGlitch — y compris Ableton, un DJ set, Spotify...

OS	Solution	Mise en place
Linux (PipeWire)	Monitor natif	Dans le sélecteur d'entrée de WebGlitch, choisir Monitor of .... Sinon pw-loopback ou qpwgraph pour router finement.
Linux (PulseAudio)	Monitor natif	Idem : chaque sortie expose un *.monitor utilisable comme entrée.

Firefox sous Linux ne liste pas les sources Monitor of ... (limitation connue de getUserMedia). Créez une source dédiée que Firefox verra comme un vrai micro :

pactl load-module module-remap-source \
  master="$(pactl get-default-sink).monitor" \
  source_name=webglitch_loopback \
  source_properties=device.description=WebGlitch-Loopback

La source « WebGlitch-Loopback » apparaît alors dans le sélecteur (à recréer après redémarrage, ou via votre config PipeWire). Autre option : démarrer la capture puis rerouter le flux Firefox vers le monitor dans pavucontrol → Enregistrement.

Chrome n'affiche pas la demande de permission micro dans le panneau latéral : au premier « ▶ Démarrer », WebGlitch ouvre automatiquement un onglet d'autorisation. Accordez le micro, fermez l'onglet, recliquez « ▶ Démarrer » — c'est acquis pour de bon. | macOS | BlackHole | Créer un Multi-Output Device (sortie physique + BlackHole), sélectionner BlackHole comme entrée dans WebGlitch. | | Windows | VB-Cable | Router la sortie système vers CABLE Input, choisir CABLE Output comme entrée dans WebGlitch. |

L'extension liste tous les périphériques d'entrée disponibles et permet de filtrer la source — chaque bande travaille sur cette entrée commune.

Web MIDI (Ableton & co)

En complément (ou à la place) de l'audio, WebGlitch écoute les messages MIDI CC via un adaptateur Web MIDI unique (src/ui/midi.ts + src/core/midi/). Depuis Ableton Live :

1. Créer un port MIDI virtuel (Linux : natif ALSA ; macOS : IAC Driver ; Windows : loopMIDI).
2. Dans Ableton, router une piste MIDI (ou des automations d'enveloppe) vers ce port.
3. Dans WebGlitch, ouvrir le menu 🎹 de la barre de transport : l'énumération des entrées ne démarre qu'à ce moment (init paresseuse, le prompt de permission n'apparaît pas avant), choisir « Toutes les entrées » ou un port précis — branchement à chaud si un contrôleur arrive après coup.

CC learn : bouton Learn dans le même menu → les contrôles assignables (cutoff, Q, depth, attack, release, mute d'une bande, ou PERF) s'illuminent d'un halo → cliquer le contrôle visé, puis bouger le contrôleur ou le CC de la piste Ableton : l'assignation se fait toute seule, avec un badge ch1·CC74 affiché à côté du contrôle. Un même CC peut piloter plusieurs contrôles à la fois (macro). Le menu affiche aussi une table d'assignation (--kick · cutoff — ch1·CC74 ✕) pour éditer ou nettoyer d'un clic.

Source CC par bande : dans le panneau de mapping, un sélecteur Source : Audio | MIDI CC (+ bouton « CC ? » pour apprendre le CC source) fait passer la bande en pilotage direct — la valeur 0–127 du CC remplace la mesure audio et traverse le même lissage/mapping que d'habitude. Ce mode fonctionne sans capture audio : la boucle de lecture tourne dès qu'une bande CC existe. Les contrôles de filtre se grisent (un filtre biquad n'a pas de sens sur un CC). C'est le mode « CV » évoqué dans l'idée d'origine : des automations Ableton qui pilotent directement la page, avec une précision impossible à obtenir par analyse audio.

Firefox : la disponibilité de Web MIDI dans les pages d'extension reste incertaine (gating « permission par site » côté add-on). WebGlitch le détecte : si l'API est absente, le menu 🎹 se masque proprement avec un message, sans casser le reste de l'interface.

L'interface

Construite avec potard (knobs, faders, VU-mètres, XY pads style Ableton) et habillée par lunar-aurora. Depuis la v0.3, la console tient dans une barre de transport unique (façon DAW), enrichie en v0.4 des menus MIDI et presets :

[▶/■] [MIX|GRV|TML] [PERF] ───── [🎹 MIDI] [💾 presets] [🎯 cible] [◐ thème] [＋ Bande]

• Transport à gauche : ▶ démarre la capture, ■ l'arrête.
• Sélecteur de vue segmenté : MIX (Mixage), GRV (Groovebox), TML (Timeline) — la vue est globale, choisie librement.
• PERF bascule le mode Performance (mis en évidence en rouge).
• 🎹 MIDI (v0.4) : entrées disponibles, Learn, table d'assignation — voir Web MIDI.
• 💾 Presets (v0.4) : sauvegarder sous, charger, supprimer, export/import JSON — voir Les presets.
• À droite : le témoin de cible 🎯 (suivi/verrouillé/reciblage, comportement v0.2 conservé), un menu thème ◐, et le menu ＋ Bande avec des départs rapides — Kick (bandpass 60 Hz), Mids (bandpass 1 kHz), Hats (highpass 8 kHz), Énergie (lowpass large) — pour ne plus repartir d'une bande vierge à chaque fois.

Dans l'éditeur CSS, un menu {} (v0.4) insère au curseur un des 7 effets intégrés (pulse, shake, hue-spin, invert-flash, aberration chromatique, scanlines, blur-beat) ou un snippet perso : sélectionner du CSS dans l'éditeur → « ＋ snippet » → le nommer — il est ensuite disponible dans le menu et exporté avec les presets (voir Les presets).

Les trois vues

• Mixage — les bandes en colonnes verticales, table de mixage classique : nom, LED, filtre, VU. La tranche sélectionnée ouvre son mapping complet dans un panneau bas partagé (façon channel-strip), plutôt qu'un <details> par tranche.
• Groovebox — une grille de pads, un pad par bande. Le pad est le XY (cutoff/Q au doigt) et pulse visuellement avec le signal.
• Timeline — une ligne dense par bande (LED, nom, résumé du filtre, mini-knobs, VU à traînée qui garde l'historique du signal) : pensée pour scaler à beaucoup de bandes visibles d'un coup.

Les deux modes

• Édition — tous les réglages fins accessibles (filtre, mapping, panneau bas / onglets selon la vue).
• Performance — la même vue, réduite aux gestes de live : cibles tactiles élargies, réglages fins masqués, mute par bande au premier plan. Le VU continue de vivre, mais la page ne réagit plus tant qu'une bande est coupée.

Les trois thèmes

Trois peaux commutables, assignables par mode (par défaut : mat en Édition, neon en Performance) :

Thème	Traits
mat — Mat industriel	Surfaces plates, la couleur ne dit que l'information
relief — Relief discret	Ombres douces, knobs bombés, VU encastrés, LED émissives
neon — Arêtes néon	Fond quasi noir, contours luisants, signal qui irradie

La vue courante, le mode et le choix de thème par mode sont persistés (config d'interface, pas les presets — voir Les presets).

Sous le capot, deux attributs cohabitent sur <html> : data-theme="cyberpunk" (statique, le socle lunar-aurora dont hérite l'app) et data-wg-theme (dynamique, seul porteur de ces trois peaux).

Deux surfaces, inchangées depuis v0.2, toutes deux habillées par cette même barre de transport :

• Panneau latéral (sidePanel Chrome / sidebar Firefox) — le mode « tweaking » : la console reste ouverte à côté de la page pendant qu'on ajuste.
• Fenêtre détachée — le mode « live » : la console dans une fenêtre indépendante, déplaçable sur l'écran du laptop, pendant que la page glitchée part en plein écran sur le vidéoprojecteur.

Les presets

• Config d'interface persistée — vue courante, mode et thème par mode sont déjà sauvegardés localement (v0.3) : on retrouve son poste de pilotage tel qu'on l'a laissé.
• Contenu d'un preset — bandes (filtre + mapping), CSS utilisateur et assignations MIDI : tout ce qui fait une configuration de live tient dans un seul objet.
• Menu 💾 — sauvegarder sous (nom saisi en ligne), charger, supprimer ; le rechargement d'un preset est à chaud, sans couper la capture en cours.
• Rappel par site — l'état courant s'auto-sauvegarde (debounce 500 ms) sous le hostname de l'onglet ciblé, et se recharge automatiquement au démarrage ou au reciblage vers un site déjà connu.
• Export / Import JSON — partagez vos presets, versionnez-les, préparez vos sets ; un import fusionne avec l'existant, en suffixant les doublons de nom (« (2) »).
• Sidepanel et fenêtre détachée synchronisés — les deux surfaces partagent le même stockage et se mettent à jour l'une l'autre via storage.onChanged.

Architecture technique

Vue d'ensemble

flowchart TB
    subgraph UI["UI (sidepanel / fenêtre détachée)"]
        MIC[getUserMedia<br/>entrée loopback] --> WA[Web Audio<br/>BiquadFilterNode + AnalyserNode<br/>par bande]
        MIDI[Web MIDI<br/>CC in] --> CORE
        WA --> CORE[core/ — moteur de mapping<br/>TS pur, zéro API navigateur]
        POTARD[potard<br/>knobs & faders] <--> CORE
    end
    CORE -- "valeurs des bandes<br/>(runtime.sendMessage)" --> BG[background/<br/>service worker — routage]
    BG --> CS[content/<br/>content script]
    CS -- "setProperty('--band-a', v)" --> PAGE[(Page web)]
    CS -- "injection &lt;style&gt;" --> PAGE

Loading

Trois zones d'exécution, reliées par le message passing de WebExtensions :

1. UI (sidepanel ou fenêtre détachée) — c'est ici que vivent la capture audio, le graphe Web Audio, l'écoute MIDI et le moteur de mapping. Un document visible a le droit d'ouvrir getUserMedia et tourne sans être throttlé.
2. Background (service worker) — pur routeur de messages, sans état lourd (contrainte MV3 : il peut être tué à tout moment).
3. Content script — minimal par design : il reçoit des paquets de valeurs et les écrit (documentElement.style.setProperty), et gère la balise <style> du CSS utilisateur. Aucune logique métier dans la page.

Structure du dépôt

WebGlitch/
├─ src/
│  ├─ core/          # Moteur pur TypeScript — AUCUNE API navigateur
│  │                 # band.ts, mapping.ts, smoothing.ts, frequency.ts, live.ts,
│  │                 # preset.ts / snippets.ts (sérialisation JSON), starters.ts
│  │  └─ midi/       # assignments.ts, learn.ts, scale.ts — CC learn et mise à l'échelle, TS pur
│  │                 # → 100 % testable sous Vitest, candidat à extraction en lib
│  ├─ audio/         # Graphe Web Audio : source → filtres biquad → analyseurs
│  ├─ ui/            # Console : composants potard, thème lunar-aurora, éditeur CSS,
│  │                 # midi.ts (adaptateur Web MIDI), presets.ts (menu 💾)
│  ├─ content/       # Content script : pose des variables + CSS utilisateur
│  ├─ background/    # Service worker : routage des messages UI ↔ contenu
│  └─ platform/      # Adaptateur browser.ts (Chrome/Firefox) écrit maison
├─ tests/            # Tests Vitest (TDD)
├─ docs/             # Documentation, specs de design
├─ manifest.chrome.json   # Manifest V3 Chrome
├─ manifest.firefox.json  # Manifest V3 Firefox
└─ Idea.md           # L'idée d'origine, conservée pour l'histoire

Règle d'or de core/ : aucun import d'API navigateur (ni chrome.*, ni Web Audio, ni DOM). Le moteur reçoit des nombres, rend des nombres. C'est ce qui le rend testable en TDD sans navigateur, et extractible plus tard en bibliothèque autonome (voir Roadmap).

Flux de données

1. L'UI capture l'audio → le graphe Web Audio produit, par bande, un niveau (0–1) mesuré à requestAnimationFrame.
2. Le MIDI arrive en événements midimessage, normalisés en 0–1.
3. core/ applique le mapping de chaque bande (interpolation min/max, seuils bool, lissage attack/release).
4. Les valeurs qui ont changé (et seulement elles) partent en un seul message groupé par frame vers le content script.
5. Le content script écrit les variables CSS. Le navigateur fait son travail : le CSS utilisateur réagit.

Performance

• Filtres natifs : BiquadFilterNode et AnalyserNode sont implémentés en code natif par le navigateur — aucun DSP JavaScript dans le chemin chaud.
• Un message par frame maximum, valeurs groupées et dédupliquées — pas de spam du message passing.
• Variables CSS ciblées : modifier une custom property ne recalcule que les règles qui l'utilisent.
• Mesuré, pas supposé : au banc d'essai (pire cas 26 bandes — RMS 1024 échantillons, lissage, mapping, quantification, traînées), le moteur JS coûte ~0,5 ms par frame, soit ~3 % du budget 60 Hz. Le vrai coût d'un glitch est ailleurs : le pipeline de rendu de la page cible (préférer transform/opacity, compositeur seul, aux filter/text-shadow globaux qui repeignent tout).
• Tachymètre intégré : la barre de transport affiche en continu le coût réel du moteur par frame, le débit de messages et le framerate de la page cible (0.42 ms · 12 msg/s · page 58 fps).
• Cadence adaptative : la page cible mesure son propre framerate et le remonte à la console ; si le repaint sature (CSS lourd), l'envoi des variables est automatiquement décimé (÷2 … ÷6, avec hystérésis) — moins de changements = moins de repaints — puis revient à pleine cadence dès que la page respire. Le lissage, lui, reste calculé à 60 Hz : l'enveloppe ne triche jamais.
• WebAssembly : envisagé dès l'origine du projet, volontairement repoussé en phase 2. Il ne deviendra pertinent que pour du DSP custom (détection d'attaques, suivi de pitch, FFT exotique) que les nœuds natifs ne couvrent pas — pas pour un chemin chaud qui consomme 3 % du budget.

Philosophie : zéro dépendance externe

WebGlitch ne dépend d'aucune bibliothèque tierce en production. Les deux seules dépendances runtime sont des projets maison, maîtrisés de bout en bout et co-évolutifs :

Dépendance	Rôle	Pourquoi
potard	Contrôles audio (Web Components, canvas, zéro dépendance)	Knobs, faders, crossfaders, VU-mètres, XY pads — exactement l'UI d'une console
lunar-aurora	Framework CSS (OKLCH, @property, @layer, thèmes)	Habillage de l'interface, thèmes sombres adaptés au live

Côté outillage (dev uniquement) : typescript, vite, vitest — la même chaîne que potard. Pas de framework d'extension (WXT...), pas de webextension-polyfill : l'adaptateur cross-browser (src/platform/browser.ts) est écrit maison (~50 lignes), parce qu'un code qu'on maîtrise vaut mieux qu'une dépendance qu'on subit.

Compatibilité navigateurs

	Chrome / Chromium	Firefox
Manifest	V3 (manifest.chrome.json)	V3 (manifest.firefox.json)
Panneau latéral	chrome.sidePanel	sidebar_action
Fenêtre détachée	chrome.windows.create({type:"popup"})	idem
Entrée audio	getUserMedia ✅	getUserMedia ✅
Web MIDI	✅	⚠️ selon gating (permission par site) — dégradation propre sinon

Les différences d'API sont absorbées par src/platform/, seul endroit du code autorisé à connaître le navigateur qui l'exécute.

Développement

git clone git@github.com:yrbane/WebGlitch.git
cd WebGlitch
pnpm install

pnpm test        # Vitest — le projet est développé en TDD
pnpm dev         # build rapide (sans vérification des types) ; recharger l'extension à la main
pnpm build       # build de production (Chrome + Firefox)

Chargement de l'extension en dev :

• Chrome : chrome://extensions → mode développeur → « Charger l'extension non empaquetée » → dist/chrome/
• Firefox : about:debugging → « Ce Firefox » → « Charger un module complémentaire temporaire » → dist/firefox/manifest.json

Roadmap

v0.1 — Le cœur (en cours)

• Moteur core/ : bande, filtre, mapping, lissage — en TDD
• Graphe Web Audio : entrée loopback → filtres → mesures
• Content script : injection des variables et du CSS utilisateur
• UI sidepanel minimale : une bande, un knob, un textarea CSS

v0.2 — La console

• Multi-bandes dynamique (ajout/suppression/duplication)
• Tranches de console complètes avec potard (VU-mètres, XY pad filtre)
• Fenêtre détachée (mode vidéoprojecteur)
• Thème lunar-aurora

v0.3 — Refonte UX (livrée)

• Barre de transport unique (transport, sélecteur de vue, mode Performance, cible, thème, ＋ Bande avec départs rapides)
• Trois vues commutables : Mixage (panneau de mapping bas partagé), Groovebox (pads-XY pulsés par le signal), Timeline (lignes denses à VU à traînée)
• Deux modes Édition/Performance, avec mute par bande et cibles élargies en Performance
• Trois thèmes (mat / relief / neon) assignables par mode, config d'interface persistée

v0.4 — Le live avancé (livrée)

• Entrée Web MIDI + apprentissage CC (« MIDI learn »), table d'assignation, source CC par bande (mode CV)
• Presets nommés, auto-rappel par site, export/import JSON
• Bibliothèque de snippets CSS de départ (glitch pack) + snippets perso

Phase 2 — L'écosystème

• Extraction de core/ en bibliothèque autonome (yrbane/…) : moteur audio→valeurs réutilisable hors extension (sites, installations, Node)
• Pont Ableton : patch Max for Live envoyant OSC/WebSocket vers l'extension (automations « CV » haute précision)
• WebAssembly pour DSP custom (détection d'attaques, suivi de pitch) — si les mesures le justifient
• Publication des stores (Chrome Web Store, AMO)

Conventions du projet

• TDD : le test d'abord, toujours. core/ vise une couverture complète.
• SOLID / DRY / KISS : des unités petites, une responsabilité chacune, des interfaces claires entre core/, audio/, ui/ et content/.
• Langue : code et identifiants en anglais, commentaires et messages de commit en français.
• Zéro dépendance : toute nouvelle dépendance runtime externe doit être refusée par défaut ; on écrit, ou on fait évoluer un repo maison.

Licence

MIT — comme potard et le reste de l'écosystème.

---

WebGlitch fait partie de l'écosystème yrbane : potard · lunar-aurora