webear and web perception

Dê à sua IA sentidos reais (áudio, visuais, desempenho, rede, segurança e logs de console) em tempo real a partir de qualquer aplicação web em execução.

GitHub

Experimente este MCPPatrocinado

Documentação

webear

Dê à sua IA sentidos reais — ouça, veja e sinta qualquer aplicativo web.

Um servidor MCP + SDK de navegador que dá aos assistentes de codificação com IA acesso sensorial direto a um aplicativo web em execução. Áudio, visuais, desempenho, rede, segurança e console — capturados do navegador, analisados em tempo real, entregues via MCP.

"A batida soa embaçada" → sua IA captura 3 segundos, mede o centroide espectral em 580 Hz com 45% de energia abaixo de 250 Hz e diz exatamente o porquê.

AI Web Perception Demo

O Que Ele Faz

Ferramenta	Descrição
`capture_audio`	Grave um clipe curto (500ms–30s) do que seu aplicativo web está emitindo agora
`analyze_audio`	Análise de sinal: RMS, pico em dB, clipping, centroide espectral, bandas de frequência, BPM, jitter de tempo
`describe_audio`	Descrição em linguagem natural pela IA — "o bumbo está encorpado com forte acúmulo de subgraves em torno de 80 Hz"
`diff_audio`	Compare duas capturas e aponte o que mudou — volume, tom, tempo, clipping

Como 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."

A diferença fundamental de todos os outros MCPs de áudio: este acessa o grafo Web Audio diretamente, ignorando acústica da sala, hardware de microfone e a necessidade de exportar arquivos.

Início Rápido

1. Instalação

npm install webear

2. Adicione o middleware Express ao seu servidor de desenvolvimento

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. Adicione o trecho de código do cliente ao seu aplicativo web

Opção A — detecção automática de tudo (Tone.js ou Web Audio puro)

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

Opção B — AudioContext explícito

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

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

Opção C — projeto Tone.js

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

Opção D — jogo Three.js WebGL

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

Opção E — tag script simples

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

4. Configure sua IDE

Claude Code (.mcp.json na raiz do projeto):

{
  "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. Obtenha uma chave de API — opcional, e não é necessária para começar

analyze_audio funciona sem chave e sem conta. Se ffmpeg estiver no seu PATH, ele decodifica e analisa a captura na sua máquina e retorna um relatório básico: duração, volume, nível de pico e se o áudio está com clipping. Nada é enviado. Experimente a ferramenta antes de se cadastrar em qualquer coisa.

Uma chave desbloqueia as partes que exigem mais do que aritmética:

	Sem chave	Com chave
`capture_audio`	✓	✓
`analyze_audio`	Básico — duração, volume, pico, clipping (local)	Completo — centroide espectral, energia de banda, fator de crista, BPM, jitter de tempo
`describe_audio` — como SOA	—	✓
`mix_coach` — medido + ouvido	—	✓
`diff_audio` — antes/depois	—	✓

Para obter uma:

Crie uma conta gratuita em codedswitch.com.
Acesse codedswitch.com/developer (também no menu da conta como Developer API).
Clique em Generate API Key — esse valor é sua CODEDSWITCH_API_KEY. As chaves começam com wbr_.

Plano gratuito: 50 análises/dia. Não é necessário cartão de crédito.

6. Inicie seu servidor de desenvolvimento, abra seu aplicativo, reproduza áudio e pergunte à sua IA:

"Capture 3 segundos e me diga por que o baixo soa embaçado."

"Compare o áudio antes e depois do meu último commit."

"Há algum clipping na faixa de alta frequência?"

Exemplo de Saída

`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.

Configuração

Variáveis de Ambiente

Variável	Padrão	Descrição
`WEBEAR_BASE_URL`	`http://localhost:4000`	URL do seu servidor de desenvolvimento (onde o middleware está montado)
`CODEDSWITCH_API_KEY`	—	Chave de API de codedswitch.com — necessária para `analyze_audio` e `describe_audio`
`MCP_API_URL`	`https://www.codedswitch.com`	Substituir a base da API de análise (avançado / auto-hospedado)

Opções de 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)
})

Opções do 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
Um navegador que suporte MediaRecorder (Chrome, Firefox, Edge, Safari 14+)
Uma CODEDSWITCH_API_KEY para análise (gratuita em codedswitch.com)

Para Quem É Isso?

Desenvolvedores de Web Audio / Tone.js — depure batidas, sintetizadores, efeitos e mixagem sem sair da sua IDE
Desenvolvedores de áudio de jogos — verifique efeitos sonoros, áudio espacial e mixagem em tempo real
Criadores de aplicativos de música — detecte regressões entre mudanças de código com diff_audio
Aplicativos de podcast / streaming — valide qualidade de áudio, níveis e codificação
Qualquer pessoa cujo aplicativo produza som — se ele tem um grafo Web Audio, sua IA agora pode ouvi-lo

Por Que Não Usar Apenas o Microfone?

MCPs de microfone capturam o som da sala — o ruído do ventilador, rangidos da cadeira e a reverberação do ambiente estão todos na gravação. webear acessa a Web Audio API antes de chegar ao DAC, fornecendo um sinal digital limpo, sem artefatos da sala.

Web Perception — Conjunto Completo de Sensores

O WebEar começou apenas com áudio. Web Perception o expande para 6 sentidos:

Sensor	O que percebe
WebEar	Áudio — qualidade da mixagem, ritmo, instrumentos, clipping
WebEye	Visual — canvas, layout da interface, animações, capturas de tela
WebSense	Desempenho — taxa de quadros, memória, latência de áudio
WebNerve	Rede — latências de API, qualidade da conexão, armazenamento
WebShield	Segurança — cookies, exposição de armazenamento, CSP, framing
WebLog	Console — logs, avisos, erros, exceções não capturadas

Instale o SDK completo do 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'],
})

Ou use um único sensor:

import { WebEar } from 'webear/perception'

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

Conecte via MCP (relay hospedado — sem necessidade de servidor local)

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

Ferramentas MCP Disponíveis

Sensor	Ferramenta	Créditos	Descrição
Ear	`capture_audio`	Grátis	Grave áudio ao vivo da aba
Ear	`analyze_audio`	1	BPM, volume, bandas de frequência, clipping, faixa dinâmica
Ear	`describe_audio`	2	Descrição em linguagem natural pela IA — instrumentos, gênero, clima, notas de mixagem
Ear	`diff_audio`	1	Compare duas capturas — deltas de volume, tom, tempo
Ear	`groove_score`	2	Alinhamento de grade, fator de swing, consistência (0–100%)
Ear	`capture_and_analyze`	1	Captura + análise em uma única chamada
Ear	`mix_coach`	3	Feedback estruturado de mixagem
Eye	`capture_video`	Grátis	Grave canvas/vídeo da aba
Eye	`describe_video`	2	Descrição visual pela IA — layout, cores, bugs
Eye	`diff_visuals`	2	Compare duas capturas visuais
Sense	`capture_telemetry`	Grátis	FPS, memória, mudanças de layout, latência de áudio
Sense	`analyze_telemetry`	1	Quedas de quadros, pressão de memória, underruns de áudio
Nerve	`capture_nerve`	Grátis	Tempos de API, qualidade da conexão, tamanho do armazenamento
Nerve	`analyze_nerve`	1	APIs lentas, qualidade da conexão, inchaço do armazenamento
Shield	`capture_shield`	Grátis	Cookies, CSP, exposição de armazenamento, framing
Shield	`analyze_shield`	1	Problemas de CORS, cookies não-HttpOnly, CSP ausente
Log	`capture_logs`	Grátis	Saída do console + exceções não capturadas
Log	`analyze_logs`	1	Padrões de erro, stack traces, avisos repetidos

Obtenha uma Chave de API

Crie uma conta gratuita em codedswitch.com.
Abra codedswitch.com/developer — também vinculado como Developer API no menu da conta.
Clique em Generate API Key e copie-a. As chaves começam com wbr_.

Plano gratuito: 50 análises/dia, sem necessidade de cartão de crédito.

Registro de Alterações

2.0.1

Corrigido o caminho de início para chaves de API. A instrução anterior ("Settings → WebEar") estava errada — não existe uma seção WebEar em Settings. As chaves ficam em codedswitch.com/developer (vinculado como Developer API no menu da conta). Tanto o Início Rápido quanto as seções de Web Perception agora apontam para o lugar correto.
O erro de console "missing API key" do SDK agora vincula diretamente à página de chaves.

Contribuição

Veja CONTRIBUTING.md.

Licença

MIT — veja LICENSE

Autor

Criado por @asume21 — CodedSwitch