webear and web perception

webear

Dale a tu IA sentidos reales: escucha, ve y siente cualquier aplicación web.

Un servidor MCP + SDK de navegador que brinda a los asistentes de codificación con IA acceso sensorial directo a una aplicación web en vivo. Audio, visuales, rendimiento, red, seguridad y consola: capturados desde el navegador, analizados en tiempo real y entregados vía MCP.

"El ritmo suena turbio" → tu IA captura 3 segundos, mide el centroide espectral a 580 Hz con un 45 % de energía por debajo de 250 Hz y te dice exactamente por qué.

---

---

Qué Hace

Herramienta	Descripción
capture_audio	Graba un clip corto (500 ms–30 s) de lo que tu aplicación web está emitiendo ahora mismo
analyze_audio	Análisis de señal: RMS, pico en dB, recorte, centroide espectral, bandas de frecuencia, BPM, fluctuación de sincronización
describe_audio	Descripción IA en lenguaje natural — "el bombo es retumbante con una acumulación grave intensa alrededor de 80 Hz"
diff_audio	Compara dos capturas y señala qué cambió: sonoridad, tono, sincronización, recorte

Cómo Funciona

Browser (Web Audio API)
    ↓ MediaRecorder taps the AudioContext output node
    ↓ Uploads WebM blob via HTTP POST
Express Middleware (your dev server)
    ↓ Stores captures in memory, dispatches commands via SSE
MCP Server (stdio — runs inside your IDE)
    ↓ Retrieves captures, sends to CodedSwitch analysis API
AI Coding Assistant
    → "Your bass band is 42% of the mix (high), spectral centroid
       is 580 Hz (muddy), and timing jitter is 23ms — the scheduler
       is drifting under load."

La diferencia clave con cualquier otro MCP de audio: este accede directamente al grafo de Web Audio, evitando la acústica de la sala, el hardware del micrófono y la necesidad de exportar archivos.

---

Inicio Rápido

1. Instalación

npm install webear

2. Añade el middleware de Express a tu servidor de desarrollo

import express from 'express'
import { webearMiddleware } from 'webear/middleware'

const app = express()
app.use(express.json())

// Mount the audio debug bridge (automatically disabled in production)
app.use('/api/webear', webearMiddleware())

app.listen(5000)

3. Añade el fragmento de cliente a tu aplicación web

Opción A: detección automática de todo (Tone.js o Web Audio puro)

import WebEar from 'webear/client'
WebEar.init()

Opción B: AudioContext explícito

const ctx = new AudioContext()
const masterGain = ctx.createGain()
masterGain.connect(ctx.destination)

WebEar.init({ audioContext: ctx, outputNode: masterGain })

Opción C: proyecto Tone.js

import * as Tone from 'tone'
WebEar.init({ toneJs: true })

Opción D: juego Three.js WebGL

import * as THREE from 'three'
const listener = new THREE.AudioListener()
camera.add(listener)
WebEar.init({ tapNode: listener.getInput() })

Opción E: etiqueta script simple

<script src="node_modules/webear/client-snippet.js"></script>
<script>WebEar.init()</script>

4. Configura tu IDE

Claude Code (.mcp.json en la raíz del proyecto):

{
  "mcpServers": {
    "webear": {
      "command": "npx",
      "args": ["webear"],
      "env": {
        "WEBEAR_BASE_URL": "http://localhost:5000",
        "CODEDSWITCH_API_KEY": "your-key-here"
      }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "webear": {
      "command": "npx",
      "args": ["webear"],
      "env": {
        "WEBEAR_BASE_URL": "http://localhost:5000",
        "CODEDSWITCH_API_KEY": "your-key-here"
      }
    }
  }
}

Windsurf (mcp_config.json):

{
  "webear": {
    "command": "npx",
    "args": ["webear"],
    "disabled": false,
    "env": {
      "WEBEAR_BASE_URL": "http://localhost:5000",
      "CODEDSWITCH_API_KEY": "your-key-here"
    }
  }
}

5. Obtén una clave API: opcional y no necesaria para empezar

analyze_audio funciona sin clave y sin cuenta. Si ffmpeg está en tu PATH, decodifica y analiza la captura en tu máquina y devuelve un informe básico: duración, sonoridad, nivel de pico y si el audio se está recortando. No se sube nada. Prueba la herramienta antes de registrarte en nada.

Una clave desbloquea las partes que necesitan más que aritmética:

	Sin clave	Con clave
capture_audio	✓	✓
analyze_audio	Básico: duración, sonoridad, pico, recorte (local)	Completo: centroide espectral, energía de banda, factor de cresta, BPM, fluctuación de sincronización
describe_audio — cómo SUENA	—	✓
mix_coach — medido + escuchado	—	✓
diff_audio — antes/después	—	✓

Para obtener una:

1. Crea una cuenta gratuita en codedswitch.com.
2. Ve a codedswitch.com/developer (también en el menú de la cuenta como Developer API).
3. Haz clic en Generate API Key: ese valor es tu CODEDSWITCH_API_KEY. Las claves comienzan con wbr_.

Plan gratuito: 50 análisis/día. No se requiere tarjeta de crédito.

6. Inicia tu servidor de desarrollo, abre tu aplicación, reproduce audio y luego pregúntale a tu IA:

"Captura 3 segundos y dime por qué el bajo suena turbio."

"Compara el audio antes y después de mi último commit."

"¿Hay algún recorte en el rango de alta frecuencia?"

---

Ejemplo de Salida

analyze_audio

── Audio Analysis Report ──────────────────────────────
Duration:          3.02s

── Loudness ─────────────────────────────────────────
RMS:               -12.4 dBFS
Peak:              -1.2 dBFS
Dynamic range:     11.2 dB
Crest factor:      3.63
Clipping:          none

── Tone ──────────────────────────────────────────────
Spectral centroid: 2847 Hz
DC offset:         0.00012 (ok)

── Frequency Bands ───────────────────────────────────
Sub  (20-80 Hz):   8.2%
Bass (80-250 Hz):  22.1%
Mid  (250-2k Hz):  38.4%
Hi-mid (2-6k Hz):  21.8%
High (6k+ Hz):     9.5%

── Rhythm ────────────────────────────────────────────
Estimated BPM:     92
Onset count:       12
Timing jitter:     4.2 ms std dev

── Summary ───────────────────────────────────────────
Loudness: -12.4 dBFS RMS, peak -1.2 dBFS. Tone: balanced (centroid 2847 Hz).
Band mix — sub: 8% | bass: 22% | mid: 38% | hi-mid: 22% | high: 10%.
Rhythm: estimated 92 BPM, 12 onsets detected. Timing: very tight (< 5 ms jitter).

diff_audio

── Audio Diff: a1b2c3d4… → e5f6g7h8… ──

── Loudness ──────────────────────────────────────────
  RMS: -14.2 dBFS → -12.4 dBFS  (+1.8 dBFS)
⚠ Peak: -3.1 dBFS → -0.2 dBFS  (+2.9 dBFS)
⚠ CLIPPING INTRODUCED — gain staging regression

── Tone ──────────────────────────────────────────────
⚠ Spectral centroid: 2847.0 Hz → 1920.0 Hz  (-927.0 Hz)

── Interpretation ────────────────────────────────────
A gain bug was introduced that causes clipping.
Tonal character changed noticeably — EQ or filter behaviour may have shifted.

---

Configuración

Variables de Entorno

Variable	Valor predeterminado	Descripción
WEBEAR_BASE_URL	http://localhost:4000	URL de tu servidor de desarrollo (donde está montado el middleware)
CODEDSWITCH_API_KEY	—	Clave API de codedswitch.com: necesaria para analyze_audio y describe_audio
MCP_API_URL	https://www.codedswitch.com	Sobrescribe la base de la API de análisis (avanzado / autoalojado)

Opciones del Middleware

webearMiddleware({
  maxCaptures: 50,       // Max captures in memory (default: 50)
  maxAgeMins: 10,        // Auto-evict after N minutes (default: 10)
  maxUploadBytes: 50e6,  // Max upload size (default: 50MB)
  devOnly: true,         // Disable in production (default: true)
})

Opciones del Cliente

WebEar.init({
  audioContext: myCtx,             // Your AudioContext instance
  outputNode: myGainNode,          // The node to tap (defaults to destination)
  toneJs: true,                    // Auto-detect Tone.js context
  bridgeBase: '/api/webear',  // Override API path
  devOnly: true,                   // Only init outside of production (default: true)
})

---

Requisitos

• Node.js >= 18
• Un navegador que admita MediaRecorder (Chrome, Firefox, Edge, Safari 14+)
• Una CODEDSWITCH_API_KEY para análisis (gratuita en codedswitch.com)

---

¿Para Quién Es?

• Desarrolladores de Web Audio / Tone.js — depura ritmos, sintetizadores, efectos y mezclas sin salir de tu IDE
• Desarrolladores de audio para juegos — verifica efectos de sonido, audio espacial y mezclas en tiempo real
• Creadores de aplicaciones musicales — detecta regresiones entre cambios de código con diff_audio
• Aplicaciones de podcast / streaming — valida calidad de audio, niveles y codificación
• Cualquiera cuya aplicación produzca sonido — si tiene un grafo de Web Audio, tu IA ahora puede escucharlo

---

¿Por Qué No Usar Simplemente el Micrófono?

Los MCP de micrófono capturan el sonido de la sala: el ruido de tu ventilador, los crujidos de la silla y la reverberación de la habitación están todos en la grabación. webear accede a la API de Web Audio antes de que llegue al DAC, brindándote una señal digital limpia sin artefactos de la sala.

---

Web Perception: Suite Completa de Sensores

WebEar comenzó solo con audio. Web Perception lo expande a 6 sentidos:

Sensor	Lo que percibe
WebEar	Audio: calidad de mezcla, ritmo, instrumentos, recorte
WebEye	Visual: canvas, diseño de interfaz, animaciones, capturas de pantalla
WebSense	Rendimiento: tasa de fotogramas, memoria, latencia de audio
WebNerve	Red: latencias de API, calidad de conexión, almacenamiento
WebShield	Seguridad: cookies, exposición de almacenamiento, CSP, framing
WebLog	Consola: registros, advertencias, errores, excepciones no capturadas

Instala el SDK completo del navegador

import { WebPerception } from 'webear/perception'

WebPerception.init({
  apiKey: 'wbr_YOUR_API_KEY',
  relayUrl: 'https://www.codedswitch.com',
  sensors: ['ear', 'eye', 'sense', 'nerve', 'shield', 'log'],
})

O usa un solo sensor:

import { WebEar } from 'webear/perception'

WebEar.init({
  apiKey: 'wbr_YOUR_API_KEY',
  ear: { audioContext: myCtx, audioNode: masterGain },
})

Conéctate vía MCP (relé alojado: no se requiere servidor local)

{
  "mcpServers": {
    "webear": {
      "url": "https://www.codedswitch.com/api/webear/mcp/sse",
      "headers": {
        "Authorization": "Bearer wbr_YOUR_API_KEY"
      }
    }
  }
}

Herramientas MCP Disponibles

Sensor	Herramienta	Créditos	Descripción
Ear	capture_audio	Gratis	Graba el audio en vivo de la pestaña
Ear	analyze_audio	1	BPM, sonoridad, bandas de frecuencia, recorte, rango dinámico
Ear	describe_audio	2	Descripción IA en lenguaje natural: instrumentos, género, ambiente, notas de mezcla
Ear	diff_audio	1	Compara dos capturas: diferencias de sonoridad, tono y sincronización
Ear	groove_score	2	Alineación de rejilla, factor de swing, consistencia (0–100 %)
Ear	capture_and_analyze	1	Captura + análisis en una sola llamada
Ear	mix_coach	3	Retroalimentación estructurada de mezcla
Eye	capture_video	Gratis	Graba canvas/video de la pestaña
Eye	describe_video	2	Descripción visual IA: diseño, colores, errores
Eye	diff_visuals	2	Compara dos capturas visuales
Sense	capture_telemetry	Gratis	FPS, memoria, cambios de diseño, latencia de audio
Sense	analyze_telemetry	1	Caídas de fotogramas, presión de memoria, underruns de audio
Nerve	capture_nerve	Gratis	Tiempos de API, calidad de conexión, tamaño de almacenamiento
Nerve	analyze_nerve	1	APIs lentas, calidad de conexión, almacenamiento inflado
Shield	capture_shield	Gratis	Cookies, CSP, exposición de almacenamiento, framing
Shield	analyze_shield	1	Problemas de CORS, cookies no HttpOnly, CSP ausente
Log	capture_logs	Gratis	Salida de consola + excepciones no capturadas
Log	analyze_logs	1	Patrones de error, trazas de pila, advertencias repetidas

Obtén una Clave API

1. Crea una cuenta gratuita en codedswitch.com.
2. Abre codedswitch.com/developer — también enlazado como Developer API en el menú de la cuenta.
3. Haz clic en Generate API Key y cópiala. Las claves comienzan con wbr_.

Plan gratuito: 50 análisis/día, sin tarjeta de crédito.

---

Registro de Cambios

2.0.1

• Se corrigió la ruta de inicio para las claves API. La instrucción anterior ("Settings → WebEar") era incorrecta: no existe una sección WebEar en Settings. Las claves están en codedswitch.com/developer (enlazado como Developer API en el menú de la cuenta). Tanto la sección de Inicio Rápido como la de Web Perception ahora apuntan al lugar correcto.
• El error de consola del SDK de "clave API faltante" ahora enlaza directamente a la página de claves.

Contribuciones

Consulta CONTRIBUTING.md.

Licencia

MIT: consulta LICENSE

Autor

Creado por @asume21 — CodedSwitch