{
"markdown": "# webear\n\n[](https://www.npmjs.com/package/webear)\n[](https://www.npmjs.com/package/webear)\n[](./LICENSE)\n[](https://modelcontextprotocol.io)\n\n**Give your AI real senses — hear, see, and feel any web app.**\n\nAn [MCP](https://modelcontextprotocol.io) server + browser SDK that gives AI coding assistants **direct sensory access** to a live web application. Audio, visuals, performance, network, security, and console — captured from the browser, analyzed in real time, delivered via MCP.\n\n> *\"The beat sounds muddy\"* → your AI captures 3 seconds, measures the spectral centroid at 580 Hz with 45% energy below 250 Hz, and tells you exactly why.\n\n---\n\n\n\n---\n\n## What It Does\n\n| Tool | Description |\n|------|-------------|\n| `capture_audio` | Record a short clip (500ms–30s) of what your web app is outputting right now |\n| `analyze_audio` | Signal analysis: RMS, peak dB, clipping, spectral centroid, frequency bands, BPM, timing jitter |\n| `describe_audio` | Plain-English AI description — *\"the kick is boomy with heavy sub buildup around 80 Hz\"* |\n| `diff_audio` | Compare two captures and flag what changed — loudness, tone, timing, clipping |\n\n## How It Works\n\n```\nBrowser (Web Audio API)\n ↓ MediaRecorder taps the AudioContext output node\n ↓ Uploads WebM blob via HTTP POST\nExpress Middleware (your dev server)\n ↓ Stores captures in memory, dispatches commands via SSE\nMCP Server (stdio — runs inside your IDE)\n ↓ Retrieves captures, sends to CodedSwitch analysis API\nAI Coding Assistant\n → \"Your bass band is 42% of the mix (high), spectral centroid\n is 580 Hz (muddy), and timing jitter is 23ms — the scheduler\n is drifting under load.\"\n```\n\nThe key difference from every other audio MCP: **this taps the Web Audio graph directly**, bypassing room acoustics, microphone hardware, and the need to export files.\n\n---\n\n## Quick Start\n\n### 1. Install\n\n```bash\nnpm install webear\n```\n\n### 2. Add the Express middleware to your dev server\n\n```js\nimport express from 'express'\nimport { webearMiddleware } from 'webear/middleware'\n\nconst app = express()\napp.use(express.json())\n\n// Mount the audio debug bridge (automatically disabled in production)\napp.use('/api/webear', webearMiddleware())\n\napp.listen(5000)\n```\n\n### 3. Add the client snippet to your web app\n\n**Option A — auto-detect everything (Tone.js or raw Web Audio)**\n```js\nimport WebEar from 'webear/client'\nWebEar.init()\n```\n\n**Option B — explicit AudioContext**\n```js\nconst ctx = new AudioContext()\nconst masterGain = ctx.createGain()\nmasterGain.connect(ctx.destination)\n\nWebEar.init({ audioContext: ctx, outputNode: masterGain })\n```\n\n**Option C — Tone.js project**\n```js\nimport * as Tone from 'tone'\nWebEar.init({ toneJs: true })\n```\n\n**Option D — Three.js WebGL Game**\n```js\nimport * as THREE from 'three'\nconst listener = new THREE.AudioListener()\ncamera.add(listener)\nWebEar.init({ tapNode: listener.getInput() })\n```\n\n**Option E — plain script tag**\n```html\n\n\n```\n\n### 4. Configure your IDE\n\n**Claude Code** (`.mcp.json` in project root):\n```json\n{\n \"mcpServers\": {\n \"webear\": {\n \"command\": \"npx\",\n \"args\": [\"webear\"],\n \"env\": {\n \"WEBEAR_BASE_URL\": \"http://localhost:5000\",\n \"CODEDSWITCH_API_KEY\": \"your-key-here\"\n }\n }\n }\n}\n```\n\n**Cursor** (`.cursor/mcp.json`):\n```json\n{\n \"mcpServers\": {\n \"webear\": {\n \"command\": \"npx\",\n \"args\": [\"webear\"],\n \"env\": {\n \"WEBEAR_BASE_URL\": \"http://localhost:5000\",\n \"CODEDSWITCH_API_KEY\": \"your-key-here\"\n }\n }\n }\n}\n```\n\n**Windsurf** (`mcp_config.json`):\n```json\n{\n \"webear\": {\n \"command\": \"npx\",\n \"args\": [\"webear\"],\n \"disabled\": false,\n \"env\": {\n \"WEBEAR_BASE_URL\": \"http://localhost:5000\",\n \"CODEDSWITCH_API_KEY\": \"your-key-here\"\n }\n }\n}\n```\n\n### 5. Get an API key — optional, and not to start\n\n**`analyze_audio` works with no key and no account.** If `ffmpeg` is on your PATH,\nit decodes and analyzes the capture **on your machine** and returns a basic report:\nduration, loudness, peak level and whether the audio is clipping. Nothing is\nuploaded. Try the tool before you sign up for anything.\n\nA key unlocks the parts that need more than arithmetic:\n\n| | No key | With key |\n|---|---|---|\n| `capture_audio` | ✓ | ✓ |\n| `analyze_audio` | Basic — duration, loudness, peak, clipping (local) | Full — spectral centroid, band energy, crest factor, BPM, timing jitter |\n| `describe_audio` — what it SOUNDS like | — | ✓ |\n| `mix_coach` — measured + heard | — | ✓ |\n| `diff_audio` — before/after | — | ✓ |\n\nTo get one:\n\n1. Create a free account at **[codedswitch.com](https://www.codedswitch.com)**.\n2. Go to **[codedswitch.com/developer](https://www.codedswitch.com/developer)** (also in the account menu as **Developer API**).\n3. Click **Generate API Key** — that value is your `CODEDSWITCH_API_KEY`. Keys start with `wbr_`.\n\nFree tier: 50 analyses/day. No credit card required.\n\n### 6. Start your dev server, open your app, play audio, then ask your AI:\n\n> \"Capture 3 seconds and tell me why the bass sounds muddy.\"\n\n> \"Compare the audio before and after my last commit.\"\n\n> \"Is there any clipping in the high-frequency range?\"\n\n---\n\n## Example Output\n\n### `analyze_audio`\n\n```\n── Audio Analysis Report ──────────────────────────────\nDuration: 3.02s\n\n── Loudness ─────────────────────────────────────────\nRMS: -12.4 dBFS\nPeak: -1.2 dBFS\nDynamic range: 11.2 dB\nCrest factor: 3.63\nClipping: none\n\n── Tone ──────────────────────────────────────────────\nSpectral centroid: 2847 Hz\nDC offset: 0.00012 (ok)\n\n── Frequency Bands ───────────────────────────────────\nSub (20-80 Hz): 8.2%\nBass (80-250 Hz): 22.1%\nMid (250-2k Hz): 38.4%\nHi-mid (2-6k Hz): 21.8%\nHigh (6k+ Hz): 9.5%\n\n── Rhythm ────────────────────────────────────────────\nEstimated BPM: 92\nOnset count: 12\nTiming jitter: 4.2 ms std dev\n\n── Summary ───────────────────────────────────────────\nLoudness: -12.4 dBFS RMS, peak -1.2 dBFS. Tone: balanced (centroid 2847 Hz).\nBand mix — sub: 8% | bass: 22% | mid: 38% | hi-mid: 22% | high: 10%.\nRhythm: estimated 92 BPM, 12 onsets detected. Timing: very tight (< 5 ms jitter).\n```\n\n### `diff_audio`\n\n```\n── Audio Diff: a1b2c3d4… → e5f6g7h8… ──\n\n── Loudness ──────────────────────────────────────────\n RMS: -14.2 dBFS → -12.4 dBFS (+1.8 dBFS)\n⚠ Peak: -3.1 dBFS → -0.2 dBFS (+2.9 dBFS)\n⚠ CLIPPING INTRODUCED — gain staging regression\n\n── Tone ──────────────────────────────────────────────\n⚠ Spectral centroid: 2847.0 Hz → 1920.0 Hz (-927.0 Hz)\n\n── Interpretation ────────────────────────────────────\nA gain bug was introduced that causes clipping.\nTonal character changed noticeably — EQ or filter behaviour may have shifted.\n```\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `WEBEAR_BASE_URL` | `http://localhost:4000` | URL of your dev server (where middleware is mounted) |\n| `CODEDSWITCH_API_KEY` | — | API key from [codedswitch.com](https://www.codedswitch.com) — required for `analyze_audio` and `describe_audio` |\n| `MCP_API_URL` | `https://www.codedswitch.com` | Override the analysis API base (advanced / self-hosted) |\n\n### Middleware Options\n\n```js\nwebearMiddleware({\n maxCaptures: 50, // Max captures in memory (default: 50)\n maxAgeMins: 10, // Auto-evict after N minutes (default: 10)\n maxUploadBytes: 50e6, // Max upload size (default: 50MB)\n devOnly: true, // Disable in production (default: true)\n})\n```\n\n### Client Options\n\n```js\nWebEar.init({\n audioContext: myCtx, // Your AudioContext instance\n outputNode: myGainNode, // The node to tap (defaults to destination)\n toneJs: true, // Auto-detect Tone.js context\n bridgeBase: '/api/webear', // Override API path\n devOnly: true, // Only init outside of production (default: true)\n})\n```\n\n---\n\n## Requirements\n\n- **Node.js** >= 18\n- A browser that supports `MediaRecorder` (Chrome, Firefox, Edge, Safari 14+)\n- A `CODEDSWITCH_API_KEY` for analysis (free at [codedswitch.com](https://www.codedswitch.com))\n\n---\n\n## Who Is This For?\n\n- **Web Audio / Tone.js developers** — debug beats, synths, effects, and mixing without leaving your IDE\n- **Game audio developers** — verify sound effects, spatial audio, and mixing in real-time\n- **Music app builders** — catch regressions between code changes with `diff_audio`\n- **Podcast / streaming apps** — validate audio quality, levels, and encoding\n- **Anyone whose app makes sound** — if it has a Web Audio graph, your AI can now hear it\n\n---\n\n## Why Not Just Use the Microphone?\n\nMicrophone MCPs capture room sound — your fan noise, chair creaks, and room reverb are all in the recording. `webear` taps the Web Audio API **before it hits the DAC**, giving you a clean digital signal with no room artifacts.\n\n---\n\n## Web Perception — Full Sensor Suite\n\nWebEar started as audio-only. **Web Perception** expands it to 6 senses:\n\n| Sensor | What it perceives |\n|---|---|\n| **WebEar** | Audio — mix quality, rhythm, instruments, clipping |\n| **WebEye** | Visual — canvas, UI layout, animations, screenshots |\n| **WebSense** | Performance — frame rate, memory, audio latency |\n| **WebNerve** | Network — API latencies, connection quality, storage |\n| **WebShield** | Security — cookies, storage exposure, CSP, framing |\n| **WebLog** | Console — logs, warnings, errors, uncaught exceptions |\n\n### Install the full browser SDK\n\n```js\nimport { WebPerception } from 'webear/perception'\n\nWebPerception.init({\n apiKey: 'wbr_YOUR_API_KEY',\n relayUrl: 'https://www.codedswitch.com',\n sensors: ['ear', 'eye', 'sense', 'nerve', 'shield', 'log'],\n})\n```\n\nOr use a single sensor:\n\n```js\nimport { WebEar } from 'webear/perception'\n\nWebEar.init({\n apiKey: 'wbr_YOUR_API_KEY',\n ear: { audioContext: myCtx, audioNode: masterGain },\n})\n```\n\n### Connect via MCP (hosted relay — no local server required)\n\n```json\n{\n \"mcpServers\": {\n \"webear\": {\n \"url\": \"https://www.codedswitch.com/api/webear/mcp/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer wbr_YOUR_API_KEY\"\n }\n }\n }\n}\n```\n\n### Available MCP Tools\n\n| Sensor | Tool | Credits | Description |\n|---|---|---|---|\n| **Ear** | `capture_audio` | Free | Record live tab audio |\n| **Ear** | `analyze_audio` | 1 | BPM, loudness, frequency bands, clipping, dynamic range |\n| **Ear** | `describe_audio` | 2 | AI plain-English description — instruments, genre, mood, mix notes |\n| **Ear** | `diff_audio` | 1 | Compare two captures — loudness, tone, timing deltas |\n| **Ear** | `groove_score` | 2 | Grid alignment, swing factor, consistency (0–100%) |\n| **Ear** | `capture_and_analyze` | 1 | Capture + analysis in one call |\n| **Ear** | `mix_coach` | 3 | Structured mixing feedback |\n| **Eye** | `capture_video` | Free | Record canvas/video from the tab |\n| **Eye** | `describe_video` | 2 | AI visual description — layout, colors, bugs |\n| **Eye** | `diff_visuals` | 2 | Compare two visual captures |\n| **Sense** | `capture_telemetry` | Free | FPS, memory, layout shifts, audio latency |\n| **Sense** | `analyze_telemetry` | 1 | Frame drops, memory pressure, audio underruns |\n| **Nerve** | `capture_nerve` | Free | API timings, connection quality, storage size |\n| **Nerve** | `analyze_nerve` | 1 | Slow APIs, connection quality, storage bloat |\n| **Shield** | `capture_shield` | Free | Cookies, CSP, storage exposure, framing |\n| **Shield** | `analyze_shield` | 1 | CORS issues, non-HttpOnly cookies, missing CSP |\n| **Log** | `capture_logs` | Free | Console output + uncaught exceptions |\n| **Log** | `analyze_logs` | 1 | Error patterns, stack traces, repeated warnings |\n\n### Get an API Key\n\n1. Create a free account at **[codedswitch.com](https://www.codedswitch.com)**.\n2. Open **[codedswitch.com/developer](https://www.codedswitch.com/developer)** — also linked as **Developer API** in the account menu.\n3. Click **Generate API Key** and copy it. Keys start with `wbr_`.\n\nFree tier: 50 analyses/day, no credit card required.\n\n---\n\n## Changelog\n\n### 2.0.1\n- **Fixed the getting-started path for API keys.** The previous instruction\n (\"Settings → WebEar\") was wrong — there is no WebEar section under Settings.\n Keys live at **[codedswitch.com/developer](https://www.codedswitch.com/developer)**\n (linked as **Developer API** in the account menu). Both the Quick Start and the\n Web Perception sections now point to the correct place.\n- The SDK's \"missing API key\" console error now links straight to the key page.\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## License\n\nMIT — see [LICENSE](./LICENSE)\n\n## Author\n\nBuilt by [@asume21](https://github.com/asume21) — [CodedSwitch](https://www.codedswitch.com)\n",
"bytes": 13170,
"sha": "6a98920aed1dd66764ce1777bcc3818a403743e63e9a23fda5c50fa94df2c935",
"repo_slug": "asume21/webear",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_asume21_webear_06f3382d/readme"
}